# epfl-lcsb/etfl architecture

> Architecture diagram of the GitHub repository epfl-lcsb/etfl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/epfl-lcsb/etfl
- Repository: https://github.com/epfl-lcsb/etfl

## Overview

##### Project type and purpose
- ETFL is a domain-specific Python library (an open-source tool) for building and solving constraint-based metabolic models that integrate expression, thermodynamics and resource allocation.
- Its purpose is to let users load metabolic networks (e.g., E. coli iJO1366), augment them with multi-omics constraints via pyTFA/COBRApy/optlang, and perform analyses (MOMA, dynamic FBA, etc.).

##### File structure
- Top-level directories:
- etfl/           ← main Python package
– core/         ← core model construction (allocations, macromolecules, thermodynamics)
– analysis/     ← high-level analysis routines (dynamic, MOMA, MoPA, summary)
– optim/        ← optimization layer (config, constraints, variables)
– io/           ← serialization (JSON, dict), model import/export
– integration/  ← multi-omics integration (transcriptomics)
– utils/        ← calibration, parsing, general helpers
– data/         ← built-in organism/model data loaders (e.g., E. coli)
– debugging/    ← debug tools for model inspection
– tests/        ← unit tests for each component
- docker/         ← Dockerfiles & scripts to build/run containerized environment
- doc/            ← Sphinx documentation source
- models/         ← static model files (iJO1366.json)
- organism_data/  ← raw and preprocessed organism-specific datasets
- tutorials/      ← example scripts demonstrating usage
- work/           ← experimental code and data (not core)
- setup.py, setup.cfg, LICENSE, README.rst

##### README for additional insights
- Lists external dependencies: pyTFA, COBRApy, optlang, CPLEX/Gurobi/GLPK.
- Recommends Docker for environment consistency.
- Emphasizes model building → solver interface → analysis workflow.

