Further unification of cobrapy and cameo codebase

[Midnighter]

Just found that a cobrapy model defines the property boundaries whereas the pathway predictor expects exchanges. We are thinking about implementing further methods/properties here (https://github.com/opencobra/cobrapy/pull/589) but we should make sure the right one is used by cameo (boundaries includes sink and demand reactions).

[the-code-magician]

Hi @Midnighter

I think we need to make sure have a coherent nomenclature, that is well documented:

boundaries: all reactions that look like metabolite <-> despite of their upper and lower bound. exchanges: all boundaries in the extracellular compartment. sinks: all boundaries with lower_bound >= 0 and upper_bound > 0. things going out sources: all boundaries with lower_bound < 0 and upper_bound <= 0. things going in demands: all sinks in the extracellular compartment. uptakes: all sources in the extracellular compartment.

The upper and lower bounds can be subject of discussion, but we need to get this sorted out nicely!

Regarding sinks and sources it has been defined in graph theory "a source vertex is a vertex with indegree zero, while a sink vertex is a vertex with outdegree zero".

More arguments in favor of using sinks and sources are their meaning: https://en.oxforddictionaries.com/definition/sink

• to sink [with object] Conceal, keep in the background, or ignore. ‘they agreed to sink their differences’
• to sink [no object] Gradually decrease or decline in value, amount, quality, or intensity. ‘their output sank to a third of the pre-war figure’
• British informal [with object] Rapidly consume (an alcoholic drink) ‘English players sinking a few post-match lagers’
• technical A body or process which acts to absorb or remove energy or a particular component from a system. ‘a heat sink’ The opposite of source: ‘the oceans can act as a sink for CO₂’

https://en.oxforddictionaries.com/definition/source

• A place, person, or thing from which something originates or can be obtained. ‘mackerel is a good source of fish oil’
• A spring or fountain head from which a river or stream issues. ‘the source of the Nile’

[Midnighter]

While your definitions make sense to me I'd rather stick with conventions in the field. In Figure 7 [1]_,

• an exchange is extracellular and reversible,
• a demand is cytosolic (intracellular) and irreversibly removes a metabolite, and
• a sink is intracellular and reversible.

.. [1] Thiele, Ines, and Bernhard Ø Palsson. “A Protocol for Generating a High-Quality Genome-Scale Metabolic Reconstruction.” Nature Protocols 5, no. 1 (January 2010): 93–121. doi:10.1038/nprot.2009.203.

[ChristianLieven]

I do agree with Joao, that in particular the literal wording of the defined term 'Sink' seems counterintuitive. A 'Pool' would seem to be the more appropriate terminology in my opinion. However, it may be possible that the original authors are referring something like this. Which says:

In all cases, each of the opposing terms (source or sink) may refer to the same object, depending on the perspective of the observer and the sign convention being used; there is no intrinsic difference between a source and a sink.

I'd like to highlight the following sentence as it might provide more clarity with respect to a biological example:

In biology, the schematic barrier in the figure could represent a cell membrane, and as a result, the two compartments could represent the inside and the outside of the cell. Generally speaking the point of observation would be outside the cell. Thus the cell would be termed a sink with respect to any flow of positive charges into it, and the cell would act as a source for any positive charges flowing out of it. Note that when considering the flow of negative charges, the definitions are reversed.

I'd prefer to keep the overall amount of definitions to a minimum.