Add support for Negative BEL

[cthoyt]

This PR adds support for specifying "negative knowledge" in BEL.

BEL Update

This means you can now write BEL statements reflecting things that have been found to not be true, such as We found that Protein X does not activate Protein Y. This would translate to

p(X) ~ directlyIncreases act(p(y))

All you have to do is add the ~ before the relationship and it knows what to do. It's also allowed that no space is provided depending on style preference.

p(X) ~directlyIncreases act(p(y))

Not sure how I feel about how this looks with the short forms

p(X) ~=> act(p(y))

PyBEL Data Model Update

This change is backwards compatible, but now you can check with a given EdgeData if there is a negative flag.

from pybel.constants import NEGATIVE
graph = ...
for u, v, k, d in graph.edges(keys=True, data=True):
    if d.get(NEGATIVE):
        ... # do something with negative info

Reasoning

The existence of a positive polar statement should imply the negative antipolar statement. For example, increases implies ~decreases, positiveCorrelation implies ~negativeCorrelation

Note for causal relations that causesNoChange is equivalent to ~regulates

Causal Relation	Implication
increases	~decreases
decreases	~increases
causesNoChange	~regulates, ~decreases, ~increases
~regulates	causesNoChange, ~decreases, ~increases
~decreases ^ ~increases	~regulates
regulates ^ ~decreases	~increases
regulates ^ ~increases	~decreases

Note for correlative relations that noCorrelation is equivalent to ~correlation

Correlative Relation	Implication
positiveCorrelation	~negativeCorrelation
negativeCorrelation	~positiveCorrelation
noCorrelation	~correlation, ~positiveCorrelation, ~negativeCorrelation
~correlation	noCorrelation, ~positiveCorrelation, ~negativeCorrelation
~positiveCorrelation ^ ~negativeCorrelation	~correlation
correlation ^ ~positiveCorrelation	negativeCorrelation
correlation ^ ~negativeCorrelation	positiveCorrelation

TODO

• Add proposal for negative statement flag ~
• Implement parser for proposal
• Add tests for proposal
• Modify edge iterator to not iterate with negative edges by default
• Add negative BEL BEP
• Add several examples of negative BEL from literature
• Add graph filter function to remove all negative BEL / all positive BEL

[codecov]

Codecov Report

Merging #408 into master will increase coverage by 0.06%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #408      +/-   ##
==========================================
+ Coverage   86.48%   86.54%   +0.06%     
==========================================
  Files         147      147              
  Lines        7116     7120       +4     
  Branches      949      952       +3     
==========================================
+ Hits         6154     6162       +8     
+ Misses        749      745       -4     
  Partials      213      213              

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f2f0165...4129ac0. Read the comment docs.

[ddomingof]

Cool!

[ddomingof]

I like the pandas reference haha

[cthoyt]

In python the ~ is always the unary negation operator, not just in pandas :)

[ddomingof]

I dont like negative a lot but to be honest I cant think of something beetter