### Complete MICOM Workflow Example

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/core.md

Demonstrates a typical workflow using q2-micom functions, starting from building a metabolic model database to simulating growth and visualizing results. This example requires QIIME 2 and pandas libraries.

```python
from q2_micom import (
    db, build, minimal_medium, grow, 
    plot_growth, exchanges_per_sample
)
from qiime2 import Artifact, Metadata
import pandas as pd

# Step 1: Create or load database
metadata = Metadata.load("models_metadata.tsv")
models_db = db(meta=metadata, rank="genus", threads=4)

```

--------------------------------

### q2-micom Data Flow Example

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/README.md

Illustrates the data flow through the main workflow phases of q2-micom, from input data to results and visualizations.

```text
Abundance + Taxonomy + Database
          ↓
    [build()]
          ↓
Community Models + Medium
          ↓
    [grow()]
          ↓
Results → Visualizations
        → Statistical Analysis
        → Publication
```

--------------------------------

### Build, Grow, and Plot Community Models

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/INDEX.md

This example demonstrates the basic q2-micom workflow: loading prebuilt models, building community models from abundance and taxonomy data, simulating growth, and visualizing the results. Ensure you have 'prebuilt_models.qza', 'abundance.qza', and 'taxonomy.qza' available.

```python
from q2_micom import build, grow, plot_growth
from qiime2 import Artifact

# Load prebuilt models
models_db = Artifact.load("prebuilt_models.qza")

# Create community models
community_models = build(
    abundance=Artifact.load("abundance.qza"),
    taxonomy=Artifact.load("taxonomy.qza"),
    models=models_db
)

# Simulate growth
results = grow(models=community_models)

# Visualize
plot_growth("./output", results)
```

--------------------------------

### Register Gurobi License

Source: https://github.com/micom-dev/q2-micom/blob/main/README.md

Registers the Gurobi installation with your license key. Replace 'YOUR-LICENSE-KEY' with your actual key.

```bash
grbgetkey YOUR-LICENSE-KEY
```

--------------------------------

### Add q2-micom to QIIME 2 Environment

Source: https://github.com/micom-dev/q2-micom/blob/main/README.md

Installs q2-micom by updating a QIIME 2 environment with a provided YAML file. This is the primary method for installing the plugin.

```bash
wget https://raw.githubusercontent.com/micom-dev/q2-micom/main/q2-micom.yml
conda env update -n qiime2-2024.2 -f q2-micom.yml
# OPTIONAL CLEANUP
rm q2-micom-*.yml
```

--------------------------------

### Install CPLEX Python Package

Source: https://github.com/micom-dev/q2-micom/blob/main/README.md

Installs the CPLEX Python package into an activated QIIME 2 environment. Ensure to substitute the Python version and system folder according to your setup.

```bash
pip install ibm/cplex/python/3.8/x86-64_linux
```

--------------------------------

### Community Model Build Output

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

This is an example of the output you might see after running the `qiime micom build` command. It includes information about database matching, processing time, and model statistics.

```text
Merging with the database using ranks: genus
[16:00:08] WARNING  Less than 50% of the abundance could be matched to the model database. Model `ERR1883294` may not be   community.py:229
                    representative of the sample
Running ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:02:56
Each community model contains 10-42 taxa (average 26+-11).
Community models cover 49.46%-99.91% of the total abundance (average 88.00%+-17.00%).
Saved CommunityModels[Pickle] to: models.qza
```

--------------------------------

### Install Gurobi Solver

Source: https://github.com/micom-dev/q2-micom/blob/main/README.md

Installs the Gurobi solver using conda. This is an optional step for users who require a faster solver.

```bash
conda install -c gurobi gurobi
```

--------------------------------

### Install q2-micom Environment

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Download and update the current Conda environment with the q2-micom environment file. Ensure you replace 'qiime2-2024.2' with your specific Qiime 2 environment name.

```bash
wget https://raw.githubusercontent.com/micom-dev/q2-micom/main/q2-micom-linux.yml
conda env update -n qiime2-2024.2 -f q2-micom-linux.yml
# OPTIONAL CLEANUP
rm q2-micom-*.yml
```

--------------------------------

### Handle Solver Not Available Error

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/errors.md

Demonstrates catching an error when a requested solver (e.g., 'cplex') is not installed. Use `solver='auto'` or install the required solver.

```python
try:
    models = build(
        abundance=abundance,
        taxonomy=taxonomy,
        models=models_db,
        solver="cplex"  # Not installed
    )
except Exception as e:
    print(f"Solver not found: {e}")
```

--------------------------------

### Example Usage of MicomResultsData

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/types.md

