SIGMA: Signal Inference with Graph-based Mechanistic Analysis

SIGMA is a framework that converts curated prior knowledge into causally interpretable, elementally balanced signal-transduction cascades that connect source species to target species.

This repository contains the MATLAB implementation of SIGMA together with the data, models, and study-specific scripts used in the manuscript "Mechanistic reconstruction of receptor-to-transcription factor signaling integrating prior knowledge and omics".

With this repository you can:

1. Reproduce the analyses and outputs reported in the manuscript.
2. Use the provided Reactome or curated SIGMA model to connect your own species of interest.
3. Rebuild the workflow from scratch to generate your own curated SIGMA model and run your own case studies.

Citation

Mechanistic reconstruction of receptor-to-transcription factor signaling integrating prior knowledge and omics. David Liaskos, Omid Oftadeh, Margherita Tonini, Maria Masid, Vassily Hatzimanikatis.

Requirements

Repository download

Large binary files are tracked with Git LFS:

git clone https://github.com/EPFL-LCSB/sigma.git
cd sigma
git lfs install
git lfs pull

Software

1. MATLAB

   SIGMA was developed and tested with MATLAB R2024b. Other MATLAB versions may also work, but were not systematically tested. The MATLAB installation must include the Statistics and Machine Learning Toolbox add-on.

2. IBM ILOG CPLEX

   SIGMA uses IBM ILOG CPLEX as the optimization solver. The version used in this work was obtained via the IBM Academic Initiative. We recommend CPLEX 12.10, which has been extensively tested in this workflow. Please ensure that MATLAB, CPLEX, and your operating system are mutually compatible according to IBM's official compatibility information.

3. Python (optional, only for re-parsing raw Reactome SBML files)

   If you want to rebuild the parsed Reactome species/ and reactions/ tables from raw SBML pathway files, the parser data/REACTOME_homo_sapiens/SIGMA_parser.py also requires Python with libsbml, pandas, and tqdm.

Before You Start

1. Open MATLAB with the repository root as the current working directory. All scripts use relative paths such as ./data/ and ./models/.
2. Duplicate config_paths_template.m and save the copy as config_paths.m.
3. Edit config_paths.m and replace the placeholder CPLEX path with your local installation path.

Important: config_paths.m is machine-specific, should stay local, and should not be committed.

Repository Layout

• code/: internal MATLAB functions used by the main scripts.
• data/: input data, curated pathway selections, case-study templates, and omics files.
• models/: precomputed Reactome and curated SIGMA models.
• output/: generated network tables, cascade results, enrichment results, visualizations, and saved workspaces.

Usage

Choose the workflow that matches your goal.

1. Reproduce the paper results

Use this route if you want to rerun the study-specific analyses included in the manuscript.

Run the following scripts in this order:

1. create_reactome_model.m
2. identify_receptors.m
3. identify_TFs.m
4. create_SIGMA_model.m
5. connect_all_receptors_to_all_TFs_balanced.m
6. connect_TGFB_to_SP1_core.m
7. connect_TGFB_to_SP1.m
8. enrich_SIGMA_pathways.m

The study-specific inputs used by these scripts are already included in the repository, in particular:

• data/pathways_curation/
• data/case_studies/SIGMA_TGFB_to_SP1_nodes/
• data/omics_data/

The main output folders generated by this workflow are:

• output/Reactome_model/
• output/SIGMA_model/
• output/SIGMA_all_receptors_to_all_TFs_balanced/
• output/SIGMA_TGFB_to_SP1_core/
• output/SIGMA_TGFB_to_SP1/
• output/PEA_Tcells/

If you only want to inspect the published models and results, they are already provided in models/ and output/ and do not need to be regenerated.

2. Use the provided models for your own case study

Use this route if you want to extract cascades for your own source-target pairs while reusing one of the provided models:

• models/reactome_model.mat
• models/SIGMA_model.mat

The reusable cascade-extraction template is:

• connect_species_template.m

Recommended workflow:

1. Copy connect_species_template.m to a new user script, for example connect_my_case_study.m.
2. Set model_name to reactome or SIGMA.
3. Set a unique output_folder_name so you do not overwrite the existing study outputs.
4. Create a folder under data/case_studies/ for your case study, for example data/case_studies/my_case/.
5. Add one or more .xlsx files to that folder. Each file must contain the columns Start and Target and use valid species IDs.

The included case-study example has the following format:

Start            Target
species_170842   species_2187302

For the included SIGMA model, valid species identifiers are directly available for receptor and transcription-factor species in:

• output/SIGMA_model/SIGMA_receptors_list.xlsx
• output/SIGMA_model/SIGMA_tfs_list.xlsx

If you want to use other species from the Reactome or SIGMA models, retrieve their IDs directly from the loaded MATLAB model structure, for example from model.mets together with model.metNames.

Optional omics files can be added to data/omics_data/. The expected CSV formats are:

Absolute data:
UniProtID,expression_value

Differential data:
UniProtID,log2FoldChange,padj

If you do not want to run balanced cascade enrichment analysis (BCEA), set path_enrichment = 'No' in your copied script.

After editing the template parameters and input paths, run your copied script. Results will be written to output/<output_folder_name>/.

3. Build your own curated SIGMA model and run the full workflow

Use this route if you want to create your own curated signaling model before running cascade extraction.

Step 1: prepare the Reactome input data

• If you want to work with the Reactome release already included in this repository, you can reuse the existing parsed files in data/REACTOME_homo_sapiens/species/ and data/REACTOME_homo_sapiens/reactions/.
• If you want to update to a different Reactome release, place the raw Homo sapiens SBML files in the input folder expected by the parser (by default data/REACTOME_homo_sapiens/homo_sapiens.3.1_06_12_2024/), update the paths in data/REACTOME_homo_sapiens/SIGMA_parser.py if needed, and run the parser to regenerate the species/ and reactions/ CSV tables.

Step 2: regenerate the generic Reactome resources

1. Run create_reactome_model.m.
2. Run identify_receptors.m.
3. Run identify_TFs.m.

Step 3: define your curated SIGMA model

Edit data/pathways_curation/pathways_curation.xlsx to specify the pathways and curated additions that should define your model. In particular, this file contains the pathways, dashed_lines, and pathway_connections sheets used during model construction.

The default create_SIGMA_model.m script builds the published SIGMA model. If you want to keep the included model untouched, first duplicate that script and give your custom version a new model_name and output_folder_name. Otherwise, the default script will overwrite models/SIGMA_model.mat and output/SIGMA_model/.

Step 4: build the model

Run your customized SIGMA model-construction script. This creates:

• the model files in models/
• network tables in output/<output_folder_name>/
• automatically generated receptor-TF pair files in output/<output_folder_name>/<model_name>_receptors_TFs_nodes/

Step 5: run downstream analyses on your new model

After the model is built, you can continue in one of three ways:

1. Use a copied version of connect_species_template.m to analyze your own case-study pairs.
2. Adapt connect_all_receptors_to_all_TFs_balanced.m if you want to scan many receptor-TF connections from the generated <model_name>_receptors_TFs_nodes/ directory.
3. Adapt enrich_SIGMA_pathways.m if you want pathway enrichment analysis on your custom model.

When you customize the model name or output folder, make sure the downstream scripts point to the matching files in models/ and output/.

License

This repository is released under the Apache License 2.0.