TabularQual converter

Convert between spreadsheets and SBML-qual for logical models (Boolean and multi-valued).

Note: the format is specified here.

Web App

Use directly in your browser - no installation required!

🔗 Launch Web App

Note: there are currently resource limits on Streamlit cloud, please run it locally for large networks.

---

Install

Option 1: Run Web App Locally

# 1) Install dependencies
pip install -r requirements.txt

# 2) Launch the web app
streamlit run app.py

The app will open in your browser at http://localhost:8501

Option 2: Command-Line Tools

# Install dependencies and console script
pip install -r requirements.txt
pip install -e .

Usage

Spreadsheet ➜ SBML

# Simple usage (output defaults to input name with .sbml extension)
to-sbml model.xlsx

# From XLSX with explicit output
to-sbml model.xlsx model_out.sbml

# From CSV files (using prefix - looks for Model_Species.csv, Model_Transitions.csv, etc.)
to-sbml Model

# From CSV directory
to-sbml examples/Faure2006/

SBML ➜ Spreadsheet

# Simple usage (output defaults to input name with .xlsx extension)
to-table model.sbml

# To XLSX with explicit output
to-table model.sbml output.xlsx

# To CSV files (creates Model_Model.csv, Model_Species.csv, etc.)
to-table model.sbml --csv

# To CSV with custom prefix
to-table model.sbml MyOutput --csv

Options

to-sbml INPUT [OUTPUT]:

• INPUT: input file/path. Supports XLSX, CSV file, directory with CSVs, or CSV prefix (e.g., Model for Model_Species.csv, Model_Transitions.csv, etc.)
• OUTPUT: output SBML file (optional, defaults to input name with .sbml extension)
• --inter-anno: use interaction annotations only (unless --trans-anno is also set)
• --trans-anno: use transition annotations only (unless --inter-anno is also set)
• --no-validate: skip annotation validation
• If you pass both flags or neither, the converter includes both annotation types

to-table INPUT [OUTPUT]:

• INPUT: input SBML file
• OUTPUT: output file/prefix (optional, defaults to input name)
• --csv: output as CSV files ({prefix}_Model.csv, {prefix}_Species.csv, {prefix}_Transitions.csv, {prefix}_Interactions.csv)
• --template: specify a template file for README and Appendix sheets (XLSX only)
• --colon-format: use colon notation for transition rules (: means >=)
• --no-validate: skip annotation validation

Transition Rules Syntax

The Transition-Rules column supports boolean and comparison expressions using the following operators and syntax (space will be ignored):

• Logical operators: & (AND), | (OR), ! (NOT)
• Parentheses: ( and ) for grouping expressions
• For multi-value model: threshold-based activation:
  • Colon notation: A:2 means "A is at level 2 or higher" (A >= 2)
  • Negated colon: !A:2 means "A is below level 2" (A < 2)
  • Explicit comparisons: A >= 2, B <= 1, C != 0 for precise control
  • Equivalent expressions: !CI:2 & !Cro:3 is the same as CI < 2 & Cro < 3 or CI <= 1 & Cro <= 2
• Simple species references:
  • A - Species A is active (level >= 1 for multi-valued, or level = 1 for binary)
  • !A - Species A is inactive (level = 0)

Examples:

• A & B - Both A and B are active (level ≥ 1 for multi-valued)
• A:2 | B < 1 - A is at level 2+ OR B is inactive
• N & !CI:2 & !Cro:3 - N active AND CI below level 2 AND Cro below level 3
• (A & B) | (!C & D != 1) - Complex grouped expression

Validation

TabularQual performs several validations during conversion to ensure data quality and SBML compliance.

SId Format Validation

Model_ID, Species_ID, Transitions_ID, and Compartment fields must conform to the SBML SId specification (SBML Level 3 Version 2):

• Must start with a letter (A–Z, a–z) or underscore (_)
• May contain only letters, digits (0–9), and underscores
• Case-sensitive (equality determined by exact string matching)
• No spaces, slashes, or other special characters allowed
• Uses plain ASCII characters only (no Unicode)

Automatic Cleanup: If an ID doesn't conform, it is automatically cleaned:

• Special characters (spaces, slashes, dashes, etc.) are replaced with underscores
• IDs starting with a digit get a leading underscore prepended
• Non-ASCII characters are removed
• Multiple consecutive underscores are collapsed

Example: PI3K/AKT-pathway → PI3K_AKT_pathway

Field Value Validation

The converter validates controlled vocabulary fields:

• Species Type: Must be one of Input, Internal, or Output (case-insensitive)
• Interaction Sign: Must be one of positive, negative, dual, or unknown (case-insensitive)
• Relation Qualifiers: Must be one of is, hasVersion, isVersionOf, isDescribedBy, hasPart, isPartOf, hasProperty, isPropertyOf, encodes, isEncodedBy, isHomologTo, occursIn, hasTaxon (case-insensitive)

Annotation Validation

Annotations in the SBML output can be validated using sbmlutils:

• Validates that annotation URIs are correctly formed
• Checks that identifiers.org resources are valid
• Enable/disable with --no-validate flag or checkbox in web app

To use annotation validation: pip install sbmlutils>=0.9.6

Notes

• The reader ignores a first README sheet if present, and reads Model, Species, Transitions, and Interactions.
• The SBML to Spreadsheet converter automatically uses doc/template.xlsx if available for README and Appendix sheets (XLSX output only).
• TODO: automatically detect Species:Type, Interactions:Target, Source and Sign.