Demonstrates how to read simulation results using read_results() and access the growth_rates and exchange_fluxes DataFrames from the returned MicomResultsData object.

```python
from q2_micom import read_results

data = read_results("results.qza")
print(data.growth_rates)
print(data.exchange_fluxes)
```

--------------------------------

### Custom Database and Minimal Medium Workflow

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

This workflow shows how to build community models using a custom database created from SBML files and then find a minimal medium for growth. It includes steps for building the database, constructing community models, identifying the minimal medium, and simulating growth on it.

```python
from q2_micom import db, build, minimal_medium, grow

# 1. Build custom database from SBML files
db_models = db(
    meta=Metadata.load("organisms_metadata.tsv"),
    rank="genus"
)

# 2. Build community models
community_models = build(
    abundance=abundance,
    taxonomy=taxonomy,
    models=db_models
)

# 3. Find minimal medium
min_medium, per_sample, min_results = minimal_medium(
    models=community_models,
    community_growth=0.1,
    growth=0.01
)

# 4. Simulate on minimal medium
results = grow(
    models=community_models,
    medium=min_medium
)

```

--------------------------------

### Quick Analysis Workflow

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

This workflow demonstrates a quick analysis using a prebuilt AGORA database. It covers loading the database, building community models, simulating growth on a standard medium, and visualizing the results.

```python
from q2_micom import build, grow, plot_growth
from qiime2 import Artifact, Metadata

# 1. Load prebuilt AGORA database (downloadable from website)
models_db = Artifact.load("agora_genus.qza")

# 2. Build community models
community_models = build(
    abundance=Artifact.load("abundance.qza"),
    taxonomy=Artifact.load("taxonomy.qza"),
    models=models_db
)

# 3. Simulate on standard medium
results = grow(
    models=community_models,
    medium=standard_medium_dataframe()
)

# 4. Visualize
plot_growth("output", results, metadata=metadata_col)

```

--------------------------------

### Run Tradeoff Analysis and Analyze Results

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/tradeoff.md

Demonstrates how to load models, define a medium, run the tradeoff function with specified parameters, and analyze the resulting growth rates and taxon abundance.

```python
from q2_micom import tradeoff
from qiime2 import Artifact
import pandas as pd
import matplotlib.pyplot as plt

# Load community models and medium
models = Artifact.load("community_models.qza").view(CommunityModelDirectory)
medium = pd.DataFrame({
    'metabolite': ['glucose', 'ammonia', 'phosphate'],
    'reaction': ['EX_glc__D_e', 'EX_nh4_e', 'EX_pi_e'],
    'flux': [10.0, 2.0, 1.0]
})

# Test tradeoff values from 0.1 to 1.0
results = tradeoff(
    models=models,
    medium=medium,
    tradeoff_min=0.1,
    tradeoff_max=1.0,
    step=0.1,
    threads=4
)

# Analyze results
# How many taxa grow at each tradeoff?
taxa_per_tradeoff = results[results['growth_rate'] > 1e-6].groupby('tradeoff').size()
print("Growing taxa per tradeoff:")
print(taxa_per_tradeoff)

# Plot growth rate distribution across tradeoffs
sample1 = results[results['sample_id'] == results['sample_id'].iloc[0]]
for tradeoff_val in sample1['tradeoff'].unique():
    subset = sample1[sample1['tradeoff'] == tradeoff_val]
    growth = subset['growth_rate']
    print(f"Tradeoff {tradeoff_val}: median growth = {growth.median():.4f}, "
          f"growing taxa = {(growth > 1e-6).sum()}/{len(growth)}")

# Identify optimal tradeoff (e.g., largest value allowing most taxa to grow)
growing_by_tradeoff = results[results['growth_rate'] > 1e-6].groupby('tradeoff').size()
optimal_tradeoff = growing_by_tradeoff[growing_by_tradeoff > len(results['taxon'].unique()) * 0.5].index[-1]
print(f"Suggested optimal tradeoff: {optimal_tradeoff}")
```

--------------------------------

### Build Custom q2-micom Database

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Use this command to build a q2-micom database from SBML models and a Qiime 2 metadata file. Specify the metadata file, taxonomic rank, number of threads, and output artifact.

```bash
qiime micom db --m-meta-file agora.tsv \
               --p-rank genus \
               --p-threads 4 \
               --o-metabolic-models agora_genus_103.qza
```

--------------------------------

### Pandas Query Syntax for Filtering

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/configuration.md

Examples of using pandas query syntax for filtering data. These expressions can be used with `filter_models()` and `filter_results()` functions.

```python
age > 30
```

```python
age >= 30
```

```python
age == 30
```

```python
age != 30
```

```python
treatment == 'control'
```

