EQ Editor requirements
The EQ Editor will be used by curators to annotate phenotypic descriptions of Ostariophysi using EQ syntax and ontologies.
The curator will use the EQ Editor to code phenotypic data from an existing publication into the EQ format. This data consists of descriptions of character state values for corresponding species (or, more precisely, specimens). A published character state description may contain: the species or higher taxonomic specification, a textual description of the character state value, reference to a voucher specimen for this description, an image showing the character.
The following are essential data elements to be captured by the EQ Editor for each character state description (format is in parentheses). There is some additional discussion of how to treat character definitions at "EQ for character matrices".
- species name (free text until taxonomic ontology is available?)
- voucher specimen lot ID (format?)
- specimen count
- specimen preparation (cleared and stained, etc.)
- EQ statement for character state (Q should be a value)
- E from fish anatomy (ontology ID)
- Q from PATO (ontology ID)
- measurement (number) - used if Q is an attribute suitable for measurement (e.g. "length")
- measurement unit (units ontology ID)
- E2 from fish anatomy (if Q is descendant of "relational quality of continuant" or "relational quality of occurrent") (ontology ID)
- original description (free text)
- publication/citation (DOI? older publications don't have DOI, do they? Another possibility is SICI)
- image or URL for image (image data or URL)
- evidence statement (confirmation by taxonomic expert, etc.) - this requires discussion
Sources of data
The publication being coded may contain data in one of a few different formats. The given data format may suggest its own style of workflow. These publication types include 3 main forms:
- Description of many characters for many species and higher taxonomic levels; no character-by-taxon matrix published.
- A data matrix with multiple species and multiple characters. There is a character state value for each cell in this matrix.
- A single species description of values for many characters.
- Description of a single character for many species (perhaps less common than the other formats?). If focusing on a single character the data may come from multiple publications.
It seems like scenarios 2 and 3 can be treated as special cases of scenario 1. For each character, an interface is required for choosing the Entity and Quality from their respective ontologies, and entering free text such as the original character descriptions, as well as other relevant data.
Since many species will share common values of character states, the interface should have a way of choosing previously entered character states, perhaps by separately enumerating the possible values for a character. EQ coding will be performed at the level of character states, but there may be a facility for dynamically viewing entries in a character matrix format. See "EQ for character matrices" for a discussion - at the June 5 PI meeting we decided to work with only character states.
The standard workflow would be a curator dealing with a single publication during a session of working with the EQ Editor. Steps might be:
- Create a new EQ Editor document.
- Enter document-wide data:
- publication information (author, title, journal)
- list of specimens - input specimen info and choose taxon from taxonomic ontology for each one
- Begin making character state annotations:
- Select a specimen or multiple specimens to which this character state applies (there should be facilities for efficiently choosing sets of specimens/taxa)
- Create a new EQ statement
- Choose Entity from anatomy ontology
- Choose Quality from PATO (usually a Value term)
- If the Quality is an Attribute term (such as "length"), enter a measurement and its units
- If the Quality is relational, enter a second Entity from the anatomy ontology
- If dealing with a single specimen, enter optional image data (URL). Images may not be applied to multiple specimens at once.
- At any point, the curator can save the current work to a document (or database). We should investigate requirements regarding the document format (relationship to PhenoXML/PhenoSyntax, NEXUS, etc.), which will depend on the detailed data model.
Working with EQ statements
- A particular EQ statement (specific combination of Entity and Quality) will often be applied to multiple specimens within one document. Specimens are likely to share EQ values as a result of phylogenetic history, so facilities for efficiently selecting groups of related specimens should be available. Entries with this EQ statement would be generated for each selected specimen.
- An EQ entry panel could allow the user to choose a taxon from the taxonomic ontology, either by directly browsing the ontology or through an autocomplete text search field.
- A phylogenetic tree view could be provided, which allows the user to select a node or nodes to which to apply an EQ statement. This tree could be initialized by using the taxonomic ontology. The user could manually edit the tree to provide additional resolution (perhaps by following a tree in the paper). Alternatively, the software could allow the specification in Newick format of a tree created by another application.
- What should the user be able to do if there is not an appropriate term in the ontology?
- What will be done (in the immediate term) with the annotations produced by the EQ Editor? Will they be stored in separate documents, or compiled into a central repository?
- Is a "post-composition" capability required?
- Need to add a button to say "Need a new term"
Some technology choices may figure into the application requirements, particularly if integration with another application or system is a desired feature. Possibilities include:
- Implement EQ editing as a Mesquite plug-in, providing some additional interface to the character editing already in Mesquite. This would require extensions to the NEXUS format for storing ontology term information. Here is some more discussion on Mesquite.
- Extending Phenote with any additional functionality that is required. Phenote is being actively developed by the model organism community, but deals with a list of unordered EQ statements rather than a species-by-character matrix. Here is some more discussion on Phenote.
- Web-based application.
- Components from all of the above.