Mercurial > repos > bimib > cobraxy
changeset 492:4ed95023af20 draft
Uploaded
line wrap: on
line diff
--- a/COBRAxy/README.md Mon Sep 29 15:34:59 2025 +0000 +++ b/COBRAxy/README.md Tue Sep 30 14:02:17 2025 +0000 @@ -1,289 +1,313 @@ -<p align="center"> - <img src="https://opencobra.github.io/cobrapy/_static/img/cobrapy_logo.png" alt="COBRApy logo" width="120"/> -</p> - -# COBRAxy — Metabolic analysis and visualization toolkit (Galaxy-ready) - -COBRAxy (COBRApy in Galaxy) is a toolkit to compute, analyze, and visualize metabolism at the reaction level from transcriptomics and metabolomics data. It enables users to: +<div align="center"> + <img src="docs/_media/logo.png" alt="COBRAxy Logo" width="200"/> +</div> -- derive Reaction Activity Scores (RAS) from gene expression and Reaction Propensity Scores (RPS) from metabolite abundances, -- integrate RAS into model bounds, -- perform flux sampling with either CBS (constraint-based sampling) or OPTGP, -- compute statistics (pFBA, FVA, sensitivity) and generate styled SVG/PDF metabolic maps, -- run all tools as Galaxy wrappers or via CLI on any machine. - -It extends the MaREA 2 (Metabolic Reaction Enrichment Analysis) concept by adding sampling-based flux comparison and rich visualization. The repository ships both Python CLIs and Galaxy tool XMLs. - -## Table of contents +# COBRAxy -- Overview and features -- Requirements -- Installation (pip/conda) -- Quick start (CLI) -- Tools and usage - - custom_data_generator - - ras_generator (RAS) - - rps_generator (RPS) - - ras_to_bounds - - flux_simulation (CBS/OPTGP) - - marea (enrichment + maps) - - flux_to_map (maps from fluxes) - - marea_cluster (clustering auxiliaries) -- Typical workflow -- Input/output formats -- Galaxy usage -- Troubleshooting -- Contributing -- License and citations -- Useful links +A Python toolkit for metabolic flux analysis and visualization, with Galaxy integration. + +COBRAxy transforms gene expression and metabolite data into meaningful metabolic insights through flux sampling and interactive pathway maps. +DOC: https://compbtbs.github.io/COBRAxy +## Features -## Overview and features - -COBRAxy builds on COBRApy to deliver end‑to‑end analysis from expression/metabolite data to flux statistics and map rendering: - -- RAS and RPS computation from tabular inputs -- Bounds integration and model preparation -- Flux sampling: CBS (GLPK backend) with automatic fallback to a COBRApy interface, or OPTGP -- Flux statistics: mean/median/quantiles, pFBA, FVA, sensitivity -- Map styling/export: SVG with optional PDF/PNG export -- Ready-made Galaxy wrappers for all tools - -Bundled resources in `local/` include example models (ENGRO2, Recon), gene mappings, a default medium, and SVG maps. - -## Requirements +- **Reaction Activity Scores (RAS)** from gene expression data +- **Reaction Propensity Scores (RPS)** from metabolite abundance +- **Flux sampling** with CBS or OptGP algorithms +- **Statistical analysis** with pFBA, FVA, and sensitivity analysis +- **Interactive maps** with SVG/PDF export and custom styling +- **Galaxy tools** for web-based analysis +- **Built-in models** including ENGRO2 and Recon -- OS: Linux, macOS, or Windows (Linux recommended; Galaxy typically runs on Linux) -- Python: 3.8.20 ≤ version < 3.12 (as per `setup.py`) -- Python packages (installed automatically by `pip install .`): - - cobra==0.29.0, numpy==1.24.4, pandas==2.0.3, scipy==1.11, scikit-learn==1.3.2, seaborn==0.13.0 - - matplotlib==3.7.3, lxml==5.2.2, cairosvg==2.7.1, svglib==1.5.1, pyvips==2.2.3, Pillow - - joblib==1.4.2, anndata==0.8.0, pydeseq2==0.5.1 -- Optional but recommended for CBS sampling performance: - - GLPK solver and Python bindings - - System library: glpk (e.g., Ubuntu: `apt-get install glpk-utils libglpk40`) - - Python: `swiglpk` (note: CBS falls back to a COBRApy interface if GLPK is unavailable) -- For pyvips: system libvips (e.g., Ubuntu: `apt-get install libvips`) +## Quick Start -Notes: -- If you hit system-level library errors for SVG/PDF/PNG conversion or vips, install the corresponding OS packages. -- GPU is not required. - -## Installation - -Python virtual environment is strongly recommended. - -### Install from source (pip) - -1) Clone the repo and install: +### Installation ```bash git clone https://github.com/CompBtBs/COBRAxy.git cd COBRAxy -python3 -m venv .venv && source .venv/bin/activate -pip install --upgrade pip pip install . ``` -This installs console entry points: `custom_data_generator`, `ras_generator`, `rps_generator`, `ras_to_bounds`, `flux_simulation`, `flux_to_map`, `marea`, `marea_cluster`. - -### Install with conda (alternative) - -```bash -conda create -n cobraxy python=3.10 -y -conda activate cobraxy -pip install . -# Optional system deps (Ubuntu): sudo apt-get install libvips libxml2 libxslt1.1 glpk-utils -# Optional Python bindings for GLPK: pip install swiglpk -``` - -## Quick start (CLI) - -All tools provide `-h/--help` for details. Outputs are TSV/CSV and SVG/PDF files depending on the tool and flags. - -Example minimal flow (using built-in ENGRO2 model and provided assets): +### Basic Workflow ```bash -# 1) Generate rules/reactions/bounds/medium from a model (optional if using bundled ones) -custom_data_generator \ - -id local/models/ENGRO2.xml \ - -mn ENGRO2.xml \ - -orules out/ENGRO2_rules.tsv \ - -orxns out/ENGRO2_reactions.tsv \ - -omedium out/ENGRO2_medium.tsv \ - -obnds out/ENGRO2_bounds.tsv +# 1. Generate RAS from expression data +ras_generator -td $(pwd) -in expression.tsv -ra ras_output.tsv -rs ENGRO2 + +# 2. Generate RPS from metabolite data (optional) +rps_generator -td $(pwd) -id metabolites.tsv -rp rps_output.tsv + +# 3. Create enriched pathway maps with statistical analysis +marea -td $(pwd) -using_RAS true -input_data ras_output.tsv -choice_map ENGRO2 -gs true -idop base_maps + +# 4. Apply RAS constraints to model for flux simulation +ras_to_bounds -td $(pwd) -ms ENGRO2 -ir ras_output.tsv -rs true -idop bounds_output + +# 5. Sample metabolic fluxes with constrained model +flux_simulation -td $(pwd) -ms ENGRO2 -in bounds_output/*.tsv -a CBS -ns 1000 -idop flux_results + +# 6. Add flux data to enriched maps +flux_to_map -td $(pwd) -if flux_results/*.tsv -mp base_maps/*.svg -idop final_maps +``` + +## Tools -# 2) Compute RAS from expression data -ras_generator \ - -td $(pwd) \ - -in my_expression.tsv \ - -ra out/ras.tsv \ - -rs ENGRO2 +| Tool | Purpose | Input | Output | +|------|---------|--------|---------| +| `metabolic_model_setting` | Extract model components | SBML model | Rules, reactions, bounds, medium | +| `ras_generator` | Compute reaction activity scores | Gene expression data | RAS values | +| `rps_generator` | Compute reaction propensity scores | Metabolite abundance | RPS values | +| `marea` | Statistical pathway analysis | RAS + RPS data | Enrichment + base maps | +| `ras_to_bounds` | Apply RAS constraints to model | RAS + SBML model | Constrained bounds | +| `flux_simulation` | Sample metabolic fluxes | Constrained model | Flux distributions | +| `flux_to_map` | Add fluxes to enriched maps | Flux samples + base maps | Final styled maps | +| `marea_cluster` | Cluster analysis | Expression/flux data | Sample clusters | + +## Requirements + +- **Python**: 3.8-3.11 +- **OS**: Linux, macOS, Windows (Linux recommended) +- **Dependencies**: Automatically installed via pip (COBRApy, pandas, numpy, etc.) + +**Optional system libraries** (for enhanced features): +```bash +# Ubuntu/Debian +sudo apt-get install libvips libglpk40 glpk-utils + +# For Python GLPK bindings +pip install swiglpk +``` + +## Data Flow -# 3) Integrate RAS into bounds -ras_to_bounds \ - -td $(pwd) \ - -ms ENGRO2 \ - -ir out/ras.tsv \ - -rs true \ - -idop out/ras_bounds +``` +Gene Expression Metabolite Data SBML Model + ↓ ↓ ↓ + RAS Generator RPS Generator Model Tables + ↓ ↓ + RAS Values RPS Values + | ↓ ↓ + | └─────────┬─────────┘ + | ↓ + | MAREA + | (Enrichment + + | Base Maps) + ↓ + RAS Values → RAS to Bounds ←── Model Tables + ↓ + Constrained Model + ↓ + Flux Simulation + ↓ + Flux Samples + ↓ + Flux to Map ←── Maps (ENGRO2) + ↓ + Final Enriched Maps +``` + +## Built-in Models & Data -# 4) Flux sampling (CBS) -flux_simulation \ - -td $(pwd) \ - -ms ENGRO2 \ - -in out/ras_bounds/sample1.tsv,out/ras_bounds/sample2.tsv \ - -ni sample1,sample2 \ - -a CBS -ns 500 -sd 0 -nb 1 \ - -ot mean,median,quantiles \ - -ota pFBA,FVA,sensitivity \ - -idop out/flux +COBRAxy includes ready-to-use resources: + +- **Models**: ENGRO2, Recon (human metabolism) +- **Gene mappings**: HGNC, Ensembl, Entrez ID conversions +- **Pathway maps**: Pre-styled SVG templates +- **Medium compositions**: Standard growth conditions + +Located in `local/` directory for immediate use. + +## Command Line Usage + +All tools support `--help` for detailed options. Key commands: -# 5) Enrichment + map styling (RAS/RPS or fluxes) -marea \ - -td $(pwd) \ - -using_RAS true -input_data out/ras.tsv \ - -comparison manyvsmany -test ks \ - -generate_svg true -generate_pdf true \ - -choice_map ENGRO2 -idop out/maps +### Generate RAS/RPS scores +```bash +# From gene expression +ras_generator -td $(pwd) -in expression.tsv -ra ras_output.tsv -rs ENGRO2 + +# From metabolite data +rps_generator -td $(pwd) -id metabolites.tsv -rp rps_output.tsv +``` + +### Flux sampling +```bash +flux_simulation -td $(pwd) -ms ENGRO2 -in bounds/*.tsv -a CBS -ns 1000 -idop results/ +``` + +### Statistical analysis & visualization +```bash +marea -td $(pwd) -using_RAS true -input_data ras.tsv -choice_map ENGRO2 -gs true -idop maps/ ``` -## Tools and usage +## Galaxy Integration -Below is a high‑level summary of each CLI. Use `--help` for the full list of options. - -### 1) custom_data_generator +COBRAxy provides Galaxy tool wrappers (`.xml` files) for web-based analysis: -Generate model‑derived assets. +- Upload data through Galaxy interface +- Chain tools in visual workflows +- Share and reproduce analyses +- Access via Galaxy ToolShed -Required inputs: -- `-id/--input`: model file (XML or JSON; gz/zip/bz2 also supported via extension) -- `-mn/--name`: the original file name including extension (Galaxy renames files; this preserves the true format) -- `-orules`, `-orxns`, `-omedium`, `-obnds`: output paths +## Tutorials -Outputs: -- TSV with rules, reactions, exchange medium, and bounds. +### Local Galaxy Installation -### 2) ras_generator (Reaction Activity Scores) - -Compute RAS from a gene expression table. +To set up a local Galaxy instance with COBRAxy tools: -Key inputs: -- `-td/--tool_dir`: repository root path (used to locate `local/` assets) -- `-in/--input`: expression TSV (rows: genes; columns: samples) -- `-rs/--rules_selector`: model/rules choice, e.g. `ENGRO2` or `Custom` with `-rl` and `-rn` -- Optional: `-rl/--rule_list` custom rules TSV, `-rn/--rules_name` its original name/extension -- Output: `-ra/--ras_output` TSV +1. **Install Galaxy**: + ```bash + # Clone Galaxy repository + git clone -b release_23.1 https://github.com/galaxyproject/galaxy.git + cd galaxy + + # Install dependencies and start Galaxy + sh run.sh + ``` -### 3) rps_generator (Reaction Propensity Scores) - -Compute RPS from a metabolite abundance table. - -Key inputs: -- `-td/--tool_dir`: repository root -- `-id/--input`: metabolite TSV (rows: metabolites; columns: samples) -- `-rc/--reaction_choice`: `default` or `custom` with `-cm/--custom` reactions TSV -- Output: `-rp/--rps_output` TSV - -### 4) ras_to_bounds - -Integrate RAS into reaction bounds for a given model and medium. +2. **Install COBRAxy tools**: + ```bash + # Add COBRAxy tools to Galaxy + mkdir -p tools/cobraxy + cp path/to/COBRAxy/Galaxy_tools/*.xml tools/cobraxy/ + + # Update tool_conf.xml to include COBRAxy tools + # Add section in config/tool_conf.xml: + # <section id="cobraxy" name="COBRAxy"> + # <tool file="cobraxy/ras_generator.xml" /> + # <tool file="cobraxy/rps_generator.xml" /> + # <tool file="cobraxy/marea.xml" /> + # <!-- Add other tools --> + # </section> + ``` -Key inputs: -- `-td/--tool_dir`: repository root -- `-ms/--model_selector`: one of `ENGRO2` or `Custom` with `-mo/--model` and `-mn/--model_name` -- Medium: `-mes/--medium_selector` (default `allOpen`) or `-meo/--medium` custom TSV -- RAS: `-ir/--input_ras` and `-rs/--ras_selector` (true/false) -- Output folder: `-idop/--output_path` +3. **Galaxy Tutorial Resources**: + - [Galaxy Installation Guide](https://docs.galaxyproject.org/en/master/admin/) + - [Tool Development Tutorial](https://training.galaxyproject.org/training-material/topics/dev/) + - [Galaxy Admin Training](https://training.galaxyproject.org/training-material/topics/admin/) + +### Python Direct Usage -Outputs: -- One bounds TSV per sample in the RAS table. +For programmatic use of COBRAxy tools in Python scripts: -### 5) flux_simulation - -Flux sampling with CBS or OPTGP and downstream statistics. +1. **Installation for Development**: + ```bash + # Clone and install in development mode + git clone https://github.com/CompBtBs/COBRAxy.git + cd COBRAxy + pip install -e . + ``` -Key inputs: -- `-td/--tool_dir` -- Model: `-ms/--model_selector` (ENGRO2 or Custom with `-mo`/`-mn`) -- Bounds files: `-in` (comma‑separated list) and `-ni/--names` (comma‑separated sample names) -- Algorithm: `-a CBS|OPTGP`; CBS uses GLPK if available and falls back to a COBRApy interface -- Sampling params: `-ns/--n_samples`, `-th/--thinning` (OPTGP), `-nb/--n_batches`, `-sd/--seed` -- Outputs: `-ot/--output_type` (mean,median,quantiles) and `-ota/--output_type_analysis` (pFBA,FVA,sensitivity) -- Output path: `-idop/--output_path` - -Outputs: -- Per‑sample or aggregated CSV/TSV with flux samples and statistics. - -### 6) marea - -Statistical enrichment and map styling for RAS and/or RPS groups with optional DESeq2‑style testing via `pydeseq2`. - -Key inputs: -- `-td/--tool_dir` -- Comparison: `-co manyvsmany|onevsrest|onevsmany` -- Test: `-te ks|ttest_p|ttest_ind|wilcoxon|mw|DESeq` -- Thresholds: `-pv`, `-adj` (FDR), `-fc` -- Data: RAS `-using_RAS` plus `-input_data` or multiple datasets with names; similarly for RPS with `-using_RPS` -- Map: `-choice_map HMRcore|ENGRO2|Custom` or `-custom_map` SVG -- Output: `-gs/--generate_svg`, `-gp/--generate_pdf`, output dir `-idop` - -Outputs: -- Styled SVG (and optional PDF/PNG) highlighting enriched reactions by color/width per your thresholds. - -### 7) flux_to_map +2. **Python API Usage**: + ```python + import sys + import os + + # Add COBRAxy to Python path + sys.path.append('/path/to/COBRAxy') + + # Import tool modules + import ras_generator + import rps_generator + import flux_simulation + import marea + import ras_to_bounds + + # Set working directory + tool_dir = "/path/to/COBRAxy" + os.chdir(tool_dir) + + # Generate RAS scores + ras_args = [ + '-td', tool_dir, + '-in', 'data/expression.tsv', + '-ra', 'output/ras_values.tsv', + '-rs', 'ENGRO2' + ] + ras_generator.main(ras_args) + + # Generate RPS scores (optional) + rps_args = [ + '-td', tool_dir, + '-id', 'data/metabolites.tsv', + '-rp', 'output/rps_values.tsv' + ] + rps_generator.main(rps_args) + + # Create enriched pathway maps + marea_args = [ + '-td', tool_dir, + '-using_RAS', 'true', + '-input_data', 'output/ras_values.tsv', + '-choice_map', 'ENGRO2', + '-gs', 'true', + '-idop', 'maps' + ] + marea.main(marea_args) + + # Apply RAS constraints to model + bounds_args = [ + '-td', tool_dir, + '-ms', 'ENGRO2', + '-ir', 'output/ras_values.tsv', + '-rs', 'true', + '-idop', 'bounds' + ] + ras_to_bounds.main(bounds_args) + + # Sample metabolic fluxes + flux_args = [ + '-td', tool_dir, + '-ms', 'ENGRO2', + '-in', 'bounds/bounds_output.tsv', + '-a', 'CBS', + '-ns', '1000', + '-idop', 'flux_results' + ] + flux_simulation.main(flux_args) + ``` -Like `marea`, but driven by fluxes instead of RAS/RPS. Accepts single or multiple flux datasets and produces styled maps. - -### 8) marea_cluster - -Convenience clustering utilities (k‑means, DBSCAN, hierarchical) for grouping samples; produces labels and optional plots. +3. **Python Tutorial Resources**: + - [COBRApy Documentation](https://cobrapy.readthedocs.io/) + - [Metabolic Modeling with Python](https://opencobra.github.io/cobrapy/building_model.html) + - [Flux Sampling Tutorial](https://cobrapy.readthedocs.io/en/stable/sampling.html) + - [Jupyter Notebooks Examples](examples/) (included in repository) -## Typical workflow - -1. Prepare a model and generate its assets (optional if using bundled assets): `custom_data_generator` -2. Compute RAS from expression: `ras_generator` (and/or compute RPS via `rps_generator`) -3. Integrate RAS into bounds: `ras_to_bounds` -4. Sample fluxes: `flux_simulation` with CBS or OPTGP -5. Analyze and visualize: `marea` or `flux_to_map` to render SVG/PDF metabolic maps -6. Optionally cluster or further analyze results: `marea_cluster` +## Input/Output Formats -## Input/output formats - -Unless otherwise stated, inputs are tab‑separated (TSV) text files with headers. - -- Expression (RAS): rows = genes (HGNC/Ensembl/symbol/Entrez supported), columns = samples -- Metabolite table (RPS): rows = metabolites, columns = samples -- Rules/Reactions: TSV with two columns: ReactionID, Rule/Reaction -- Bounds: TSV with index = reaction IDs, columns = lower_bound, upper_bound -- Medium: single‑column TSV listing exchange reactions -- Flux samples/statistics: CSV/TSV with reactions as rows and samples/statistics as columns - -## Galaxy usage - -Each CLI has a corresponding Galaxy tool XML in the repository (e.g., `marea.xml`, `flux_simulation.xml`). Use `shed.yml` to publish to a Galaxy toolshed. The `local/` directory provides models, mappings, and maps for out‑of‑the‑box runs inside Galaxy. +| Data Type | Format | Description | +|-----------|---------|-------------| +| Gene expression | TSV | Genes (rows) × Samples (columns) | +| Metabolites | TSV | Metabolites (rows) × Samples (columns) | +| Models | SBML | Standard metabolic model format | +| Results | TSV/CSV | Tabular flux/score data | +| Maps | SVG/PDF | Styled pathway visualizations | ## Troubleshooting -- GLPK/CBS issues: if `swiglpk` or GLPK is missing, `flux_simulation` will attempt a COBRApy fallback. Install GLPK + `swiglpk` for best performance. -- pyvips errors: install `libvips` on your system. Reinstall the `pyvips` wheel afterward if needed. -- PDF/SVG conversions: ensure `cairosvg`, `svglib`, and system libraries (`libxml2`, `libxslt`) are installed. -- Python version: stick to Python ≥3.8.20 and <3.12. -- Memory/time: reduce `-ns` (samples) or `-nb` (batches); consider OPTGP if CBS is slow for your model. +**Common issues:** + +- **Missing GLPK**: Install `glpk-utils` and `swiglpk` for optimal CBS performance +- **SVG errors**: Install `libvips` system library +- **Memory issues**: Reduce sampling count (`-ns`) or use fewer batches (`-nb`) ## Contributing -Pull requests are welcome. Please: -- keep changes focused and documented, -- add concise docstrings/comments in English, -- preserve public CLI parameters and file formats. +Contributions welcome! Please: +- Follow existing code style +- Add documentation for new features +- Test with provided example data +- Submit focused pull requests -## License and citations +## Citation -This project is distributed under the MIT License. If you use COBRAxy in academic work, please cite COBRApy and MaREA, and reference this repository. - -## Useful links +If you use COBRAxy in research, please cite: +- [COBRApy](https://opencobra.github.io/cobrapy/) for core metabolic modeling +- [MaREA](https://galaxyproject.org/use/marea4galaxy/) for enrichment methods +- This repository for integrated workflow -- COBRAxy Google Summer of Code 2024: https://summerofcode.withgoogle.com/programs/2024/projects/LSrCKfq7 -- COBRApy: https://opencobra.github.io/cobrapy/ -- MaREA4Galaxy: https://galaxyproject.org/use/marea4galaxy/ -- Galaxy project: https://usegalaxy.org/ +## Links + +- [COBRApy Documentation](https://opencobra.github.io/cobrapy/) +- [Galaxy Project](https://usegalaxy.org/) +- [GSoC 2024 Project](https://summerofcode.withgoogle.com/programs/2024/projects/LSrCKfq7)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/README.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,57 @@ +# COBRAxy Documentation + +> A Python toolkit for metabolic flux analysis and visualization, with Galaxy integration. + +COBRAxy transforms gene expression and metabolite data into meaningful metabolic insights through flux sampling and interactive pathway maps. + +## Overview + +COBRAxy provides a complete pipeline for metabolic modeling and analysis, from raw omics data to publication-ready pathway visualizations. Whether you're a researcher analyzing metabolic changes in disease, a systems biologist studying metabolic networks, or a bioinformatician building analysis pipelines, COBRAxy offers the tools you need. + +## Key Features + +- **Reaction Activity Scores (RAS)** - Compute metabolic activity from gene expression data +- **Reaction Propensity Scores (RPS)** - Infer metabolic preferences from metabolite abundance +- **Flux Sampling** - Sample metabolic flux distributions with CBS or OptGP algorithms +- **Statistical Analysis** - Perform pFBA, FVA, and sensitivity analysis +- **Interactive Maps** - Generate publication-ready pathway visualizations with SVG/PDF export +- **Galaxy Tools** - Web-based analysis with intuitive interface +- **Built-in Models** - Ready-to-use models including ENGRO2 and Recon + +## Quick Navigation + +### [Installation](installation.md) +Install COBRAxy and get it running on your system + +### [Tutorials](tutorials/) +Step-by-step guides for Galaxy and Python usage + +### [Tools Documentation](tools/) +Complete reference for all COBRAxy tools + +## Data Flow + +COBRAxy follows two parallel analysis paths: + +1. **Enrichment Analysis**: RAS + RPS → MAREA → Enriched Maps +2. **Flux Simulation**: RAS → Model Constraints → Flux Sampling → Flux Maps + +## Community & Support + +- **Documentation**: Complete guides and API reference +- **Discussions**: Ask questions and share experiences +- **Issues**: Report bugs and request features +- **Contributing**: Help improve COBRAxy + +## Quick Links + +| Resource | Description | +|----------|-------------| +| [Installation Guide](installation.md) | Get COBRAxy running on your system | +| [Galaxy Tutorial](tutorials/galaxy-setup.md) | Web-based analysis setup | +| [Python Tutorial](tutorials/python-api.md) | Use COBRAxy programmatically | +| [Tools Documentation](tools/) | Complete tool reference | + +--- + +**Ready to start?** Follow the [Installation Guide](installation.md) to get COBRAxy up and running! \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/_sidebar.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,20 @@ +<!-- docs/_sidebar.md --> + +* [Home](/) + +* [Installation](installation.md) + +* [Tutorials](tutorials/) + * [Galaxy Setup](tutorials/galaxy-setup.md) + * [Python API](tutorials/python-api.md) + +* [Tools Documentation](tools/) + * [RAS Generator](tools/ras-generator.md) + * [RPS Generator](tools/rps-generator.md) + * [MAREA](tools/marea.md) + * [RAS to Bounds](tools/ras-to-bounds.md) + * [Flux Simulation](tools/flux-simulation.md) + * [Flux to Map](tools/flux-to-map.md) + * [Model Setting](tools/metabolic-model-setting.md) + * [Tabular to Model](tools/tabular-to-model.md) + * [MAREA Cluster](tools/marea-cluster.md) \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/getting-started.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,165 @@ +# Getting Started + +Welcome to COBRAxy! This guide will help you get up and running with metabolic flux analysis. + +## What is COBRAxy? + +COBRAxy is a comprehensive toolkit for metabolic flux analysis that bridges the gap between omics data and biological insights. It provides: + +- **Data Integration**: Combine gene expression and metabolite data +- **Metabolic Modeling**: Use constraint-based models for flux analysis +- **Visualization**: Generate interactive pathway maps +- **Statistical Analysis**: Perform enrichment and sensitivity analysis + +## Core Concepts + +### Reaction Activity Scores (RAS) +RAS quantify how active metabolic reactions are based on gene expression data. COBRAxy computes RAS by: +1. Mapping genes to reactions via GPR (Gene-Protein-Reaction) rules +2. Applying logical operations (AND/OR) based on enzyme complexes +3. Producing activity scores for each reaction in each sample + +### Reaction Propensity Scores (RPS) +RPS indicate metabolic preferences based on metabolite abundance: +1. Map metabolites to reactions as substrates/products +2. Weight by stoichiometry and frequency +3. Compute propensity scores using log-normalized formulas + +### Flux Sampling +Sample feasible flux distributions using: +- **CBS (Coordinate Hit-and-Run with Rounding)**: Fast, uniform sampling +- **OptGP (Optimal Growth Parallel)**: Growth-optimized sampling + +## Analysis Workflows + +COBRAxy supports two main analysis paths: + +### 1. Enrichment Analysis Workflow +```bash +# Generate activity scores +ras_generator → RAS values +rps_generator → RPS values + +# Statistical enrichment analysis +marea → Enriched pathway maps +``` + +**Use when**: You want to identify significantly altered pathways and create publication-ready maps. + +### 2. Flux Simulation Workflow +```bash +# Apply constraints to model +ras_generator → RAS values +ras_to_bounds → Constrained model + +# Sample flux distributions +flux_simulation → Flux samples +flux_to_map → Final visualizations +``` + +**Use when**: You want to predict metabolic flux distributions and study network-wide changes. + +## Your First Analysis + +Let's run a basic analysis with sample data: + +### Step 1: Prepare Your Data + +You'll need: +- **Gene expression data**: TSV file with genes (rows) × samples (columns) +- **Metabolic model**: SBML file or use built-in models (ENGRO2, Recon) +- **Metabolite data** (optional): TSV file with metabolites (rows) × samples (columns) + +### Step 2: Generate Activity Scores + +```bash +# Generate RAS from expression data +ras_generator -td $(pwd) \ + -in expression_data.tsv \ + -ra ras_output.tsv \ + -rs ENGRO2 +``` + +### Step 3: Create Pathway Maps + +```bash +# Generate enriched pathway maps +marea -td $(pwd) \ + -using_RAS true \ + -input_data ras_output.tsv \ + -choice_map ENGRO2 \ + -gs true \ + -idop pathway_maps +``` + +### Step 4: View Results + +Your analysis will generate: +- **RAS values**: `ras_output.tsv` - Activity scores for each reaction +- **Statistical maps**: `pathway_maps/` - SVG files with enrichment visualization +- **Log files**: Detailed execution logs for troubleshooting + +## Built-in Models + +COBRAxy includes ready-to-use metabolic models: + +| Model | Organism | Reactions | Genes | Description | +|-------|----------|-----------|-------|-------------| +| **ENGRO2** | Human | ~2,000 | ~500 | Focused human metabolism model | +| **Recon** | Human | ~10,000 | ~2,000 | Comprehensive human metabolism | + +Models are stored in the `local/` directory and include: +- SBML files +- GPR rules +- Gene mapping tables +- Pathway templates + +## Data Formats + +### Gene Expression Format +```tsv +Gene_ID Sample_1 Sample_2 Sample_3 +HGNC:5 12.5 8.3 15.7 +HGNC:10 3.2 4.1 2.8 +HGNC:15 7.9 11.2 6.4 +``` + +### Metabolite Format +```tsv +Metabolite_ID Sample_1 Sample_2 Sample_3 +glucose 100.5 85.3 120.7 +pyruvate 45.2 38.1 52.8 +lactate 23.9 41.2 19.4 +``` + +## Command Line vs Python API + +COBRAxy offers two usage modes: + +### Command Line (Quick Analysis) +```bash +# Simple command-line execution +ras_generator -td $(pwd) -in data.tsv -ra output.tsv -rs ENGRO2 +``` + +### Python API (Programming) +```python +import ras_generator +# Call main function with arguments +ras_generator.main(['-td', '/path', '-in', 'data.tsv', '-ra', 'output.tsv', '-rs', 'ENGRO2']) +``` + +## Next Steps + +Now that you understand the basics: + +1. **[Quick Start Guide](quickstart.md)** - Complete walkthrough with example data +2. **[Python API Tutorial](tutorials/python-api.md)** - Learn programmatic usage +3. **[Tools Reference](tools/)** - Detailed documentation for each tool +4. **[Examples](examples/)** - Real-world analysis examples + +## Need Help? + +- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions +- **[GitHub Issues](https://github.com/CompBtBs/COBRAxy/issues)** - Report bugs or ask questions +- **[Contributing](contributing.md)** - Help improve COBRAxy \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/index.html Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,164 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="UTF-8"> + <title>COBRAxy Documentation</title> + <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /> + <meta name="description" content="COBRAxy - A Python toolkit for metabolic flux analysis and visualization"> + <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0"> + <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/dark.css"> + <style> + :root { + --theme-color: #4CAF50; + --text-color-base: #e1e4e8; + --background-color: #0d1117; + --sidebar-background: #161b22; + --code-background: #21262d; + } + + body { + background-color: var(--background-color); + color: var(--text-color-base); + } + + .sidebar { + background-color: var(--sidebar-background); + border-right: 1px solid #30363d; + } + + .sidebar-nav a { + color: var(--text-color-base); + } + + .sidebar-nav a:hover { + color: var(--theme-color); + } + + .app-name-link { + color: var(--theme-color) !important; + font-weight: 600; + } + + .app-name img { + max-height: 50px; + max-width: 250px; + margin-right: 10px; + vertical-align: middle; + } + + .sidebar > h1 > img { + max-height: 50px; + width: auto; + } + + .markdown-section { + background-color: var(--background-color); + color: var(--text-color-base); + } + + .markdown-section code { + background-color: var(--code-background); + color: #f0f6fc; + border-radius: 6px; + padding: 0.2em 0.4em; + border: 1px solid #30363d; + } + + .markdown-section pre { + background-color: var(--code-background); + border: 1px solid #30363d; + } + + .markdown-section pre > code { + background-color: var(--code-background); + color: #f0f6fc; + } + + .markdown-section table { + border-collapse: collapse; + border: 1px solid #30363d; + } + + .markdown-section th, + .markdown-section td { + border: 1px solid #30363d; + background-color: var(--code-background); + } + + .markdown-section th { + background-color: #21262d; + font-weight: 600; + } + </style> +</head> +<body> + <div id="app"></div> + <script> + window.$docsify = { + name: 'COBRAxy', + logo: './_media/logo.png', + loadSidebar: true, + loadNavbar: false, + subMaxLevel: 3, + auto2top: true, + + // Search plugin + search: { + maxAge: 86400000, // Expiration time, the default one day + paths: 'auto', + placeholder: 'Search documentation...', + noData: 'No results found.', + depth: 3 + }, + + // Copy code plugin + copyCode: { + buttonText: 'Copy', + errorText: 'Error', + successText: 'Copied' + }, + + // Zoom image plugin + zoom: { + selector: '.medium-zoom-image', + delay: 1000, + options: { + bgColor: 'rgba(0,0,0,0.8)', + zIndex: 99999 + } + }, + + // Tabs plugin + tabs: { + persist: true, + sync: true, + theme: 'classic', + tabComments: true, + tabHeadings: true + } + } + </script> + + <!-- Core Docsify --> + <script src="//cdn.jsdelivr.net/npm/docsify@4"></script> + + <!-- Search plugin --> + <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script> + + <!-- Copy code plugin --> + <script src="//cdn.jsdelivr.net/npm/docsify-copy-code@2"></script> + + <!-- Zoom image plugin --> + <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script> + + <!-- Tabs plugin --> + <script src="//cdn.jsdelivr.net/npm/docsify-tabs@1"></script> + + <!-- Code syntax highlighting --> + <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script> + <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-python.min.js"></script> + <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script> + <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-xml.min.js"></script> + <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script> +</body> +</html> \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/installation.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,162 @@ +# Installation + +This guide walks you through installing COBRAxy on your system. + +## System Requirements + +- **Python**: 3.8-3.11 +- **Operating System**: Linux (recommended), macOS, Windows +- **Storage**: 2GB free space for installation and temporary files + +## Quick Install + +The fastest way to install COBRAxy: + +```bash +# Clone the repository +git clone https://github.com/CompBtBs/COBRAxy.git +cd COBRAxy + +# Install COBRAxy +pip install . +``` + +## Development Install + +For development or if you want to modify COBRAxy: + +```bash +# Clone and install in development mode +git clone https://github.com/CompBtBs/COBRAxy.git +cd COBRAxy +pip install -e . +``` + +## Dependencies + +COBRAxy automatically installs its Python dependencies: + +- **COBRApy** - Core metabolic modeling +- **pandas** - Data manipulation +- **numpy** - Numerical computations +- **scipy** - Scientific computing + +## Optional System Libraries + +Install additional libraries for enhanced features: + +### Ubuntu/Debian + +```bash +# Install GLPK solver +sudo apt-get update +sudo apt-get install libglpk40 glpk-utils + +# Install libvips for SVG processing +sudo apt-get install libvips + +# Install Python GLPK bindings +pip install swiglpk +``` + +### macOS + +```bash +# Using Homebrew +brew install glpk vips + +# Install Python bindings +pip install swiglpk +``` + +### Windows + +```bash +# Using conda (recommended for Windows) +conda install -c conda-forge glpk + +# Or using pip +pip install swiglpk +``` + +## Verify Installation + +Test your installation: + +```bash +# Check if COBRAxy tools are available +ras_generator --help +flux_simulation --help + +# Test with example data (if available) +cd COBRAxy +python testing.py +``` + +## Troubleshooting Installation + +### Common Issues + +**Import Error: No module named 'cobra'** +```bash +# Install COBRApy manually +pip install cobra +``` + +**GLPK solver not found** +```bash +# Install GLPK solver +# Ubuntu/Debian: sudo apt-get install glpk-utils +# macOS: brew install glpk +# Then: pip install swiglpk +``` + +**Permission denied errors** +```bash +# Use user installation +pip install --user . +# Or use virtual environment (recommended) +python -m venv cobraxy-env +source cobraxy-env/bin/activate # Linux/macOS +# cobraxy-env\Scripts\activate # Windows +pip install . +``` + +## Virtual Environment (Recommended) + +Using a virtual environment prevents conflicts with other Python packages: + +```bash +# Create virtual environment +python -m venv cobraxy-env + +# Activate environment +source cobraxy-env/bin/activate # Linux/macOS +# cobraxy-env\Scripts\activate # Windows + +# Install COBRAxy +pip install . + +# When done, deactivate +deactivate +``` + +## Next Steps + +After successful installation: + +1. **[Quick Start Guide](quickstart.md)** - Run your first analysis +2. **[Tutorial: Python API](tutorials/python-api.md)** - Learn programmatic usage +3. **[Tutorial: Galaxy Setup](tutorials/galaxy-setup.md)** - Set up web interface + +## Getting Help + +If you encounter issues: + +1. Check the [Troubleshooting Guide](troubleshooting.md) +2. Search [existing issues](https://github.com/CompBtBs/COBRAxy/issues) +3. Create a [new issue](https://github.com/CompBtBs/COBRAxy/issues/new) with: + - Your operating system + - Python version (`python --version`) + - Complete error message + - Installation method used \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/quickstart.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,153 @@ +# Quick Start Guide + +Get started with COBRAxy! This guide walks you through your first metabolic analysis. + +## Step 1: Verify Installation + +Test that COBRAxy is working: + +```bash +# Check if tools are available +ras_generator --help + +# Should display help text without errors +``` + +## Step 2: Download Sample Data + +Create a sample gene expression file: + +```bash +# Create sample data +cat > sample_expression.tsv << 'EOF' +Gene_ID Control_1 Control_2 Treatment_1 Treatment_2 +HGNC:5 8.5 9.2 15.7 14.3 +HGNC:10 3.2 4.1 8.8 7.9 +HGNC:15 7.9 8.2 4.4 5.1 +HGNC:25 12.1 13.5 18.2 17.8 +HGNC:30 6.3 7.1 11.5 10.8 +HGNC:55 14.2 15.8 22.1 21.3 +HGNC:80 5.7 6.4 2.8 3.2 +HGNC:100 9.8 10.5 16.7 15.9 +EOF +``` + +## Step 3: Generate Activity Scores + +Compute Reaction Activity Scores (RAS) from your gene expression: + +```bash +# Generate RAS scores using built-in ENGRO2 model +ras_generator -td $(pwd) \ + -in sample_expression.tsv \ + -ra ras_scores.tsv \ + -rs ENGRO2 + +# Check output +head ras_scores.tsv +``` + +**Expected output**: +```tsv +Reactions Control_1 Control_2 Treatment_1 Treatment_2 +R_HEX1 8.5 9.2 15.7 14.3 +R_PGI 7.9 8.2 4.4 5.1 +... +``` + +## Step 4: Create Pathway Visualizations + +Generate enriched pathway maps with statistical analysis: + +```bash +# Create pathway maps with statistical analysis +marea -td $(pwd) \ + -using_RAS true \ + -input_data ras_scores.tsv \ + -choice_map ENGRO2 \ + -gs true \ + -idop pathway_maps + +# Check results +ls pathway_maps/ +``` + +**Expected output**: SVG files with colored pathway maps showing metabolic changes. + +## Step 5: View Results + +Open the generated pathway maps: + +```bash +# Open SVG files in your browser or image viewer +# Files will be in pathway_maps/ directory +firefox pathway_maps/*.svg # Linux +open pathway_maps/*.svg # macOS +``` + +## What Just Happened? + +1. **RAS Generation**: Mapped gene expression to metabolic reactions using GPR rules +2. **Statistical Analysis**: Identified significantly altered pathways between conditions +3. **Visualization**: Created colored pathway maps highlighting metabolic changes + +## Next Steps + +### Learn More About the Analysis + +- **[Understanding RAS](tools/ras-generator.md)** - How activity scores are computed +- **[MAREA Analysis](tools/marea.md)** - Statistical enrichment methods +- **[Data Flow](getting-started.md#analysis-workflows)** - Complete workflow overview + +### Try Advanced Features + +- **[Flux Sampling](tutorials/workflow.md#flux-simulation-workflow)** - Predict metabolic flux distributions +- **[Python API](tutorials/python-api.md)** - Integrate into scripts and pipelines +- **[Galaxy Interface](tutorials/galaxy-setup.md)** - Web-based analysis + +### Use Your Own Data + +- **[Data Formats](tutorials/data-formats.md)** - Prepare your expression data +- **[Troubleshooting](troubleshooting.md)** - Common issues and solutions + +## Complete Example Pipeline + +Here's the full command sequence for reference: + +```bash +# Set up +cd /path/to/analysis/ + +# Generate sample data (or use your own) +cat > expression.tsv << 'EOF' +[your gene expression data] +EOF + +# Run analysis pipeline +ras_generator -td /path/to/COBRAxy -in expression.tsv -ra ras.tsv -rs ENGRO2 +marea -td /path/to/COBRAxy -using_RAS true -input_data ras.tsv -choice_map ENGRO2 -gs true -idop maps + +# View results +ls maps/*.svg +``` + +## Getting Help + +If something doesn't work: + +1. **Check Prerequisites**: Ensure COBRAxy is properly installed +2. **Verify File Format**: Make sure your data is tab-separated TSV +3. **Review Logs**: Look for error messages in the terminal output +4. **Consult Guides**: [Troubleshooting](troubleshooting.md) and [Installation](installation.md) + +**Still stuck?** Ask for help in [GitHub Discussions](https://github.com/CompBtBs/COBRAxy/discussions). + +## Summary + +🎉 **Congratulations!** You've completed your first COBRAxy analysis. You now know how to: + +- ✅ Generate metabolic activity scores from gene expression +- ✅ Create statistical pathway visualizations +- ✅ Interpret basic COBRAxy outputs + +Ready for more? Explore the [full documentation](/) to unlock COBRAxy's complete potential! \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/README.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,154 @@ +# Tool| Tool | Purpose | Input | Output | +|------|---------|--------|---------| +| [RAS Generator](ras-generator.md) | Compute reaction activity scores | Gene expression + GPR rules | RAS values | +| [RPS Generator](rps-generator.md) | Compute reaction propensity scores | Metabolite abundance | RPS values | +| [MAREA](marea.md) | Statistical pathway enrichment | RAS/RPS data | Enriched maps + statistics | +| [RAS to Bounds](ras-to-bounds.md) | Apply RAS constraints to model | RAS + SBML model | Constrained bounds | +| [Flux Simulation](flux-simulation.md) | Sample metabolic fluxes | Constrained model | Flux distributions | +| [Flux to Map](flux-to-map.md) | Visualize flux data on maps | Flux samples + statistical comparison | Color-coded pathway maps | +| [Model Setting](metabolic-model-setting.md) | Extract model components | SBML/JSON/MAT/YML model | Tabular model data | +| [Tabular to Model](tabular-to-model.md) | Create COBRA models | Tabular reaction data | SBML/JSON/MAT/YAML models | +| [MAREA Cluster](marea-cluster.md) | Cluster analysis | Expression/RAS/RPS/flux data | Sample clusters + validation plots |ation + +Complete reference for all COBRAxy tools with parameters, examples, and usage guidelines. + +## Available Tools + +| Tool | Purpose | Input | Output | +|------|---------|--------|--------| +| [RAS Generator](ras-generator.md) | Compute reaction activity scores | Gene expression + GPR rules | RAS values | +| [RPS Generator](rps-generator.md) | Compute reaction propensity scores | Metabolite abundance | RPS values | +| [MAREA](marea.md) | Statistical pathway enrichment | RAS/RPS data | Enriched maps + statistics | +| [RAS to Bounds](ras-to-bounds.md) | Apply RAS constraints to model | RAS + SBML model | Constrained bounds | +| [Flux Simulation](flux-simulation.md) | Sample metabolic fluxes | Constrained model | Flux distributions | +| [Flux to Map](flux-to-map.md) | Visualize flux data on maps | Flux samples + statistical comparison | Color-coded pathway maps | +| [Model Setting](metabolic-model-setting.md) | Extract model components | SBML/JSON/MAT/YML model | Tabular model data | +| [MAREA Cluster](marea-cluster.md) | Cluster analysis | Expression/RAS/RPS/flux data | Sample clusters + validation plots | + +## Common Parameters + +All tools share these basic parameters: + +- **`-td, --tool_dir`**: COBRAxy installation directory (required) +- **`-in, --input`**: Input dataset file +- **`-idop, --output_dir`**: Output directory for results +- **`-rs, --rules_selector`**: Built-in model (ENGRO2, Recon, HMRcore) + +## Analysis Workflows + +**Enrichment Analysis**: Gene Expression → RAS Generator → MAREA → Pathway Maps + +**Flux Simulation**: Gene Expression → RAS Generator → RAS to Bounds → Flux Simulation → Flux to Map + +## Usage Patterns + +### Command Line Usage +```bash +# Basic pattern for all tools +tool_name -td $(pwd) [tool-specific options] + +# Example: Generate RAS scores +ras_generator -td $(pwd) -in expression.tsv -ra ras_output.tsv -rs ENGRO2 +``` + +### Python API Usage +```python +import tool_module + +# All tools accept argument lists +args = ['-td', '/path/to/cobraxy', '-in', 'input.tsv', '-out', 'output.tsv'] +tool_module.main(args) +``` + +### Galaxy Integration +All tools include Galaxy XML wrappers for web-based usage through the Galaxy interface. + +## Parameter Reference + +### File Format Requirements + +**Gene Expression Files** +- Format: TSV (tab-separated values) +- Structure: Genes (rows) × Samples (columns) +- First column: Gene IDs (HGNC, Ensembl, etc.) +- Subsequent columns: Expression values + +**Metabolite Files** +- Format: TSV (tab-separated values) +- Structure: Metabolites (rows) × Samples (columns) +- First column: Metabolite names +- Subsequent columns: Abundance values + +**Model Files** +- Format: SBML (.xml) or tabular rules (.tsv) +- Content: Metabolic network with GPR rules + +### Built-in Models + +| Model | Organism | Reactions | Genes | Best For | +|-------|----------|-----------|-------|----------| +| **ENGRO2** | Human | ~2,000 | ~500 | Focused analysis, faster computation | +| **Recon** | Human | ~10,000 | ~2,000 | Comprehensive metabolism | +| **HMRcore** | Human | ~5,000 | ~1,000 | Balanced coverage | + +## Tool Selection Guide + +### Choose Your Analysis Path + +**For Pathway Enrichment** +1. [RAS Generator](ras-generator.md) → Generate activity scores +2. [RPS Generator](rps-generator.md) → Generate propensity scores (optional) +3. [MAREA](marea.md) → Statistical analysis and visualization + +**For Flux Analysis** +1. [RAS Generator](ras-generator.md) → Generate activity scores +2. [RAS to Bounds](ras-to-bounds.md) → Apply constraints +3. [Flux Simulation](flux-simulation.md) → Sample fluxes +4. [Flux to Map](flux-to-map.md) → Create visualizations + +**For Model Exploration** +1. [Model Setting](metabolic-model-setting.md) → Extract model info +2. Analyze model structure and gene coverage + +**For Sample Classification** +1. Generate RAS/RPS scores +2. [MAREA Cluster](marea-cluster.md) → Cluster samples + + + +## Troubleshooting + +### Common Issues Across Tools + +**File Path Problems** +- Use absolute paths when possible +- Ensure all input files exist before starting +- Check write permissions for output directories + +**File Issues** +- Check file paths and permissions +- Verify input file formats +- Ensure sufficient disk space + +**Model Issues** +- Verify model file format and gene ID consistency +- Check gene ID mapping between data and model +- Use built-in models to avoid compatibility issues + +### Getting Help + +For tool-specific issues: +1. Check individual tool documentation +2. Review parameter requirements and formats +3. Test with smaller datasets first +4. Consult [troubleshooting guide](../troubleshooting.md) + +## Contributing + +Help improve tool documentation: +- Report unclear instructions +- Suggest additional examples +- Contribute usage patterns +- Fix documentation errors + +Each tool page includes detailed parameter descriptions, examples, and troubleshooting tips. Select a tool from the sidebar to get started! \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/flux-simulation.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,406 @@ +# Flux Simulation + +Sample metabolic fluxes using constraint-based modeling with CBS or OPTGP algorithms. + +## Overview + +Flux Simulation performs constraint-based sampling of metabolic flux distributions from constrained models. It supports two sampling algorithms (CBS and OPTGP) and provides comprehensive flux statistics including mean, median, quantiles, pFBA, FVA, and sensitivity analysis. + +## Usage + +### Command Line + +```bash +flux_simulation -td /path/to/COBRAxy \ + -ms ENGRO2 \ + -in bounds1.tsv,bounds2.tsv \ + -ni Sample1,Sample2 \ + -a CBS \ + -ns 1000 \ + -nb 1 \ + -sd 42 \ + -ot mean,median,quantiles \ + -ota pFBA,FVA,sensitivity \ + -idop flux_results/ +``` + +### Galaxy Interface + +Select "Flux Simulation" from the COBRAxy tool suite and configure sampling parameters through the web interface. + +## Parameters + +### Required Parameters + +| Parameter | Flag | Description | +|-----------|------|-------------| +| Tool Directory | `-td, --tool_dir` | Path to COBRAxy installation directory | +| Input Bounds | `-in, --input` | Comma-separated list of bounds files | +| Sample Names | `-ni, --names` | Comma-separated sample names | +| Algorithm | `-a, --algorithm` | Sampling algorithm (CBS or OPTGP) | +| Number of Samples | `-ns, --n_samples` | Samples per batch | +| Number of Batches | `-nb, --n_batches` | Number of sampling batches | +| Random Seed | `-sd, --seed` | Random seed for reproducibility | +| Output Types | `-ot, --output_type` | Flux statistics to compute | + +### Model Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Model Selector | `-ms, --model_selector` | Built-in model (ENGRO2, Custom) | ENGRO2 | +| Custom Model | `-mo, --model` | Path to custom SBML model | - | +| Model Name | `-mn, --model_name` | Custom model filename | - | + +### Sampling Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Algorithm | `-a, --algorithm` | CBS or OPTGP | - | +| Thinning | `-th, --thinning` | OPTGP thinning parameter | 100 | +| Samples | `-ns, --n_samples` | Samples per batch | - | +| Batches | `-nb, --n_batches` | Number of batches | - | +| Seed | `-sd, --seed` | Random seed | - | + +### Output Parameters + +| Parameter | Flag | Description | Options | +|-----------|------|-------------|---------| +| Output Types | `-ot, --output_type` | Flux statistics | mean,median,quantiles,fluxes | +| Analysis Types | `-ota, --output_type_analysis` | Additional analyses | pFBA,FVA,sensitivity | +| Output Path | `-idop, --output_path` | Results directory | flux_simulation/ | +| Output Log | `-ol, --out_log` | Log file path | - | + +## Algorithms + +### CBS (Constraint-Based Sampling) + +**Method**: Random objective function optimization +- Generates random linear combinations of reactions +- Optimizes using LP solver (GLPK preferred, COBRApy fallback) +- Fast and memory-efficient +- Suitable for large models + +**Advantages**: +- High performance with GLPK +- Good coverage of solution space +- Robust to model size + +### OPTGP (Optimal Growth Perturbation) + +**Method**: MCMC-based sampling +- Markov Chain Monte Carlo with growth optimization +- Requires thinning to reduce autocorrelation +- More computationally intensive +- Better theoretical guarantees + +**Advantages**: +- Uniform sampling guarantee +- Well-established method +- Good for smaller models + +## Input Formats + +### Bounds Files + +Tab-separated format with reaction bounds: + +``` +Reaction lower_bound upper_bound +R00001 -1000.0 1250.5 +R00002 -650.2 1000.0 +R00003 0.0 2150.8 +``` + +Multiple bounds files can be processed simultaneously by providing comma-separated paths. + +### Custom Model File (Optional) + +SBML format metabolic model compatible with COBRApy. + +## Output Formats + +### Flux Statistics + +#### Mean Fluxes (`mean.csv`) +``` +Reaction Sample1 Sample2 Sample3 +R00001 15.23 -8.45 22.1 +R00002 0.0 12.67 -5.3 +R00003 45.8 38.2 51.7 +``` + +#### Median Fluxes (`median.csv`) +``` +Reaction Sample1 Sample2 Sample3 +R00001 14.1 -7.8 21.5 +R00002 0.0 11.9 -4.8 +R00003 44.2 37.1 50.3 +``` + +#### Quantiles (`quantiles.csv`) +``` +Reaction Sample1_q1 Sample1_q2 Sample1_q3 Sample2_q1 ... +R00001 10.5 14.1 18.7 -12.3 ... +R00002 -2.1 0.0 1.8 8.9 ... +R00003 38.9 44.2 49.8 32.1 ... +``` + +### Additional Analyses + +#### pFBA (`pFBA.csv`) +Parsimonious Flux Balance Analysis results: +``` +Reaction Sample1 Sample2 Sample3 +R00001 12.5 -6.7 19.3 +R00002 0.0 8.9 -3.2 +R00003 41.2 35.8 47.9 +``` + +#### FVA (`FVA.csv`) +Flux Variability Analysis bounds: +``` +Reaction Sample1_min Sample1_max Sample2_min Sample2_max ... +R00001 -5.2 35.8 -25.3 8.7 ... +R00002 -8.9 8.9 0.0 28.4 ... +R00003 15.6 78.3 10.2 65.9 ... +``` + +#### Sensitivity (`sensitivity.csv`) +Single reaction deletion effects: +``` +Reaction Sample1 Sample2 Sample3 +R00001 0.98 0.95 0.97 +R00002 1.0 0.87 1.0 +R00003 0.23 0.19 0.31 +``` + +## Examples + +### Basic CBS Sampling + +```bash +# Simple CBS sampling with statistics +flux_simulation -td /opt/COBRAxy \ + -ms ENGRO2 \ + -in sample1_bounds.tsv,sample2_bounds.tsv \ + -ni Sample1,Sample2 \ + -a CBS \ + -ns 500 \ + -nb 2 \ + -sd 42 \ + -ot mean,median \ + -ota pFBA \ + -idop cbs_results/ +``` + +### Comprehensive OPTGP Analysis + +```bash +# Full analysis with OPTGP +flux_simulation -td /opt/COBRAxy \ + -ms ENGRO2 \ + -in bounds/*.tsv \ + -ni Sample1,Sample2,Sample3,Control1,Control2 \ + -a OPTGP \ + -th 200 \ + -ns 1000 \ + -nb 1 \ + -sd 123 \ + -ot mean,median,quantiles,fluxes \ + -ota pFBA,FVA,sensitivity \ + -idop comprehensive_analysis/ \ + -ol sampling.log +``` + +### Custom Model Sampling + +```bash +# Use custom model with CBS +flux_simulation -td /opt/COBRAxy \ + -ms Custom \ + -mo models/tissue_specific.xml \ + -mn tissue_specific.xml \ + -in patient_bounds.tsv \ + -ni PatientA \ + -a CBS \ + -ns 2000 \ + -nb 5 \ + -sd 456 \ + -ot mean,quantiles \ + -ota FVA,sensitivity \ + -idop patient_analysis/ +``` + +### Batch Processing Multiple Conditions + +```bash +# Process multiple experimental conditions +flux_simulation -td /opt/COBRAxy \ + -ms ENGRO2 \ + -in ctrl1.tsv,ctrl2.tsv,treat1.tsv,treat2.tsv \ + -ni Control1,Control2,Treatment1,Treatment2 \ + -a CBS \ + -ns 800 \ + -nb 3 \ + -sd 789 \ + -ot mean,median,fluxes \ + -ota pFBA,FVA \ + -idop batch_conditions/ +``` + +## Algorithm Selection Guide + +### Choose CBS When: +- Large models (>1000 reactions) +- High sample throughput required +- GLPK solver available +- Memory constraints present + +### Choose OPTGP When: +- Theoretical sampling guarantees needed +- Smaller models (<500 reactions) +- Sufficient computational resources +- Publication-quality sampling required + +## Performance Optimization + +### CBS Optimization +- Install GLPK and swiglpk for maximum performance +- Increase batch number rather than samples per batch +- Monitor memory usage for large models + +### OPTGP Optimization +- Adjust thinning based on model size (100-500) +- Use parallel processing when available +- Consider warmup period for chain convergence + +### General Tips +- Use appropriate sample sizes (500-2000 per condition) +- Balance batches vs samples for memory management +- Set consistent random seeds for reproducibility + +## Quality Control + +### Convergence Assessment +- Compare statistics across batches +- Check for systematic trends in sampling +- Validate against known flux ranges + +### Statistical Validation +- Ensure adequate sample sizes (n≥100 recommended) +- Check for outliers and artifacts +- Validate against experimental flux data when available + +### Output Verification +- Confirm mass balance constraints satisfied +- Check thermodynamic consistency +- Verify biological plausibility of results + +## Integration Workflow + +### Upstream Tools +- [RAS to Bounds](ras-to-bounds.md) - Generate constrained bounds from RAS +- [Model Setting](metabolic-model-setting.md) - Extract model components + +### Downstream Tools +- [Flux to Map](flux-to-map.md) - Visualize flux distributions on metabolic maps +- [MAREA](marea.md) - Statistical analysis of flux differences + +### Typical Pipeline + +```bash +# 1. Generate sample-specific bounds +ras_to_bounds -td /opt/COBRAxy -ms ENGRO2 -ir ras.tsv -idop bounds/ + +# 2. Sample fluxes from constrained models +flux_simulation -td /opt/COBRAxy -ms ENGRO2 -in bounds/*.tsv \ + -ni Sample1,Sample2,Sample3 -a CBS -ns 1000 \ + -ot mean,quantiles -ota pFBA,FVA -idop fluxes/ + +# 3. Visualize results on metabolic maps +flux_to_map -td /opt/COBRAxy -input_data_fluxes fluxes/mean.csv \ + -choice_map ENGRO2 -idop flux_maps/ +``` + +## Troubleshooting + +### Common Issues + +**CBS sampling fails** +- GLPK installation issues → Install GLPK and swiglpk +- Model infeasibility → Check bounds constraints +- Memory errors → Reduce samples per batch + +**OPTGP convergence problems** +- Poor mixing → Increase thinning parameter +- Slow convergence → Extend sampling time +- Chain stuck → Check model feasibility + +**Output files missing** +- Insufficient disk space → Check available storage +- Permission errors → Verify write permissions +- Invalid sample names → Check naming conventions + +### Error Messages + +| Error | Cause | Solution | +|-------|-------|----------| +| "GLPK solver failed" | Missing GLPK/swiglpk | Install GLPK libraries | +| "Model infeasible" | Over-constrained bounds | Relax constraints or check model | +| "Sampling timeout" | Insufficient time/resources | Reduce sample size or increase resources | + +### Performance Issues + +**Slow sampling** +- Use CBS instead of OPTGP for speed +- Reduce model size if possible +- Increase system resources + +**Memory errors** +- Lower samples per batch +- Process samples sequentially +- Use more efficient data formats + +**Disk space issues** +- Monitor output file sizes +- Clean intermediate files +- Use compressed formats when possible + +## Advanced Usage + +### Custom Sampling Parameters + +For fine-tuning sampling behavior, advanced users can modify: +- Objective function generation (CBS) +- MCMC parameters (OPTGP) +- Convergence criteria +- Output precision and format + +### Parallel Processing + +```bash +# Split sampling across multiple cores/nodes +for i in {1..4}; do + flux_simulation -td /opt/COBRAxy -ms ENGRO2 \ + -in subset_${i}_bounds.tsv \ + -ni Batch${i} -a CBS -ns 250 \ + -sd $((42 + i)) -idop batch_${i}/ & +done +wait +``` + +### Result Aggregation + +Combine results from multiple simulation runs: + +```bash +# Merge statistics files +python merge_flux_results.py -i batch_*/mean.csv -o combined_mean.csv +``` + +## See Also + +- [RAS to Bounds](ras-to-bounds.md) - Generate input constraints +- [Flux to Map](flux-to-map.md) - Visualize flux results +- [CBS Algorithm Documentation](../tutorials/cbs-algorithm.md) +- [OPTGP Algorithm Documentation](../tutorials/optgp-algorithm.md) \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/flux-to-map.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,467 @@ +# Flux to Map + +Visualize metabolic flux data on pathway maps with statistical analysis and color coding. + +## Overview + +Flux to Map performs statistical analysis on flux distribution data and generates color-coded metabolic pathway maps. It compares flux values between sample groups and highlights significantly different reactions with appropriate colors and line weights. + +## Usage + +### Command Line + +```bash +flux_to_map -td /path/to/COBRAxy \ + -input_data_fluxes flux_data.tsv \ + -input_class_fluxes sample_groups.tsv \ + -comparison manyvsmany \ + -test ks \ + -pv 0.05 \ + -fc 1.5 \ + -choice_map ENGRO2 \ + -generate_svg true \ + -generate_pdf true \ + -idop flux_maps/ +``` + +### Galaxy Interface + +Select "Flux to Map" from the COBRAxy tool suite and configure flux analysis and visualization parameters. + +## Parameters + +### Required Parameters + +| Parameter | Flag | Description | +|-----------|------|-------------| +| Tool Directory | `-td, --tool_dir` | Path to COBRAxy installation directory | + +### Data Input Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Flux Data | `-idf, --input_data_fluxes` | Flux values TSV file | - | +| Flux Classes | `-icf, --input_class_fluxes` | Sample group labels for fluxes | - | +| Multiple Flux Files | `-idsf, --input_datas_fluxes` | Multiple flux datasets (space-separated) | - | +| Flux Names | `-naf, --names_fluxes` | Names for multiple flux datasets | - | +| Analysis Option | `-op, --option` | Analysis mode (datasets or dataset_class) | - | + +### Statistical Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Comparison Type | `-co, --comparison` | Statistical comparison mode | manyvsmany | +| Statistical Test | `-te, --test` | Statistical test method | ks | +| P-Value Threshold | `-pv, --pValue` | Significance threshold | 0.1 | +| Adjusted P-values | `-adj, --adjusted` | Apply FDR correction | false | +| Fold Change | `-fc, --fChange` | Minimum fold change threshold | 1.5 | + +### Visualization Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Map Choice | `-mc, --choice_map` | Built-in metabolic map | HMRcore | +| Custom Map | `-cm, --custom_map` | Path to custom SVG map | - | +| Generate SVG | `-gs, --generate_svg` | Create SVG output | true | +| Generate PDF | `-gp, --generate_pdf` | Create PDF output | true | +| Color Map | `-colorm, --color_map` | Color scheme (jet, viridis) | - | +| Output Directory | `-idop, --output_path` | Results directory | result/ | + +### Advanced Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Output Log | `-ol, --out_log` | Log file path | - | +| Control Sample | `-on, --control` | Control group identifier | - | + +## Input Formats + +### Flux Data File + +Tab-separated format with reactions as rows and samples as columns: + +``` +Reaction Sample1 Sample2 Sample3 Control1 Control2 +R00001 15.23 -8.45 22.1 12.8 14.2 +R00002 0.0 12.67 -5.3 8.9 7.4 +R00003 45.8 38.2 51.7 42.1 39.8 +R00004 -12.4 -15.8 -9.2 -11.5 -13.1 +``` + +### Sample Class File + +Group assignment for statistical comparisons: + +``` +Sample Class +Sample1 Treatment +Sample2 Treatment +Sample3 Treatment +Control1 Control +Control2 Control +``` + +### Multiple Dataset Format + +When using multiple flux files, provide space-separated paths and corresponding names: + +```bash +-idsf "dataset1_flux.tsv dataset2_flux.tsv dataset3_flux.tsv" +-naf "Condition_A Condition_B Condition_C" +``` + +## Statistical Analysis + +### Comparison Types + +#### manyvsmany +Compare all possible group pairs: +- Treatment vs Control +- Condition_A vs Condition_B +- Condition_A vs Condition_C +- Condition_B vs Condition_C + +#### onevsrest +Compare each group against all others combined: +- Treatment vs (Control + Other) +- Control vs (Treatment + Other) + +#### onevsmany +Compare one reference group against each other group: +- Control vs Treatment +- Control vs Condition_A +- Control vs Condition_B + +### Statistical Tests + +| Test | Description | Best For | +|------|-------------|----------| +| `ks` | Kolmogorov-Smirnov | Non-parametric, distribution-free | +| `ttest_p` | Paired t-test | Related samples, normal distributions | +| `ttest_ind` | Independent t-test | Independent samples, normal distributions | +| `wilcoxon` | Wilcoxon signed-rank | Non-parametric paired comparisons | +| `mw` | Mann-Whitney U | Non-parametric independent comparisons | + +### Significance Assessment + +Reactions are considered significant when: +1. **P-value** ≤ specified threshold (default: 0.1) +2. **Fold change** ≥ specified threshold (default: 1.5) +3. **FDR correction** (if enabled) maintains significance + +## Map Visualization + +### Built-in Maps + +#### HMRcore (Default) +- **Scope**: Core human metabolic network +- **Reactions**: ~300 essential reactions +- **Coverage**: Central carbon, amino acid, lipid metabolism +- **Use Case**: General overview, publication figures + +#### ENGRO2 +- **Scope**: Extended human genome-scale reconstruction +- **Reactions**: ~2,000 reactions +- **Coverage**: Comprehensive metabolic network +- **Use Case**: Detailed analysis, specialized tissues + +#### Custom Maps +User-provided SVG files with reaction elements: +```xml +<rect id="R00001" class="reaction" fill="gray" stroke="black"/> +<path id="R00002" class="reaction" fill="gray" stroke="black"/> +``` + +### Color Coding Scheme + +#### Significance Colors +- **Red Gradient**: Significantly upregulated (positive fold change) +- **Blue Gradient**: Significantly downregulated (negative fold change) +- **Gray**: Not statistically significant +- **White**: No data available + +#### Visual Elements +- **Line Width**: Proportional to fold change magnitude +- **Color Intensity**: Proportional to statistical significance (-log10 p-value) +- **Transparency**: Indicates confidence level + +### Color Maps + +#### Jet (Default) +- High contrast color transitions +- Blue (low) → Green → Yellow → Red (high) +- Good for identifying extreme values + +#### Viridis +- Perceptually uniform color scale +- Colorblind-friendly +- Purple (low) → Blue → Green → Yellow (high) + +## Output Files + +### Statistical Results +- `flux_statistics.tsv`: P-values, fold changes, test statistics for all reactions +- `significant_fluxes.tsv`: Only reactions meeting significance criteria +- `comparison_summary.txt`: Analysis parameters and summary statistics + +### Visualizations +- `flux_map.svg`: Interactive color-coded pathway map +- `flux_map.pdf`: High-resolution PDF (if requested) +- `flux_map.png`: Raster image (if requested) +- `legend.svg`: Color scale and statistical significance legend + +### Analysis Files +- `fold_changes.tsv`: Detailed fold change calculations +- `group_statistics.tsv`: Per-group summary statistics +- `comparison_matrix.tsv`: Pairwise comparison results + +## Examples + +### Basic Flux Comparison + +```bash +# Compare treatment vs control fluxes +flux_to_map -td /opt/COBRAxy \ + -idf treatment_vs_control_fluxes.tsv \ + -icf sample_groups.tsv \ + -co manyvsmany \ + -te ks \ + -pv 0.05 \ + -fc 2.0 \ + -mc HMRcore \ + -gs true \ + -gp true \ + -idop flux_comparison/ +``` + +### Multiple Condition Analysis + +```bash +# Compare multiple experimental conditions +flux_to_map -td /opt/COBRAxy \ + -idsf "cond1_flux.tsv cond2_flux.tsv cond3_flux.tsv" \ + -naf "Control Treatment1 Treatment2" \ + -co onevsrest \ + -te wilcoxon \ + -adj true \ + -pv 0.01 \ + -fc 1.8 \ + -mc ENGRO2 \ + -colorm viridis \ + -idop multi_condition_flux/ +``` + +### Custom Map Visualization + +```bash +# Use tissue-specific custom map +flux_to_map -td /opt/COBRAxy \ + -idf liver_flux_data.tsv \ + -icf liver_conditions.tsv \ + -co manyvsmany \ + -te ttest_ind \ + -pv 0.05 \ + -fc 1.5 \ + -cm maps/liver_specific_map.svg \ + -gs true \ + -gp true \ + -idop liver_flux_analysis/ \ + -ol liver_analysis.log +``` + +### High-Throughput Analysis + +```bash +# Process multiple datasets with stringent criteria +flux_to_map -td /opt/COBRAxy \ + -idsf "exp1.tsv exp2.tsv exp3.tsv exp4.tsv" \ + -naf "Exp1 Exp2 Exp3 Exp4" \ + -co manyvsmany \ + -te ks \ + -adj true \ + -pv 0.001 \ + -fc 3.0 \ + -mc HMRcore \ + -colorm jet \ + -gs true \ + -gp true \ + -idop high_throughput_flux/ +``` + +## Quality Control + +### Data Validation + +#### Pre-analysis Checks +- Verify flux value distributions (check for outliers) +- Ensure sample names match between data and class files +- Validate reaction coverage across samples +- Check for missing values and their patterns + +#### Statistical Validation +- Assess normality assumptions for parametric tests +- Verify adequate sample sizes per group (n≥3 recommended) +- Check variance homogeneity between groups +- Evaluate multiple testing burden + +### Result Interpretation + +#### Biological Validation +- Compare results with known pathway activities +- Check for pathway coherence (related reactions should cluster) +- Validate against literature or experimental evidence +- Assess metabolic network connectivity + +#### Technical Validation +- Compare results across different statistical tests +- Check sensitivity to parameter changes +- Validate fold change calculations +- Verify map element correspondence + +## Tips and Best Practices + +### Data Preparation +- **Normalization**: Ensure consistent flux units across samples +- **Filtering**: Remove reactions with excessive missing values (>50%) +- **Outlier Detection**: Identify and handle extreme flux values +- **Batch Effects**: Account for technical variation between experiments + +### Statistical Considerations +- Use FDR correction for multiple comparisons (`-adj true`) +- Choose appropriate statistical tests based on data distribution +- Consider effect size (fold change) alongside significance +- Validate results with independent datasets when possible + +### Visualization Optimization +- Select appropriate color maps for your audience +- Use high fold change thresholds (>2.0) for cleaner maps +- Export both SVG (editable) and PDF (publication) formats +- Include comprehensive legends and annotations + +### Performance Tips +- Use HMRcore for faster processing and clearer visualizations +- Reduce dataset size for initial exploratory analysis +- Process large datasets in batches if memory constrained +- Cache intermediate results for parameter optimization + +## Integration Workflow + +### Upstream Tools +- [Flux Simulation](flux-simulation.md) - Generate flux distributions for comparison +- [MAREA](marea.md) - Alternative analysis pathway for RAS/RPS data + +### Downstream Analysis +- Export results to statistical software (R, Python) for advanced analysis +- Integrate with pathway databases (KEGG, Reactome) +- Combine with other omics data for systems-level insights + +### Typical Pipeline + +```bash +# 1. Generate flux samples from constrained models +flux_simulation -td /opt/COBRAxy -ms ENGRO2 -in bounds/*.tsv \ + -ni Sample1,Sample2,Control1,Control2 -a CBS \ + -ot mean -idop fluxes/ + +# 2. Analyze and visualize flux differences +flux_to_map -td /opt/COBRAxy -idf fluxes/mean.csv \ + -icf sample_groups.tsv -co manyvsmany -te ks \ + -mc HMRcore -gs true -gp true -idop flux_maps/ + +# 3. Further analysis with custom scripts +python analyze_flux_results.py -i flux_maps/ -o final_results/ +``` + +## Troubleshooting + +### Common Issues + +**No significant reactions found** +- Lower p-value threshold (`-pv 0.2`) +- Reduce fold change requirement (`-fc 1.2`) +- Check sample group definitions and sizes +- Verify flux data quality and normalization + +**Map rendering problems** +- Check SVG map file integrity and format +- Verify reaction ID matching between data and map +- Ensure sufficient system memory for large maps +- Validate XML structure of custom maps + +**Statistical test failures** +- Check data distribution assumptions +- Verify sufficient sample sizes per group +- Consider alternative non-parametric tests +- Examine variance patterns between groups + +### Error Messages + +| Error | Cause | Solution | +|-------|-------|----------| +| "Map file not found" | Missing/invalid map path | Check file location and format | +| "No matching reactions" | ID mismatch between data and map | Verify reaction naming consistency | +| "Insufficient data" | Too few samples per group | Increase sample sizes or merge groups | +| "Memory allocation failed" | Large dataset/map combination | Reduce data size or increase system memory | + +### Performance Issues + +**Slow processing** +- Use HMRcore instead of ENGRO2 for faster rendering +- Reduce dataset size for testing +- Process subsets of reactions separately +- Monitor system resource usage + +**Large output files** +- Use compressed formats when possible +- Reduce map resolution for preliminary analysis +- Export only essential output formats +- Clean temporary files regularly + +## Advanced Usage + +### Custom Statistical Functions + +Advanced users can implement custom statistical tests by modifying the analysis functions: + +```python +def custom_test(group1, group2): + # Custom statistical test implementation + statistic, pvalue = your_test_function(group1, group2) + return statistic, pvalue +``` + +### Batch Processing Script + +Process multiple experiments systematically: + +```bash +#!/bin/bash +experiments=("exp1" "exp2" "exp3" "exp4") +for exp in "${experiments[@]}"; do + flux_to_map -td /opt/COBRAxy \ + -idf "data/${exp}_flux.tsv" \ + -icf "data/${exp}_classes.tsv" \ + -co manyvsmany -te ks -pv 0.05 \ + -mc HMRcore -gs true -gp true \ + -idop "results/${exp}/" +done +``` + +### Result Aggregation + +Combine results across multiple analyses: + +```bash +# Merge significant reactions across experiments +python merge_flux_results.py \ + -i results/exp*/significant_fluxes.tsv \ + -o combined_significant_reactions.tsv \ + --method intersection +``` + +## See Also + +- [Flux Simulation](flux-simulation.md) - Generate input flux distributions +- [MAREA](marea.md) - Alternative pathway analysis approach +- [Custom Map Creation Guide](../tutorials/custom-map-creation.md) +- [Statistical Methods Reference](../tutorials/statistical-methods.md) \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/marea-cluster.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,512 @@ +# MAREA Cluster + +Perform clustering analysis on metabolic data to identify sample groups and patterns. + +## Overview + +MAREA Cluster performs unsupervised clustering analysis on RAS, RPS, or flux data to identify natural groupings among samples. It supports multiple clustering algorithms (K-means, DBSCAN, Hierarchical) with optional data scaling and validation metrics including elbow plots and silhouette analysis. + +## Usage + +### Command Line + +```bash +marea_cluster -td /path/to/COBRAxy \ + -in metabolic_data.tsv \ + -cy kmeans \ + -sc true \ + -k1 2 \ + -k2 8 \ + -el true \ + -si true \ + -idop clustering_results/ \ + -ol cluster.log +``` + +### Galaxy Interface + +Select "MAREA Cluster" from the COBRAxy tool suite and configure clustering parameters through the web interface. + +## Parameters + +### Required Parameters + +| Parameter | Flag | Description | +|-----------|------|-------------| +| Tool Directory | `-td, --tool_dir` | Path to COBRAxy installation directory | +| Input Data | `-in, --input` | Metabolic data file (TSV format) | + +### Clustering Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Cluster Type | `-cy, --cluster_type` | Clustering algorithm | kmeans | +| Data Scaling | `-sc, --scaling` | Apply data normalization | true | +| Minimum K | `-k1, --k_min` | Minimum number of clusters | 2 | +| Maximum K | `-k2, --k_max` | Maximum number of clusters | 7 | + +### Analysis Options + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Elbow Plot | `-el, --elbow` | Generate elbow plot for K-means | false | +| Silhouette Analysis | `-si, --silhouette` | Generate silhouette plots | false | + +### DBSCAN Specific Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Min Samples | `-ms, --min_samples` | Minimum samples per cluster | - | +| Epsilon | `-ep, --eps` | Maximum distance between samples | - | + +### Output Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Output Path | `-idop, --output_path` | Results directory | clustering/ | +| Output Log | `-ol, --out_log` | Log file path | - | +| Best Cluster | `-bc, --best_cluster` | Best clustering result file | - | + +## Clustering Algorithms + +### K-means +**Method**: Partitional clustering using centroids +- Assumes spherical clusters +- Requires pre-specified number of clusters (k) +- Fast and scalable +- Works well with normalized data + +**Best for**: +- Well-separated, compact clusters +- Large datasets +- When cluster number is approximately known + +### DBSCAN +**Method**: Density-based clustering +- Identifies clusters of varying shapes +- Automatically determines cluster number +- Robust to outliers and noise +- Requires epsilon and min_samples parameters + +**Best for**: +- Irregular cluster shapes +- Datasets with noise/outliers +- Unknown number of clusters + +### Hierarchical +**Method**: Agglomerative clustering with dendrograms +- Creates tree-like cluster hierarchy +- No need to specify cluster number initially +- Deterministic results +- Provides multiple resolution levels + +**Best for**: +- Small to medium datasets +- When cluster hierarchy is important +- Exploratory analysis + +## Input Format + +### Metabolic Data File + +Tab-separated format with samples as rows and reactions/metabolites as columns: + +``` +Sample R00001 R00002 R00003 R00004 ... +Sample1 1.25 0.85 1.42 0.78 ... +Sample2 0.65 1.35 0.72 1.28 ... +Sample3 2.15 2.05 0.45 0.52 ... +Control1 1.05 0.98 1.15 1.08 ... +Control2 0.95 1.12 0.88 0.92 ... +``` + +**Requirements**: +- First column: sample identifiers +- Subsequent columns: feature values (RAS, RPS, fluxes) +- Missing values: use 0 or leave empty +- Numeric data only (excluding sample names) + +## Data Preprocessing + +### Scaling Options + +#### Standard Scaling (Recommended) +- Mean centering and unit variance scaling +- Formula: `(x - mean) / std` +- Ensures equal feature contribution +- Required for distance-based algorithms + +#### No Scaling +- Use original data values +- May be appropriate for already normalized data +- Risk of feature dominance by high-magnitude variables + +### Feature Selection + +Consider preprocessing steps: +- Remove low-variance features +- Apply dimensionality reduction (PCA) +- Select most variable reactions/metabolites +- Handle missing data appropriately + +## Output Files + +### Cluster Assignments + +#### Best Clustering Result (`best_clusters.tsv`) +``` +Sample Cluster Silhouette_Score +Sample1 1 0.73 +Sample2 1 0.68 +Sample3 2 0.81 +Control1 0 0.59 +Control2 0 0.62 +``` + +#### All K Results (`clustering_results_k{n}.tsv`) +Individual files for each tested cluster number. + +### Validation Metrics + +#### Elbow Plot (`elbow_plot.png`) +- X-axis: Number of clusters (k) +- Y-axis: Within-cluster sum of squares (WCSS) +- Identifies optimal k at the "elbow" point + +#### Silhouette Plots (`silhouette_k{n}.png`) +- Individual sample silhouette scores +- Average silhouette width per cluster +- Overall clustering quality assessment + +### Summary Statistics + +#### Clustering Summary (`clustering_summary.txt`) +``` +Algorithm: kmeans +Scaling: true +Optimal K: 3 +Best Silhouette Score: 0.72 +Number of Samples: 20 +Feature Dimensions: 150 +``` + +#### Cluster Characteristics (`cluster_stats.tsv`) +``` +Cluster Size Centroid_R00001 Centroid_R00002 Avg_Silhouette +0 8 0.95 1.12 0.68 +1 7 1.35 0.82 0.74 +2 5 0.65 1.55 0.69 +``` + +## Examples + +### Basic K-means Clustering + +```bash +# Simple K-means with elbow analysis +marea_cluster -td /opt/COBRAxy \ + -in ras_data.tsv \ + -cy kmeans \ + -sc true \ + -k1 2 \ + -k2 10 \ + -el true \ + -si true \ + -idop kmeans_results/ \ + -ol kmeans.log +``` + +### DBSCAN Analysis + +```bash +# Density-based clustering with custom parameters +marea_cluster -td /opt/COBRAxy \ + -in flux_samples.tsv \ + -cy dbscan \ + -sc true \ + -ms 5 \ + -ep 0.5 \ + -idop dbscan_results/ \ + -bc best_dbscan_clusters.tsv \ + -ol dbscan.log +``` + +### Hierarchical Clustering + +```bash +# Hierarchical clustering for small dataset +marea_cluster -td /opt/COBRAxy \ + -in rps_scores.tsv \ + -cy hierarchy \ + -sc true \ + -k1 2 \ + -k2 6 \ + -si true \ + -idop hierarchical_results/ \ + -ol hierarchy.log +``` + +### Comprehensive Clustering Analysis + +```bash +# Compare multiple algorithms +algorithms=("kmeans" "dbscan" "hierarchy") +for alg in "${algorithms[@]}"; do + marea_cluster -td /opt/COBRAxy \ + -in metabolomics_data.tsv \ + -cy "$alg" \ + -sc true \ + -k1 2 \ + -k2 8 \ + -el true \ + -si true \ + -idop "${alg}_clustering/" \ + -ol "${alg}_cluster.log" +done +``` + +## Parameter Optimization + +### K-means Optimization + +#### Elbow Method +1. Run K-means for k = 2 to k_max +2. Plot WCSS vs k +3. Identify "elbow" point where improvement diminishes +4. Select k at elbow as optimal + +#### Silhouette Analysis +1. Compute silhouette scores for each k +2. Select k with highest average silhouette score +3. Validate with silhouette plots +4. Ensure clusters are well-separated + +### DBSCAN Parameter Tuning + +#### Epsilon (eps) Selection +- Use k-distance plot to identify knee point +- Start with eps = average distance to k-th nearest neighbor +- Adjust based on cluster quality metrics + +#### Min Samples Selection +- Rule of thumb: min_samples ≥ dimensionality + 1 +- Higher values create denser clusters +- Lower values may increase noise sensitivity + +### Hierarchical Clustering + +#### Linkage Method +- Ward: Minimizes within-cluster variance +- Complete: Maximum distance between clusters +- Average: Mean distance between clusters +- Single: Minimum distance (prone to chaining) + +## Quality Assessment + +### Internal Validation Metrics + +#### Silhouette Score +- Range: [-1, 1] +- >0.7: Strong clustering +- 0.5-0.7: Reasonable clustering +- <0.5: Weak clustering + +#### Calinski-Harabasz Index +- Higher values indicate better clustering +- Ratio of between-cluster to within-cluster variance + +#### Davies-Bouldin Index +- Lower values indicate better clustering +- Average similarity between clusters + +### External Validation + +When ground truth labels available: +- Adjusted Rand Index (ARI) +- Normalized Mutual Information (NMI) +- Homogeneity and Completeness scores + +## Biological Interpretation + +### Cluster Characterization + +#### Metabolic Pathway Analysis +- Identify enriched pathways per cluster +- Compare metabolic profiles between clusters +- Relate clusters to biological conditions + +#### Sample Annotation +- Map clusters to experimental conditions +- Identify batch effects or confounders +- Validate with independent datasets + +#### Feature Importance +- Determine reactions/metabolites driving clustering +- Analyze cluster centroids for biological insights +- Connect to known metabolic phenotypes + +## Integration Workflow + +### Upstream Data Sources + +#### COBRAxy Tools +- [RAS Generator](ras-generator.md) - Cluster based on reaction activities +- [RPS Generator](rps-generator.md) - Cluster based on reaction propensities +- [Flux Simulation](flux-simulation.md) - Cluster flux distributions + +#### External Data +- Gene expression matrices +- Metabolomics datasets +- Clinical metadata + +### Downstream Analysis + +#### Supervised Learning +Use cluster labels for: +- Classification model training +- Biomarker discovery +- Outcome prediction + +#### Differential Analysis +- Compare clusters with [MAREA](marea.md) +- Identify cluster-specific metabolic signatures +- Pathway enrichment analysis + +### Typical Pipeline + +```bash +# 1. Generate metabolic scores +ras_generator -td /opt/COBRAxy -in expression.tsv -ra ras.tsv + +# 2. Perform clustering analysis +marea_cluster -td /opt/COBRAxy -in ras.tsv -cy kmeans \ + -sc true -k1 2 -k2 8 -el true -si true \ + -idop clusters/ -bc best_clusters.tsv + +# 3. Analyze cluster differences +marea -td /opt/COBRAxy -input_data ras.tsv \ + -input_class best_clusters.tsv -comparison manyvsmany \ + -test ks -choice_map ENGRO2 -idop cluster_analysis/ +``` + +## Tips and Best Practices + +### Data Preparation +- **Normalization**: Always scale features for distance-based methods +- **Dimensionality**: Consider PCA for high-dimensional data (>1000 features) +- **Missing Values**: Handle appropriately (imputation or removal) +- **Outliers**: Identify and consider removal for K-means + +### Algorithm Selection +- **K-means**: Start here for most applications +- **DBSCAN**: Use when clusters have irregular shapes or noise present +- **Hierarchical**: Choose for small datasets or when hierarchy matters + +### Parameter Selection +- **Start Simple**: Begin with default parameters +- **Use Validation**: Always employ silhouette analysis +- **Cross-Validate**: Test stability across parameter ranges +- **Biological Validation**: Ensure clusters make biological sense + +### Result Interpretation +- **Multiple Algorithms**: Compare results across methods +- **Stability Assessment**: Check clustering reproducibility +- **Biological Context**: Integrate with known sample characteristics +- **Statistical Testing**: Validate cluster differences formally + +## Troubleshooting + +### Common Issues + +**Poor clustering quality** +- Check data scaling and normalization +- Assess feature selection and dimensionality +- Try different algorithms or parameters +- Evaluate data structure with PCA/t-SNE + +**Algorithm doesn't converge** +- Increase iteration limits for K-means +- Adjust epsilon/min_samples for DBSCAN +- Check for numerical stability issues +- Verify input data format + +**Memory or performance issues** +- Reduce dataset size or dimensionality +- Use sampling for large datasets +- Consider approximate algorithms +- Monitor system resources + +### Error Messages + +| Error | Cause | Solution | +|-------|-------|----------| +| "Convergence failed" | K-means iteration limit | Increase max iterations or check data | +| "No clusters found" | DBSCAN parameters too strict | Reduce eps or min_samples | +| "Memory allocation error" | Dataset too large | Reduce size or increase memory | +| "Invalid silhouette score" | Single cluster found | Adjust parameters or algorithm | + +### Performance Optimization + +**Large Datasets** +- Use mini-batch K-means for speed +- Sample data for parameter optimization +- Employ dimensionality reduction +- Consider distributed computing + +**High-Dimensional Data** +- Apply feature selection +- Use PCA preprocessing +- Consider specialized algorithms +- Validate results carefully + +## Advanced Usage + +### Custom Distance Metrics + +For specialized applications, modify distance calculations: + +```python +# Custom distance function for metabolic data +def metabolic_distance(x, y): + # Implement pathway-aware distance metric + return custom_distance_value +``` + +### Ensemble Clustering + +Combine multiple clustering results: + +```bash +# Run multiple algorithms and combine +for method in kmeans dbscan hierarchy; do + marea_cluster -cy $method -in data.tsv -idop ${method}_results/ +done + +# Consensus clustering (requires custom script) +python consensus_clustering.py -i *_results/best_clusters.tsv -o consensus.tsv +``` + +### Interactive Analysis + +Generate interactive plots for exploration: + +```python +import plotly.express as px +import pandas as pd + +# Load clustering results +results = pd.read_csv('best_clusters.tsv', sep='\t') +data = pd.read_csv('metabolic_data.tsv', sep='\t') + +# Interactive scatter plot +fig = px.scatter(data, x='PC1', y='PC2', color=results['Cluster']) +fig.show() +``` + +## See Also + +- [MAREA](marea.md) - Statistical analysis of cluster differences +- [RAS Generator](ras-generator.md) - Generate clustering input data +- [Flux Simulation](flux-simulation.md) - Alternative clustering data source +- [Clustering Tutorial](../tutorials/clustering-analysis.md) +- [Validation Methods Reference](../tutorials/cluster-validation.md) \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/marea.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,279 @@ +# MAREA + +Metabolic Reaction Enrichment Analysis for statistical comparison and map visualization. + +## Overview + +MAREA performs statistical enrichment analysis on RAS/RPS data to identify significantly different metabolic reactions between sample groups. It generates enriched pathway maps with color-coded reactions showing statistical significance and fold changes. + +## Usage + +### Command Line + +```bash +marea -td /path/to/COBRAxy \ + -using_RAS true \ + -input_data ras_data.tsv \ + -input_class class_labels.tsv \ + -comparison manyvsmany \ + -test ks \ + -pv 0.05 \ + -fc 1.5 \ + -choice_map ENGRO2 \ + -generate_svg true \ + -idop results/ +``` + +### Galaxy Interface + +Select "MAREA" from the COBRAxy tool suite and configure analysis parameters through the web interface. + +## Parameters + +### Required Parameters + +| Parameter | Flag | Description | +|-----------|------|-------------| +| Tool Directory | `-td, --tool_dir` | Path to COBRAxy installation directory | + +### Data Input Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Use RAS | `-using_RAS, --using_RAS` | Include RAS analysis | true | +| RAS Data | `-input_data, --input_data` | RAS scores TSV file | - | +| RAS Classes | `-input_class, --input_class` | Sample group labels | - | +| Multiple RAS | `-input_datas, --input_datas` | Multiple RAS files (space-separated) | - | +| RAS Names | `-names, --names` | Names for multiple datasets | - | +| Use RPS | `-using_RPS, --using_RPS` | Include RPS analysis | false | +| RPS Data | `-input_data_rps, --input_data_rps` | RPS scores TSV file | - | +| RPS Classes | `-input_class_rps, --input_class_rps` | RPS sample groups | - | + +### Statistical Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Comparison Type | `-co, --comparison` | Statistical comparison mode | manyvsmany | +| Statistical Test | `-te, --test` | Statistical test method | ks | +| P-Value Threshold | `-pv, --pValue` | Significance threshold | 0.1 | +| Adjusted P-values | `-adj, --adjusted` | Apply FDR correction | false | +| Fold Change | `-fc, --fChange` | Minimum fold change | 1.5 | +| Net Enrichment | `-ne, --net` | Use net enrichment for RPS | false | +| Analysis Option | `-op, --option` | Analysis mode | datasets | + +### Visualization Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Map Choice | `-choice_map, --choice_map` | Built-in metabolic map | - | +| Custom Map | `-custom_map, --custom_map` | Path to custom SVG map | - | +| Generate SVG | `-gs, --generate_svg` | Create SVG output | true | +| Generate PDF | `-gp, --generate_pdf` | Create PDF output | false | +| Generate PNG | `-gpng, --generate_png` | Create PNG output | false | +| Color Map | `-colorm, --color_map` | Color scheme (jet/viridis) | jet | +| Output Directory | `-idop, --output_path` | Results directory | result/ | + +### Advanced Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Output Log | `-ol, --out_log` | Log file path | - | +| Control Sample | `-on, --control` | Control group identifier | - | + +## Input Formats + +### RAS/RPS Data File + +Tab-separated format with reactions as rows and samples as columns: + +``` +Reaction Sample1 Sample2 Sample3 Sample4 +R00001 1.25 0.85 1.42 0.78 +R00002 0.65 1.35 0.72 1.28 +R00003 2.15 2.05 0.45 0.52 +``` + +### Class Labels File + +Sample grouping information: + +``` +Sample Class +Sample1 Control +Sample2 Treatment +Sample3 Control +Sample4 Treatment +``` + +## Comparison Types + +### manyvsmany +Compare all possible pairs of groups: +- Group A vs Group B +- Group A vs Group C +- Group B vs Group C + +### onevsrest +Compare each group against all others combined: +- Group A vs (Group B + Group C) +- Group B vs (Group A + Group C) + +### onevsmany +Compare one specific group against each other group separately: +- Control vs Treatment1 +- Control vs Treatment2 + +## Statistical Tests + +| Test | Description | Use Case | +|------|-------------|----------| +| `ks` | Kolmogorov-Smirnov | Non-parametric, distribution-free | +| `ttest_p` | Paired t-test | Related samples | +| `ttest_ind` | Independent t-test | Unrelated samples | +| `wilcoxon` | Wilcoxon signed-rank | Non-parametric paired | +| `mw` | Mann-Whitney U | Non-parametric independent | +| `DESeq` | DESeq2-style analysis | Count-like data with dispersion | + +## Output Files + +### Statistical Results +- `comparison_stats.tsv`: P-values, fold changes, and test statistics +- `enriched_reactions.tsv`: Significantly enriched reactions only +- `comparison_summary.txt`: Analysis summary and parameters + +### Visualization +- `pathway_map.svg`: Color-coded metabolic map +- `pathway_map.pdf`: PDF version (if requested) +- `pathway_map.png`: PNG version (if requested) +- `legend.svg`: Color scale and significance indicators + +## Examples + +### Basic RAS Analysis + +```bash +# Simple two-group comparison +marea -td /opt/COBRAxy \ + -using_RAS true \ + -input_data ras_scores.tsv \ + -input_class sample_groups.tsv \ + -comparison manyvsmany \ + -test ks \ + -pv 0.05 \ + -choice_map ENGRO2 \ + -idop results/ +``` + +### Combined RAS + RPS Analysis + +```bash +# Multi-modal analysis +marea -td /opt/COBRAxy \ + -using_RAS true \ + -input_data ras_scores.tsv \ + -input_class ras_groups.tsv \ + -using_RPS true \ + -input_data_rps rps_scores.tsv \ + -input_class_rps rps_groups.tsv \ + -comparison onevsrest \ + -test DESeq \ + -adj true \ + -fc 2.0 \ + -choice_map HMRcore \ + -generate_pdf true \ + -idop multimodal_results/ +``` + +### Multiple Dataset Analysis + +```bash +# Compare multiple experiments +marea -td /opt/COBRAxy \ + -using_RAS true \ + -input_datas exp1_ras.tsv exp2_ras.tsv exp3_ras.tsv \ + -names "Experiment1" "Experiment2" "Experiment3" \ + -comparison onevsmany \ + -test wilcoxon \ + -pv 0.01 \ + -custom_map custom_pathway.svg \ + -idop multi_experiment/ +``` + +## Map Visualization + +### Built-in Maps +- **ENGRO2**: Human genome-scale reconstruction +- **HMRcore**: Core human metabolic network +- **Recon**: Recon3D human model + +### Color Coding +- **Red**: Significantly upregulated (high activity) +- **Blue**: Significantly downregulated (low activity) +- **Gray**: Not significant +- **Line Width**: Proportional to fold change magnitude + +### Custom Maps +SVG files with reaction elements having IDs matching your data: +```xml +<rect id="R00001" class="reaction" .../> +<path id="R00002" class="reaction" .../> +``` + +## Quality Control + +### Pre-analysis Checks +- Verify sample names match between data and class files +- Check for missing values and outliers +- Ensure adequate sample sizes per group (n ≥ 3 recommended) + +### Post-analysis Validation +- Review statistical distribution assumptions +- Check multiple testing correction effects +- Validate biological relevance of enriched pathways + +## Tips and Best Practices + +### Statistical Considerations +- Use FDR correction (`-adj true`) for multiple comparisons +- Choose appropriate tests based on data distribution +- Consider effect size alongside significance + +### Visualization Optimization +- Use high fold change thresholds (>2.0) for cleaner maps +- Export both SVG (editable) and PDF (publication-ready) formats +- Adjust color schemes for colorblind accessibility + +## Troubleshooting + +### Common Issues + +**No significant reactions found** +- Lower p-value threshold (`-pv 0.1`) +- Reduce fold change requirement (`-fc 1.2`) +- Check sample group definitions + +**Map rendering errors** +- Verify SVG map file integrity +- Check reaction ID matching between data and map +- Ensure sufficient system memory for large maps + +**Statistical test failures** +- Verify data normality for parametric tests +- Check for sufficient sample sizes +- Consider alternative test methods + +## Integration + +### Upstream Tools +- [RAS Generator](ras-generator.md) - Generate RAS scores +- [RPS Generator](rps-generator.md) - Generate RPS scores + +### Downstream Analysis +- [Flux to Map](flux-to-map.md) - Additional visualization options +- [MAREA Cluster](marea-cluster.md) - Sample clustering analysis + +## See Also + +- [Statistical Tests Documentation](../tutorials/statistical-tests.md) +- [Map Customization Guide](../tutorials/custom-maps.md) +- [Multi-modal Analysis Tutorial](../tutorials/multimodal-analysis.md) \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/metabolic-model-setting.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,425 @@ +# Metabolic Model Setting + +Extract and organize metabolic model components into tabular format for analysis and integration. + +## Overview + +Metabolic Model Setting (metabolicModel2Tabular) extracts key components from SBML metabolic models and generates comprehensive tabular summaries. This tool processes built-in or custom models, applies medium constraints, handles gene nomenclature conversion, and outputs structured data for downstream analysis. + +## Usage + +### Command Line + +```bash +metabolicModel2Tabular --model ENGRO2 \ + --name ENGRO2 \ + --medium_selector allOpen \ + --gene_format Default \ + --out_tabular model_data.csv \ + --out_log extraction.log \ + --tool_dir /path/to/COBRAxy +``` + +### Galaxy Interface + +Select "Metabolic Model Setting" from the COBRAxy tool suite and configure model extraction parameters. + +## Parameters + +### Required Parameters + +| Parameter | Flag | Description | +|-----------|------|-------------| +| Model Name | `--name` | Model identifier for output files | +| Medium Selector | `--medium_selector` | Medium configuration option | +| Output Tabular | `--out_tabular` | Output file path (CSV or XLSX) | +| Output Log | `--out_log` | Log file for processing information | +| Tool Directory | `--tool_dir` | COBRAxy installation directory | + +### Model Selection Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Built-in Model | `--model` | Pre-installed model (ENGRO2, Recon, HMRcore) | - | +| Custom Model | `--input` | Path to custom SBML/JSON model file | - | + +**Note**: Provide either `--model` OR `--input`, not both. + +### Optional Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Gene Format | `--gene_format` | Gene ID format conversion | Default | + +## Model Selection + +### Built-in Models + +#### ENGRO2 +- **Species**: Homo sapiens +- **Scope**: Genome-scale reconstruction +- **Reactions**: ~2,000 reactions +- **Metabolites**: ~1,500 metabolites +- **Coverage**: Comprehensive human metabolism + +#### Recon +- **Species**: Homo sapiens +- **Scope**: Recon3D human reconstruction +- **Reactions**: ~10,000+ reactions +- **Metabolites**: ~5,000+ metabolites +- **Coverage**: Most comprehensive human model + +#### HMRcore +- **Species**: Homo sapiens +- **Scope**: Core metabolic network +- **Reactions**: ~300 essential reactions +- **Metabolites**: ~200 core metabolites +- **Coverage**: Central carbon and energy metabolism + +### Custom Models + +Supported formats for custom model import: +- **SBML**: Systems Biology Markup Language (.xml, .sbml) +- **JSON**: COBRApy JSON format (.json) +- **MAT**: MATLAB format (.mat) +- **YML**: YAML format (.yml, .yaml) +- **Compressed**: All formats support .gz, .zip, .bz2 compression + +## Medium Configuration + +### allOpen (Default) +- All exchange reactions unconstrained +- Maximum metabolic flexibility +- Suitable for general analysis + +### Custom Medium +User can specify custom medium constraints through Galaxy interface or by modifying the tool configuration. + +## Gene Format Options + +| Format | Description | Example | +|--------|-------------|---------| +| Default | Original model gene IDs | As stored in model | +| ENSNG | Ensembl Gene IDs | ENSG00000139618 | +| HGNC_SYMBOL | HUGO Gene Symbols | BRCA2 | +| HGNC_ID | HUGO Gene Committee IDs | HGNC:1101 | +| ENTREZ | NCBI Entrez Gene IDs | 675 | + +Gene format conversion uses internal mapping tables and may not cover all genes in custom models. + +## Output Format + +### Tabular Summary File + +The output contains comprehensive model information in CSV or XLSX format: + +#### Column Structure +``` +Reaction_ID GPR_Rule Reaction_Formula Lower_Bound Upper_Bound Objective_Coefficient Medium_Member Compartment Subsystem +R00001 GENE1 or GENE2 A + B -> C + D -1000.0 1000.0 0.0 FALSE cytosol Glycolysis +R00002 GENE3 and GENE4 E <-> F -1000.0 1000.0 0.0 FALSE mitochondria TCA_Cycle +EX_glc_e - glc_e <-> -1000.0 1000.0 0.0 TRUE extracellular Exchange +``` + +#### Data Fields + +| Field | Description | Values | +|-------|-------------|---------| +| Reaction_ID | Unique reaction identifier | String | +| GPR_Rule | Gene-protein-reaction association | Logical expression | +| Reaction_Formula | Stoichiometric equation | Metabolites with coefficients | +| Lower_Bound | Minimum flux constraint | Numeric (typically -1000) | +| Upper_Bound | Maximum flux constraint | Numeric (typically 1000) | +| Objective_Coefficient | Biomass/objective weight | Numeric (0 or 1) | +| Medium_Member | Exchange reaction flag | TRUE/FALSE | +| Compartment | Subcellular location | String (for ENGRO2 only) | +| Subsystem | Metabolic pathway | String | + +## Examples + +### Extract Built-in Model Data + +```bash +# Extract ENGRO2 model with default settings +metabolicModel2Tabular --model ENGRO2 \ + --name ENGRO2_extraction \ + --medium_selector allOpen \ + --gene_format Default \ + --out_tabular ENGRO2_data.csv \ + --out_log ENGRO2_log.txt \ + --tool_dir /opt/COBRAxy +``` + +### Process Custom Model + +```bash +# Extract custom SBML model with gene conversion +metabolicModel2Tabular --input /data/custom_model.xml \ + --name CustomModel \ + --medium_selector allOpen \ + --gene_format HGNC_SYMBOL \ + --out_tabular custom_model_data.xlsx \ + --out_log custom_extraction.log \ + --tool_dir /opt/COBRAxy +``` + +### Extract Core Model for Quick Analysis + +```bash +# Extract HMRcore for rapid prototyping +metabolicModel2Tabular --model HMRcore \ + --name CoreModel \ + --medium_selector allOpen \ + --gene_format ENSNG \ + --out_tabular core_reactions.csv \ + --out_log core_log.txt \ + --tool_dir /opt/COBRAxy +``` + +### Batch Processing Multiple Models + +```bash +#!/bin/bash +models=("ENGRO2" "HMRcore" "Recon") +for model in "${models[@]}"; do + metabolicModel2Tabular --model "$model" \ + --name "${model}_extract" \ + --medium_selector allOpen \ + --gene_format HGNC_SYMBOL \ + --out_tabular "${model}_data.csv" \ + --out_log "${model}_log.txt" \ + --tool_dir /opt/COBRAxy +done +``` + +## Use Cases + +### Model Comparison +Extract multiple models to compare: +- Reaction coverage across different reconstructions +- Gene-reaction associations +- Pathway representation +- Metabolite compartmentalization + +### Data Integration +Prepare model data for: +- Custom analysis pipelines +- Database integration +- Pathway annotation +- Cross-reference mapping + +### Quality Control +Validate model properties: +- Check reaction balancing +- Verify gene associations +- Assess network connectivity +- Identify missing annotations + +### Custom Analysis +Export structured data for: +- Network analysis (graph theory) +- Machine learning applications +- Statistical modeling +- Comparative genomics + +## Integration Workflow + +### Downstream Tools + +The extracted tabular data serves as input for: + +#### COBRAxy Tools +- [RAS Generator](ras-generator.md) - Use extracted GPR rules +- [RPS Generator](rps-generator.md) - Use reaction formulas +- [RAS to Bounds](ras-to-bounds.md) - Use reaction bounds +- [MAREA](marea.md) - Use reaction annotations + +#### External Analysis +- **R/Bioconductor**: Import CSV for pathway analysis +- **Python/pandas**: Load data for network analysis +- **MATLAB**: Process XLSX for modeling +- **Cytoscape**: Network visualization +- **Databases**: Populate reaction databases + +### Typical Pipeline + +```bash +# 1. Extract model components +metabolicModel2Tabular --model ENGRO2 --name ModelData \ + --out_tabular model_components.csv + +# 2. Use extracted data for RAS analysis +ras_generator -td /opt/COBRAxy -rs Custom \ + -rl model_components.csv \ + -in expression_data.tsv -ra ras_scores.tsv + +# 3. Apply constraints and sample fluxes +ras_to_bounds -td /opt/COBRAxy -ms Custom -mo model_components.csv \ + -ir ras_scores.tsv -idop constrained_bounds/ + +# 4. Visualize results +marea -td /opt/COBRAxy -input_data ras_scores.tsv \ + -choice_map Custom -custom_map custom.svg -idop results/ +``` + +## Quality Control + +### Pre-extraction Validation +- Verify model file integrity and format +- Check SBML compliance for custom models +- Validate gene ID formats and coverage +- Confirm medium constraint specifications + +### Post-extraction Checks +- **Completeness**: Verify all expected reactions extracted +- **Consistency**: Check stoichiometric balance +- **Annotations**: Validate gene-reaction associations +- **Formatting**: Confirm output file structure + +### Data Validation + +#### Reaction Balancing +```bash +# Check for unbalanced reactions +awk -F'\t' 'NR>1 && $3 !~ /\<->\|->/ {print $1, $3}' model_data.csv +``` + +#### Gene Coverage +```bash +# Count reactions with GPR rules +awk -F'\t' 'NR>1 && $2 != "" {count++} END {print count " reactions with GPR"}' model_data.csv +``` + +#### Exchange Reactions +```bash +# List medium components +awk -F'\t' 'NR>1 && $7 == "TRUE" {print $1}' model_data.csv +``` + +## Tips and Best Practices + +### Model Selection +- **ENGRO2**: Balanced coverage for human tissue analysis +- **HMRcore**: Fast processing for algorithm development +- **Recon**: Comprehensive analysis requiring computational resources +- **Custom**: Organism-specific or specialized models + +### Gene Format Selection +- **Default**: Preserve original model annotations +- **HGNC_SYMBOL**: Human-readable gene names +- **ENSNG**: Stable identifiers for bioinformatics +- **ENTREZ**: Cross-database compatibility + +### Output Format Optimization +- **CSV**: Lightweight, universal compatibility +- **XLSX**: Rich formatting, multiple sheets possible +- Choose based on downstream analysis requirements + +### Performance Considerations +- Large models (Recon) may require substantial memory +- Gene format conversion adds processing time +- Consider batch processing for multiple extractions + +## Troubleshooting + +### Common Issues + +**Model loading fails** +- Check file format and compression +- Verify SBML validity for custom models +- Ensure sufficient system memory + +**Gene format conversion errors** +- Mapping tables may not cover all genes +- Original gene IDs retained when conversion fails +- Check log file for conversion statistics + +**Empty output file** +- Model may contain no reactions +- Check model file integrity +- Verify tool directory configuration + +### Error Messages + +| Error | Cause | Solution | +|-------|-------|----------| +| "Model file not found" | Invalid file path | Check file location and permissions | +| "Unsupported format" | Invalid model format | Use SBML, JSON, MAT, or YML | +| "Gene mapping failed" | Missing gene conversion data | Use Default format or update mappings | +| "Memory allocation error" | Insufficient system memory | Use smaller model or increase memory | + +### Performance Issues + +**Slow processing** +- Large models require more time +- Gene conversion adds overhead +- Monitor system resource usage + +**Memory errors** +- Reduce model size if possible +- Process in smaller batches +- Increase available system memory + +**Output file corruption** +- Check disk space availability +- Verify file write permissions +- Monitor for system interruptions + +## Advanced Usage + +### Custom Gene Mapping + +Advanced users can extend gene format conversion by modifying mapping files in the `local/mappings/` directory. + +### Batch Extraction Script + +```python +#!/usr/bin env python3 +import subprocess +import sys + +models = ['ENGRO2', 'HMRcore', 'Recon'] +formats = ['Default', 'HGNC_SYMBOL', 'ENSNG'] + +for model in models: + for fmt in formats: + cmd = [ + 'metabolicModel2Tabular', + '--model', model, + '--name', f'{model}_{fmt}', + '--medium_selector', 'allOpen', + '--gene_format', fmt, + '--out_tabular', f'{model}_{fmt}.csv', + '--out_log', f'{model}_{fmt}.log', + '--tool_dir', '/opt/COBRAxy' + ] + subprocess.run(cmd, check=True) +``` + +### Database Integration + +Export model data to databases: + +```sql +-- Load CSV into PostgreSQL +CREATE TABLE model_reactions ( + reaction_id VARCHAR(50), + gpr_rule TEXT, + reaction_formula TEXT, + lower_bound FLOAT, + upper_bound FLOAT, + objective_coefficient FLOAT, + medium_member BOOLEAN, + compartment VARCHAR(50), + subsystem VARCHAR(100) +); + +COPY model_reactions FROM 'model_data.csv' WITH CSV HEADER; +``` + +## See Also + +- [RAS Generator](ras-generator.md) - Use extracted GPR rules for RAS computation +- [RPS Generator](rps-generator.md) - Use reaction formulas for RPS analysis +- [Custom Model Tutorial](../tutorials/custom-model-integration.md) +- [Gene Mapping Reference](../tutorials/gene-id-conversion.md) \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/ras-generator.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,320 @@ +# RAS Generator + +Generate Reaction Activity Scores (RAS) from gene expression data and GPR (Gene-Protein-Reaction) rules. + +## Overview + +The RAS Generator computes metabolic reaction activity by: +1. Mapping gene expression to reactions via GPR rules +2. Applying logical operations (AND/OR) for enzyme complexes +3. Producing activity scores for each reaction in each sample + +**Input**: Gene expression data + GPR rules +**Output**: Reaction activity scores (RAS) + +## Parameters + +### Required Parameters + +| Parameter | Short | Type | Description | +|-----------|--------|------|-------------| +| `--tool_dir` | `-td` | string | COBRAxy installation directory | +| `--input` | `-in` | file | Gene expression dataset (TSV format) | +| `--ras_output` | `-ra` | file | Output file for RAS values | +| `--rules_selector` | `-rs` | choice | Built-in model (ENGRO2, Recon, HMRcore) | + +### Optional Parameters + +| Parameter | Short | Type | Default | Description | +|-----------|--------|------|---------|-------------| +| `--none` | `-n` | boolean | true | Handle missing gene values | +| `--model_upload` | `-rl` | file | - | Custom GPR rules file | +| `--model_upload_name` | `-rn` | string | - | Custom model name | +| `--out_log` | - | file | log.txt | Output log file | + +## Input Format + +### Gene Expression File +```tsv +Gene_ID Sample_1 Sample_2 Sample_3 Sample_4 +HGNC:5 10.5 11.2 15.7 14.3 +HGNC:10 3.2 4.1 8.8 7.9 +HGNC:15 7.9 8.2 4.4 5.1 +HGNC:25 12.1 13.5 18.2 17.8 +``` + +**Requirements**: +- First column: Gene identifiers (HGNC, Ensembl, Entrez, etc.) +- Subsequent columns: Expression values (numeric) +- Header row with sample names +- Tab-separated format + +### Custom GPR Rules File (Optional) +```tsv +Reaction_ID GPR +R_HEX1 HGNC:4922 +R_PGI HGNC:8906 +R_PFK HGNC:8877 or HGNC:8878 +R_ALDOA HGNC:414 and HGNC:417 +``` + +## Algorithm Details + +### GPR Rule Processing + +**Gene Mapping**: Each gene in the expression data is mapped to reactions via GPR rules. + +**Logical Operations**: +- **OR**: `Gene1 or Gene2` → `max(expr1, expr2)` or `expr1 + expr2` +- **AND**: `Gene1 and Gene2` → `min(expr1, expr2)` + +**Missing Gene Handling**: +- `-n true`: Missing genes treated as 0, OR operations continue +- `-n false`: Missing genes cause reaction score to be null + +### RAS Computation + +For each reaction and sample: + +1. **Parse GPR rule** into nested logical structure +2. **Replace gene names** with expression values +3. **Evaluate logical operations** recursively +4. **Assign RAS score** based on final result + +**Example**: +``` +GPR: (HGNC:5 and HGNC:10) or HGNC:15 +Expression: HGNC:5=10.5, HGNC:10=3.2, HGNC:15=7.9 +RAS = max(min(10.5, 3.2), 7.9) = max(3.2, 7.9) = 7.9 +``` + +## Output Format + +### RAS Values File +```tsv +Reactions Sample_1 Sample_2 Sample_3 Sample_4 +R_HEX1 8.5 9.2 12.1 11.3 +R_PGI 7.3 8.1 6.4 7.2 +R_PFK 15.2 16.8 20.1 18.9 +R_ALDOA 3.2 4.1 4.4 5.1 +``` + +**Format**: +- First column: Reaction identifiers +- Subsequent columns: RAS values for each sample +- Missing values represented as "None" + +## Usage Examples + +### Command Line + +```bash +# Basic usage with built-in model +ras_generator -td /path/to/COBRAxy \ + -in expression_data.tsv \ + -ra ras_output.tsv \ + -rs ENGRO2 + +# With custom model and strict missing gene handling +ras_generator -td /path/to/COBRAxy \ + -in expression_data.tsv \ + -ra ras_output.tsv \ + -rl custom_rules.tsv \ + -rn "CustomModel" \ + -n false +``` + +### Python API + +```python +import ras_generator + +# Basic RAS generation +args = [ + '-td', '/path/to/COBRAxy', + '-in', 'expression_data.tsv', + '-ra', 'ras_output.tsv', + '-rs', 'ENGRO2' +] + +ras_generator.main(args) +``` + +### Galaxy Usage + +1. Upload gene expression file to Galaxy +2. Select **RAS Generator** from COBRAxy tools +3. Configure parameters: + - **Input dataset**: Your expression file + - **Rule selector**: ENGRO2 (or other model) + - **Handle missing genes**: Yes/No +4. Click **Execute** + +## Built-in Models + +### ENGRO2 (Recommended for most analyses) +- **Scope**: Focused human metabolism +- **Reactions**: ~2,000 +- **Genes**: ~500 +- **Use case**: General metabolic analysis + +### Recon (Comprehensive analysis) +- **Scope**: Complete human metabolism +- **Reactions**: ~10,000 +- **Genes**: ~2,000 +- **Use case**: Detailed metabolic studies + +### HMRcore (Balanced option) +- **Scope**: Core human metabolism +- **Reactions**: ~5,000 +- **Genes**: ~1,000 +- **Use case**: Balanced coverage + +## Gene ID Mapping + +COBRAxy supports multiple gene identifier formats: + +| Format | Example | Notes | +|--------|---------|--------| +| **HGNC ID** | HGNC:5 | Recommended, most stable | +| **HGNC Symbol** | ALDOA | Human-readable but may change | +| **Ensembl** | ENSG00000149925 | Version-specific | +| **Entrez** | 226 | Numeric identifier | + +**Recommendation**: Use HGNC IDs for best compatibility and stability. + + + +## Troubleshooting + +### Common Issues + +**"Gene not found" warnings** +``` +Solution: Check gene ID format matches model expectations +- Verify gene identifiers (HGNC vs symbols vs Ensembl) +- Use gene mapping tools if needed +- Set -n true to handle missing genes gracefully +``` + +**"No computable scores" error** +``` +Solution: Insufficient gene overlap between data and model +- Check gene ID format compatibility +- Verify expression file format +- Try different built-in model +``` + +**Empty output file** +``` +Solution: Check input file format and permissions +- Ensure TSV format with proper headers +- Verify file paths are correct +- Check write permissions for output directory +``` + + + +### Debug Mode + +Enable detailed logging: + +```bash +ras_generator -td /path/to/COBRAxy \ + -in expression_data.tsv \ + -ra ras_output.tsv \ + -rs ENGRO2 \ + --out_log detailed_log.txt +``` + +Check log file for detailed error messages and processing statistics. + +## Validation + +### Check Output Quality + +```python +import pandas as pd + +# Read RAS output +ras_df = pd.read_csv('ras_output.tsv', sep='\t', index_col=0) + +# Basic statistics +print(f"RAS matrix shape: {ras_df.shape}") +print(f"Non-null values: {ras_df.count().sum()}") +print(f"Value range: {ras_df.min().min():.2f} to {ras_df.max().max():.2f}") + +# Check for problematic reactions +null_reactions = ras_df.isnull().all(axis=1).sum() +print(f"Reactions with no data: {null_reactions}") +``` + +### Expected Results + +- **Coverage**: 60-90% of reactions should have computable scores +- **Range**: RAS values typically 0-20 for log-transformed expression +- **Distribution**: Should reflect biological variation in your samples + +## Integration with Other Tools + +### Downstream Analysis + +RAS output can be used with: + +- **[MAREA](marea.md)**: Statistical enrichment analysis +- **[RAS to Bounds](ras-to-bounds.md)**: Flux constraint application +- **[MAREA Cluster](marea-cluster.md)**: Sample clustering + +### Preprocessing Options + +Before RAS generation: +- **Normalize** expression data (log2, quantile, etc.) +- **Filter** low-expression genes +- **Batch correct** if multiple datasets + +## Advanced Usage + +### Custom Model Integration + +```python +# Create custom GPR rules +custom_rules = { + 'R_CUSTOM1': 'HGNC:5 and HGNC:10', + 'R_CUSTOM2': 'HGNC:15 or HGNC:20' +} + +# Save as TSV +import pandas as pd +rules_df = pd.DataFrame(list(custom_rules.items()), + columns=['Reaction_ID', 'GPR']) +rules_df.to_csv('custom_rules.tsv', sep='\t', index=False) + +# Use with RAS generator +args = ['-rl', 'custom_rules.tsv', '-rn', 'CustomModel'] +``` + +### Batch Processing + +```python +# Process multiple expression files +expression_files = ['data1.tsv', 'data2.tsv', 'data3.tsv'] + +for i, exp_file in enumerate(expression_files): + output_file = f'ras_output_{i}.tsv' + + args = [ + '-td', '/path/to/COBRAxy', + '-in', exp_file, + '-ra', output_file, + '-rs', 'ENGRO2' + ] + + ras_generator.main(args) + print(f"Processed {exp_file} → {output_file}") +``` + +## References + +- [COBRApy documentation](https://cobrapy.readthedocs.io/) - Underlying metabolic modeling +- [GPR rules format](https://cobrapy.readthedocs.io/en/stable/getting_started.html#gene-protein-reaction-rules) - Standard format specification +- [HGNC database](https://www.genenames.org/) - Gene nomenclature standards \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/ras-to-bounds.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,333 @@ +# RAS to Bounds + +Apply Reaction Activity Scores (RAS) as constraints to metabolic model bounds. + +## Overview + +The RAS to Bounds tool integrates RAS values into metabolic model flux bounds, creating sample-specific constrained models for flux sampling. This enables personalized metabolic modeling based on gene expression patterns. + +## Usage + +### Command Line + +```bash +ras_to_bounds -td /path/to/COBRAxy \ + -ms ENGRO2 \ + -ir ras_scores.tsv \ + -rs true \ + -mes allOpen \ + -idop constrained_bounds/ +``` + +### Galaxy Interface + +Select "RAS to Bounds" from the COBRAxy tool suite and configure model and constraint parameters. + +## Parameters + +### Required Parameters + +| Parameter | Flag | Description | +|-----------|------|-------------| +| Tool Directory | `-td, --tool_dir` | Path to COBRAxy installation directory | +| Model Selector | `-ms, --model_selector` | Built-in model (ENGRO2, Custom) | +| RAS Selector | `-rs, --ras_selector` | Enable RAS constraint application | + +### Model Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Model Selector | `-ms, --model_selector` | Built-in model choice | ENGRO2 | +| Custom Model | `-mo, --model` | Path to custom SBML model | - | +| Model Name | `-mn, --model_name` | Custom model filename | - | + +### Medium Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Medium Selector | `-mes, --medium_selector` | Medium configuration | allOpen | +| Custom Medium | `-meo, --medium` | Path to custom medium file | - | + +### Constraint Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| RAS Input | `-ir, --input_ras` | RAS scores TSV file | - | +| RAS Names | `-rn, --name` | Sample names for RAS data | - | +| Cell Class | `-cc, --cell_class` | Output cell class information | - | + +### Output Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Output Path | `-idop, --output_path` | Directory for constrained bounds | ras_to_bounds/ | +| Output Log | `-ol, --out_log` | Log file path | - | + +## Input Formats + +### RAS Scores File + +Tab-separated format with reactions as rows and samples as columns: + +``` +Reaction Sample1 Sample2 Sample3 Control1 Control2 +R00001 1.25 0.85 1.42 1.05 0.98 +R00002 0.65 1.35 0.72 1.15 1.08 +R00003 2.15 2.05 0.45 0.95 1.12 +``` + +### Custom Model File (Optional) + +SBML format metabolic model: +- XML format (.xml, .sbml) +- Compressed formats supported (.xml.gz, .xml.zip, .xml.bz2) +- Must contain valid reaction, metabolite, and gene definitions + +### Custom Medium File (Optional) + +Exchange reactions defining growth medium: + +``` +reaction +EX_glc__D_e +EX_o2_e +EX_pi_e +EX_nh4_e +``` + +## Algorithm + +### Constraint Application + +1. **Base Model Loading**: Load specified metabolic model and medium +2. **Bounds Extraction**: Extract original flux bounds for each reaction +3. **RAS Integration**: For each sample and reaction: + ``` + if RAS > 1.0: + new_upper_bound = original_upper_bound * RAS + if RAS < 1.0: + new_lower_bound = original_lower_bound * RAS + ``` +4. **Bounds Output**: Generate sample-specific bounds files + +### Scaling Rules + +- **RAS > 1**: Upregulated reactions → increased flux capacity +- **RAS < 1**: Downregulated reactions → decreased flux capacity +- **RAS = 1**: No change from original bounds +- **Missing RAS**: Original bounds retained + +## Output Format + +### Bounds Files + +One TSV file per sample with constrained bounds: + +``` +# bounds_Sample1.tsv +Reaction lower_bound upper_bound +R00001 -1000 1250.5 +R00002 -650.2 1000 +R00003 -1000 2150.8 +``` + +### Directory Structure + +``` +ras_to_bounds/ +├── bounds_Sample1.tsv +├── bounds_Sample2.tsv +├── bounds_Sample3.tsv +├── bounds_Control1.tsv +├── bounds_Control2.tsv +└── constraints_log.txt +``` + +## Examples + +### Basic Usage with Built-in Model + +```bash +# Apply RAS constraints to ENGRO2 model +ras_to_bounds -td /opt/COBRAxy \ + -ms ENGRO2 \ + -ir ras_data.tsv \ + -rs true \ + -idop results/bounds/ +``` + +### Custom Model and Medium + +```bash +# Use custom model with specific medium +ras_to_bounds -td /opt/COBRAxy \ + -ms Custom \ + -mo models/custom_model.xml \ + -mn custom_model.xml \ + -mes custom \ + -meo media/minimal_medium.tsv \ + -ir patient_ras.tsv \ + -rs true \ + -idop personalized_models/ \ + -ol constraints.log +``` + +### Multiple Sample Processing + +```bash +# Process cohort data with sample classes +ras_to_bounds -td /opt/COBRAxy \ + -ms ENGRO2 \ + -ir cohort_ras_scores.tsv \ + -rn "Patient1,Patient2,Patient3,Healthy1,Healthy2" \ + -rs true \ + -cc sample_classes.tsv \ + -idop cohort_bounds/ +``` + +## Built-in Models + +### ENGRO2 +- **Species**: Homo sapiens +- **Scope**: Genome-scale reconstruction +- **Reactions**: ~2,000 reactions +- **Metabolites**: ~1,500 metabolites +- **Use Case**: General human metabolism + +### Custom Model Requirements +- Valid SBML format +- Consistent reaction/metabolite naming +- Proper compartment definitions +- Gene-protein-reaction associations + +## Medium Configurations + +### allOpen (Default) +- All exchange reactions unconstrained +- Maximum metabolic flexibility +- Suitable for exploratory analysis + +### Custom Medium +- User-defined nutrient availability +- Tissue-specific conditions +- Disease-specific constraints + +## Quality Control + +### Pre-processing Checks +- Verify RAS data completeness (recommend >80% reaction coverage) +- Check for extreme RAS values (>10 or <0.1 may indicate issues) +- Validate model consistency and solvability + +### Post-processing Validation +- Confirm bounds files generated for all samples +- Check constraint log for warnings +- Test model feasibility with sample bounds + +## Tips and Best Practices + +### RAS Data Preparation +- **Normalization**: Ensure RAS values are properly normalized (median ~1.0) +- **Filtering**: Remove reactions with consistently missing data +- **Validation**: Check RAS distributions across samples + +### Model Selection +- Use ENGRO2 for general human tissue analysis +- Consider custom models for specific organisms or tissues +- Validate model scope matches your biological question + +### Medium Configuration +- Match medium to experimental conditions +- Use minimal medium for growth requirement analysis +- Consider tissue-specific nutrient availability + +## Integration Workflow + +### Upstream Tools +- [RAS Generator](ras-generator.md) - Generate RAS scores from expression data + +### Downstream Tools +- [Flux Simulation](flux-simulation.md) - Sample fluxes using constrained bounds +- [MAREA](marea.md) - Statistical analysis of constraint effects + +### Typical Pipeline + +```bash +# 1. Generate RAS from expression data +ras_generator -td /opt/COBRAxy -in expression.tsv -ra ras.tsv + +# 2. Apply RAS constraints to model bounds +ras_to_bounds -td /opt/COBRAxy -ms ENGRO2 -ir ras.tsv -rs true -idop bounds/ + +# 3. Sample fluxes with constraints +flux_simulation -td /opt/COBRAxy -ms ENGRO2 -in bounds/*.tsv -a CBS -idop fluxes/ + +# 4. Analyze and visualize results +marea -td /opt/COBRAxy -input_data fluxes/mean.tsv -choice_map ENGRO2 -idop maps/ +``` + +## Troubleshooting + +### Common Issues + +**No bounds files generated** +- Check RAS file format and sample names +- Verify model loading (check model path/format) +- Ensure sufficient disk space for output + +**Model infeasibility after constraints** +- RAS values may be too restrictive +- Consider scaling factor adjustment +- Check medium compatibility with constraints + +**Missing reactions in bounds** +- RAS data may not cover all model reactions +- Original bounds retained for missing reactions +- Consider reaction mapping validation + +### Error Messages + +| Error | Cause | Solution | +|-------|-------|----------| +| "Model not found" | Invalid model path | Check model file location | +| "RAS file invalid" | Malformed TSV format | Verify file structure and encoding | +| "Infeasible solution" | Over-constrained model | Relax RAS scaling or medium constraints | + +### Performance Issues + +**Slow processing** +- Large models may require significant memory +- Consider batch processing for many samples +- Monitor system resource usage + +**Memory errors** +- Reduce model size or split processing +- Increase available system memory +- Use more efficient file formats + +## Advanced Usage + +### Batch Processing Script + +```bash +#!/bin/bash +# Process multiple RAS files +for ras_file in ras_data/*.tsv; do + sample_name=$(basename "$ras_file" .tsv) + ras_to_bounds -td /opt/COBRAxy \ + -ms ENGRO2 \ + -ir "$ras_file" \ + -rs true \ + -idop "bounds_$sample_name/" +done +``` + +### Custom Scaling Functions + +For advanced users, RAS scaling can be customized by modifying the constraint application logic in the source code. + +## See Also + +- [RAS Generator](ras-generator.md) - Generate input RAS data +- [Flux Simulation](flux-simulation.md) - Use constrained bounds for sampling +- [Model Setting](metabolic-model-setting.md) - Extract model components \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/rps-generator.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,165 @@ +# RPS Generator + +Generate Reaction Propensity Scores (RPS) from metabolite abundance data. + +## Overview + +The RPS Generator computes reaction propensity scores based on metabolite abundance measurements. RPS values indicate how likely metabolic reactions are to be active based on the availability of their substrate and product metabolites. + +## Usage + +### Command Line + +```bash +rps_generator -td /path/to/COBRAxy \ + -id metabolite_abundance.tsv \ + -rp output_rps.tsv \ + -ol log.txt +``` + +### Galaxy Interface + +Select "RPS Generator" from the COBRAxy tool suite and upload your metabolite abundance file. + +## Parameters + +### Required Parameters + +| Parameter | Flag | Description | +|-----------|------|-------------| +| Tool Directory | `-td, --tool_dir` | Path to COBRAxy installation directory | +| Input Dataset | `-id, --input` | Metabolite abundance TSV file (rows=metabolites, cols=samples) | +| RPS Output | `-rp, --rps_output` | Output file path for RPS scores | + +### Optional Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Custom Reactions | `-rl, --model_upload` | Path to custom reactions file | Built-in reactions | +| Output Log | `-ol, --out_log` | Log file for warnings/errors | Standard output | + +## Input Format + +### Metabolite Abundance File + +Tab-separated values (TSV) format: + +``` +Metabolite Sample1 Sample2 Sample3 +glucose 100.5 85.2 92.7 +pyruvate 45.3 38.9 41.2 +lactate 15.8 22.1 18.5 +``` + +**Requirements:** +- First column: metabolite names (case-insensitive) +- Subsequent columns: abundance values for each sample +- Missing values: use 0 or leave empty +- File encoding: UTF-8 + +### Custom Reactions File (Optional) + +If using custom reactions instead of built-in ones: + +``` +ReactionID Reaction +R00001 glucose + ATP -> glucose-6-phosphate + ADP +R00002 glucose-6-phosphate <-> fructose-6-phosphate +``` + +## Output Format + +### RPS Scores File + +``` +Reaction Sample1 Sample2 Sample3 +R00001 0.85 0.72 0.79 +R00002 0.45 0.38 0.52 +R00003 0.12 0.28 0.21 +``` + +- Values range from 0 (low propensity) to 1 (high propensity) +- NaN values indicate insufficient metabolite data for that reaction + +## Algorithm + +1. **Metabolite Matching**: Input metabolite names are matched against internal synonyms +2. **Abundance Normalization**: Raw abundances are normalized per sample +3. **Reaction Scoring**: For each reaction, RPS is computed based on: + - Substrate availability (geometric mean of substrate abundances) + - Product formation potential + - Stoichiometric coefficients + +## Examples + +### Basic Usage + +```bash +# Generate RPS from metabolite data +rps_generator -td /opt/COBRAxy \ + -id /data/metabolomics.tsv \ + -rp /results/rps_scores.tsv +``` + +### With Custom Reactions + +```bash +# Use custom reaction set +rps_generator -td /opt/COBRAxy \ + -id /data/metabolomics.tsv \ + -rl /custom/reactions.tsv \ + -rp /results/custom_rps.tsv \ + -ol /logs/rps.log +``` + +## Tips and Best Practices + +### Data Preparation + +- **Metabolite Names**: Use standard nomenclature (KEGG, ChEBI, or common names) +- **Missing Data**: Remove samples with >50% missing metabolites +- **Outliers**: Consider log-transformation for highly variable metabolites +- **Replicates**: Average technical replicates before analysis + +### Quality Control + +- Check log file for unmatched metabolite names +- Verify RPS score distributions (should span 0-1 range) +- Compare results with expected pathway activities + +### Integration with Other Tools + +RPS scores are typically used with: +- [MAREA](marea.md) for pathway enrichment analysis +- [Flux to Map](flux-to-map.md) for metabolic map visualization + +## Troubleshooting + +### Common Issues + +**No RPS scores generated** +- Check metabolite name format and spelling +- Verify input file has correct TSV format +- Ensure tool directory contains reaction databases + +**Many NaN values in output** +- Insufficient metabolite coverage for reactions +- Consider using a smaller, more focused reaction set + +**Memory errors** +- Reduce dataset size or split into batches +- Increase available system memory + +### Error Messages + +| Error | Cause | Solution | +|-------|--------|----------| +| "File not found" | Missing input file | Check file path and permissions | +| "Invalid format" | Malformed TSV | Verify column headers and data types | +| "No metabolites matched" | Name mismatch | Check metabolite nomenclature | + +## See Also + +- [RAS Generator](ras-generator.md) - Generate reaction activity scores from gene expression +- [MAREA](marea.md) - Statistical analysis and visualization +- [Flux Simulation](flux-simulation.md) - Constraint-based modeling \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tools/tabular-to-model.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,480 @@ +# Tabular to Metabolic Model + +Convert tabular data (CSV/TSV) into COBRA metabolic models in various formats. + +## Overview + +Tabular to Metabolic Model (tabular2MetabolicModel) converts structured tabular data containing reaction information into fully functional COBRA metabolic models. This tool enables creation of custom models from spreadsheet data and supports multiple output formats including SBML, JSON, MATLAB, and YAML. + +## Usage + +### Command Line + +```bash +tabular2MetabolicModel --input model_data.csv \ + --format sbml \ + --output custom_model.xml \ + --out_log conversion.log \ + --tool_dir /path/to/COBRAxy +``` + +### Galaxy Interface + +Select "Tabular to Metabolic Model" from the COBRAxy tool suite and configure conversion parameters. + +## Parameters + +### Required Parameters + +| Parameter | Flag | Description | +|-----------|------|-------------| +| Input File | `--input` | Tabular file (CSV/TSV) with model data | +| Output Format | `--format` | Model format (sbml, json, mat, yaml) | +| Output File | `--output` | Output model file path | +| Output Log | `--out_log` | Log file for conversion process | + +### Optional Parameters + +| Parameter | Flag | Description | Default | +|-----------|------|-------------|---------| +| Tool Directory | `--tool_dir` | COBRAxy installation directory | Current directory | + +## Input Format + +### Tabular Model Data + +The input file must contain structured model information with the following columns: + +```csv +Reaction_ID,GPR_Rule,Reaction_Formula,Lower_Bound,Upper_Bound,Objective_Coefficient,Medium_Member,Compartment,Subsystem +R00001,GENE1 or GENE2,A + B -> C + D,-1000.0,1000.0,0.0,FALSE,cytosol,Glycolysis +R00002,GENE3 and GENE4,E <-> F,-1000.0,1000.0,0.0,FALSE,mitochondria,TCA_Cycle +EX_glc_e,-,glc_e <->,-1000.0,1000.0,0.0,TRUE,extracellular,Exchange +BIOMASS,GENE5,0.5 A + 0.3 B -> 1 BIOMASS,0.0,1000.0,1.0,FALSE,cytosol,Biomass +``` + +### Required Columns + +| Column | Description | Format | +|--------|-------------|--------| +| **Reaction_ID** | Unique reaction identifier | String | +| **Reaction_Formula** | Stoichiometric equation | Metabolite notation | +| **Lower_Bound** | Minimum flux constraint | Numeric | +| **Upper_Bound** | Maximum flux constraint | Numeric | + +### Optional Columns + +| Column | Description | Default | +|--------|-------------|---------| +| **GPR_Rule** | Gene-protein-reaction association | Empty string | +| **Objective_Coefficient** | Biomass/objective weight | 0.0 | +| **Medium_Member** | Exchange reaction flag | FALSE | +| **Compartment** | Subcellular location | Empty | +| **Subsystem** | Metabolic pathway | Empty | + +## Output Formats + +### SBML (Systems Biology Markup Language) +- **Format**: XML-based standard +- **Extension**: `.xml` or `.sbml` +- **Use Case**: Interoperability with other tools +- **Advantages**: Widely supported, standardized + +### JSON (JavaScript Object Notation) +- **Format**: COBRApy native JSON +- **Extension**: `.json` +- **Use Case**: Python/COBRApy workflows +- **Advantages**: Human-readable, lightweight + +### MATLAB (.mat) +- **Format**: MATLAB workspace format +- **Extension**: `.mat` +- **Use Case**: MATLAB COBRA Toolbox +- **Advantages**: Direct MATLAB compatibility + +### YAML (YAML Ain't Markup Language) +- **Format**: Human-readable data serialization +- **Extension**: `.yml` or `.yaml` +- **Use Case**: Configuration and documentation +- **Advantages**: Most human-readable format + +## Reaction Formula Syntax + +### Standard Notation +``` +# Irreversible reaction +A + B -> C + D + +# Reversible reaction +A + B <-> C + D + +# With stoichiometric coefficients +2 A + 3 B -> 1 C + 4 D + +# Compartmentalized metabolites +glc_c + atp_c -> g6p_c + adp_c +``` + +### Compartment Suffixes +- `_c`: Cytosol +- `_m`: Mitochondria +- `_e`: Extracellular +- `_r`: Endoplasmic reticulum +- `_x`: Peroxisome +- `_n`: Nucleus + +### Exchange Reactions +``` +# Import reaction +EX_glc_e: glc_e <-> + +# Export reaction +EX_co2_e: co2_e <-> +``` + +## GPR Rule Syntax + +### Logical Operators +- **AND**: Gene products required together +- **OR**: Alternative gene products +- **Parentheses**: Grouping for complex logic + +### Examples +``` +# Single gene +GENE1 + +# Alternative genes (isozymes) +GENE1 or GENE2 or GENE3 + +# Required genes (complex) +GENE1 and GENE2 + +# Complex logic +(GENE1 and GENE2) or (GENE3 and GENE4) +``` + +## Examples + +### Create Basic Model + +```bash +# Convert simple CSV to SBML model +tabular2MetabolicModel --input simple_model.csv \ + --format sbml \ + --output simple_model.xml \ + --out_log simple_conversion.log +``` + +### Multi-format Export + +```bash +# Create models in all supported formats +formats=("sbml" "json" "mat" "yaml") +for fmt in "${formats[@]}"; do + tabular2MetabolicModel --input comprehensive_model.csv \ + --format "$fmt" \ + --output "model.$fmt" \ + --out_log "conversion_$fmt.log" +done +``` + +### Custom Model Creation + +```bash +# Build tissue-specific model from curated data +tabular2MetabolicModel --input liver_reactions.tsv \ + --format sbml \ + --output liver_model.xml \ + --out_log liver_model.log \ + --tool_dir /opt/COBRAxy +``` + +### Model Integration Pipeline + +```bash +# Extract existing model, modify, and recreate +metabolicModel2Tabular --model ENGRO2 --out_tabular base_model.csv + +# Edit base_model.csv with custom reactions/constraints + +# Create modified model +tabular2MetabolicModel --input modified_model.csv \ + --format sbml \ + --output custom_model.xml \ + --out_log custom_creation.log +``` + +## Model Validation + +### Automatic Checks + +The tool performs validation during conversion: +- **Stoichiometric Balance**: Reaction mass balance +- **Metabolite Consistency**: Compartment assignments +- **Bound Validation**: Feasible constraint ranges +- **Objective Function**: Valid biomass reaction + +### Post-conversion Validation + +```python +import cobra + +# Load and validate model +model = cobra.io.read_sbml_model('custom_model.xml') + +# Check basic properties +print(f"Reactions: {len(model.reactions)}") +print(f"Metabolites: {len(model.metabolites)}") +print(f"Genes: {len(model.genes)}") + +# Test model solvability +solution = model.optimize() +print(f"Growth rate: {solution.objective_value}") + +# Validate mass balance +unbalanced = cobra.flux_analysis.check_mass_balance(model) +if unbalanced: + print("Unbalanced reactions found:", unbalanced) +``` + +## Integration Workflow + +### Upstream Data Sources + +#### COBRAxy Tools +- [Metabolic Model Setting](metabolic-model-setting.md) - Extract tabular data for modification + +#### External Sources +- **Databases**: KEGG, Reactome, BiGG +- **Literature**: Manually curated reactions +- **Spreadsheets**: User-defined custom models + +### Downstream Applications + +#### COBRAxy Analysis +- [RAS to Bounds](ras-to-bounds.md) - Apply constraints to custom model +- [Flux Simulation](flux-simulation.md) - Sample fluxes from custom model +- [MAREA](marea.md) - Analyze custom pathways + +#### External Tools +- **COBRApy**: Python-based analysis +- **COBRA Toolbox**: MATLAB analysis +- **OptFlux**: Strain design +- **Escher**: Pathway visualization + +### Typical Pipeline + +```bash +# 1. Start with existing model data +metabolicModel2Tabular --model ENGRO2 \ + --out_tabular base_reactions.csv + +# 2. Modify/extend the reaction data +# Edit base_reactions.csv to add tissue-specific reactions + +# 3. Create custom model +tabular2MetabolicModel --input modified_reactions.csv \ + --format sbml \ + --output tissue_model.xml \ + --out_log tissue_creation.log + +# 4. Validate and use custom model +ras_to_bounds --model Custom --input tissue_model.xml \ + --ras_input tissue_expression.tsv \ + --idop tissue_bounds/ + +# 5. Perform flux analysis +flux_simulation --model Custom --input tissue_model.xml \ + --bounds tissue_bounds/*.tsv \ + --algorithm CBS --idop tissue_fluxes/ +``` + +## Quality Control + +### Input Data Validation + +#### Pre-conversion Checks +- **Format Consistency**: Verify column headers and data types +- **Reaction Completeness**: Check for missing required fields +- **Stoichiometric Validity**: Validate reaction formulas +- **Bound Feasibility**: Ensure lower ≤ upper bounds + +#### Common Data Issues +```bash +# Check for missing reaction IDs +awk -F',' 'NR>1 && ($1=="" || $1=="NA") {print "Empty ID in line " NR}' input.csv + +# Validate reaction directions +awk -F',' 'NR>1 && $3 !~ /->|<->/ {print "Invalid formula: " $1 ", " $3}' input.csv + +# Check bound consistency +awk -F',' 'NR>1 && $4>$5 {print "Invalid bounds: " $1 ", LB=" $4 " > UB=" $5}' input.csv +``` + +### Model Quality Assessment + +#### Structural Properties +- **Network Connectivity**: Ensure realistic pathway structure +- **Compartmentalization**: Validate transport reactions +- **Exchange Reactions**: Verify medium composition +- **Biomass Function**: Check objective reaction completeness + +#### Functional Testing +```python +# Test model functionality +model = cobra.io.read_sbml_model('custom_model.xml') + +# Check growth capability +growth = model.optimize().objective_value +print(f"Maximum growth rate: {growth}") + +# Flux Variability Analysis +fva_result = cobra.flux_analysis.flux_variability_analysis(model) +blocked_reactions = fva_result[(fva_result.minimum == 0) & (fva_result.maximum == 0)] +print(f"Blocked reactions: {len(blocked_reactions)}") + +# Essential gene analysis +essential_genes = cobra.flux_analysis.find_essential_genes(model) +print(f"Essential genes: {len(essential_genes)}") +``` + +## Tips and Best Practices + +### Data Preparation +- **Consistent Naming**: Use systematic metabolite/reaction IDs +- **Compartment Notation**: Follow standard suffixes (_c, _m, _e) +- **Balanced Reactions**: Verify mass and charge balance +- **Realistic Bounds**: Use physiologically relevant constraints + +### Model Design +- **Modular Structure**: Organize reactions by pathway/subsystem +- **Exchange Reactions**: Include all necessary transport processes +- **Biomass Function**: Define appropriate growth objective +- **Gene Associations**: Add GPR rules where available + +### Format Selection +- **SBML**: Choose for maximum compatibility and sharing +- **JSON**: Use for COBRApy-specific workflows +- **MATLAB**: Select for COBRA Toolbox integration +- **YAML**: Pick for human-readable documentation + +### Performance Optimization +- **Model Size**: Balance comprehensiveness with computational efficiency +- **Reaction Pruning**: Remove unnecessary or blocked reactions +- **Compartmentalization**: Minimize unnecessary compartments +- **Validation**: Test model properties before distribution + +## Troubleshooting + +### Common Issues + +**Conversion fails with format error** +- Check CSV/TSV column headers and data consistency +- Verify reaction formula syntax +- Ensure numeric fields contain valid numbers + +**Model is infeasible after conversion** +- Check reaction bounds for conflicts +- Verify exchange reaction setup +- Validate stoichiometric balance + +**Missing metabolites or reactions** +- Confirm all required columns present in input +- Check for empty rows or malformed data +- Validate reaction formula parsing + +### Error Messages + +| Error | Cause | Solution | +|-------|-------|----------| +| "Input file not found" | Invalid file path | Check file location and permissions | +| "Unknown format" | Invalid output format | Use: sbml, json, mat, or yaml | +| "Formula parsing failed" | Malformed reaction equation | Check reaction formula syntax | +| "Model infeasible" | Conflicting constraints | Review bounds and exchange reactions | + +### Performance Issues + +**Slow conversion** +- Large input files require more processing time +- Complex GPR rules increase parsing overhead +- Monitor system memory usage + +**Memory errors** +- Reduce model size or split into smaller files +- Increase available system memory +- Use more efficient data structures + +**Output file corruption** +- Ensure sufficient disk space +- Check file write permissions +- Verify format-specific requirements + +## Advanced Usage + +### Batch Model Creation + +```python +#!/usr/bin/env python3 +import subprocess +import pandas as pd + +# Create multiple tissue-specific models +tissues = ['liver', 'muscle', 'brain', 'heart'] +base_data = pd.read_csv('base_model.csv') + +for tissue in tissues: + # Modify base data for tissue specificity + tissue_data = customize_for_tissue(base_data, tissue) + tissue_data.to_csv(f'{tissue}_model.csv', index=False) + + # Convert to SBML + subprocess.run([ + 'tabular2MetabolicModel', + '--input', f'{tissue}_model.csv', + '--format', 'sbml', + '--output', f'{tissue}_model.xml', + '--out_log', f'{tissue}_conversion.log' + ]) +``` + +### Model Merging + +Combine multiple tabular files into comprehensive models: + +```bash +# Merge core metabolism with tissue-specific pathways +cat core_reactions.csv > combined_model.csv +tail -n +2 tissue_reactions.csv >> combined_model.csv +tail -n +2 disease_reactions.csv >> combined_model.csv + +# Create merged model +tabular2MetabolicModel --input combined_model.csv \ + --format sbml \ + --output comprehensive_model.xml +``` + +### Model Versioning + +Track model versions and changes: + +```bash +# Version control for model development +git add model_v1.csv +git commit -m "Initial model version" + +# Create versioned models +tabular2MetabolicModel --input model_v1.csv --format sbml --output model_v1.xml +tabular2MetabolicModel --input model_v2.csv --format sbml --output model_v2.xml + +# Compare model versions +cobra_compare_models model_v1.xml model_v2.xml +``` + +## See Also + +- [Metabolic Model Setting](metabolic-model-setting.md) - Extract tabular data from existing models +- [RAS to Bounds](ras-to-bounds.md) - Apply constraints to custom models +- [Flux Simulation](flux-simulation.md) - Analyze custom models with flux sampling +- [Model Creation Tutorial](../tutorials/custom-model-creation.md) +- [COBRA Model Standards](../tutorials/cobra-model-standards.md) \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/troubleshooting.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,380 @@ +# Troubleshooting + +Common issues and solutions when using COBRAxy. + +## Installation Issues + +### Python Import Errors + +**Problem**: `ModuleNotFoundError: No module named 'cobra'` +```bash +# Solution: Install missing dependencies +pip install cobra pandas numpy scipy + +# Or reinstall COBRAxy +cd COBRAxy +pip install -e . +``` + +**Problem**: `ImportError: No module named 'cobraxy'` +```python +# Solution: Add COBRAxy to Python path +import sys +sys.path.insert(0, '/path/to/COBRAxy') +``` + +### System Dependencies + +**Problem**: GLPK solver not found +```bash +# Ubuntu/Debian +sudo apt-get install libglpk40 glpk-utils +pip install swiglpk + +# macOS +brew install glpk +pip install swiglpk + +# Windows (using conda) +conda install -c conda-forge glpk swiglpk +``` + +**Problem**: SVG processing errors +```bash +# Install libvips for image processing +# Ubuntu/Debian: sudo apt-get install libvips +# macOS: brew install vips +``` + +## Data Format Issues + +### Gene Expression Problems + +**Problem**: "No computable scores" error +``` +Cause: Gene IDs don't match between data and model +Solution: +1. Check gene ID format (HGNC vs symbols vs Ensembl) +2. Verify first column contains gene identifiers +3. Ensure tab-separated format +4. Try different built-in model +``` + +**Problem**: Many "gene not found" warnings +```python +# Check gene overlap with model +import pickle +genes_dict = pickle.load(open('local/pickle files/ENGRO2_genes.p', 'rb')) +model_genes = set(genes_dict['hugo_id'].keys()) + +import pandas as pd +data_genes = set(pd.read_csv('expression.tsv', sep='\t').iloc[:, 0]) + +overlap = len(model_genes.intersection(data_genes)) +print(f"Gene overlap: {overlap}/{len(data_genes)} ({overlap/len(data_genes)*100:.1f}%)") +``` + +**Problem**: File format not recognized +```tsv +# Correct format - tab-separated: +Gene_ID Sample_1 Sample_2 +HGNC:5 10.5 11.2 +HGNC:10 3.2 4.1 + +# Wrong - comma-separated or spaces will fail +``` + +### Model Issues + +**Problem**: Custom model not loading +``` +Solution: +1. Check TSV format with "GPR" column header +2. Verify reaction IDs are unique +3. Test GPR syntax (use 'and'/'or', proper parentheses) +4. Check file permissions and encoding (UTF-8) +``` + +## Tool Execution Errors + + + +### File Path Problems + +**Problem**: "File not found" errors +```python +# Use absolute paths +from pathlib import Path + +tool_dir = str(Path('/path/to/COBRAxy').absolute()) +input_file = str(Path('expression.tsv').absolute()) + +args = ['-td', tool_dir, '-in', input_file, ...] +``` + +**Problem**: Permission denied +```bash +# Check write permissions +ls -la output_directory/ + +# Fix permissions +chmod 755 output_directory/ +chmod 644 input_files/* +``` + +### Galaxy Integration Issues + +**Problem**: COBRAxy tools not appearing in Galaxy +```xml +<!-- Check tool_conf.xml syntax --> +<section id="cobraxy" name="COBRAxy"> + <tool file="cobraxy/ras_generator.xml" /> +</section> + +<!-- Verify file paths are correct --> +ls tools/cobraxy/ras_generator.xml +``` + +**Problem**: Tool execution fails in Galaxy +``` +Check Galaxy logs: +- main.log: General Galaxy issues +- handler.log: Job execution problems +- uwsgi.log: Web server issues + +Common fixes: +1. Restart Galaxy after adding tools +2. Check Python environment has COBRApy installed +3. Verify file permissions on tool files +``` + + + +**Problem**: Flux sampling hangs +```bash +# Check solver availability +python -c "import cobra; print(cobra.Configuration().solver)" + +# Should show: glpk, cplex, or gurobi +# Install GLPK if missing: +pip install swiglpk +``` + +### Large Dataset Handling + +**Problem**: Cannot process large expression matrices +```python +# Process in chunks +def process_large_dataset(expression_file, chunk_size=1000): + df = pd.read_csv(expression_file, sep='\t') + + for i in range(0, len(df), chunk_size): + chunk = df.iloc[i:i+chunk_size] + chunk_file = f'chunk_{i}.tsv' + chunk.to_csv(chunk_file, sep='\t', index=False) + + # Process chunk + ras_generator.main(['-in', chunk_file, ...]) +``` + +## Output Validation + +### Unexpected Results + +**Problem**: All RAS values are zero or null +```python +# Debug gene mapping +import pandas as pd +ras_df = pd.read_csv('ras_output.tsv', sep='\t', index_col=0) + +# Check data quality +print(f"Null percentage: {ras_df.isnull().sum().sum() / ras_df.size * 100:.1f}%") +print(f"Zero percentage: {(ras_df == 0).sum().sum() / ras_df.size * 100:.1f}%") + +# Check expression data preprocessing +expr_df = pd.read_csv('expression.tsv', sep='\t', index_col=0) +print(f"Expression range: {expr_df.min().min():.2f} to {expr_df.max().max():.2f}") +``` + +**Problem**: RAS values seem too high/low +``` +Possible causes: +1. Expression data not log-transformed +2. Wrong normalization method +3. Incorrect gene ID mapping +4. GPR rule interpretation issues + +Solutions: +1. Check expression data preprocessing +2. Validate against known control genes +3. Compare with published metabolic activity patterns +``` + +### Missing Pathway Maps + +**Problem**: MAREA generates no output maps +``` +Debug steps: +1. Check RAS input has non-null values +2. Verify model choice matches RAS generation +3. Check statistical significance thresholds +4. Look at log files for specific errors +``` + +## Environment Issues + +### Conda/Virtual Environment Problems + +**Problem**: Tool import fails in virtual environment +```bash +# Activate environment properly +source venv/bin/activate # Linux/macOS +# or +venv\Scripts\activate # Windows + +# Verify COBRAxy installation +pip list | grep cobra +python -c "import cobra; print('COBRApy version:', cobra.__version__)" +``` + +**Problem**: Version conflicts +```bash +# Create clean environment +conda create -n cobraxy python=3.9 +conda activate cobraxy + +# Install COBRAxy fresh +cd COBRAxy +pip install -e . +``` + +### Cross-Platform Issues + +**Problem**: Windows path separator issues +```python +# Use pathlib for cross-platform paths +from pathlib import Path + +# Instead of: '/path/to/file' +# Use: str(Path('path') / 'to' / 'file') +``` + +**Problem**: Line ending issues (Windows/Unix) +```bash +# Convert line endings if needed +dos2unix input_file.tsv # Unix +unix2dos input_file.tsv # Windows +``` + +## Debugging Strategies + +### Enable Detailed Logging + +```python +import logging +logging.basicConfig(level=logging.DEBUG) + +# Many tools accept log file parameter +args = [..., '--out_log', 'detailed.log'] +``` + +### Test with Small Datasets + +```python +# Create minimal test case +test_data = """Gene_ID Sample1 Sample2 +HGNC:5 10.0 15.0 +HGNC:10 5.0 8.0""" + +with open('test_input.tsv', 'w') as f: + f.write(test_data) + +# Test basic functionality +ras_generator.main(['-td', tool_dir, '-in', 'test_input.tsv', + '-ra', 'test_output.tsv', '-rs', 'ENGRO2']) +``` + +### Check Dependencies + +```python +# Verify all required packages +required_packages = ['cobra', 'pandas', 'numpy', 'scipy'] + +for package in required_packages: + try: + __import__(package) + print(f"✓ {package}") + except ImportError: + print(f"✗ {package} - MISSING") +``` + +## Getting Help + +### Information to Include in Bug Reports + +When reporting issues, include: + +1. **System information**: + ```bash + python --version + pip list | grep cobra + uname -a # Linux/macOS + ``` + +2. **Complete error messages**: Copy full traceback +3. **Input file format**: First few lines of input data +4. **Command/parameters used**: Exact command or Python code +5. **Expected vs actual behavior**: What should happen vs what happens + +### Community Resources + +- **GitHub Issues**: [Report bugs](https://github.com/CompBtBs/COBRAxy/issues) +- **Discussions**: [Ask questions](https://github.com/CompBtBs/COBRAxy/discussions) +- **COBRApy Community**: [General metabolic modeling help](https://github.com/opencobra/cobrapy) + +### Self-Help Checklist + +Before reporting issues: + +- ✅ Checked this troubleshooting guide +- ✅ Verified installation completeness +- ✅ Tested with built-in example data +- ✅ Searched existing GitHub issues +- ✅ Tried alternative models/parameters +- ✅ Checked file formats and permissions + +## Prevention Tips + +### Best Practices + +1. **Use virtual environments** to avoid conflicts +2. **Validate input data** before processing +3. **Start with small datasets** for testing +4. **Keep backups** of working configurations +5. **Document successful workflows** for reuse +6. **Test after updates** to catch regressions + +### Data Quality Checks + +```python +def validate_expression_data(filename): + """Validate gene expression file format.""" + df = pd.read_csv(filename, sep='\t') + + # Check basic format + assert df.shape[0] > 0, "Empty file" + assert df.shape[1] > 1, "Need at least 2 columns" + + # Check numeric data + numeric_cols = df.select_dtypes(include=[np.number]).columns + assert len(numeric_cols) > 0, "No numeric expression data" + + # Check for missing values + null_pct = df.isnull().sum().sum() / df.size * 100 + if null_pct > 50: + print(f"Warning: {null_pct:.1f}% missing values") + + print(f"✓ File valid: {df.shape[0]} genes × {df.shape[1]-1} samples") +``` + +This troubleshooting guide covers the most common issues. For tool-specific problems, check the individual tool documentation pages. \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tutorials/README.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,72 @@ +# Tutorials + +Learn COBRAxy through hands-on tutorials covering the two main usage scenarios. + +## Available Tutorials + +| Tutorial | Duration | Description | +|----------|----------|-------------| +| [Galaxy Setup](galaxy-setup.md) | 30 min | Set up Galaxy for web-based analysis | +| [Python API Usage](python-api.md) | 45 min | Programmatic analysis with Python | + +## Choose Your Path + +### Web Interface → [Galaxy Setup Tutorial](galaxy-setup.md) + +Set up a local Galaxy instance with COBRAxy tools for point-and-click analysis. Perfect for users who prefer graphical interfaces and don't want to write code. + +### Python Programming → [Python API Tutorial](python-api.md) + +Learn to call COBRAxy tools programmatically in your analysis pipelines. Ideal for integrating COBRAxy into custom workflows and automation. + +## Prerequisites + +Before starting the tutorials, make sure you have: + +- ✅ [COBRAxy installed](../installation.md) +- ✅ Basic understanding of metabolic modeling (helpful but not required) +- ✅ Familiarity with command line or Python (depending on tutorial) + +## Tutorial Data + +Download example datasets used in tutorials: + +```bash +# Download tutorial data +wget https://github.com/CompBtBs/COBRAxy/releases/download/v1.0/tutorial_data.zip +unzip tutorial_data.zip +``` + +The tutorial data includes: +- Sample gene expression datasets +- Metabolite abundance data +- Pre-configured Galaxy workflows +- Expected output files for verification + +## Learning Path + +We recommend following tutorials in this order: + +1. **[Data Formats](data-formats.md)** - Understand input requirements +2. **[Basic Workflow](workflow.md)** - Learn the analysis pipeline +3. Choose your interface: + - **[Galaxy Setup](galaxy-setup.md)** for web-based analysis + - **[Python API](python-api.md)** for programmatic analysis + +## Getting Help + +If you encounter issues during tutorials: + +1. Check the specific tutorial's troubleshooting section +2. Refer to the main [Troubleshooting Guide](../troubleshooting.md) +3. Ask questions in [GitHub Discussions](https://github.com/CompBtBs/COBRAxy/discussions) + +## Contributing + +Found an error or want to improve a tutorial? + +- [Edit on GitHub](https://github.com/CompBtBs/COBRAxy/tree/main/docs/tutorials) +- [Report issues](https://github.com/CompBtBs/COBRAxy/issues) +- Suggest new tutorial topics + +Ready to start? Pick your first tutorial above! 🚀 \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tutorials/galaxy-setup.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,159 @@ +# Galaxy Setup Tutorial + +Learn how to set up a local Galaxy instance with COBRAxy tools for web-based metabolic analysis. + +## Overview + +This tutorial provides guidance and references to official Galaxy documentation for: + +- Installing Galaxy locally (using official Galaxy guides) +- Adding COBRAxy tools to your Galaxy instance +- Running COBRAxy analyses through the web interface + +## Step 1: Install Galaxy Locally + +For installing Galaxy on your local machine, follow the official documentation: + +### Official Installation Guides + +- **[Galaxy Installation Guide](https://docs.galaxyproject.org/en/master/admin/)** + +- **[Galaxy Quick Start](https://docs.galaxyproject.org/en/master/admin/production.html)** + +- **[Galaxy Training: Admin Track](https://training.galaxyproject.org/training-material/topics/admin/)** + +### Quick Summary + +1. Clone Galaxy repository: `git clone https://github.com/galaxyproject/galaxy.git` +2. Run setup script: `sh run.sh` +3. Access at: `http://localhost:8080` + +**Note**: Refer to official documentation for detailed configuration, security settings, and production deployment. + +## Step 2: Add COBRAxy Tools to Galaxy + +For adding custom tools to Galaxy, refer to the official documentation: + +### Official Tool Installation Guides + +- **[Adding Tools to Galaxy](https://docs.galaxyproject.org/en/master/admin/tool_panel.html)** + +- **[Tool Development Tutorial](https://training.galaxyproject.org/training-material/topics/dev/)** + +- **[Galaxy Tool Installation](https://planemo.readthedocs.io/en/latest/)** + +### COBRAxy-Specific Setup + +1. **Copy COBRAxy files** to Galaxy's tools directory: + ```bash + mkdir -p tools/cobraxy + cp /path/to/COBRAxy/*.xml tools/cobraxy/ + cp /path/to/COBRAxy/*.py tools/cobraxy/ + cp -r /path/to/COBRAxy/utils tools/cobraxy/ + cp -r /path/to/COBRAxy/local tools/cobraxy/ + ``` + +2. **Add tools to Galaxy configuration**: + Edit `config/tool_conf.xml` and add a COBRAxy section with all tool XML files. + +3. **Restart Galaxy** to load the new tools. + +**Note**: Consult the official Galaxy documentation for detailed instructions on tool installation, dependency management, and troubleshooting. + +## Step 3: Using COBRAxy in Galaxy + +### Verify Installation + +After following the official Galaxy setup and tool installation procedures: + +1. Access your Galaxy instance (typically `http://localhost:8080`) +2. Check that COBRAxy tools appear in the tool panel +3. Verify Python dependencies are available in Galaxy's environment + +### Basic Usage + +1. **Upload data** using Galaxy's data upload interface +2. **Select COBRAxy tools** from the tool panel +3. **Configure parameters** through the web interface +4. **Execute analyses** and monitor job progress +5. **Download results** from Galaxy's history panel + +## Creating COBRAxy Workflows + +### Workflow Development Resources + +For creating workflows with COBRAxy tools in Galaxy: + +- **[Galaxy Workflow Tutorial](https://training.galaxyproject.org/training-material/topics/galaxy-interface/tutorials/workflow-editor/tutorial.html)** + - Creating, editing, and sharing workflows + - Workflow best practices + +- **[Workflow Management](https://docs.galaxyproject.org/en/master/user/galaxy_workflow.html)** + - Official workflow documentation + - Advanced workflow features + +### Example COBRAxy Workflow + +A typical COBRAxy workflow might include: + +1. **RAS Generator** → Generate activity scores from gene expression +2. **MAREA** → Perform statistical analysis and create pathway maps +3. **RAS to Bounds** → Apply constraints (optional, for flux analysis) +4. **Flux Simulation** → Sample metabolic fluxes (optional) +5. **Flux to Map** → Create final visualizations (optional) + +## Additional Resources + +### Galaxy Administration Resources + +- **[Galaxy Admin Documentation](https://docs.galaxyproject.org/en/master/admin/)** + - Complete administrator guide + - Configuration, security, and maintenance + +- **[Galaxy Training Materials](https://training.galaxyproject.org/)** + - Hands-on tutorials for administrators and users + - Best practices and troubleshooting + +- **[Galaxy Community Hub](https://galaxyproject.org/)** + - Community support and resources + - Tool repositories and shared workflows + +### COBRAxy-Specific Resources + +- **Dependencies**: Ensure `cobra`, `pandas`, `numpy`, `scipy` are installed in Galaxy's Python environment +- **Tool Files**: All COBRAxy XML and Python files should be accessible to Galaxy +- **Configuration**: Follow Galaxy's tool installation procedures for proper integration + +## Troubleshooting + +For troubleshooting Galaxy installations and tool integration issues: + +### Official Troubleshooting Resources + +- **[Galaxy FAQ](https://docs.galaxyproject.org/en/master/admin/faq.html)** + - Common installation and configuration issues + - Performance optimization tips + +- **[Galaxy Help Forum](https://help.galaxyproject.org/)** + - Community-driven support + - Search existing solutions or ask new questions + +- **[Galaxy GitHub Issues](https://github.com/galaxyproject/galaxy/issues)** + - Report bugs and technical issues + - Feature requests and discussions + +### COBRAxy-Specific Issues + +For issues specific to COBRAxy tools in Galaxy: + +- **Tool not appearing**: Check tool_conf.xml configuration and restart Galaxy +- **Execution failures**: Verify Python dependencies and file permissions +- **Parameter errors**: Ensure input data formats match tool requirements + +Refer to the [COBRAxy Tools Documentation](../tools/) for detailed parameter information and data format requirements. + +## Summary + +This tutorial provides guidance for setting up Galaxy with COBRAxy tools by referencing official Galaxy documentation. For detailed installation procedures, always consult the official Galaxy administrator guides, as they are regularly updated with the latest best practices and troubleshooting information. + +The combination of Galaxy's web interface with COBRAxy's metabolic analysis capabilities provides a powerful platform for researchers who prefer graphical interfaces over command-line tools. \ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/COBRAxy/docs/tutorials/python-api.md Tue Sep 30 14:02:17 2025 +0000 @@ -0,0 +1,531 @@ +# Python API Tutorial + +Learn how to use COBRAxy tools programmatically in Python scripts and analysis pipelines. + +## Overview + +This tutorial teaches you to integrate COBRAxy into Python workflows by calling tool main functions directly with parsed arguments. + +**Time required**: ~45 minutes +**Difficulty**: Intermediate +**Prerequisites**: Basic Python knowledge, COBRAxy installation + +## Understanding COBRAxy Architecture + +### Tool Structure + +Each COBRAxy tool is a Python module with: +- `main(args)` function that accepts argument list +- Command-line argument parsing +- Self-contained execution logic + +```python +# General pattern for all tools +import tool_module +tool_module.main(['-arg1', 'value1', '-arg2', 'value2']) +``` + +### Available Tools + +| Python Module | Purpose | Key Arguments | +|---------------|---------|---------------| +| `ras_generator` | Compute reaction activity scores | `-in`, `-ra`, `-rs` | +| `rps_generator` | Compute reaction propensity scores | `-id`, `-rp` | +| `marea` | Statistical pathway analysis | `-input_data`, `-choice_map` | +| `ras_to_bounds` | Apply RAS constraints to model | `-ir`, `-ms`, `-idop` | +| `flux_simulation` | Sample metabolic fluxes | `-ms`, `-in`, `-a`, `-ns` | +| `flux_to_map` | Add flux data to maps | `-if`, `-mp`, `-idop` | + +## Setup Your Environment + +### Import Required Modules + +```python +import sys +import os +from pathlib import Path + +# Add COBRAxy to Python path +cobraxy_path = "/path/to/COBRAxy" +sys.path.insert(0, cobraxy_path) + +# Import COBRAxy tools +import ras_generator +import rps_generator +import marea +import ras_to_bounds +import flux_simulation +import flux_to_map +import metabolicModel2Tabular as model_setting +``` + +### Set Working Directory + +```python +# Set up working directory +work_dir = Path("/path/to/analysis") +work_dir.mkdir(exist_ok=True) +os.chdir(work_dir) + +# COBRAxy tools expect this parameter +tool_dir = str(Path(cobraxy_path).absolute()) +``` + +## Basic Workflow Example + +### Step 1: Prepare Sample Data + +```python +import pandas as pd +import numpy as np + +# Create sample gene expression data +genes = ['HGNC:5', 'HGNC:10', 'HGNC:15', 'HGNC:25', 'HGNC:30'] +samples = ['Control_1', 'Control_2', 'Treatment_1', 'Treatment_2'] + +# Generate random expression values +np.random.seed(42) +data = np.random.lognormal(mean=2, sigma=1, size=(len(genes), len(samples))) + +# Create DataFrame +expression_df = pd.DataFrame(data, index=genes, columns=samples) +expression_df.index.name = 'Gene_ID' + +# Save to file +expression_file = work_dir / "expression_data.tsv" +expression_df.to_csv(expression_file, sep='\t') +print(f"Created sample data: {expression_file}") +``` + +### Step 2: Extract Model Information + +```python +# Extract model components (optional, for understanding model structure) +model_args = [ + '-td', tool_dir, + '-ms', 'ENGRO2', # Use built-in ENGRO2 model + '-idop', str(work_dir / 'model_info') +] + +try: + model_setting.main(model_args) + print("✓ Model information extracted") +except Exception as e: + print(f"Model extraction failed: {e}") +``` + +### Step 3: Generate RAS Scores + +```python +# Generate Reaction Activity Scores +ras_output = work_dir / "ras_scores.tsv" + +ras_args = [ + '-td', tool_dir, + '-in', str(expression_file), + '-ra', str(ras_output), + '-rs', 'ENGRO2', # Built-in model + '-n', 'true' # Handle missing genes +] + +try: + ras_generator.main(ras_args) + print(f"✓ RAS scores generated: {ras_output}") +except Exception as e: + print(f"RAS generation failed: {e}") + raise +``` + +### Step 4: Generate RPS Scores (Optional) + +```python +# Create sample metabolite data +metabolites = ['glucose', 'pyruvate', 'lactate', 'ATP', 'NADH'] +met_data = np.random.lognormal(mean=3, sigma=0.5, size=(len(metabolites), len(samples))) + +met_df = pd.DataFrame(met_data, index=metabolites, columns=samples) +met_df.index.name = 'Metabolite_ID' + +metabolite_file = work_dir / "metabolite_data.tsv" +met_df.to_csv(metabolite_file, sep='\t') + +# Generate Reaction Propensity Scores +rps_output = work_dir / "rps_scores.tsv" + +rps_args = [ + '-td', tool_dir, + '-id', str(metabolite_file), + '-rp', str(rps_output) +] + +try: + rps_generator.main(rps_args) + print(f"✓ RPS scores generated: {rps_output}") +except Exception as e: + print(f"RPS generation warning: {e}") + # RPS generation might fail with sample data - that's OK +``` + +### Step 5: Statistical Analysis with MAREA + +```python +# Create enriched pathway maps +maps_output = work_dir / "pathway_maps" + +marea_args = [ + '-td', tool_dir, + '-using_RAS', 'true', + '-input_data', str(ras_output), + '-choice_map', 'ENGRO2', + '-gs', 'true', # Gene set analysis + '-idop', str(maps_output) +] + +try: + marea.main(marea_args) + print(f"✓ Pathway maps created: {maps_output}") +except Exception as e: + print(f"MAREA analysis failed: {e}") +``` + +### Step 6: Flux Simulation Pipeline + +```python +# Apply RAS constraints to model +bounds_output = work_dir / "model_bounds" + +bounds_args = [ + '-td', tool_dir, + '-ms', 'ENGRO2', + '-ir', str(ras_output), + '-rs', 'true', # Use RAS values + '-idop', str(bounds_output) +] + +try: + ras_to_bounds.main(bounds_args) + print(f"✓ Model constraints applied: {bounds_output}") +except Exception as e: + print(f"Bounds generation failed: {e}") + raise + +# Sample metabolic fluxes +flux_output = work_dir / "flux_samples" + +flux_args = [ + '-td', tool_dir, + '-ms', 'ENGRO2', + '-in', str(bounds_output / "*.tsv"), # Will be expanded by tool + '-a', 'CBS', # Sampling algorithm + '-ns', '1000', # Number of samples + '-idop', str(flux_output) +] + +try: + flux_simulation.main(flux_args) + print(f"✓ Flux samples generated: {flux_output}") +except Exception as e: + print(f"Flux simulation failed: {e}") +``` + +### Step 7: Create Final Visualizations + +```python +# Add flux data to enriched maps +final_maps = work_dir / "final_visualizations" + +# Check if we have both maps and flux data +maps_dir = maps_output +flux_dir = flux_output + +if maps_dir.exists() and flux_dir.exists(): + flux_to_map_args = [ + '-td', tool_dir, + '-if', str(flux_dir / "*.tsv"), + '-mp', str(maps_dir / "*.svg"), + '-idop', str(final_maps) + ] + + try: + flux_to_map.main(flux_to_map_args) + print(f"✓ Final visualizations created: {final_maps}") + except Exception as e: + print(f"Final mapping failed: {e}") +else: + print("Skipping final visualization - missing input files") +``` + +## Advanced Usage Patterns + +### Error Handling and Validation + +```python +def run_cobraxy_tool(tool_module, args, description): + """Helper function to run COBRAxy tools with error handling.""" + try: + print(f"Running {description}...") + tool_module.main(args) + print(f"✓ {description} completed successfully") + return True + except Exception as e: + print(f"✗ {description} failed: {e}") + return False + +# Usage +success = run_cobraxy_tool( + ras_generator, + ras_args, + "RAS generation" +) + +if not success: + print("Pipeline stopped due to error") + exit(1) +``` + +### Batch Processing Multiple Datasets + +```python +def process_dataset(dataset_path, output_dir): + """Process a single dataset through COBRAxy pipeline.""" + + dataset_name = dataset_path.stem + out_dir = Path(output_dir) / dataset_name + out_dir.mkdir(exist_ok=True) + + # Generate RAS + ras_file = out_dir / "ras_scores.tsv" + ras_args = [ + '-td', tool_dir, + '-in', str(dataset_path), + '-ra', str(ras_file), + '-rs', 'ENGRO2' + ] + + if run_cobraxy_tool(ras_generator, ras_args, f"RAS for {dataset_name}"): + # Continue with MAREA analysis + maps_dir = out_dir / "maps" + marea_args = [ + '-td', tool_dir, + '-using_RAS', 'true', + '-input_data', str(ras_file), + '-choice_map', 'ENGRO2', + '-idop', str(maps_dir) + ] + run_cobraxy_tool(marea, marea_args, f"MAREA for {dataset_name}") + + return out_dir + +# Process multiple datasets +datasets = [ + "/path/to/dataset1.tsv", + "/path/to/dataset2.tsv", + "/path/to/dataset3.tsv" +] + +results = [] +for dataset in datasets: + result_dir = process_dataset(Path(dataset), work_dir / "batch_results") + results.append(result_dir) + +print(f"Processed {len(results)} datasets") +``` + +### Custom Analysis Pipelines + +```python +class COBRAxyPipeline: + """Custom COBRAxy analysis pipeline.""" + + def __init__(self, tool_dir, work_dir): + self.tool_dir = tool_dir + self.work_dir = Path(work_dir) + self.work_dir.mkdir(exist_ok=True) + + def run_enrichment_analysis(self, expression_file, model='ENGRO2'): + """Run enrichment-focused analysis.""" + + # Generate RAS + ras_file = self.work_dir / "ras_scores.tsv" + ras_args = ['-td', self.tool_dir, '-in', str(expression_file), + '-ra', str(ras_file), '-rs', model] + + if not run_cobraxy_tool(ras_generator, ras_args, "RAS generation"): + return None + + # Run MAREA + maps_dir = self.work_dir / "enrichment_maps" + marea_args = ['-td', self.tool_dir, '-using_RAS', 'true', + '-input_data', str(ras_file), '-choice_map', model, + '-gs', 'true', '-idop', str(maps_dir)] + + if run_cobraxy_tool(marea, marea_args, "MAREA analysis"): + return maps_dir + return None + + def run_flux_analysis(self, expression_file, model='ENGRO2', n_samples=1000): + """Run flux sampling analysis.""" + + # Generate RAS and apply bounds + ras_file = self.work_dir / "ras_scores.tsv" + bounds_dir = self.work_dir / "bounds" + flux_dir = self.work_dir / "flux_samples" + + # RAS generation + ras_args = ['-td', self.tool_dir, '-in', str(expression_file), + '-ra', str(ras_file), '-rs', model] + if not run_cobraxy_tool(ras_generator, ras_args, "RAS generation"): + return None + + # Apply bounds + bounds_args = ['-td', self.tool_dir, '-ms', model, '-ir', str(ras_file), + '-rs', 'true', '-idop', str(bounds_dir)] + if not run_cobraxy_tool(ras_to_bounds, bounds_args, "Bounds application"): + return None + + # Flux sampling + flux_args = ['-td', self.tool_dir, '-ms', model, + '-in', str(bounds_dir / "*.tsv"), + '-a', 'CBS', '-ns', str(n_samples), '-idop', str(flux_dir)] + + if run_cobraxy_tool(flux_simulation, flux_args, "Flux simulation"): + return flux_dir + return None + +# Usage +pipeline = COBRAxyPipeline(tool_dir, work_dir / "custom_analysis") + +# Run enrichment analysis +enrichment_results = pipeline.run_enrichment_analysis(expression_file) +if enrichment_results: + print(f"Enrichment analysis completed: {enrichment_results}") + +# Run flux analysis +flux_results = pipeline.run_flux_analysis(expression_file, n_samples=500) +if flux_results: + print(f"Flux analysis completed: {flux_results}") +``` + +## Integration with Data Analysis Libraries + +### Pandas Integration + +```python +# Read COBRAxy results back into pandas +ras_df = pd.read_csv(ras_output, sep='\t', index_col=0) +print(f"RAS data shape: {ras_df.shape}") +print(f"Sample statistics:\n{ras_df.describe()}") + +# Filter highly variable reactions +ras_std = ras_df.std(axis=1) +variable_reactions = ras_std.nlargest(20).index +print(f"Most variable reactions: {list(variable_reactions)}") +``` + +### Matplotlib Visualization + +```python +import matplotlib.pyplot as plt +import seaborn as sns + +# Visualize RAS distributions +plt.figure(figsize=(12, 8)) +sns.heatmap(ras_df.iloc[:50], cmap='RdBu_r', center=0, cbar_kws={'label': 'RAS Score'}) +plt.title('Reaction Activity Scores (Top 50 Reactions)') +plt.xlabel('Samples') +plt.ylabel('Reactions') +plt.tight_layout() +plt.savefig(work_dir / 'ras_heatmap.png', dpi=300) +plt.show() +``` + +## Best Practices + +### 1. Environment Management +```python +# Use pathlib for cross-platform compatibility +from pathlib import Path + +# Use absolute paths +tool_dir = str(Path(cobraxy_path).absolute()) +work_dir = Path("/analysis").absolute() +``` + +### 2. Error Handling +```python +# Always wrap tool calls in try-except +try: + ras_generator.main(ras_args) +except Exception as e: + print(f"RAS generation failed: {e}") + # Log details, cleanup, or alternative action +``` + +### 3. Argument Validation +```python +def validate_file_exists(filepath): + """Validate input file exists.""" + path = Path(filepath) + if not path.exists(): + raise FileNotFoundError(f"Input file not found: {filepath}") + return str(path.absolute()) + +# Use before calling tools +expression_file = validate_file_exists(expression_file) +``` + + + +## Troubleshooting + +### Common Issues + +**Import errors** +```python +# Check if COBRAxy path is correct +import sys +print("Python path includes:") +for p in sys.path: + print(f" {p}") + +# Add COBRAxy path +sys.path.insert(0, "/correct/path/to/COBRAxy") +``` + +**Tool execution failures** +```python +# Enable verbose output +import logging +logging.basicConfig(level=logging.DEBUG) + +# Check working directory +print(f"Current directory: {os.getcwd()}") +print(f"Directory contents: {list(Path('.').iterdir())}") +``` + +**File path issues** +```python +# Use absolute paths +ras_args = [ + '-td', str(Path(tool_dir).absolute()), + '-in', str(Path(expression_file).absolute()), + '-ra', str(Path(ras_output).absolute()), + '-rs', 'ENGRO2' +] +``` + +## Next Steps + +Now that you can use COBRAxy programmatically: + +1. **[Tools Reference](../tools/)** - Detailed parameter documentation +2. **[Examples](../examples/)** - Real-world analysis scripts +3. **Build custom analysis pipelines** for your research needs +4. **Integrate with workflow managers** like Snakemake or Nextflow + +## Resources + +- [COBRApy Documentation](https://cobrapy.readthedocs.io/) - Underlying metabolic modeling library +- [Pandas Documentation](https://pandas.pydata.org/) - Data manipulation +- [Matplotlib Gallery](https://matplotlib.org/gallery/) - Visualization examples +- [Python Pathlib](https://docs.python.org/3/library/pathlib.html) - Modern path handling \ No newline at end of file
--- a/COBRAxy/metabolicModel2Tabular.py Mon Sep 29 15:34:59 2025 +0000 +++ b/COBRAxy/metabolicModel2Tabular.py Tue Sep 30 14:02:17 2025 +0000 @@ -203,8 +203,6 @@ # Determine final model name: explicit --name overrides, otherwise use the model id - model_name = ARGS.name if ARGS.name else ARGS.model - if ARGS.name == "ENGRO2" and ARGS.medium_selector != "Default": df_mediums = pd.read_csv(ARGS.tool_dir + "/local/medium/medium.csv", index_col = 0) ARGS.medium_selector = ARGS.medium_selector.replace("_", " ")
--- a/COBRAxy/utils/model_utils.py Mon Sep 29 15:34:59 2025 +0000 +++ b/COBRAxy/utils/model_utils.py Tue Sep 30 14:02:17 2025 +0000 @@ -692,7 +692,7 @@ # If anything goes wrong, return the original expression return expr -# ---------- Main public function ---------- + def translate_model_genes(model: 'cobra.Model', mapping_df: 'pd.DataFrame', target_nomenclature: str,