```python
diagnosis.str.contains('disease')
```

```python
subject.isin(['S001', 'S002'])
```

```python
(age > 30) and (treatment == 'case')
```

```python
(age > 30) or (age < 10)
```

```python
not (treatment == 'control')
```

```python
"age > 30"
```

```python
"treatment == 'case' and age > 50"
```

```python
"disease_status.isin(['IBD', 'UC'])"
```

```python
"(location == 'gut') and (age < 18)"
```

--------------------------------

### Create a Medium DataFrame

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/configuration.md

Demonstrates how to create a pandas DataFrame for the 'medium' parameter, specifying metabolite, reaction, and flux.

```python
import pandas as pd

medium = pd.DataFrame({
    'metabolite': ['glucose', 'ammonia', 'phosphate'],
    'reaction': ['EX_glc__D_e', 'EX_nh4_e', 'EX_pi_e'],
    'flux': [10.0, 2.0, 1.0]
})
```

--------------------------------

### Configuration Error: Invalid Solver

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/errors.md

Raised when an unsupported solver is specified in the `build()` function. Use 'auto' for default selection or ensure CPLEX/Gurobi are installed if needed.

```python
try:
    models = build(
        abundance=abundance,
        taxonomy=taxonomy,
        models=models_db,
        solver="cplex2000"  # Invalid solver
    )
except Exception as e:
    print(f"Solver error: {e}")
```

--------------------------------

### High-Level Workflow of q2-micom

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

Illustrates the general data flow from raw data preparation to community model construction, growth simulation, and result analysis.

```text
Raw Data Preparation
    ↓
[Abundance Data] + [Taxonomy] + [Database]
    ↓
Community Model Construction
    ↓
[Community Models] + [Medium]
    ↓
Growth Simulation
    ↓
[Results] → Visualization
         → Statistical Analysis
         → Publication/Sharing
```

--------------------------------

### Plugin Registration Entry Points

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

This snippet shows how the MICOM plugin is registered with QIIME 2 using entry points in setup.cfg. This makes the plugin's methods and visualizers accessible via the QIIME 2 CLI and API.

```ini
[options.entry_points]
qiime2.plugins =
    q2-micom = q2_micom.plugin_setup:plugin

```

--------------------------------

### Refresh QIIME 2 Plugin Cache

Source: https://github.com/micom-dev/q2-micom/blob/main/README.md

Updates the QIIME 2 plugin cache after installing q2-micom in an existing environment. This ensures QIIME 2 recognizes the new plugin.

```bash
conda activate qiime2-2024.2  # or whatever you called your environment
qiime dev refresh-cache
```

--------------------------------

### grow()

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/growth.md

Simulates community metabolic growth on a given medium. It takes community models and medium specifications to predict growth rates and exchange fluxes for each taxon.

```APIDOC
## grow()

### Description
Simulate community metabolic growth on a given medium. This function performs personalized (sample-specific) metabolic simulations on community models, optimizing for a weighted combination of community and individual taxon growth.

### Method
`grow()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

#### Function Parameters
- **models** (CommunityModelDirectory) - Required - Collection of metabolic community models, one per sample.
- **medium** (pd.DataFrame) - Required - Growth medium specification. Must have columns: metabolite, reaction, flux. The flux value specifies the maximum uptake rate from the environment.
- **tradeoff** (float) - Optional - Default: 0.5 - Cooperative tradeoff parameter between 0 and 1. Controls the balance between community-level biomass production and individual taxon growth. Lower values (closer to 0) allow more taxa to grow individually; higher values (closer to 1) maximize total community biomass.
- **threads** (int) - Optional - Default: 1 - Number of parallel threads to use for simulations across samples.
- **strategy** (str) - Optional - Default: "minimal uptake" - Flux selection strategy for choosing optimal solutions. Options: "minimal uptake" (minimizes total nutrient uptake), "pFBA" (parsimonious FBA minimizing enzyme usage), "none" (arbitrary optimal solution).

### Returns
**mw.GrowthResults** — A namedtuple containing:
- **growth_rates** (pd.DataFrame): Taxa-level growth rates for each sample and taxon
- **exchanges** (pd.DataFrame): Metabolic exchange fluxes (imports/exports) for each metabolite, taxon, and sample

