BEP-0007 - Numeric Annotations

docs/drafts/BEP-0007.md

@@ -0,0 +1,62 @@
+# Numeric Annotations
+
+## Abstract
+
+The purpose of this BEP is to add support for numeric annotations. 
+
+## Preamble
+
+BEP-Id: BEP-0007
+
+Status: Draft
+
+Version: 1
+
+BEL-Version: 2.0.0+
+
+Authors: Natalie Catlett ([email protected]) and Vy Hoang ([email protected])
+
+Created-Date: 2018-07-24
+
+Type: Standards Track
+
+## Rationale and Goals
+
+The purpose of this BEP is to add specific support for numeric annotations. The original BEL specifications allowed for annotations to be defined as a url (pointing to a belanno file), a list of values, or a pattern/regular expression. Defining annotations as a pattern/regular expression supports the capture and validation of numeric annotations, but not their interpretation as numbers for downstream uses.
+
+## Use Cases
+
+Capture quantitative information about BEL statements, like the significance (p-value) or magnitude of a fold-change. Use annotations to filter BEL nanpopubs or edges for those annotated with smaller p-values or larger fold-changes.
+
+
+Example: 
+
+    Citation = {“PubMed”,”7742155”}
+    Evidence = “TSB [total serum bilirubin] concentrations at 24 h were about 2.5 times higher after a fast compared with the nonfasting treatment”
+    FoldChange = 2.5
+    Time = “24 h”
+    Anatomy = UBERON:serum
+    bp(MESH:"Fasting") increases a(CHEBI:bilirubin)
+
+
+## Discussion
+
+Do time annotations belong in a separate BEP since units (minutes, hours, days, years) also need to be considered? Ideally, time annotations would include both a number and a unit, and conversion between units would be supported to enable filtering. E.g., 24 hours is equivalent to 1 day, 30 minutes is less than 6 hours.
+
+Should any numeric annotations be standardized, similar to BEL annotations for Anatomy, Cell, Cell Line, etc.?
+
+Are there additional data types that might be desirable to support for BEL annotations?
+
+## Specification
+
+Define an annotation as a numeric value. Include acceptable ranges as part of the annotation definition, e.g., ‘P-value’ must be between 0 and 1. Numbers can be expressed as integers, decimals, or scientific notation. 
+
+
+## Backwards Compatibility
+
+This proposed feature is for 2.0.0+ and will be added to the language so does not require any efforts to migrate older BEL knowledge.
+
+## Reference Implementation
+
+The reference implementation must be completed before any BEP is given status "Final", but it need not be completed before the BEP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of BEL Language and API details.
+