Why Package a QSP Workflow?
A mechanistic model file alone may not tell another researcher which simulation to run, what inputs it requires, or how its outputs should be interpreted. A simulation protocol alone may refer to a model that is missing or stored at a location meaningful only on the original author’s computer. A COMBINE archive brings related model and workflow files together in a standard, inspectable package. For a QSP project, that package can include an SBML model, an SED-ML simulation description, data descriptions, and metadata.
The earlier material on machine-readable model exchange with SBML and recording simulation protocols with SED-ML establishes what those files represent. Here the focus is the package that gathers them and describes their roles. Packaging supports exchange and interpretation; it does not by itself demonstrate that a model is biologically adequate, that a protocol is scientifically appropriate, or that different software will produce identical numerical results.
Archive Structure and the Manifest
An archive is more than a folder compressed into a ZIP file. Its root-level manifest.xml describes the packaged resources. A manifest entry associates a location within the archive with a format identifier, and can designate an entry as a master file. The archive’s root is conventionally represented by the location “.”. Manifest locations are paths within the archive, not paths on the creator’s computer.
Format identifiers communicate what kind of content a file contains. For example, an SBML model and an SED-ML document should be identified as their respective formats, rather than both being labelled as generic text. Use identifiers recognized by the relevant COMBINE specifications and consuming tools. A master designation signals a principal starting point for an application; it does not mean that the other files are unimportant or that the designated file contains the entire workflow.
| Package item | Typical role | Check when assembling |
|---|---|---|
| manifest.xml | Lists archive resources, their formats, and any master entry | Locations and format identifiers match the actual package |
| SBML model | Machine-readable representation of model structure and parameters | The file is present and the protocol refers to its packaged location |
| SED-ML document | Describes simulation tasks and outputs | Referenced model and data locations resolve within the archive |
| Data or data description | Provides workflow inputs or describes their structure and provenance | Content, units, columns, and use are sufficiently explained |
| Metadata | Describes the archive or its components, such as identity and provenance | Descriptions are accurate and point to the intended resources |
A metadata file such as metadata.rdf may describe the archive or individual components. Metadata is not a substitute for the manifest: a description of a model does not make a missing model available, and a manifest entry does not explain the scientific meaning of every parameter. Keep those roles distinct. Similarly, include data only when it is appropriate to share. If data cannot be distributed, a precise data description can state what is required, how it is structured, and where access is controlled, but it cannot make unavailable input data reproducible.
Worked Example: Choosing Files for a QSP Package
Suppose a hypothetical team shares a cytokine-pathway simulation. Its workflow uses the model file cytokine_model.xml, the protocol run_scenarios.xml, a small, non-sensitive input table baseline_inputs.csv, and a data description input_dictionary.csv. The team also prepares archive metadata.
First, identify the dependency chain: the SED-ML protocol needs the model, and the simulation uses the input table. The data description explains the table’s columns and units. Therefore, the package should contain all four files, as well as the manifest and metadata. The file names and roles can be summarized as follows:
| Location inside archive | Format or role | Reason for inclusion |
|---|---|---|
| cytokine_model.xml | SBML model | Model resource used by the protocol |
| run_scenarios.xml | SED-ML protocol; designated master | Principal description of the simulation workflow |
| baseline_inputs.csv | CSV input data | Input required by the workflow |
| input_dictionary.csv | CSV data description | Defines input columns and units |
The package contains four substantive resources. If the protocol also refers to a fifth resource, such as an external file called dose_schedule.csv, the package is not complete unless that dependency is included or the protocol is deliberately revised to use a documented, accessible external resource. Merely placing the four known files in a ZIP does not resolve that missing reference.
From Files to a Portable Workflow
Portability depends on relationships between files, not just on their presence. If a protocol points to a model using a machine-specific path, such as a directory on one researcher’s workstation, another user will not have that path. Prefer references that resolve to the intended resources within the archive. Keep filenames stable and unambiguous, and avoid relying on the current working directory or on undocumented software search paths.
A useful way to reason about package completeness is to follow the dependency chain. Begin with the intended workflow, identify each resource it references, and then check whether that resource is included and correctly described. Repeat for dependencies of those resources where relevant. The package is closed with respect to its declared workflow when every required dependency resolves either to a file inside the archive or to an explicitly documented external resource that is available to the intended users.
An archive can be portable while still requiring compatible software. A consumer must be able to read the formats and interpret the instructions. In addition, numerical outcomes can vary with software implementation, solver choices, or computational environment. The archive’s manifest and file references help a user locate and interpret the intended resources; they do not alone lock an environment or certify simulation equivalence.
Worked Example: Finding a Broken File Reference
A hypothetical archive contains model.xml, protocol.xml, and inputs/arm_A.csv. Its protocol refers to arm_A.csv at the archive root. The file is present, but its actual location is in the inputs directory.
Check the reference against the archive contents. The protocol’s requested location is arm_A.csv; the packaged location is inputs/arm_A.csv. These strings do not identify the same path, so the reference does not resolve as written. The fact that the file exists somewhere in the ZIP does not repair the mismatch.
A complete correction is to update the protocol reference to the packaged relative location, inputs/arm_A.csv, and then test that the protocol resolves it after extraction or in a COMBINE-aware tool. Alternatively, move the file to the location already referenced and update the manifest accordingly. Either choice is valid if the protocol, manifest, and archive contents agree. Recheck every reference after the change, since moving a file can also invalidate other references.
Verification Before Sharing
A practical inspection proceeds from the outside in: first check the archive structure, then the manifest, then file references, and finally whether a consumer can make sense of the package. These checks address different failure modes. A syntactically valid manifest can describe a file that is missing; a complete list of files can still contain an unusable protocol reference; and a technically readable package can still leave essential scientific context unexplained.
Confirm it opens as a ZIP-based COMBINE archive and contains the root-level manifest. Check for accidental duplicates, temporary files, and unexpected personal or sensitive data.
For each declared location, confirm that the corresponding resource exists and that its format identifier describes the file. Check the archive-root entry and any master designation for consistency with the intended package.
Follow references from the simulation description to the model, inputs, and other required resources. Verify that paths resolve inside the archive or that any external dependency is explicitly explained and accessible.
Confirm that metadata and data descriptions provide enough context to identify the model, protocol, inputs, units, and intended relationships among files. Do not treat metadata as validation of the scientific content.
Open or run the package with an appropriate COMBINE-aware tool when available. A successful open is useful evidence of structural compatibility, but it does not establish scientific validity or guarantee identical results in other environments.
Where possible, test the archive from a clean location rather than from the author’s working directory. This helps reveal hidden reliance on local files that were not packaged. Keep a record of what was checked and which software was used; that record makes the scope of the check clear. A successful structural check means the package can be read under the tested conditions, not that every biological assumption or prediction has been qualified.
Worked Example: Applying a Pre-Share Checklist
A hypothetical package contains a manifest and five listed resources: one SBML model, one SED-ML protocol, two CSV files, and one metadata file. On inspection, all five resources are present. The protocol refers to the model correctly but refers to dose.csv; the packaged dose input is named dose_schedule.csv. The input dictionary describes both CSV files and specifies their units.
Count the manifest-listed resources: \(1+1+2+1=5\). All five are present, so the presence check passes. The model reference resolves, but the dose reference does not, because dose.csv and dose_schedule.csv are different locations. Thus, the package fails the reference check even though the file count and data descriptions are satisfactory.
The team can correct the protocol to refer to dose_schedule.csv or rename the packaged file to match the existing reference. Afterward, it should repeat the reference check and open the archive from a clean location. If the revised protocol resolves both inputs, and the manifest and data descriptions remain consistent, the structural and interpretive checks pass. This outcome supports sharing the package; it does not by itself validate the model’s predictions.
Alternatives, Limits, and Common Pitfalls
A shared project folder or version-control repository is useful for ongoing development and may preserve the broader history of changes. A COMBINE archive instead provides a compact, described package of selected resources for exchange or use by compatible tools. A standalone model file is simpler to distribute but may omit the protocol, data description, and metadata needed to interpret a simulation. These approaches can complement each other: a repository can retain development history, while a released archive contains a chosen, coherent set of files.
A COMBINE archive has important limits. It does not automatically include every dependency, ensure that a format is supported by the recipient’s software, resolve access restrictions on external data, or preserve the exact computational environment. Nor does a successful simulation establish that its assumptions are appropriate for a particular application. Treat the archive as a structured exchange package, not as a certificate of reproducibility or qualification.
Common pitfall: “All the files are somewhere in the ZIP, so the workflow is portable.” This reasoning ignores the manifest and the paths used by the protocol. A file placed in a subdirectory may not satisfy a reference to the archive root, and an unlisted or mislabeled file may be difficult for tools or users to interpret. The correction is to check the manifest, trace each required reference to its actual location, and test the package outside the original working environment.
Check Your Understanding
Answer each question, then compare your reasoning with the brief solutions.
- A protocol refers to inputs.csv, but the archive contains only data/inputs.csv. Is the package complete for that reference? Explain.
- What does a master designation communicate, and what does it not establish?
- A manifest lists four resources, and all four files are present. Does that alone show that the workflow can run? Give one reason.
- Why might a data description be valuable even when the input table is included?
- A COMBINE-aware tool opens an archive successfully. What conclusion is justified, and what conclusion is not?
Solutions. (1) No. The reference and packaged path differ; update the reference or relocate the file, then recheck. (2) It identifies a principal entry point for an application; it does not show that other resources are unnecessary or that the workflow is scientifically correct. (3) No. A protocol reference may still be broken, or the required software may not support the files. (4) It can explain columns, units, and intended use, making the input interpretable rather than merely present. (5) The archive was readable under the tested conditions; this does not prove scientific validity, complete environmental reproducibility, or identical results in other software.