### Example
```python
from q2_micom import grow
from qiime2 import Artifact
import pandas as pd

# Load community models
models = Artifact.load("community_models.qza").view(CommunityModelDirectory)

# Define growth medium
medium = pd.DataFrame({
    'metabolite': ['glucose', 'ammonia', 'phosphate'],
    'reaction': ['EX_glc__D_e', 'EX_nh4_e', 'EX_pi_e'],
    'flux': [10.0, 2.0, 1.0]
})

# Simulate growth
results = grow(
    models=models,
    medium=medium,
    tradeoff=0.5,
    threads=4,
    strategy="minimal uptake"
)

# Access results
growth_rates = results.growth_rates
exchange_fluxes = results.exchanges

# Growth rates format: sample_id, taxon, growth_rate, abundance, etc.
print(growth_rates[['sample_id', 'taxon', 'growth_rate']].head())

# Exchange fluxes: sample_id, taxon, metabolite, flux, direction
print(exchange_fluxes[['sample_id', 'taxon', 'reaction', 'flux']].head())
```

### Output Format
**growth_rates DataFrame columns:**
- sample_id: Sample identifier
- taxon: Taxon name/identifier
- reactions: Number of reactions in the taxon model
- metabolites: Number of metabolites in the taxon model
- abundance: Relative abundance of the taxon in the sample
- tradeoff: The tradeoff value used (always matches input parameter)
- growth_rate: Predicted growth rate (g biomass/g dry weight/h or equivalent)

**exchanges (exchange_fluxes) DataFrame columns:**
- sample_id: Sample identifier
- taxon: Taxon name/identifier (or "medium" for community-level exchanges)
- reaction: Exchange reaction ID (e.g., "EX_glc__D_e")
- metabolite: Metabolite name or ID
- flux: Exchange flux value (mmol/g dry weight/h)
```

--------------------------------

### Load and Build Community Models

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/core.md

Loads abundance and taxonomy data to build community models. Ensure 'abundance.qza' and 'taxonomy.qza' are available, and 'models_db' is defined.

```python
abundance = Artifact.load("abundance.qza")
taxonomy = Artifact.load("taxonomy.qza")
community_models = build(
    abundance=abundance.view(biom.Table),
    taxonomy=taxonomy.view(pd.Series),
    models=models_db,
    threads=4
)
```

--------------------------------

### Comparative Analysis Workflow

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

This workflow outlines how to perform comparative analyses on microbial community simulation results. It includes building and simulating models, filtering results based on metadata, and testing for associations between variables and metabolic fluxes.

```python
from q2_micom import build, grow, filter_results, association

# Build and simulate for all samples
results = grow(models=community_models, medium=medium)

# Filter results by metadata
disease_results = filter_results(results, metadata, query="disease == 'IBD'")
control_results = filter_results(results, metadata, query="disease == 'control'")

# Test associations
association(
    output_dir="./metabolite_associations",
    results=results,
    metadata=metadata.get_column("disease"),
    variable_type="binary",
    flux_type="production"
)

```

--------------------------------

### Handle Optimization Failure During Growth Simulation

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/errors.md

Illustrates how to catch optimization failures during the `grow()` function and provides strategies for recovery, such as relaxing constraints or using a different optimization strategy.

```python
try:
    results = grow(
        models=models,
        medium=medium,
        tradeoff=0.5,
        threads=4
    )
except Exception as e:
    print(f"Optimization failed: {e}")
    
    # Try with different parameters
    # Option 1: Relax constraints
    results = grow(
        models=models,
        medium=medium,
        tradeoff=0.1  # Less strict community constraint
    )
    
    # Option 2: Use different strategy
    results = grow(
        models=models,
        medium=medium,
        strategy="none"  # Skip flux optimization
    )
```

--------------------------------

### Run MICOM Tradeoff Simulation

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

This command simulates microbial community growth with various tradeoff values to find an optimal balance between community and individual taxon growth rates. It requires input models and a medium, and outputs the tradeoff results.

```bash
qiime micom tradeoff --i-models models.qza \
                     --i-medium western_diet_gut_agora.qza \
                     --p-threads 4 \
                     --o-results tradeoff.qza \
                     --verbose
```

--------------------------------

### Build Community Models

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Use this command to build community metabolic models. Specify input abundance and taxonomy tables, a model database, cutoff, threads, and output file. The --verbose flag shows progress.

```bash
qiime micom build --i-abundance cdi_table.qza \
                  --i-taxonomy cdi_taxa.qza \
                  --i-models agora103_refseq216_genus_1.qza \
                  --p-cutoff 0.0001 \
                  --p-threads 4 \
                  --o-community-models models.qza \
                  --verbose
```

--------------------------------

### Generate Niche Visualization

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Use this command to generate a visualization of taxa growth niches based on metabolite exchange data. This helps in understanding the metabolic behavior shifts of taxa across different samples.

```bash
qiime micom exchanges-per-taxon --i-results growth.qza \
                                --o-visualization niche.qzv
