sbml2cellml 0.1.0__py3-none-any.whl

sbml2cellml/__init__.py

@@ -0,0 +1,16 @@
+"""sbml2cellml - conversion between SBML and CellML."""
+
+import logging
+
+from sbml2cellml.cellml2sbml import convert_cellml2sbml
+from sbml2cellml.sbml2cellml import convert_sbml2cellml
+
+# the package does not configure logging, see `sbml2cellml.log`
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__author__ = "Matthias Koenig"
+__version__ = "0.1.0"
+
+program_name: str = "sbml2cellml"
+
+__all__ = ["convert_cellml2sbml", "convert_sbml2cellml"]

sbml2cellml/biomodels/__init__.py

@@ -0,0 +1 @@
+"""BioModels release check: the curated models through both converters."""

sbml2cellml/biomodels/cases.py

@@ -0,0 +1,122 @@
+"""Case construction for a BioModels model.
+
+Every curated model runs the same generic timecourse: there are no expected
+results (`Case.expected` is `None`, the roadrunner simulation of the
+original SBML becomes the reference the later stages are compared with, see
+`sbml2cellml.testsuite.runner`).
+"""
+
+from pathlib import Path
+
+import libsbml
+
+from sbml2cellml.biomodels.models import BioModelsError, ModelInfo
+from sbml2cellml.testsuite.cases import Case, Settings
+
+#: duration (time units of the model) of the generic timecourse
+DURATION = 100.0
+#: number of steps of the generic timecourse
+STEPS = 100
+#: absolute tolerance of the comparison
+ABSOLUTE = 1e-6
+#: relative tolerance of the comparison
+RELATIVE = 1e-3
+
+
+def constructs(model: libsbml.Model, text: str) -> tuple[str, ...]:
+    """SBML constructs a model uses, as component tags of a `Case`.
+
+    Args:
+        model: the model to inspect.
+        text: the file content the model was read from, used to detect a
+            `csymbol` delay (not exposed on the `libsbml.Model` API).
+
+    Returns:
+        The construct tags present in the model, e.g. `("Reactions",
+        "AssignmentRules")`.
+    """
+    tags: list[str] = []
+    if model.getNumReactions():
+        tags.append("Reactions")
+    if model.getNumEvents():
+        tags.append("Events")
+    if model.getNumFunctionDefinitions():
+        tags.append("FunctionDefinitions")
+    if model.getNumInitialAssignments():
+        tags.append("InitialAssignments")
+    if model.getNumConstraints():
+        tags.append("Constraints")
+    rules = [model.getRule(k) for k in range(model.getNumRules())]
+    if any(rule.isAlgebraic() for rule in rules):
+        tags.append("AlgebraicRules")
+    if any(rule.isAssignment() for rule in rules):
+        tags.append("AssignmentRules")
+    if any(rule.isRate() for rule in rules):
+        tags.append("RateRules")
+    if "symbols/delay" in text:
+        tags.append("Delay")
+    return tuple(tags)
+
+
+def biomodel_case(info: ModelInfo, sbml_path: Path, packages: tuple[str, ...]) -> Case:
+    """Build the generic timecourse case of a BioModels model.
+
+    Args:
+        info: metadata of the model.
+        sbml_path: path of the downloaded SBML file.
+        packages: SBML packages the model uses (`models.packages`); each
+            becomes a `<package>:package` component tag so `skip_reason`
+            skips the case the same way it skips a test suite case using an
+            unsupported package.
+
+    Returns:
+        The case, with `expected=None` and `test_type="TimeCourse"`.
+        `settings.variables` is the species ids, followed by the ids of the
+        rate-rule and assignment-rule targets which are not species
+        (parameters and compartments), in document order and without
+        duplicates; `amount` and `concentration` stay species only.
+
+    Raises:
+        BioModelsError: if the SBML file has no model.
+    """
+    doc = libsbml.readSBMLFromFile(str(sbml_path))
+    model = doc.getModel()
+    if model is None:
+        raise BioModelsError(f"{info.id}: no model in {sbml_path.name}")
+    species = list(model.getListOfSpecies())
+    species_ids = tuple(s.getId() for s in species)
+    variables = list(species_ids)
+    seen = set(species_ids)
+    for rule in model.getListOfRules():
+        if not (rule.isRate() or rule.isAssignment()):
+            continue
+        target = rule.getVariable()
+        if target and target not in seen:
+            variables.append(target)
+            seen.add(target)
+    settings = Settings(
+        start=0.0,
+        duration=DURATION,
+        steps=STEPS,
+        variables=tuple(variables),
+        absolute=ABSOLUTE,
+        relative=RELATIVE,
+        amount=frozenset(s.getId() for s in species if s.getHasOnlySubstanceUnits()),
+        concentration=frozenset(
+            s.getId() for s in species if not s.getHasOnlySubstanceUnits()
+        ),
+    )
+    tags = constructs(model, sbml_path.read_text(encoding="utf-8")) + tuple(
+        f"{package}:package" for package in packages
+    )
+    return Case(
+        id=info.id,
+        case_dir=sbml_path.parent,
+        sbml_path=sbml_path,
+        settings=settings,
+        expected=None,
+        test_tags=(),
+        component_tags=tags,
+        test_type="TimeCourse",
+        name=info.name,
+    )

