[feature] Add new interaction analysis API

[cdiener]

Purpose

This adds functionality to analyze metabolic interactions in already existing outputs from the grow workflow. Functionality is added in the new micom.interaction module and the extended visualizations that go along with those.

Interactions are calculated between a focal taxon (taxon of interest) and all interaction partners by default, but one can also specify arbitrary sets of focal taxa, including all taxa giving all n x n interactions.

Focal interactions

Can be calculated with the interactions command as interactions(results, taxa=[focal taxa]).

All interactions would be obtained with interactions(results, taxa=None). This is relatively slow as all it scales with $|samples|\cdot|metabolites|\cdot|taxa|^2$. If more than one focal taxon is specified it will be parallelized across focal taxa.

For each metabolite M with focal taxon A and interaction partner B this will classify interactions into the following three groups:

provided:    A -> M -> B 
received:    A <- M <- B
co-consumed: A <- M -> B

Summaries

The resulting interactions can further be summarized into overall interaction fluxes using the summarize_interactions functions which collapses each focal:partner:group interaction in each sample onto the total flux, total mass flux, total carbon flux, total nitrogen flux, and number of interactions.

Scores

This includes a general framework to calculate and visualize interaction scores. For now I added the MES.

Visualizations

There are new visualizations for focal interactions and the MES score.

@vrmarcelino: Let me know if those make sense. Range of the MES looks similar to the paper.

example visualizations

TODO

• [ ] add tests
• [ ] add docs

[vrmarcelino]

Hi @cdiener Thanks for adding this feature! Yes the formula is correct and the values are in the range of what we found. Let me know if you want me to rub some tests.

[cdiener]

Hi @cdiener Thanks for adding this feature! Yes the formula is correct and the values are in the range of what we found. Let me know if you want me to rub some tests.

Awesome, yes it would be great if you could run some tests. You should be able to install this branch in a new python or conda env with

pip install git+https://github.com/micom-dev/micom.git@feature/interaction

Also for the visualizations I currently remove MES scores of 0 so I can show them on a log-scale and to not have too many metabolites with zero scores. Do you think that makes sense or should I include them?

[vrmarcelino]

Test done, and it works!

I've re-run the grow workflow for one sample, and calculated MES with MES_res = scores.MES(res) using the new feature.

The MES results are calculated correctly (same MES scores obtained using my scripts with the newly grown community). I expected some stochasticity with the grow workflow, but the MES results are extremely similar to what we obtained before for that sample, which is reassuring!

Yes I think it makes sense to remove the metabolites with zero scores for the visualisation, but if there is an option to download the .csv file I would leave all MESs in there (as it might be interesting if MES=0 in disease but >> 1 in health for example).

Thanks for implementing this!

[cdiener]

@vrmarcelino Thanks so much for the detailed validation. I would also expect some slight variation due to tolerance cutoffs and solver versions but overall super encouraging agreement. Happy it works. I'll leave all the MES in the CSV then.

[codecov[bot]]

Codecov Report

Attention: Patch coverage is 95.19231% with 5 lines in your changes are missing coverage. Please review.

Project coverage is 81.21%. Comparing base (691c30c) to head (f6b09eb).

Files	Patch %	Lines
micom/viz/interactions.py	90.24%	2 Missing and 2 partials :warning:
micom/interaction/focal.py	97.36%	0 Missing and 1 partial :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #170      +/-   ##
==========================================
+ Coverage   80.48%   81.21%   +0.72%     
==========================================
  Files          32       37       +5     
  Lines        2055     2156     +101     
  Branches      434      449      +15     
==========================================
+ Hits         1654     1751      +97     
- Misses        273      274       +1     
- Partials      128      131       +3     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.