```

--------------------------------

### Create Community Models Function

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/INDEX.md

The `build()` function constructs community models from abundance, taxonomy, and existing models. The output is in Pickle format.

```python
build()
```

--------------------------------

### Explore Parameters Function

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/INDEX.md

The `tradeoff()` function explores parameter effects on community models given a medium, returning tradeoff analysis results.

```python
tradeoff()
```

--------------------------------

### Run MICOM Growth Simulation

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Execute a growth simulation using MICOM. This command requires input models, a medium file, and specifies tradeoff and thread parameters. The output is saved as a results file.

```bash
qiime micom grow --i-models models.qza \
                 --i-medium western_diet_gut_agora.qza \
                 --p-tradeoff 0.5 \
                 --p-threads 4 \
                 --o-results growth.qza \
                 --verbose
```

--------------------------------

### Visualize MICOM Growth Rates

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Plots the growth rates of individual taxa across different samples. This visualization helps in observing the heterogeneity of growth rates within the microbial community.

```bash
qiime micom plot-growth --i-results growth.qza \
                        --o-visualization growth_rates.qzv
```

--------------------------------

### Growth Simulation Phase Data Flow

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

Explains the process of simulating taxon growth rates and metabolic exchange fluxes using community models and medium specifications via the MICOM algorithm.

```text
Community Models
     ↓
     → Optimize via MICOM algorithm
Medium                    balancing community and individual growth
     ↓                    via tradeoff parameter
   grow() function
     ↓
MicomResults (growth rates + exchange fluxes)
```

--------------------------------

### Exchanges Per Sample Visualization

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/INDEX.md

The `exchanges_per_sample()` function visualizes sample-level fluxes from simulation results, outputting an HTML file.

```python
exchanges_per_sample()
```

--------------------------------

### File Organization Structure

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/INDEX.md

This snippet shows the directory structure for MiCoM documentation files.

```bash
output/
├── INDEX.md                          ← You are here
├── OVERVIEW.md                       ← Start here for big picture
├── types.md                          ← Data structure definitions
├── configuration.md                  ← Parameter reference
├── errors.md                         ← Troubleshooting guide
└── api-reference/                    ← Detailed function docs
    ├── core.md
    ├── db.md
    ├── build.md
    ├── medium.md
    ├── growth.md
    ├── tradeoff.md
    ├── filter.md
    └── viz.md
```

--------------------------------

### Create Database Function

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/INDEX.md

The `db()` function is used to create a database from metadata and SBML files. It outputs metabolic models in JSON format.

```python
db()
```

--------------------------------

### Create Metabolic Model Database

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/db.md

Builds a reusable pan-genome model database from individual SBML metabolic models specified in a metadata file. Collapses reactions and metabolites across organisms at a chosen phylogenetic rank and exports unified models in JSON format. Ensure the metadata file contains 'file' and all classification columns up to 'species'.

```python
from q2_micom import db
from qiime2 import Artifact, Metadata

# Create metadata table with model information
# Expected format:
# file,kingdom,phylum,class,order,family,genus,species
# /path/to/model1.xml,Bacteria,Bacteroidota,Bacteroidia,Bacteroidales,Bacteroidaceae,Bacteroides,fragilis
# /path/to/model2.xml,Bacteria,Firmicutes,Clostridia,Clostridiales,Lachnospiraceae,Faecalibacterium,prausnitzii

metadata = Metadata.load("model_metadata.tsv")

# Build database at genus level
metabolic_db = db(
    meta=metadata,
    rank="genus",
    threads=4
)

# Save output
db_artifact = Artifact.from_view(
    "MetabolicModels[JSON]",
    metabolic_db,
    view_type="JSONDirectory"
)
db_artifact.save("metabolic_database.qza")
```

--------------------------------

### q2-micom Module Organization

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

Shows the directory structure and main Python files within the q2-micom plugin package.

```text
q2_micom/
  ├── __init__.py              # Package exports, version, read_results()
  ├── plugin_setup.py          # QIIME 2 plugin registration
  ├── _formats_and_types.py    # Custom types and formats
  ├── _build.py                # Community model construction
  ├── _db.py                   # Database building
  ├── _medium.py               # Minimal medium calculation
  ├── _growth.py               # Growth simulation
  ├── _tradeoff.py             # Tradeoff parameter analysis
  ├── _filter.py               # Sample filtering
  ├── _viz.py                  # Visualization functions
  ├── _transform.py            # Type transformers
  └── tests/                   # Test suite
```

--------------------------------

### Simulate Growth Function

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/INDEX.md

The `grow()` function simulates the growth of community models given a specific medium, producing simulation results.

```python
grow()
```

--------------------------------

### Handle Missing Required Metadata Columns for DB Creation

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/errors.md

Shows how to catch and handle errors when the metadata is missing required fields (e.g., 'genus', 'species') for the db() function. Verify metadata columns and ensure all required fields are present.

```python
metadata = Metadata.load("incomplete_meta.tsv")
# Missing 'genus' and 'species' columns

