From 974e571fbda52cba469e5d1f4afa552484936b07 Mon Sep 17 00:00:00 2001 From: vtoure Date: Mon, 1 Jun 2020 11:52:58 +0200 Subject: [PATCH] draft BEP-0013.md - update annotation handling --- docs/published/BEP-0013.md | 103 +++++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 docs/published/BEP-0013.md diff --git a/docs/published/BEP-0013.md b/docs/published/BEP-0013.md new file mode 100644 index 0000000..6362645 --- /dev/null +++ b/docs/published/BEP-0013.md @@ -0,0 +1,103 @@ + +# BEP-0013: Update Annotation Handling + +## Abstract +The purpose of this BEP is to update the way annotations are handled in BEL script. First, it updates the syntax for defining annotations in the header of BEL Script and for setting annotations in the body of BEL Script. Second, introduces the CURIE type of annotation in addition to URL, LIST, PATTERN, and MIRIAM. Third, it introduces BEP-0008 OBO-style identifiers for definitions of annotations. Finally, it introduces alternate semantics for the SET Citation annotation that resemble OBO-style identifiers. + +## Preamble +BEP-Id: BEP-0013 +Status: Draft +Version: 1 +BEL-Version: 2.0.0+ +Authors: Vasundra Touré ([vasundra.toure@ntnu.no](mailto:vasundra.toure@ntnu.no)) and Charles Tapley Hoyt ([https://github.com/cthoyt](@cthoyt)) +Created-Date: 2020-05-07 +Type: Standards Track + +## Rationale and Goals +While BEP-0008 updated the way that identifiers are defined and handled for entities in BEL terms, annotations still need an update. The current state of annotations is much worse - many annotations commonly used in BEL Script derive from the Selventa definitions. For example, the historical "Anatomy" annotation corresponds loosely to a combination of UBERON and a subset of the EFO, which makes it difficult to look up the identifiers because it's not clear from what database a given name comes. +There are obvious benefits to grouping annotations of a similar class (cell, cell line, species, compartment), so this BEP will enable users to continue to define their own classes of annotations, but use more structured identifiers (CURIEs). This is accomplished by creating a new type of annotation definition - CURIE, that will allow users to use OBO-like identifiers (as described in BEP-0008). Validation and normalization of identifiers defined this way will be left as an implementation detail. + +## Use Cases +The main motivation for this BEP comes from the desire to make BEL compliant with MI2CAST ([https://www.preprints.org/manuscript/202004.0480/v1](https://www.preprints.org/manuscript/202004.0480/v1)) by supporting all possible contextual and defining details specified. MI2CAST is a standard guideline developed to unify the representation of causal statements. Most recommended terms are already supported by BEL, and only a few need to be added. Being compliant with MI2CAST will also ease the process of conversion between PSI-MITAB level 2.8 and BEL. Several use cases are presented before full examples derived from the MI2CAST recommendations. + +### Allow single value for SET Citation +Previously, the SET Citation annotation had special semantics where the number of entries changed how it was handled as in: +`SET Citation = {"PubMed", "15596805"}` +This BEP proposes that a single value could be used in the SET Citation that corresponds to a CURIE for PubMed, PubMed Central, or any other reasonable CURIE for citations (including bioRxiv, medRxiv, DOI, etc.) +`SET Citation = "pubmed:15596805"` +This BEP also deprecates old-style usage of SET Citation, to be removed in the next major version change of BEL. + +### Define annotation as CURIE +In the following example, the CellLine annotation is defined as CURIE, such that either annotations from the Brenda Tissue Ontology (BTO), Cell Line Ontology (CLO), Cell Ontology (CL), Experimental Factor Ontology (EFO), or others could be used. This annotation covers Rule 4.5 of MI2CAST and its sub-rules with the annotation of location information, and Rule 3.2.1 for the annotation of experimental setups applied to the source or target entity that are necessary for observing the causal interaction. +``` +DEFINE ANNOTATION CellLine AS CURIE +... +SET CellLine = "bto:0000944 ! NIH-3T3 cell" +... +complex(p(uniprot:P05412), p(uniprot:P15408)) -> r(ncbigene:5971) +``` +Note that in this example, the OBO-style identifier does not need quotes around the name, even though it has special characters like spaces. This is not necessary inside the annotations because it's easier to parser. + +### Extend set annotation to accept OBO-Style +In the following example, the Evidence and Conclusion Ontology (ECO) is defined as MIRIAM as per BEP-0009, which means the implementation should look up the appropriate pattern from [https://identifiers.org](https://identifiers.org). This is an example of how the OBO-style syntax can be used to write out the name. Here, adding ‘ECO’ enables to annotate the evidence type assessing the way a causal interaction has been created, which covers Rule 3.2 of MI2CAST. +``` +DEFINE ANNOTATION ECO AS MIRIAM +... +SET ECO = "0007682 ! reporter gene assay evidence used in manual assertion" +... +complex(p(uniprot:P05412), p(uniprot:P15408)) -> r(ncbigene:5971) +``` +As an aside: for MI2CAST compliance, it would be best to actually define this using the "EvidenceType" keyword as in the following. +``` +DEFINE ANNOTATION EvidenceType AS CURIE +... +SET EvidenceType = "eco:0007682 ! reporter gene assay evidence used in manual assertion" +... +complex(p(uniprot:P05412), p(uniprot:P15408)) -> r(ncbigene:5971) +``` + +### Full Example +Below is the full Transcription Factor Regulation [example](https://github.com/MI2CAST/MI2CAST/blob/master/examples/2TF-TG.md) from the MI2CAST site, encoded as BEL using the updated definition syntax. +``` +DEFINE ANNOTATION EvidenceType AS CURIE +DEFINE ANNOTATION CellLine AS CURIE +DEFINE ANNOTATION Tissue AS CURIE +DEFINE ANNOTATION Taxonomy AS CURIE +DEFINE ANNOTATION Compartment AS CURIE +DEFINE ANNOTATION ExperimentSetupSource AS CURIE +DEFINE ANNOTATION ExperimentSetupTarget AS CURIE +... +SET Citation = "pubmed:15596805" +SET Taxonomy = "taxonomy:9606" +SET CellLine = "bto:0000944" +SET Compartment = "go:0005634" +SET EvidenceType = "eco:0007682" +SET ExperimentSetupSource = "eco:0005802 ! cell transfection experiment evidence used in manual assertion" +SET ExperimentSetupTarget = "so:0000832 ! promoter_region" +... +complex(p(uniprot:P05412), p(uniprot:P15408)) -> r(ncbigene:5971) +``` +This example shows a mixture of normal annotations using definitions by MIRIAM, using definitions by CURIE, and a mixture of normal CURIEs and OBO-style CURIEs. + +## Discussion + + +## Specification +The new definition syntax looks like: +`DEFINE ANNOTATION AS CURIE` +Where `` does not correspond to a prefix from https://identifiers.org, but rather a user-defined category of annotations. Another BEP could provide recommendations for which are most relevant, similar to MI2CAST. +The new set annotation looks like: +``` +SET = ":[ ! ]" +SET = {":[ ! ]", ...} +``` +The new set citation looks like: +`SET Citation = ":[ ! ]"` +Where `` could be the title of the article. However, as with all OBO-style identifiers, the implementation can choose to throw away the labels and look up canonical ones. + +## Backwards Compatibility +This BEP does not introduce any backwards incompatibilities. + +## Reference Implementation + +