fieldstudiescouncil / tombiovis

The FSC Identikit for creating online keys and resources for biological identification (previously called Tom.bio ID Visualisation Framework).

The FSC Identikit

Note

We have a forum.

Join us there to ask for help using Identikit, help with creating resources, discuss features, bugs, or anything else related to the software.

The FSC Identikit is an open-source project which anyone is free to get involved in. It is provided as-is and Field Studies Council is not able to provide any support or development for it at this time.

To get started quickly, follow our Quickstart Guide.

The FSC Identikit is a framework for creating online biological identification resources, including multi-access keys.

The genesis of the project was the Field Studies Council's (FSC) Tomorrow's Biodiversity project (funded by Esmée Fairbairn 2013-2017 inclusive). Esmée Fairbairn funded a further year's development of the Identikit (covering 2018) to facilitate rolling the work forward into the HLF-funded FSC BioLinks project which ran from 2018 to the end of 2022.

Prior to March 2018, The FSC Identikit was referred to as 'The Tom.bio ID Visualisation Framework', or variations thereof.

Try it out

Try the software out:

• With the standard interface.
• With the mobile interface.

Developers

The repostitory can be cloned thus: git clone https://github.com/FieldStudiesCouncil/tombiovis.git.

If the clone fails, try the following: git clone https://github.com/FieldStudiesCouncil/tombiovis.git --depth 1 --no-single-branch.

The second git command clones the repostiory with a truncated history. This should be fine for most purposes.

Documentation

All documentation for this project is found in the 'documentation' sub-folder and includes the following:

• Quickstart Guide
• Getting started (more detailed than the Quickstart Guide)
• Building a knowledge-base (essential guide for knowledge-base developers)
• Deploying your resources (how to make your ID resources available to other people)
• Character scoring (only for those who want more detail on Identikit's mechanism for scoring with multi-access keys)
• Notes for coders (only for programmers who want to extend or contribute to the Identikit)

We are also working on moving the documentation online so that it will be available here. Currently the following is available:

• Quickstart Guide

Other information

• Change log
• Release notes
• Support

tombiovis's Issues

Update deployment doc to account for service workers

Deployment documentation needs to account for service workers.

Title on characters menu of mobile

From Steve Docker: "When you select the list of characters (either swiping right or selecting the keyboard symbol) it would be good to have the heading 'Characters' above the list of character groups."

Make getViewURL part of interface for visualisations

Consider making getViewURL part of the api on visualisations (as it is for key input). Again - no change for user, just coding structure.

New photo-grid visualisation and tagged images

Photo grid with wholesale character selection (should all be inline), e.g. float left picture squares that will flow when screen resized. Therefore responsive. Images should be able to be tagged so that users could say something like, show me pictures of cones for this species. (Matt Parratt very keen on this.) This would also be really useful for Rubus Identikit too.

Paths to resources in CSS files not flexible enough for various deployments

Several CSS files reference resources via the url function. But the way this is currently used means that resources not found when deployed to sub-folder on server. Also it was not working when I experimented with deployment in Node electron. Need to find a solution which works for all environments.

Spin control problem when cleared by spinning

Email from Leslie Reid 20/07/2018: I then made the mistake of removing the entry by deleting it directly, rather than by using the “x” button to the right of the entry field. Even though the field then appeared to be empty, it remained as an implicit value of 0, so the rankings continued to be influenced—I figured that out by switching to single-column mode to see what was controlling the rankings. If a deleted value were either displayed as an explicit 0 or considered to be equivalent to the “x” click, the problem would be solved.

Double spaces in CharacterStateTranslation column of values tab

During a workshop at WWBIC yesterday, Josh Jones had a problem with some translated character states values not appearing to work. Today I tracked this problem down to the occurrence of a double-space in the value in the CharacterStateTranslation column. Workaround is to ensure that there are no double-spaces, but it needs fixing.

Update deployment doc to account for manifest

Will need to include description of what the manifest does and what the fields are - particularly the title fields and icon fields.

add images from the web

Currently, tombiovis only supports image-local for adding images. Any plans for adding image-web support to add any http(s) URL? It would allow to link to images already stored elsewhere like Flickr, SmugMug, Google Photos...

I am a developer and I could code this feature as it is required for one of my project. Before doing so, I wanted to check with you whether it was already done in your v1.7 branch, already planned, or if there is anything I should know before starting?

Thanks

Taxon name 'Pinus nigra var laricio/var nigra' breaks name shortening in vis5

Console reported original error on line 640 which was where the circles were tagged with an ID from the taxon circle's circleID property.

Images cropped in details dialog

The dialog is a set width and height (though you can resize it by dragging the corner) and the images are always shown at 100% in it and the dialog not resized to accommodate the different heights. I may add another option on the dialog so that you can stipulate that the whole image is to be shown.

Character called 'height' breaks the two-cloumn key visualisation

Malcolm Greaves found that the two-column key wasn't working for a new knowledge-base that he is putting together - even though the other two key visualisations worked. It turned out to be because the two-column key visualisation (vis1) cannot handle a character with the name 'height'. This needs to be fixed in the code. Also examine the code for other character names that would break a visualisation.

If you are having this problem with version 1.6.0 or earlier, the workaround is to use a character of a different name (e.g. 'height1') - it won't make any difference to users who will still see the label associated with the character (which can be 'height' or anything else).

An option to ignore non-matching character input

Currently non-matching characters score against the taxon. We could provide an option to ignore all 'against' scores. Could be implemented as a context menu option or via the general options.

Per taxon character weighting

Add facility for KB developers to provide a downloadable PDF to instruct key users

This feature was requested via Mal Hargreaves from an issue raised to him by someone using one of his keys. The wanted instructions on how to get the information from specimens to put into the key - not instructions on using the key itself. We already have the facility to supply an HTML file that includes information on the KB, but what is really required is facility for KB developers to create a downloadable PDF using whatever tools they wish.

Change recommended local server

There is a much simpler, ready-made simple node.js simple local server implementation called 'http-server' that could be configured & recommended instead of the way we currently do it. Requires only one node.js package instead of two and requires less setup/configuration than the method we currently recommend.

Links from species descriptions to change selected image

Attribute of link will be the image URL as it appears in the KB. Need nice error handling for cases where this not found. Also an option (attribute) to signify that image should be popped out full size? What about displaying as a tooltip? Or maybe image should just be popped out in a galleria image control on link?

Macros don't work with LibreOffice

Currently the macros in kb/biscuits/biscuits.xls don't work with LibreOffice. Has anyone done any work on macros that will work? I have got the Save as CSV one basically working but have not looked at the others yet. My plan was to put both versions in the macro with the LO code commented out so it could be enabled if required.

URL generation from keys doesn't always reflect currently specified character values

To reproduce, select some character values then unset one or two. Generating the URL from context menu, treats the unset values as if they were still set.

sexual dimorphy coding for non text characters (new feature)

develop capability to use format “value (f) | value (m)” for numerical characters

Update input controls to use new group data structure

I was repeating code in Onsen key input to create group collections so I added to tombiovis to add to general data structure. (tbv.d.groupedCharacters). Other stuff can now take advantage of that.

Save audit trail

From email from Steve Docker: "Would it be possible to have a 'save' function to retain an audit trail of selections made? For example, this would be very useful for the 'Macrofungi Genera' app as the ID can/should be started in the field with the fresh material and may well be completed later with the specimen in the laboratory/classroom. The audit trail would be helpful to the final determination etc."

This could be another right-click option based on the URL generation

Dealing with Bingo! characters

There needs to be an explicit way of dealing with 'Bingo!' characters - i.e. those characters with immediately shout individual or small groups of taxa. For example Paul Richards highlighted some of these characters in red in his Excel matrix, but we currently have no special way of dealing with them in any of the visualisations. This needs some thought and development - probably both of the software and the knowledge-base format.

Missing group gives spurious error message

Encountered this problem using version 1.8.2 in November 2018.

Update small format devices warning mechanism

Update message that warns for small format devices to make it sensitive to the tool used. Tool should have a flag to indicate if this message is displayed.

Multiple spaces in translated values prevent ordinals from working

From email from Leslie Reid dated 25/07/2018: Hi, Rich,

I’m now framing out my fourth key, and the software continues to work great. I did run across another unexpected behavior that appears to have resulted from a quirk in my labeling strategy; I’ve attached my “TestResult” spreadsheet that illustrates the problem and the solution I found. The problem was that I couldn’t get the “Mass1” character to provide results as an ordinal variable—it worked just fine as a text-multi or text-single, and other characters in the original (Russula) spreadsheet worked just fine as ordinals. If you turn this spreadsheet into a key, you’ll find that the first and third characters work fine, while the second registers nothing. The fourth reflects the solution.

I tried a number of things to isolate the problem, which turned out to be the way I’d translated the CharacterState in the “CharacterStateTranslation” field. When I put the input code in parentheses (see lines 36-45 in Values) instead of leading off with it (lines 14-23), everything worked fine.

And at this point I have to admit that I thoroughly enjoy working on this kind of puzzle!

Simplify the citation stuff

Simplify the citation stuff. Remove citations for individual tools.

Add ability to save user selections for future reference

Caroline Hobart suggested (by email) an enhancement to allow users to save their input choices for future reference and provided the following example from a tool called MycoKey. This would be a useful enhancement - probably to implement for release 1.8.

Fruitbody type agariciod; fruitbody height 40 mm; pileus conical; pileus surface with radial fibers or dry; hymenophore dull brown; lamellae attachment adnexed; lamellae medium crowded; stipe/outer surface colour whitish to cream; stipe width 3 mm; colour of spore deposit clay buff to pale grey brown.
[Description auto-generated from character input in MycoKey.]

Typo in KB checking messages

From an email from Leslie Reid (16/08/2018):

I ran across what I think is a typo that I thought I should bring to your attention. I’d been using a temporary extra column as I was working on the taxa sheet and I didn’t want it to display, so I hadn’t added it to the “characters” sheet. Consequently, I got a diagnostic (attached) warning me to include it on the sheet, but explaining that if I left “group” blank it wouldn’t display. That turned out not to work—I did need to fill in a value for “group,” so my temporary column is now included as a display variable

In fact it should read 'Status' not 'Group' column. Will address in release 1.8.0.

Intelligent selection of full details tab

In multi-access keys when taxon is clicked to get full details, some (e.g. mobile key) go straight to photos tab even if there are no photos. If there are no photos, it would be better to display kb values by default.

Width of pictures in full details visualisation not controllable

This problem was pointed out to me by Malcolm Greaves. When no text is displayed on the full details visualisation, images are shown at 100%, but the width of the display is governed by the table that displays the knowledge-base values underneath. This changes depending on the contents of the knowledge-base for the taxon being viewed. There needs to be a way to fix the width of the images.

Knowledge-base values header needs CSS clearing in vis4

In the full species details visualisation (vis4), when images are specified and a small amount of text, the images are floated to the right. The header for the 'Knowledge-base values' is displayed directly under the text (to the left of the floated image), but then there is a large gap before the actual knowledge-base values which appear under the image. Need to fix this by applying the CSS clear attribute to the header.

Help dialog spacing

Improve spacing between caption and next character value option in help dialog.

Update D3 to version 5

Update D3 from version 4 to version 5. There are only minor changes.

Checking doesn't pick capital letters as errors in status values

No errors are generated but character is ignored if Key is used as a value instead of key in the status column of the characters tab v1.8.2

Red-line characters

For certain characters, if they do not have the right value, they should be excluded from the analysis (or visually distinguished, e.g. by moving to a different column). Or maybe a more general way of forcing strict matching.

Ability to filter taxa

It would be good to have an ability to filter taxa, e.g. by taxonomic group such as genus, but perhaps by any ad hoc group.

Leslie Reid has also asked for this.

Moving to single column key from another key leads to interrupted animation

If you are working with two column key and then move to single-column key, the visualisation animation is interrupted and doesn't complete properly so that column labels, for example, aren't properly justified.

'Key' character pointers

Idea from Matt Parratt email dated 14/08/2018: "There might also be scope for a 'key characters' pointer. I'm thinking this might give people a set of maybe 4 or 5 characters that are really important and that will pull out small groups of species with minimal effort."

Crash of refresh or reload KB on Earthworm site

This was because no service worker implemented on the CMS site so in tombiovis.js references to caches (e.g. line 667 cause crash because caches is not defined). Worked around by adding - var caches - in top level page.

Manifest path to start URL should not be relative to root

Remove the leading slash to start_url file so that it can be found if deployed in sub-folder on website.

Circle pack key not always overflowing

The Circle pack key visualisation not always overflowing its SVG (it should). I noticed this in a visualisation implemented as a Drupal page. I think that site's CSS has a higher priority assignment of hidden overflow on SVG. I was handling the overflow in vis5's external CSS file - best change it so that it is assigned on the element in code.

Magic wand feature requested

A number of people have requested a 'next best character' features similar to the magic wand on LUCID.

Template load dependent on dev option

Make load of template for interface testing dependent on dev option. Refactoring - no visible difference for users.

Glossary

We have no glossary facility! It should be possible to tag a word, e.g. cephalothorax and have the framework attach a tooltip to that word to display a definition.

Mis-spelling ordinalCircular bug

Mis-spelling ordinalCircular with lower-case c gives black score squares.

2 level character scoring and associated visualisation

Single select text elements sometimes mis-selected

This bug was discovered by Mal Greaves. Identikit was scoring taxa with values of ‘black’ and ‘brown’ for a character when the user specified a value of ‘blackbrown’ because it could find both of those strings as substrings of ‘blackbrown’. The same would happen with ‘green’ and ‘lightgreen’ for example. It’s quite a serious bug and will likely affect lots of keys, especially for characters that use colours like this. And will therefore be addressed by an updated release - 1.7.2.

Sites suppressing drop-down tool menu can crash on certain selections

On harvestmen and conifers website, going to the help page for a tool not yet used causes crash.

Facebook link bug

When URLs are generated from visualisations (from the right-click context menu) and pasted into Facebook, fb can replace some space characters with the plus symbol. So they need searching for and converting to spaces.