try:
    db_models = db(meta=metadata, rank="genus")
except Exception as e:
    print(f"Metadata error: {e}")
```

--------------------------------

### Step-by-Step MICOM Debugging Workflow

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/errors.md

This comprehensive script outlines a step-by-step validation process for MICOM analysis, from loading inputs to visualizing results. It includes error handling to pinpoint issues at each stage.

```python
from q2_micom import build, grow, plot_growth
from qiime2 import Artifact, Metadata
import pandas as pd
import traceback

try:
    # Step 1: Load and validate inputs
    abundance = Artifact.load("abundance.qza").view(biom.Table)
    taxonomy = Artifact.load("taxonomy.qza").view(pd.Series)
    models = Artifact.load("models.qza").view(JSONDirectory)
    metadata = Metadata.load("metadata.tsv")
    
    print("✓ Inputs loaded successfully")
    
    # Step 2: Build models
    community_models = build(
        abundance=abundance,
        taxonomy=taxonomy,
        models=models,
        threads=4
    )
    print("✓ Community models built")
    
    # Step 3: Create medium
    medium = pd.DataFrame({...}) # Placeholder for actual medium creation
    print(f"✓ Medium created with {len(medium)} components")
    
    # Step 4: Simulate growth
    results = grow(
        models=community_models,
        medium=medium,
        threads=4
    )
    print(f"✓ Growth simulation complete ({len(results.growth_rates)} observations)")
    
    # Step 5: Visualize
    plot_growth(
        output_dir="./output",
        results=results
    )
    print("✓ Visualization complete")
    
except Exception as e:
    print(f"\n✗ Error occurred:")
    print(f"  Type: {type(e).__name__}")
    print(f"  Message: {e}")
    traceback.print_exc()
```

--------------------------------

### Tradeoff Optimization Workflow

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

This workflow focuses on optimizing tradeoff values for microbial community simulations. It involves building models, testing a range of tradeoff values using the `tradeoff` function, visualizing the results to identify an optimal value, and then running a final simulation with that optimal tradeoff.

```python
from q2_micom import build, tradeoff, plot_tradeoff

# Build models (from workflow 1 or 2)
community_models = build(...)

# Test tradeoff values
tradeoff_results = tradeoff(
    models=community_models,
    medium=medium,
    tradeoff_min=0.1,
    tradeoff_max=1.0,
    step=0.1
)

# Visualize to find optimal value
plot_tradeoff("output", tradeoff_results)

# Use optimal value in final simulation
optimal_tradeoff = 0.5  # Based on visualization
results = grow(
    models=community_models,
    medium=medium,
    tradeoff=optimal_tradeoff
)

```

--------------------------------

### Community Model Building Phase Data Flow

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

Outlines the steps for constructing sample-specific community metabolic models using abundance data, taxonomy, and a model database.

```text
Feature Table (Abundance)
     ↓
     → Match to database at specified rank
Taxonomy                  using strict/non-strict matching
     ↓
Abundance Cutoff → Filter low-abundance taxa
     ↓
    build() function
     ↓
CommunityModels[Pickle] (one model per sample)
```

--------------------------------

### Filter Community Models

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Create a q2-micom artifact containing a subset of samples from existing community models. Use a metadata file and a query to select samples, or use `--p-exclude` to select all samples except those matching the query.

```bash
qiime micom filter-models --i-models models.qza \
                          --m-metadata-file metadata.tsv \
                          --p-query "disease_state == 'healthy'" \
                          --o-filtered-models cancer_built_models.qza
```

--------------------------------

### Define CommunityModelDirectory Format

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/types.md

Defines a directory format containing pickled community models and a manifest. The manifest.csv has a sample_id column, and *.pickle files are pickled community models, one per sample. The sample_id column matches the pickle filename.

```python
class CommunityModelDirectory(model.DirectoryFormat)
```

--------------------------------

### Define SBMLDirectory Format

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/types.md

Defines a directory format containing SBML models and a manifest. The manifest.csv file contains model metadata with required fields, and *.xml files are individual SBML model files. Required manifest columns include file and taxonomic information.

```python
class SBMLDirectory(model.DirectoryFormat)
```

--------------------------------

### Simulate Community Growth

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/core.md

Simulates the growth of a microbial community given a specific medium and tradeoff parameter. Uses the community models and the determined global medium.

```python
growth_results = grow(
    models=community_models,
    medium=medium_global,
    tradeoff=0.5,
    threads=4
)
```

--------------------------------

### Build Community Models with build()

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/build.md

Constructs sample-specific metabolic community models using abundance, taxonomy, and a model database. Filters taxa below a specified abundance cutoff and allows for parallel processing. Use this function to generate personalized metabolic models for each sample in your dataset.

```python
from q2_micom import build
from qiime2 import Artifact

