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
OpenSourceBrain · Jan 29, 2025 · 4b561d9 · 4b561d9
1 parent 2dc0312
commit 4b561d9
Show file tree

Hide file tree

Showing 7 changed files with 153 additions and 37 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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 <number>`  
   **Default:** `0` (no limit)
 
- `--cases`  
-  **Description:** list specific cases to process
+- `--cases`  
+  **Description:** List specific cases to process.  
   **Usage:** `--cases <list>`  
   **Default:** `[]` (no limit)
 
-
 - `--suite-path`  
   **Description:** Specifies the path to the directory containing the test suite files.  
   **Usage:** `--suite-path <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 <string>`  
   **Default:** `highest`
 
@@ -68,9 +60,14 @@ The `process_test_suite.py` script provides various command-line options to cust
   **Usage:** `--suite-url-base <url>`  
   **Default:** `https://github.com/sbmlteam/sbml-test-suite/blob/release/cases/semantic`
 
+ ### process_test_suite only
+- `--skip`  
+  **Description:** Skip cases listed.  
+  **Usage:** `--skip <list>`  
+  **Default:** `[]` (no skip)
+
 - `--output-file`  
   **Description:** Specifies the path to the output file where the results will be written.  
   **Usage:** `--output-file <file path>`  
   **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
@@ -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
@@ -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)