From 03e057749eeb2f6ab629256027bee013c7c348c1 Mon Sep 17 00:00:00 2001
From: Natalie Catlett <1619255+ncatlett@users.noreply.github.com>
Date: Tue, 24 Jul 2018 15:10:38 -0400
Subject: [PATCH] Create BEP-0007.md

Numeric annotations

closes #15
---
 docs/drafts/BEP-0007.md | 62 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 docs/drafts/BEP-0007.md

diff --git a/docs/drafts/BEP-0007.md b/docs/drafts/BEP-0007.md
new file mode 100644
index 0000000..1ed61ce
--- /dev/null
+++ b/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 (ncatlett@patientslikeme.com) and Vy Hoang (vhoang@patientslikeme.com)
+
+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.
+