search

micom-dev / micom

Python package to study microbial communities using metabolic modeling.
https://micom-dev.github.io/micom
Apache License 2.0
82 stars 17 forks source link

[feature] Add new interaction analysis API #170

Closed cdiener closed 2 months ago

cdiener commented 2 months ago

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

vrmarcelino commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

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!

correlation_between_old_new_MES

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 commented 2 months ago

@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] commented 2 months ago

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 ```diff @@ 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.