sbml2cellml/biomodels/cli.py

@@ -0,0 +1,228 @@
+"""The `sbml2cellml-biomodels` command.
+
+    sbml2cellml-biomodels run [--models biomodels/models.json] [--ids ID,ID]
+                              [--count N] [--work-dir biomodels/work]
+                              [--results FILE] [--report FILE] [--timeout SECONDS] [-v]
+    sbml2cellml-biomodels update [--models biomodels/models.json] [--count N]
+    sbml2cellml-biomodels report --results FILE --output FILE
+
+`run` runs the pipeline over `--ids` or, by default, the selection file,
+writes the results and the report; it gives up without writing either when
+too many ids failed to download (`DOWNLOAD_FAILURE_FRACTION`, e.g. a
+BioModels outage) or when no case was left to run, and, when `--results`
+already exists, prints its regressions and improvements against the new run.
+`update` refreshes the selection file from the current BioModels search.
+`report` renders a results file.
+"""
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from sbml2cellml import __version__, log
+from sbml2cellml.biomodels.models import (
+    load_selection,
+    query_curated_ids,
+    write_selection,
+)
+from sbml2cellml.biomodels.runner import run_biomodels
+from sbml2cellml.testsuite.report import write_report
+from sbml2cellml.testsuite.results import STAGES, SuiteResult, improvements, regressions
+
+DEFAULT_MODELS = Path("biomodels") / "models.json"
+DEFAULT_RESULTS = Path("biomodels") / "results.json"
+DEFAULT_REPORT = Path("docs") / "biomodels.md"
+#: fraction of the requested ids whose download may fail before `run` gives
+#: up instead of writing a mostly empty result (e.g. a BioModels outage)
+DOWNLOAD_FAILURE_FRACTION = 0.05
+#: intro paragraph of the BioModels report
+BIOMODELS_INTRO = (
+    "Manually curated SBML models of [BioModels](https://www.biomodels.org) "
+    "(the ids in `biomodels/models.json`). Every model is simulated with "
+    "roadrunner over 0 to 100 time units in 100 steps (`reference`), converted "
+    "to CellML (`sbml2cellml`), simulated with libopencor (`libopencor`), "
+    "converted back to SBML (`cellml2sbml`) and simulated with roadrunner again "
+    "(`roundtrip`); the two later simulations are compared with the reference "
+    "for every species and every other variable set by a rate rule or an "
+    "assignment rule, with a relative tolerance of 1e-3 and an absolute "
+    "tolerance of 1e-6. A `reference` failure means roadrunner cannot simulate "
+    "the model, it says nothing about the converters. See "
+    "[Development](development.md#biomodels-check) for how to run it."
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser.
+
+    Returns:
+        The parser with the `run`, `update` and `report` subcommands.
+    """
+    parser = argparse.ArgumentParser(
+        prog="sbml2cellml-biomodels",
+        description=(
+            "Run the curated BioModels selection through sbml2cellml and cellml2sbml."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run = subparsers.add_parser(
+        "run", help="run the selection, write results and report"
+    )
+    run.add_argument(
+        "--models", default=str(DEFAULT_MODELS), help="selection file (json)"
+    )
+    run.add_argument("--ids", help="comma separated model ids, overrides --models")
+    run.add_argument("--count", type=int, help="run only the first N ids")
+    run.add_argument(
+        "--work-dir", default="biomodels/work", help="directory for the converted files"
+    )
+    run.add_argument(
+        "--results", default=str(DEFAULT_RESULTS), help="results file (json)"
+    )
+    run.add_argument(
+        "--report", default=str(DEFAULT_REPORT), help="report file (markdown)"
+    )
+    run.add_argument(
+        "--timeout", type=float, default=60.0, help="seconds per simulation"
+    )
+    run.add_argument("-v", "--verbose", action="store_true", help="log the steps")
+
+    update = subparsers.add_parser(
+        "update", help="refresh the selection file from the current BioModels search"
+    )
+    update.add_argument(
+        "--models", default=str(DEFAULT_MODELS), help="selection file (json)"
+    )
+    update.add_argument("--count", type=int, help="keep only the first N ids")
+
+    report = subparsers.add_parser("report", help="render a results file")
+    report.add_argument(
+        "--results", default=str(DEFAULT_RESULTS), help="results file (json)"
+    )
+    report.add_argument(
+        "--output", default=str(DEFAULT_REPORT), help="report file (markdown)"
+    )
+    return parser
+
+
+def _run(args: argparse.Namespace) -> int:
+    """The `run` subcommand."""
+    if args.verbose:
+        log.enable_rich_logging(logging.INFO)
+    if args.ids:
+        ids = [mid.strip() for mid in args.ids.split(",")]
+    else:
+        models_path = Path(args.models)
+        if not models_path.is_file():
+            print(f"Selection file does not exist: '{models_path}'", file=sys.stderr)
+            return 1
+        ids = list(load_selection(models_path).models)
+    if args.count is not None:
+        ids = ids[: args.count]
+
+    result = run_biomodels(
+        ids, work_dir=Path(args.work_dir), timeout=args.timeout, progress=print
+    )
+
+    download_failures = sum(
+        1 for reason in result.skipped.values() if reason.startswith("download failed")
+    )
+    if ids and download_failures > DOWNLOAD_FAILURE_FRACTION * len(ids):
+        print(
+            f"{download_failures} of {len(ids)} ids failed to download, more than "
+            f"{DOWNLOAD_FAILURE_FRACTION:.0%} of the ids",
+            file=sys.stderr,
+        )
+        return 1
+    if not result.cases:
+        print("No cases to run", file=sys.stderr)
+        return 1
+
+    for stage in STAGES:
+        counts = result.counts(stage)
+        print(
+            f"{stage}: {counts['pass']} pass, {counts['fail']} fail, {counts['skip']} skip"
+        )
+    print(f"{len(result.skipped)} models skipped")
+
+    results_path = Path(args.results)
+    if results_path.is_file():
+        previous = SuiteResult.from_json(results_path)
+        regs = regressions(previous, result)
+        print(f"{len(regs)} regressions")
+        for line in regs:
+            print(line)
+        imps = improvements(previous, result)
+        print(f"{len(imps)} improvements")
+        for line in imps:
+            print(line)
+
+    results_path.parent.mkdir(parents=True, exist_ok=True)
+    result.to_json(results_path)
+    report_path = Path(args.report)
+    report_path.parent.mkdir(parents=True, exist_ok=True)
+    write_report(
+        result,
+        report_path,
+        title="BioModels",
+        intro=BIOMODELS_INTRO,
+        command="sbml2cellml-biomodels",
+        names=True,
+    )
+    print(f"{results_path}\n{report_path}")
+    return 0
+
+
+def _update(args: argparse.Namespace) -> int:
+    """The `update` subcommand."""
+    ids = query_curated_ids()
+    if args.count is not None:
+        ids = ids[: args.count]
+    models_path = Path(args.models)
+    models_path.parent.mkdir(parents=True, exist_ok=True)
+    selection = write_selection(models_path, ids)
+    print(f"{len(selection.models)} ids written to {models_path}")
+    return 0
+
+
+def _report(args: argparse.Namespace) -> int:
+    """The `report` subcommand."""
+    results_path = Path(args.results)
+    if not results_path.is_file():
+        print(f"Results file does not exist: '{results_path}'", file=sys.stderr)
+        return 1
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    write_report(
+        SuiteResult.from_json(results_path),
+        output,
+        title="BioModels",
+        intro=BIOMODELS_INTRO,
+        command="sbml2cellml-biomodels",
+        names=True,
+    )
+    print(output)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command.
+
+    Args:
+        argv: arguments without the program name, `sys.argv[1:]` by default.
+
+    Returns:
+        0 on success, 1 on a missing selection or results file.
+    """
+    args = build_parser().parse_args(argv)
+    if args.command == "run":
+        return _run(args)
+    if args.command == "update":
+        return _update(args)
+    return _report(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sbml2cellml/biomodels/models.py

@@ -0,0 +1,281 @@
+"""Access to the BioModels database: search, model info, download, selection.
+
+The curated model set is queried and downloaded through the BioModels REST
+API (`https://www.biomodels.org`, `www.ebi.ac.uk/biomodels` rejects the
+quoted search query used here). Model info and the downloaded SBML are
+cached on disk under `biomodels_cache()` so a rerun of the check never
+re-fetches a model it already has.
+"""
+
+import dataclasses
+import json
+import logging
+import os
+import re
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+import requests
+
+from sbml2cellml.testsuite.cases import cache_dir
+
+logger = logging.getLogger(__name__)
+
+#: root of the BioModels REST API
+BIOMODELS_URL = "https://www.biomodels.org"
+#: search query selecting the manually curated SBML models
+SEARCH_QUERY = 'curationstatus:"Manually curated" AND modelformat:"SBML"'
+#: number of models requested per search page
+PAGE_SIZE = 100
+#: timeout (seconds) of every BioModels request
+TIMEOUT = 60.0
+#: namespace declarations of an SBML package, e.g. `xmlns:comp="http://www.
+#: sbml.org/sbml/level3/version1/comp/version1"`; group 1 is the declared
+#: prefix, group 2 is the package name
+_XMLNS = re.compile(
+    r'xmlns:(\w+)="http://www\.sbml\.org/sbml/level3/version\d+/(\w+)/version\d+"'
+)
+#: `comp` elements which actually change the model (a `comp:port` alone does
+#: not touch the math, so it is not enough to count the package as used)
+_COMP_ELEMENTS = ("submodel", "modelDefinition", "externalModelDefinition")
+
+
+class BioModelsError(RuntimeError):
+    """A BioModels request failed or returned an unexpected response."""
+
+
+@dataclass(frozen=True)
+class ModelInfo:
+    """Metadata of one BioModels model, from `/{id}?format=json`."""
+
+    id: str
+    name: str
+    publication_id: str
+    format_version: str
+    main_file: str
+
+
+@dataclass(frozen=True)
+class Selection:
+    """A snapshot of the curated model ids, e.g. `biomodels/models.json`."""
+
+    date: str
+    query: str
+    models: tuple[str, ...]
+
+
+def biomodels_cache(cache: Path | None = None) -> Path:
+    """Cache directory of the BioModels info and downloads.
+
+    Args:
+        cache: cache root, `sbml2cellml.testsuite.cases.cache_dir()` by
+            default.
+
+    Returns:
+        `<cache>/biomodels`.
+    """
+    return (cache or cache_dir()) / "biomodels"
+
+
+def _get_json(url: str, params: dict[str, str | int] | None = None) -> dict:
+    """`GET` a BioModels endpoint and parse its JSON body.
+
+    Args:
+        url: endpoint to request.
+        params: query parameters.
+
+    Returns:
+        The parsed JSON body.
+
+    Raises:
+        BioModelsError: if the request fails or the status is not ok.
+    """
+    try:
+        response = requests.get(url, params=params, timeout=TIMEOUT)
+        response.raise_for_status()
+        return response.json()
+    except requests.RequestException as err:
+        raise BioModelsError(f"Request to {url} failed: {err}") from err
+
+
+def query_curated_ids() -> list[str]:
+    """Ids of every manually curated SBML model, paged through the search.
+
+    Returns:
+        The model ids, sorted and without duplicates.
+
+    Raises:
+        BioModelsError: if a search page cannot be fetched.
+    """
+    offset = 0
+    ids: list[str] = []
+    matches: int | None = None
+    while matches is None or offset < matches:
+        data = _get_json(
+            f"{BIOMODELS_URL}/search",
+            {
+                "query": SEARCH_QUERY,
+                "numResults": PAGE_SIZE,
+                "offset": offset,
+                "format": "json",
+            },
+        )
+        matches = int(data["matches"])
+        ids.extend(model["id"] for model in data["models"])
+        offset += PAGE_SIZE
+    logger.info("%d curated models found on BioModels", len(set(ids)))
+    return sorted(set(ids))
+
+
+def model_info(model_id: str, cache: Path | None = None) -> ModelInfo:
+    """Metadata of a model, cached as `<cache>/biomodels/<id>/info.json`.
+
+    Args:
+        model_id: BioModels id, e.g. `BIOMD0000000001`.
+        cache: cache root, `sbml2cellml.testsuite.cases.cache_dir()` by
+            default.
+
+    Returns:
+        The model metadata.
+
+    Raises:
+        BioModelsError: if the request fails or the response has no main
+            SBML file.
+    """
+    root = biomodels_cache(cache) / model_id
+    info_path = root / "info.json"
+    if info_path.is_file():
+        data = json.loads(info_path.read_text(encoding="utf-8"))
+        return ModelInfo(**data)
+    data = _get_json(f"{BIOMODELS_URL}/{model_id}", {"format": "json"})
+    main_files = data.get("files", {}).get("main") or []
+    if not main_files:
+        raise BioModelsError(f"{model_id}: no main SBML file in the BioModels response")
+    info = ModelInfo(
+        id=model_id,
+        name=data["name"],
+        publication_id=data.get("publicationId", ""),
+        format_version=data.get("format", {}).get("version", ""),
+        main_file=main_files[0]["name"],
+    )
+    root.mkdir(parents=True, exist_ok=True)
+    tmp_path = info_path.with_name(info_path.name + ".part")
+    tmp_path.write_text(
+        json.dumps(dataclasses.asdict(info), indent=1), encoding="utf-8"
+    )
+    os.replace(tmp_path, info_path)
+    logger.info("Fetched BioModels info for %s: %s", model_id, info.name)
+    return info
+
+
+def download_model(model_id: str, cache: Path | None = None) -> Path:
+    """Download the main SBML file of a model, cached on disk.
+
+    Args:
+        model_id: BioModels id, e.g. `BIOMD0000000001`.
+        cache: cache root, `sbml2cellml.testsuite.cases.cache_dir()` by
+            default.
+
+    Returns:
+        Path of the cached SBML file.
+
+    Raises:
+        BioModelsError: if the info or download request fails.
+    """
+    info = model_info(model_id, cache)
+    root = biomodels_cache(cache) / model_id
+    path = root / Path(info.main_file).name
+    if path.is_file():
+        return path
+    root.mkdir(parents=True, exist_ok=True)
+    url = f"{BIOMODELS_URL}/model/download/{model_id}"
+    tmp_path = path.with_name(path.name + ".part")
+    logger.info("Downloading %s from %s", model_id, url)
+    try:
+        with requests.get(
+            url, params={"filename": info.main_file}, stream=True, timeout=TIMEOUT
+        ) as response:
+            response.raise_for_status()
+            with tmp_path.open("wb") as f_sbml:
+                for chunk in response.iter_content(1 << 16):
+                    f_sbml.write(chunk)
+    except requests.RequestException as err:
+        tmp_path.unlink(missing_ok=True)
+        raise BioModelsError(f"{model_id}: download failed: {err}") from err
+    os.replace(tmp_path, path)
+    return path
+
+
+def load_selection(path: Path) -> Selection:
+    """Read a selection file (e.g. `biomodels/models.json`).
+
+    Args:
+        path: the selection file.
+
+    Returns:
+        The selection.
+    """
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return Selection(
+        date=data["date"], query=data["query"], models=tuple(data["models"])
+    )
+
+
+def write_selection(path: Path, ids: list[str]) -> Selection:
+    """Write a selection file with today's date and the given ids.
+
+    Args:
+        path: file to write.
+        ids: model ids, written sorted and without duplicates.
+
+    Returns:
+        The selection written.
+    """
+    selection = Selection(
+        date=date.today().isoformat(),
+        query=SEARCH_QUERY,
+        models=tuple(sorted(set(ids))),
+    )
+    path.write_text(
+        json.dumps(
+            {
+                "date": selection.date,
+                "query": selection.query,
+                "models": list(selection.models),
+            },
+            indent=1,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    return selection
+
+
+def packages(sbml_path: Path) -> tuple[str, ...]:
+    """SBML packages an SBML file uses, not merely declares.
+
+    A package declared through the root element's `xmlns` counts only when
+    an element with its prefix actually occurs in the file, e.g. `<comp:...`
+    for a `comp` declaration. `comp` is the exception: its `port` elements
+    do not change the math, so it counts only when a `<comp:submodel`,
+    `<comp:modelDefinition` or `<comp:externalModelDefinition` element
+    occurs.
+
+    Args:
+        sbml_path: SBML file to inspect.
+
+    Returns:
+        The package names, sorted and without duplicates.
+    """
+    text = sbml_path.read_text(encoding="utf-8", errors="replace")
+    used: set[str] = set()
+    for prefix, package in {
+        (match.group(1), match.group(2)) for match in _XMLNS.finditer(text)
+    }:
+        if package == "comp":
+            if any(f"<{prefix}:{element}" in text for element in _COMP_ELEMENTS):
+                used.add(package)
+        elif f"<{prefix}:" in text:
+            used.add(package)
+    return tuple(sorted(used))