Skip to content

draft BEP-0013.md - update annotation handling #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
vtoure wants to merge 1 commit into
base: master
Choose a base branch
from
Open

draft BEP-0013.md - update annotation handling #36

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions docs/published/BEP-0013.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <keyword> AS CURIE`
Where `<keyword>` 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 <keyword> = "<prefix>:<identifier>[ ! <name>]"
SET <keyword> = {"<prefix>:<identifier>[ ! <name>]", ...}
```
The new set citation looks like:
`SET Citation = "<prefix>:<identifier>[ ! <name>]"`
Where `<name>` 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