From 4b561d90e747696a9bd3eb5347245cd41e2cbd40 Mon Sep 17 00:00:00 2001 From: Stella <30465823+stellaprins@users.noreply.github.com> Date: Wed, 29 Jan 2025 10:27:58 +0000 Subject: [PATCH] Feat update readme (#116) * add egg info to gitignore * remove commented out code * draft readme * bugfix level_version tag process_test_suite * remove BIOMD files that should not be there * update READMEs * bugfix command line options overrule main script * pre-commit comment for developers * add back BIOMD models, they are needed in validate all sh * add forward slashes in filepaths, fix typos --- .gitignore | 1 + BioModels/parse_biomodels.py | 1 - ...t_biomodels_compatibility_biosimulators.py | 2 +- README.md | 123 +++++++++++++++++- test_suite/README.md | 49 ++++--- test_suite/process_test_suite.py | 5 +- ..._test_suite_compatibility_biosimulators.py | 9 +- 7 files changed, 153 insertions(+), 37 deletions(-) diff --git a/.gitignore b/.gitignore index 0b8437e8..f51cc53b 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,4 @@ venv /SBML/.DS_Store /SBML/LEMS_NML2_Ex9_FN_missing_xmlns.omex /SBML/output +*.egg-info diff --git a/BioModels/parse_biomodels.py b/BioModels/parse_biomodels.py index ee434a6e..9270e766 100755 --- a/BioModels/parse_biomodels.py +++ b/BioModels/parse_biomodels.py @@ -353,5 +353,4 @@ def main(): if __name__ == "__main__": use_pickles = True - # model_id_n = 443 main() diff --git a/BioModels/test_biomodels_compatibility_biosimulators.py b/BioModels/test_biomodels_compatibility_biosimulators.py index 695c2953..ccdf6d0d 100644 --- a/BioModels/test_biomodels_compatibility_biosimulators.py +++ b/BioModels/test_biomodels_compatibility_biosimulators.py @@ -180,7 +180,7 @@ def main(): if __name__ == "__main__": - use_original_files = False + use_original_files = False # False allows you to tweak the SED-ML files before running. True overwrites the test files with the original BioModels files. biomodel_id_list = [ "BIOMD0000000001", "BIOMD0000000138", diff --git a/README.md b/README.md index 03f6ab14..c1255a28 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,125 @@ -# Converting NeuroML2/LEMS to & from SBML - +# SBML Showcase [![Continuous build using OMV](https://github.com/OpenSourceBrain/SBMLShowcase/actions/workflows/omv-ci.yml/badge.svg)](https://github.com/OpenSourceBrain/SBMLShowcase/actions/workflows/omv-ci.yml) [![Testing non OMV scripts](https://github.com/OpenSourceBrain/SBMLShowcase/actions/workflows/non-omv.yml/badge.svg)](https://github.com/OpenSourceBrain/SBMLShowcase/actions/workflows/non-omv.yml) +This repository contains files and instructions for testing validity of Systems Biology Markup Language (SBML) and Simulation Experiment Description Markup Language (SED-ML) files, and their compatibility with different simulations engines. + +## Results tables + +### SBML +- [LEMS_NML2_Ex9_FN](SBML/tests/results_compatibility_biosimulators.md) + +### BioModels +- [BioModels overview table](BioModels/README.md) +- [BIOMD0000000001](BioModels/BIOMD0000000001/tests/results_BIOMD0000000001_url.md) +- [BIOMD0000000138](BioModels/BIOMD0000000138/tests/results_BIOMD0000000138_url.md) +- [BIOMD0000000724](BioModels/BIOMD0000000724/tests/results_Theinmozhi_2018.md) +- [BIOMD0000001077](BioModels/BIOMD0000001077/tests/results_Adlung2021_model_jakstat_pa.md) + +### Test Suite +- [Test Suite overview table](test_suite/results.md) +- [00001](test_suite/test_00001/tests/results_compatibility_biosimulators.md) +- [01186](test_suite/test_01186/tests/results_compatibility_biosimulators.md) + +## Clone the Repository +To clone this repository to your local machine using the following command: + +```sh +git clone https://github.com/OpenSourceBrain/SBMLShowcase.git +cd SBMLShowcase +``` + +## Conda environment +To set up a conda environment for the code in the SBML, BioModels, and test_suite folders. +``` +conda create -n sbmlshowcase -c conda-forge python=3.10 +conda activate sbmlshowcase +pip install -e . +conda activate sbmlshowcase +``` +### for developers +``` +conda create -n sbmlshowcase-dev -c conda-forge python=3.10 +conda activate sbmlshowcase-dev +pip install -e .[dev] +conda activate sbmlshowcase-dev +``` +To install the pre-commit hooks +``` +pre-commit install +``` +## Main Folders + +The repository is organized into several folders each serving a specific purpose. Some of the key folders are: + +- [**SBML**](SBML) Contains scripts and files related to a few simple SBML models and testing their compatibility with different BioSimulator engines. +- [**BioModels**](BioModels) Includes scripts for parsing and testing the compatibility of [BioModels](https://www.ebi.ac.uk/biomodels/) with various BioSimulator engines. +- [**test_suite**](test_suite) Holds test cases and scripts for validating the functionality of the repository's tools and models. +- [**utils**](utils) containing general functions. + +## SBML +[**SBML**](SBML) contains a simple SBML model [`LEMS_NML2_Ex9_FN.sbml`](SBML/LEMS_NML2_Ex9_FN.sbml) and it's simulation file [`LEMS_NML2_Ex9_FN_missing_xmlns.sedml`](SBML/LEMS_NML2_Ex9_FN_missing_xmlns.sedml). + +[test_compatibility_biosimulators](SBML/tests/test_compatibility_biosimulators.py) adds any missing XML or FBC namespaces to the SED-ML file, wraps up the SBML and SED-ML files into an Open Modeling EXchange format (OMEX) file, submits the OMEX file to different BioSimulator engines either locally via docker (indicated with an `L` for local in the results table), or remotely through the BioSimulators API (indicated with an `R`). The results table created by this script can be found in [here](SBML/tests/results_compatibility_biosimulators.md). + +To run the script, change your directory to the SBML folder and run: + +``` +python test_compatibility_biosimulators.py +``` + +The following scripts test specific components of the process described above and are mainly run as workflows in GitHub Actions. +- [test_biosimulators_api](SBML/tests/test_biosimulators_api.py) +- [test_biosimulators_docker](SBML/tests/test_biosimulators_docker.py) +- [test_biosimulators_local](SBML/tests/test_biosimulators_local.py) +- [test_biosimulators_remote](SBML/tests/test_biosimulators_remote.py) +- [test_compatibility_biosimulators](SBML/tests/test_compatibility_biosimulators.py) +- [test_tellurium](SBML/tests/test_tellurium.py) + +## BioModels +### Overview with all curated BioModels + +[parse_biomodels](BioModels/parse_biomodels.py) creates an overview table in [`BioModels/README.md`](BioModels/README.md), testing curated [BioModels](https://www.ebi.ac.uk/biomodels/). + +To run the script, change your directory to the BioModels folder and run: + +``` +python parse_biomodels.py +``` +### Test specific BioModels +[test_biomodels_compatibility_biosimulators](BioModels/test_biomodels_compatibility_biosimulators.py) +tests engine compatibility of BioModels listed in `biomodel_id_list` ([BIOMD0000000001](https://www.ebi.ac.uk/biomodels/BIOMD0000000001), [BIOMD0000000138](https://www.ebi.ac.uk/biomodels/BIOMD0000000138), [BIOMD0000000724](https://www.ebi.ac.uk/biomodels/BIOMD0000000724), [BIOMD0000001077](https://www.ebi.ac.uk/biomodels/BIOMD0000001077)) and creates subfolders containing the results. Results can be found in `BioModels/BIOMOD_id/tests/results_BioModel_name.md`. + +For example for BioModel [BIOMD0000000001](https://www.ebi.ac.uk/biomodels/BIOMD0000000001), results can be found [here](BioModels/BIOMD0000000001/tests/results_BIOMD0000000001_url.md). + +## test_suite +### Overview with semantic test suite cases +Processes the [semantic](https://github.com/sbmlteam/sbml-test-suite/tree/release/cases/semantic) [SBML Test Suite](https://github.com/sbmlteam/sbml-test-suite?tab=readme-ov-file) test cases which should all be valid SBML models with deterministic simulation results. + +[process_test_suite](test_suite/process_test_suite.py) creates an overview table summarising whether the SBML files, SBML units, and SED-ML files are valid. In addition to that it shows whether the XML SBML namespaces (`xmlns-sbml`) are missing, and whether the models can be run (`pass` / `FAIL`) in tellurium natively, or remotely through the BioSimulators API. The table can be found [here](test_suite/results.md). + +To run the script, change your directory to the test_suite folder and run: + +``` +python process_test_suite.py +``` + +There are several command line options for testing a limited amount of cases or specific test suite cases, see the [test_suite README](test_suite/README.md) for more information. + + +### Testing specific test suite cases +[test_test_suite_compatibility_biosimulators](test_suite/test_test_suite_compatibility_biosimulators.py) tests engine compatibility of specific semantic test suite cases (00001, 01186) Results can be found in `test_suite/test_case_id/tests/results_compatibility_biosimulators.md`. + +For example for for semantic test case [00001](https://www.ebi.ac.uk/biomodels/BIOMD0000000001), results can be found [here](test_suite/test_00001/tests/results_compatibility_biosimulators.md). + +To run the script, change your directory to the test_suite folder and run: + +``` +python test_test_suite_compatibility_biosimulators.py +``` +There are several command line options in the [test_suite README](test_suite/README.md). + +# Converting NeuroML2/LEMS to & from SBML + Most of the interactions between [SBML](https://sbml.org) and LEMS/NeuroML showcased here are enabled by: - The SBML to LEMS import function in: [org.neuroml.importer](https://github.com/NeuroML/org.neuroml.import/blob/master/src/main/java/org/neuroml/importer/sbml/SBMLImporter.java) @@ -23,4 +141,3 @@ Note these features can be accessed easily with the [pyNeuroML](https://docs.neu pynml -sbml-import SBMLFile.sbml duration dt See also https://github.com/ModECI/modelspec/blob/main/examples/COMBINE.md. - diff --git a/test_suite/README.md b/test_suite/README.md index 6526fd78..835571af 100644 --- a/test_suite/README.md +++ b/test_suite/README.md @@ -9,57 +9,49 @@ It currently runs three validation tests: The output is a markdown file containing a simple table of the results obtained on each file, where each test result is recorded as either a `pass` or `FAIL`. -## Getting Started +## Run the Validation Script -### Step 1: Download the Test Suite -Download the [zipfile](https://github.com/sbmlteam/sbml-test-suite/releases/download/3.4.0/semantic_tests_with_sedml_and_graphs.v3.4.0.zip) (or the latest equivalent) of the [SBML test suite](https://github.com/sbmlteam/sbml-test-suite) that includes [SEDML](https://github.com/SED-ML/sed-ml) files. +Navigate to the test_suite directory and run for example -### Step 2: Extract the Files -Extract the downloaded ZIP file to a desired location, for example using the `unzip` command: - -```bash -unzip semantic_tests_with_sedml_and_graphs.v3.4.0.zip -d /path_to_extraction_folder ``` + python process_test_suite.py --cases 00001 00002 00011 --sbml-level_version l1v2 --output-file results_00001_00002_00011.md +``` +or to run all test cases using the highest SBML versions available navigate to the test_suite directory and run (overwrites `results.md`) -### Step 3: Set up the right environment ``` -pip install matplotlib -pip install pyneuroml -pip install pyneuroml[combine] -pip install pyneuroml[tellurium] -pip install pymetadata -pip install docker + python process_test_suite.py ``` +## Test specific cases +Navigate to the test_suite directory and run for example -### Step 3: Run the Validation Script -Navigate to the directory containing the `process_test_suite.py` script and execute it, specifying the path to the extracted test files. For example if the extraction folder is `C:\Users\Username\Documents\compbiolibs\SBML_test_suite\semantic` and the `process_test_suite.py` script is in the current directory. +``` +test_test_suite_compatibility_biosimulators.py --cases 00006 01280 --sbml-level_version highest +``` +or to run test cases 00001 and 01186 (tested in this repository) using the highest SBML versions available navigate to the test_suite directory and run ``` - python process_test_suite.py --suite-path C:\Users\Username\Documents\compbiolibs\SBML_test_suite\semantic --sbml-level_version 'sbml-l3v2' --output-file ./results_test.md --limit 5 +test_test_suite_compatibility_biosimulators.py ``` ## Command Line Options -The `process_test_suite.py` script provides various command-line options to customize the execution of the tests. Below are the available options. - - `--limit` **Description:** Limits the number of test cases processed. **Usage:** `--limit ` **Default:** `0` (no limit) - `--cases` - **Description:** list specific cases to process +- `--cases` + **Description:** List specific cases to process. **Usage:** `--cases ` **Default:** `[]` (no limit) - - `--suite-path` **Description:** Specifies the path to the directory containing the test suite files. **Usage:** `--suite-path ` **Default:** `.` (current directory) -- `--sbml-level_version' - **Description:** String that specifies level and version of files to select for processing (e.g. 'l3v2') +- `--sbml-level_version` + **Description:** String that specifies the level and version of files to select for processing (e.g., 'l3v2'). **Usage:** `--sbml-level_version ` **Default:** `highest` @@ -68,9 +60,14 @@ The `process_test_suite.py` script provides various command-line options to cust **Usage:** `--suite-url-base ` **Default:** `https://github.com/sbmlteam/sbml-test-suite/blob/release/cases/semantic` + ### process_test_suite only +- `--skip` + **Description:** Skip cases listed. + **Usage:** `--skip ` + **Default:** `[]` (no skip) + - `--output-file` **Description:** Specifies the path to the output file where the results will be written. **Usage:** `--output-file ` **Default:** `results.md` -Each option can be used to modify the behavior of the script to fit specific needs, such as limiting the number of cases to process for testing purposes or specifying a different output file for the results. diff --git a/test_suite/process_test_suite.py b/test_suite/process_test_suite.py index bbda8788..f242e0ac 100755 --- a/test_suite/process_test_suite.py +++ b/test_suite/process_test_suite.py @@ -431,7 +431,7 @@ def process_cases(args): ) sedml_file_path = ( glob.glob(sedml_file_name)[0] - if len(glob.glob(subfolder, sedml_file_name)) > 0 + if len(glob.glob(sedml_file_name)) > 0 else [] ) @@ -634,6 +634,7 @@ def run_test_suite_with_retries(max_retries=10): args.suite_path = os.path.join( os.path.dirname(os.path.realpath(__file__)), "SBML_test_suite", "semantic" ) - args.limit = 0 + if len(sys.argv) == 1: + args.limit = 0 run_test_suite_with_retries() diff --git a/test_suite/test_test_suite_compatibility_biosimulators.py b/test_suite/test_test_suite_compatibility_biosimulators.py index 6b1919cd..3e565228 100644 --- a/test_suite/test_test_suite_compatibility_biosimulators.py +++ b/test_suite/test_test_suite_compatibility_biosimulators.py @@ -186,10 +186,11 @@ def process_cases(args): if __name__ == "__main__": args = parse_arguments() - args.cases = ["00001", "01186"] - args.sbml_level_version = "l3v2" - user_folder = os.path.expanduser("~") + if len(sys.argv) == 1: + # No command line arguments provided, set default values + args.cases = ["00001", "01186"] + args.sbml_level_version = "highest" args.suite_path = os.path.join( - user_folder, "Documents", "compbiolibs", "SBML_test_suite", "semantic" + os.path.dirname(os.path.realpath(__file__)), "SBML_test_suite", "semantic" ) process_cases(args)