# Load input data
abundance = Artifact.load("abundance.qza").view(biom.Table)
taxonomy = Artifact.load("taxonomy.qza").view(pd.Series)
models = Artifact.load("models.qza").view(JSONDirectory)

# Build community models
community_models = build(
    abundance=abundance,
    taxonomy=taxonomy,
    models=models,
    threads=4,
    cutoff=0.0001,
    strict=False,
    solver="auto"
)

# Save output
community_artifact = Artifact.from_view(
    "CommunityModels[Pickle]",
    community_models,
    view_type="CommunityModelDirectory"
)
community_artifact.save("community_models.qza")
```

--------------------------------

### Activate QIIME 2 Environment

Source: https://github.com/micom-dev/q2-micom/blob/main/README.md

Activates the specified QIIME 2 environment. This command should be run after updating the environment with q2-micom.

```bash
conda activate qiime2-2024.2
```

--------------------------------

### Visualize Growth Simulation Results

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/core.md

Generates plots for growth simulation results, saving them to a specified output directory. Requires growth results and sample metadata.

```python
plot_growth(
    output_dir="./growth_plots",
    results=growth_results,
    metadata=Metadata.load("samples.tsv").get_column("treatment")
)
```

--------------------------------

### Filter Simulation Results

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Create a q2-micom artifact containing a subset of simulation results. Similar to filtering models, use a metadata file and a query to select results, or use `--p-exclude`.

```bash
qiime micom filter-results --i-results growth.qza \
                            --m-metadata-file metadata.tsv \
                            --p-query "disease_state == 'healthy'" \
                            --o-filtered-results cancer_results.qza
```

--------------------------------

### Plot Growth Visualization

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/INDEX.md

The `plot_growth()` function visualizes taxa growth rates from simulation results, outputting an HTML file.

```python
plot_growth()
```

--------------------------------

### Estimate Minimal Medium

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Use this command to predict a minimal medium for a microbial community. Specify community and individual taxon growth rates, optimization preferences (e.g., minimize mass uptake), and output file paths. The `--verbose` flag provides detailed output.

```bash
qiime micom minimal-medium --i-models models.qza \
                           --p-community-growth 0.1 \
                           --p-growth 0.01 \
                           --p-weights mass \
                           --p-threads 2 \
                           --o-medium minimal_medium.qza \
                           --o-sample-media sample_minimal_media.qza \
                           --o-results media_results.qza \
                           --verbose
```

--------------------------------

### Growth Rate Thresholds for Taxa

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/configuration.md

Illustrates common thresholds for determining taxon growth status based on growth rate.

```python
# Effectively zero growth
growth_rate < 1e-6

# Minimal growth (numerical noise)
1e-6 < growth_rate < 0.001

# Clear growth
growth_rate > 0.001
```

--------------------------------

### Define MicomResultsDirectory Format

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/types.md

Defines a directory format containing simulation results. It includes growth_rates.csv, exchange_fluxes.csv, and annotations.csv files.

```python
class MicomResultsDirectory(model.DirectoryFormat)
```

--------------------------------

### Simulate Community Metabolic Growth

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/growth.md

Simulates community metabolic growth on a given medium. Use this function to predict growth rates and exchange fluxes for each taxon within a community under specific environmental conditions. The tradeoff parameter balances community biomass production with individual taxon growth, while the strategy parameter influences flux selection.

```python
from q2_micom import grow
from qiime2 import Artifact
import pandas as pd

# Load community models
models = Artifact.load("community_models.qza").view(CommunityModelDirectory)

# Define growth medium
medium = pd.DataFrame({
    'metabolite': ['glucose', 'ammonia', 'phosphate'],
    'reaction': ['EX_glc__D_e', 'EX_nh4_e', 'EX_pi_e'],
    'flux': [10.0, 2.0, 1.0]
})

# Simulate growth
results = grow(
    models=models,
    medium=medium,
    tradeoff=0.5,
    threads=4,
    strategy="minimal uptake"
)

# Access results
growth_rates = results.growth_rates
exchange_fluxes = results.exchanges

# Growth rates format: sample_id, taxon, growth_rate, abundance, etc.
print(growth_rates[['sample_id', 'taxon', 'growth_rate']].head())