##### Important reminders
- Be exhaustive: include every top-level module and its role
- Flow of data & control from start (model load) to finish (result analysis)
- Extensibility: where a user could plug in a new analysis or solver
- Keep component granularity aligned with the file structure (each submodule = one block)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        DataRaw[(organism_data/)]:::data
        DataModels[(models/iJO1366.json)]:::data
    end

    %% Input/IO
    subgraph "Input / IO" 
        IOJSON["etfl/io/json.py"]:::io
        IODict["etfl/io/dict.py"]:::io
    end

    %% Core Modeling Engine
    subgraph "Core Modeling Engine"
        CoreAlloc["allocation.py"]:::internal
        CoreMacro["macromolecule.py"]:::internal
        CoreExpr["expression.py"]:::internal
        CoreGenes["genes.py"]:::internal
        CoreThermo["thermomemodel.py"]:::internal
        CoreMem["memodel.py"]:::internal
        CoreReactions["reactions.py"]:::internal
        CoreIon["ion.py"]:::internal
        CoreCarb["carbohydrate.py"]:::internal
        CoreLipid["lipid.py"]:::internal
        CoreEnzyme["enzyme.py"]:::internal
        CoreRNA["rna.py"]:::internal
        CoreDNA["dna.py"]:::internal
        CoreVector["vector.py"]:::internal
        CoreRecomb["recombmodel.py"]:::internal
    end

    %% Optimization Layer
    subgraph "Optimization Layer"
        OptConfig["config.py"]:::internal
        OptConstr["constraints.py"]:::internal
        OptVars["variables.py"]:::internal
        OptUtils["utils.py"]:::internal
    end

    %% Analysis Workflows
    subgraph "Analysis Workflows"
        DynFBA["dynamic.py"]:::internal
        MOMA["moma.py"]:::internal
        MoPA["mopa.py"]:::internal
        Summary["summary.py"]:::internal
        AnalysisUtils["utils.py"]:::internal
    end

    %% Integration
    subgraph "Multi-Omics Integration"
        Integration["transcriptomics.py"]:::internal
    end

    %% Utilities & Debugging
    subgraph "Utilities & Debugging"
        UtilsCalib["calibration.py"]:::internal
        UtilsParse["parsing.py"]:::internal
        UtilsGen["utils.py"]:::internal
        Debug["debugging.py"]:::internal
    end

    %% Built-In Data Loaders
    subgraph "Built-In Data Loaders"
        DataEcoli["ecoli.py"]:::internal
        EcoliUtils["ecoli_utils.py"]:::internal
    end

    %% Presentation & Deployment
    subgraph "Presentation"
        Tutorials["tutorials/"]:::external
        Documentation["doc/"]:::external
    end

    subgraph "Deployment"
        Docker["docker/"]:::deployment
    end

    %% Tests
    subgraph "Tests"
        TestSmall["small_model.py"]:::internal
        TestCore["test_core.py"]:::internal
        TestResAlloc["test_resources_alloc.py"]:::internal
        TestThermo["test_thermo.py"]:::internal
    end

    %% External Dependencies
    subgraph "External Dependencies"
        COBRApy((COBRApy)):::external
        pyTFA((pyTFA)):::external
        Optlang((optlang)):::external
        Solvers((GLPK/CPLEX/Gurobi)):::external
    end

    %% Relationships
    DataRaw -->|feeds| IOJSON
    DataModels -->|feeds| IODict
    IOJSON -->|load model| CoreAlloc
    IODict -->|load dict| CoreAlloc
    CoreAlloc --> CoreExpr
    CoreExpr --> CoreThermo
    CoreThermo --> CoreReactions
    CoreReactions --> CoreRecomb
    CoreRecomb --> OptConfig
    OptConfig --> OptConstr
    OptConstr --> OptVars
    OptVars -->|build problem| OptUtils
    OptUtils --> Optlang
    Optlang --> Solvers
    Solvers --> Optlang
    Optlang --> OptUtils
    OptUtils --> Summary
    Summary --> DynFBA
    Summary --> MOMA
    Summary --> MoPA
    DynFBA --> AnalysisUtils
    MOMA --> AnalysisUtils
    MoPA --> AnalysisUtils
    Integration --> CoreExpr
    Integration --> AnalysisUtils
    UtilsCalib --> CoreAlloc
    UtilsParse --> IOJSON
    UtilsGen --> CoreRecomb
    Debug --> CoreReactions
    DataEcoli --> IOJSON
    EcoliUtils --> DataEcoli
    Tutorials --> CoreAlloc
    Tutorials --> DynFBA
    Documentation --> IOJSON
    Documentation --> CoreAlloc
    Docker --> COBRApy
    Docker --> pyTFA
    Docker --> Solvers
    TestSmall --> CoreAlloc
    TestCore --> CoreReactions
    TestResAlloc --> CoreAlloc
    TestThermo --> CoreThermo

    %% Click Events
    click DataRaw "https://github.com/epfl-lcsb/etfl/tree/master/organism_data/"
    click DataModels "https://github.com/epfl-lcsb/etfl/blob/master/models/iJO1366.json"
    click IOJSON "https://github.com/epfl-lcsb/etfl/blob/master/etfl/io/json.py"
    click IODict "https://github.com/epfl-lcsb/etfl/blob/master/etfl/io/dict.py"
    click CoreAlloc "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/allocation.py"
    click CoreMacro "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/macromolecule.py"
    click CoreExpr "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/expression.py"
    click CoreGenes "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/genes.py"
    click CoreThermo "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/thermomemodel.py"
    click CoreMem "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/memodel.py"
    click CoreReactions "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/reactions.py"
    click CoreIon "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/ion.py"
    click CoreCarb "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/carbohydrate.py"
    click CoreLipid "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/lipid.py"
    click CoreEnzyme "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/enzyme.py"
    click CoreRNA "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/rna.py"
    click CoreDNA "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/dna.py"
    click CoreVector "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/vector.py"
    click CoreRecomb "https://github.com/epfl-lcsb/etfl/blob/master/etfl/core/recombmodel.py"
    click OptConfig "https://github.com/epfl-lcsb/etfl/blob/master/etfl/optim/config.py"
    click OptConstr "https://github.com/epfl-lcsb/etfl/blob/master/etfl/optim/constraints.py"
    click OptVars "https://github.com/epfl-lcsb/etfl/blob/master/etfl/optim/variables.py"
    click OptUtils "https://github.com/epfl-lcsb/etfl/blob/master/etfl/optim/utils.py"
    click DynFBA "https://github.com/epfl-lcsb/etfl/blob/master/etfl/analysis/dynamic.py"
    click MOMA "https://github.com/epfl-lcsb/etfl/blob/master/etfl/analysis/moma.py"
    click MoPA "https://github.com/epfl-lcsb/etfl/blob/master/etfl/analysis/mopa.py"
    click Summary "https://github.com/epfl-lcsb/etfl/blob/master/etfl/analysis/summary.py"
    click AnalysisUtils "https://github.com/epfl-lcsb/etfl/blob/master/etfl/analysis/utils.py"
    click Integration "https://github.com/epfl-lcsb/etfl/blob/master/etfl/integration/transcriptomics.py"
    click UtilsCalib "https://github.com/epfl-lcsb/etfl/blob/master/etfl/utils/calibration.py"
    click UtilsParse "https://github.com/epfl-lcsb/etfl/blob/master/etfl/utils/parsing.py"
    click UtilsGen "https://github.com/epfl-lcsb/etfl/blob/master/etfl/utils/utils.py"
    click Debug "https://github.com/epfl-lcsb/etfl/blob/master/etfl/debugging/debugging.py"
    click DataEcoli "https://github.com/epfl-lcsb/etfl/blob/master/etfl/data/ecoli.py"
    click EcoliUtils "https://github.com/epfl-lcsb/etfl/blob/master/etfl/data/ecoli_utils.py"
    click Tutorials "https://github.com/epfl-lcsb/etfl/tree/master/tutorials/"
    click Documentation "https://github.com/epfl-lcsb/etfl/tree/master/doc/"
    click Docker "https://github.com/epfl-lcsb/etfl/tree/master/docker/"

    %% Styles
    classDef data fill:#9f6,stroke:#333,stroke-width:1px
    classDef io fill:#f96,stroke:#333,stroke-width:1px
    classDef internal fill:#6cf,stroke:#333,stroke-width:1px
    classDef external fill:#a6f,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef deployment fill:#fc9,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
