add petab export

Author: JR-1991

pyenzyme/__init__.py

@@ -20,6 +20,7 @@
 # Output functions
 to_pandas = EnzymeMLHandler.to_pandas
 to_sbml = EnzymeMLHandler.to_sbml
+to_petab = EnzymeMLHandler.to_petab
 write_enzymeml = EnzymeMLHandler.write_enzymeml
 
 __all__ = [

pyenzyme/petab/__init__.py

@@ -0,0 +1,3 @@
+from .io import to_petab
+
+__all__ = ["to_petab"]

pyenzyme/petab/baserow.py

@@ -0,0 +1,16 @@
+from typing import Any
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseRow(BaseModel):
+    """
+    Base class for all PEtab rows.
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    def to_row(self) -> dict[str, Any]:
+        """
+        Converts the row to a dictionary suitable for a PEtab table row.
+        """
+        return self.model_dump(by_alias=True, mode="json")

pyenzyme/petab/conditions.py

@@ -0,0 +1,68 @@
+from typing import Dict, Self, Any
+from pydantic import Field
+
+from pyenzyme.versions import v2
+from .baserow import BaseRow
+
+
+class ConditionRow(BaseRow):
+    """
+    Represents a row in a PEtab conditions table.
+
+    This class models experimental conditions with species initial concentrations
+    and other condition-specific parameters.
+
+    Attributes:
+        condition_id: Unique identifier for the condition
+        condition_name: Human-readable name for the condition
+        species: Dictionary mapping species IDs to their initial concentrations
+    """
+
+    condition_id: str = Field(alias="conditionId")
+    condition_name: str = Field(alias="conditionName")
+    species: dict[str, float] = Field(default_factory=dict)
+
+    def to_row(self) -> Dict[str, Any]:
+        """
+        Converts the condition to a dictionary suitable for a PEtab conditions table row.
+
+        Returns:
+            Dictionary with condition ID, name, and species initial concentrations
+        """
+        return {
+            **self.model_dump(exclude={"species"}, by_alias=True),
+            **self.species,
+        }
+
+    @classmethod
+    def from_measurements(cls, measurements: list[v2.Measurement]) -> list[Self]:
+        """
+        Creates a list of ConditionRow objects from a list of PyEnzyme Measurement objects.
+        """
+        return [cls.from_measurement(measurement) for measurement in measurements]
+
+    @classmethod
+    def from_measurement(cls, measurement: v2.Measurement) -> Self:
+        """
+        Creates a ConditionRow from a PyEnzyme Measurement object.
+
+        This method extracts species initial concentrations from the measurement
+        and creates a corresponding condition row.
+
+        Args:
+            measurement: PyEnzyme Measurement object containing species data
+
+        Returns:
+            A new ConditionRow instance with data from the measurement
+        """
+        inits = {
+            str(meas_data.species_id): meas_data.initial
+            for meas_data in measurement.species_data
+            if meas_data.initial is not None
+        }
+
+        return cls(
+            conditionId=measurement.id,
+            conditionName=measurement.name,
+            species=inits,
+        )

pyenzyme/petab/io.py

@@ -0,0 +1,124 @@
+from pathlib import Path
+from typing import Union
+
+import pandas as pd
+import yaml
+
+from pyenzyme.sbml.serializer import to_sbml
+from pyenzyme.versions import v2
+
+from .petab import PEtab, Problem
+from .conditions import ConditionRow
+from .observables import ObservableRow
+from .measurements import MeasurementRow
+from .parameters import ParameterRow
+
+# Default filenames for PEtab format components
+PARAMETER_FILENAME = "parameters.tsv"
+CONDITION_FILENAME = "conditions.tsv"
+OBSERVABLE_FILENAME = "observables.tsv"
+MEASUREMENT_FILENAME = "measurements.tsv"
+SBML_FILENAME = "model.xml"
+
+
+def to_petab(doc: v2.EnzymeMLDocument, path: Union[Path, str]) -> PEtab:
+    """
+    Convert an EnzymeML document to a PEtab parameter estimation problem.
+
+    This function exports an EnzymeML document to the PEtab format, which is a
+    standardized format for specifying parameter estimation problems in systems biology.
+    The function creates all necessary PEtab files:
+
+    1. SBML model file: Contains the mathematical model specification
+    2. Condition table: Specifies experimental conditions
+    3. Observable table: Defines model outputs that correspond to measurements
+    4. Measurement table: Contains experimental data points
+    5. Parameter table: Defines model parameters and their estimation settings
+    6. YAML configuration file: Links all files together in a PEtab problem definition
+
+    Parameters
+    ----------
+    doc : v2.EnzymeMLDocument
+        The EnzymeML document to convert, containing all model information,
+        measurements, and parameters.
+    path : Union[Path, str]
+        Directory path where PEtab files will be written. If the directory
+        doesn't exist, it will be created.
+
+    Returns
+    -------
+    None
+        Files are written to the specified path.
+
+    Notes
+    -----
+    The file naming convention is based on the EnzymeML document name,
+    with spaces replaced by underscores and converted to lowercase.
+    """
+
+    if isinstance(path, str):
+        path = Path(path)
+
+    if not path.exists():
+        path.mkdir(parents=True)
+
+    # Create paths for all PEtab files
+    name = doc.name.replace(" ", "_").lower()
+    meta_path = path / f"{name}.yaml"
+    condition_path = path / f"{name}_{CONDITION_FILENAME}"
+    observable_path = path / f"{name}_{OBSERVABLE_FILENAME}"
+    measurement_path = path / f"{name}_{MEASUREMENT_FILENAME}"
+    parameter_path = path / f"{name}_{PARAMETER_FILENAME}"
+    sbml_path = path / f"{name}_{SBML_FILENAME}"
+
+    # Write SBML model file
+    with open(sbml_path, "w") as f:
+        sbml, _ = to_sbml(doc)
+        f.write(sbml)
+
+    # Generate and write conditions table
+    pd.DataFrame(
+        [row.to_row() for row in ConditionRow.from_measurements(doc.measurements)],
+    ).to_csv(condition_path, index=False, sep="\t")
+
+    # Generate and write observables table
+    pd.DataFrame(
+        [row.to_row() for row in ObservableRow.from_enzymeml(doc)],
+    ).to_csv(observable_path, index=False, sep="\t")
+
+    # Generate and write measurements table
+    pd.DataFrame(
+        [row.to_row() for row in MeasurementRow.from_measurements(doc.measurements)],
+    ).to_csv(measurement_path, index=False, sep="\t")
+
+    # Generate and write parameters table
+    pd.DataFrame(
+        [row.to_row() for row in ParameterRow.from_parameters(doc.parameters)],
+    ).to_csv(parameter_path, index=False, sep="\t")
+
+    # Create PEtab configuration object
+    meta = PEtab(
+        format_version=1,
+        parameter_file=parameter_path,
+        problems=[
+            Problem(
+                sbml_files=[sbml_path],
+                measurement_files=[measurement_path],
+                condition_files=[condition_path],
+                observable_files=[observable_path],
+            )
+        ],
+    )
+
+    # Serialize configuration to YAML
+    with open(meta_path, "w") as f:
+        yaml.dump(
+            meta.model_dump(
+                mode="json",
+                by_alias=True,
+                exclude_none=True,
+            ),
+            f,
+        )
+
+    return meta

pyenzyme/petab/measurements.py

@@ -0,0 +1,104 @@
+from typing import List, Self, Union
+from pydantic import Field
+
+from pyenzyme.versions import v2
+from .baserow import BaseRow
+
+
+class MeasurementRow(BaseRow):
+    """
+    Represents a row in a PEtab measurements table.
+
+    This class models experimental measurements with species initial concentrations
+    and other measurement-specific parameters.
+
+    Attributes:
+        observable_id (str): The identifier of the observable being measured.
+            Maps to 'observableId' in the PEtab specification.
+        preequilibration_condition_id (str | None): The identifier of the preequilibration condition.
+            Maps to 'preequilibrationConditionId' in the PEtab specification.
+            Defaults to None if no preequilibration was performed.
+        condition_id (str): The identifier of the simulation condition.
+            Maps to 'simulationConditionId' in the PEtab specification.
+        measurement (float): The measured value of the observable.
+            Maps to 'measurement' in the PEtab specification.
+        time (float): The time point at which the measurement was taken.
+            Maps to 'time' in the PEtab specification.
+        observable_parameters (Union[str, float, None]): Parameters for the observable transformation.
+            Maps to 'observableParameters' in the PEtab specification.
+            Can be a parameter ID, a numeric value, or None if not applicable.
+        noise_parameters (Union[str, float, None]): Parameters for the noise model.
+            Maps to 'noiseParameters' in the PEtab specification.
+            Can be a parameter ID, a numeric value, or None if not applicable.
+        dataset_id (str | None): An identifier for the dataset this measurement belongs to.
+            Maps to 'datasetId' in the PEtab specification.
+            Useful for grouping measurements from the same experiment.
+        replicate_id (str | None): An identifier for the replicate this measurement belongs to.
+            Maps to 'replicateId' in the PEtab specification.
+            Useful for identifying repeated measurements under identical conditions.
+    """
+
+    observable_id: str = Field(alias="observableId")
+    preequilibration_condition_id: str | None = Field(
+        default=None,
+        alias="preequilibrationConditionId",
+    )
+    condition_id: str = Field(alias="simulationConditionId")
+    measurement: float = Field(alias="measurement")
+    time: float = Field(alias="time")
+    observable_parameters: Union[str, float, None] = Field(
+        default=None,
+        alias="observableParameters",
+    )
+    noise_parameters: Union[str, float, None] = Field(
+        default=None,
+        alias="noiseParameters",
+    )
+    dataset_id: str | None = Field(alias="datasetId", default=None)
+    replicate_id: str | None = Field(alias="replicateId", default=None)
+
+    @classmethod
+    def from_measurements(cls, measurements: list[v2.Measurement]) -> List[Self]:
+        """
+        Convert a list of EnzymeML Measurement objects to a list of PEtab MeasurementRow objects.
+        """
+        return [
+            row
+            for measurement in measurements
+            for row in cls.from_measurement(measurement)
+        ]
+
+    @classmethod
+    def from_measurement(cls, measurement: v2.Measurement) -> List[Self]:
+        """
+        Convert an EnzymeML Measurement object to a list of PEtab MeasurementRow objects.
+
+        This method extracts the time series data from a Measurement object and creates
+        individual MeasurementRow entries for each time point and corresponding data value.
+
+        Args:
+            measurement (v2.Measurement): An EnzymeML Measurement object containing
+                species concentration time series data.
+
+        Returns:
+            List[Self]: A list of MeasurementRow objects, each representing a single
+                data point from the original measurement. Each row contains the species ID,
+                measurement condition ID, the measured value, and the time point.
+
+        Example:
+            If a Measurement contains data for species 'S1' with time points [0, 10, 20]
+            and corresponding values [1.0, 0.8, 0.6], this method will return three
+            MeasurementRow objects, one for each time-value pair.
+        """
+        meas_rows = []
+        for meas_data in measurement.species_data:
+            for t, x in zip(meas_data.time, meas_data.data):
+                meas_rows.append(
+                    cls(
+                        observableId=meas_data.species_id,
+                        simulationConditionId=measurement.id,
+                        measurement=x,
+                        time=t,
+                    )
+                )
+        return meas_rows