# Exchange fluxes: sample_id, taxon, metabolite, flux, direction
print(exchange_fluxes[['sample_id', 'taxon', 'reaction', 'flux']].head())
```

--------------------------------

### db()

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/db.md

Creates a metabolic model database from a collection of individual organism models. This function reads individual metabolic models, collapses reactions and metabolites across organisms at a specified phylogenetic rank, creates unified pan-genome models, and exports them in JSON format.

```APIDOC
## db()

### Description
Create a metabolic model database from a collection of individual organism models.

### Method
Python Function

### Signature
db(meta: Metadata, rank: str = "genus", threads: int = 1) -> JSONDirectory

### Parameters
#### Positional Parameters
- **meta** (Metadata) - Required - Metadata table describing the individual metabolic models. Must contain the following columns: file, kingdom, phylum, class, order, family, genus, species.
- **rank** (str) - Optional - The phylogenetic rank at which to summarize taxa. Must be one of: kingdom, phylum, class, order, family, genus, species, strain. Defaults to "genus".
- **threads** (int) - Optional - Number of parallel threads to use when constructing the database. Defaults to 1.

### Returns
**JSONDirectory** — A metabolic model database in JSON format containing pan-genome models summarized to the specified phylogenetic rank.

### Example
```python
from q2_micom import db
from qiime2 import Artifact, Metadata

metadata = Metadata.load("model_metadata.tsv")

metabolic_db = db(
    meta=metadata,
    rank="genus",
    threads=4
)

db_artifact = Artifact.from_view(
    "MetabolicModels[JSON]",
    metabolic_db,
    view_type="JSONDirectory"
)
db_artifact.save("metabolic_database.qza")
```
```

--------------------------------

### Database Construction Phase Data Flow

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

Details the process of building a metabolic model database from individual SBML models, merging them at a specified phylogenetic rank.

```text
Individual SBML Models
        ↓
    db() function
        ↓
Merge at phylogenetic rank → MetabolicModels[JSON]
```

--------------------------------

### Inspect Minimal Medium with Qiime 2 API

Source: https://github.com/micom-dev/q2-micom/blob/main/docs/README.md

Load the generated minimal medium artifact and view it as a pandas DataFrame. This allows for inspection and sorting of metabolites by flux to identify key components.

```python
In [1]: from qiime2 import Artifact

In [2]: import pandas as pd

In [3]: medium = Artifact.load("minimal_medium.qza").view(pd.DataFrame)

In [4]: medium.sort_values(by="flux", ascending=False).head()
Out[4]:
       reaction      flux metabolite
2   EX_MGlcn9_m  0.108333   MGlcn9_m
19      EX_pi_m  0.088816       pi_m
12    EX_hspg_m  0.001911     hspg_m
10  EX_glygn2_m  0.001554   glygn2_m
9      EX_fe3_m  0.001250      fe3_m

In [5]: medium.shape
Out[5]: (27, 3)
```

--------------------------------

### Build Community Models at Species Rank with Genus-Level DB

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/errors.md

Demonstrates an error when attempting to build community models at a species rank using a database that was built at the genus rank. Ensure ranks match between the database and community model construction.

```python
# Database built at genus level
models_db = db(meta=metadata, rank="genus")

# But trying to build at species level
community_models = build(
    abundance=abundance,
    taxonomy=taxonomy,
    models=models_db,  # genus-level DB
    # strict=False finds matches only at genus rank
)
```

--------------------------------

### Custom Visualization: Growing Taxa and Average Growth Rate

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/OVERVIEW.md

Generate custom plots showing the number of growing taxa per sample and the average growth rate per sample. Requires matplotlib.

```python
from q2_micom import read_results
import matplotlib.pyplot as plt

data = read_results("results.qza")
growth_rates = data.growth_rates

# Custom analysis
fig, axes = plt.subplots(1, 2, figsize=(12, 5))

# Plot 1: Richness per sample
growth_rates[growth_rates['growth_rate'] > 1e-6].groupby('sample_id')['taxon'].nunique().plot(ax=axes[0])
axes[0].set_title("Growing Taxa per Sample")

# Plot 2: Average growth
growth_rates[growth_rates['growth_rate'] > 1e-6].groupby('sample_id')['growth_rate'].mean().plot(ax=axes[1])
axes[1].set_title("Average Growth Rate")

plt.tight_layout()
plt.savefig("custom_analysis.png")
```

--------------------------------

### Find Minimal Medium for Community

Source: https://github.com/micom-dev/q2-micom/blob/main/_autodocs/api-reference/core.md

Determines the minimal medium required for a microbial community to achieve a specified growth rate. Requires pre-built community models.

```python
medium_global, media_per_sample, min_results = minimal_medium(
    models=community_models,
    community_growth=0.1,
    growth=0.01,
    threads=4
)
```