SOP: Adding an EQ definition (TSV)

This is a standard operating procedure (SOP) for creating entity–quality (EQ) definitions. An EQ definition contains a reference to an entity (E) and a quality (Q). The entity can be an actual material entity (such as an eye), or an abstract entity (such as a biological process). The quality defines a characteristic or trait, such as 'size', 'shape', 'length', and so on. (See the 2018 POTATO Workshop report for more details)

Steps for adding an EQ definition

1. When adding a new term to a phenotype ontology (MP, HP, WBP, DPO, etc.), you should consider whether it is possible to also define an EQ definition for that term.

2. Check the public directory of patterns and the development branch to see if there a suitable pattern for your term. Search the page (command+F, ctrl+F) for possible matches.

3. If you cannot find a suitable pattern, open a new issue, and title it something like "Need new pattern for X", where X is a summary of your term (or your use case). Tag the issue with dosdp-patterns. In the main text of the issue, provide two or three examples of why you need the pattern.

   • If the response to your issue confirms that no suitable pattern exists, you may continue to develop your EQ definition and use it in your ontology edit file (e.g. by using Protege). Make sure to provide the URL of the pattern request issue (from GitHub) in your commit message when you create the pattern.

     (The reason to proceed like this is that it may take a few weeks before the community has agreed on a pattern to use, and waiting for a pattern should not impair your progress in adding EQ definitions. Alternatively, you can choose to wait until the pattern is created before proceeding to the next step.)

4. If you do find a suitable pattern, copy its PURL (e.g. http://purl.obolibrary.org/obo/upheno/patterns-dev/abnormalBehavior.yaml) into the file called external.txt in your ontology repository (src/patterns/dosdp-patterns/external.txt).

   • Caution: Make sure external.txt does not already contain the PURL for your chosen pattern. Also, make sure that the same PURL does not appear more than once in the file (there should be no duplicate PURLs).

5. Unless it already exists, create a TSV file in your pattern directory (usually src/patterns/data/default or src/patterns/data/manual) that has the same name as the pattern, followed by the .tsv file extension (e.g. abnormalBehavior.tsv). This TSV file must have the following columns:

   • the defined_class column, which contains the PURLS or CURIEs of your ontology terms, such as HP:00000111;

   • at least one column for each entry in the list of vars in your chosen pattern's YAML file. Common entries in the vars list include biological_process, anatomical_entity, cellular_component, chemical_entity, and location. The TSV file can have any other columns if required; DOSDP will ignore them unless they end with _name or _description.

6. For each ontology term to which your EQ definition should apply, add rows in your TSV file with the relevant information. Here is an example:

   defined_class	biological_process	biological_process_label	anatomical_entity	anatomical_entity_label
   MP:0000001	GOX:0000001	fictional process	UBERX:0000001	fictional anatomical entity

   Note that the columns ending in _label are optional, but recommended: they provide a helpful explanation of what concept the term ID refers to. It can be difficult to make sense of a pattern when these term labels are not included, since term IDs alone contain no meaningful information.

7. Commit the TSV file to your branch.

   Note that if the TSV file fails its quality control (QC) checks, the most likely reasons for this are:

   • you have not specified the correct column names according to the vars section in the YAML pattern file; or

   • your TSV file is not formatted correctly: for example, you have not used tab characters to separate the columns, or you placed tab characters in the wrong places, etc.