From a Simulation Plan to a Reproducible Protocol
A QSP model can be shared in a machine-readable form while leaving an important question unanswered: what exactly should another person simulate? They need to know which model to use, which parameter values to apply, what simulation to run, and which results to return. SED-ML—the Simulation Experiment Description Markup Language—records these instructions in a structured form. It describes a simulation experiment; it does not replace the model itself.
This distinction matters in practice. Two analysts can start from the same SBML model and obtain different results if one changes a parameter, uses a different time span, or plots a different state. A useful SED-ML protocol makes those choices explicit enough to reproduce the intended calculation, while still relying on a compatible software tool to execute it.
A model element identifies a source, commonly an SBML file, and declares its modelling language. Its source should resolve to the intended model version, and any edits should be explicit. A simulation element specifies the numerical experiment. For a time course, a uniform time-course simulation records the initial time, the time from which output is requested, the end time, and the requested number of points. It also identifies a numerical algorithm, usually through a KISAO identifier, and may specify algorithm parameters where supported.
A task connects one model to one simulation. That link is what turns a model description and a set of numerical settings into an instruction to run. Data generators then refer to task results and define quantities such as time and a model state. Outputs refer to those data generators: a two-dimensional plot can use one for the x-axis and another for the y-axis, while a report can list data sets in a table.
State the Conditions Before Running the Protocol
An SED-ML file can only reproduce an experiment to the extent that its references and assumptions are clear. Before encoding it, establish the model source, the intended parameter values and units, the simulation start and end, and the requested outputs. Confirm that the selected model contains the species or parameters the protocol refers to, and that its initial conditions and units match the question being asked.
The protocol also depends on execution assumptions. The chosen algorithm must be available to the software, and its implementation must interpret the settings as intended. If a model uses events, discontinuities, or other features that affect the solution, the simulation settings and engine must handle them appropriately. A protocol can record settings; it cannot make an unsupported solver or model feature work.
SED-ML uses identifiers and, for model elements, XPath targets to refer to model content. A target must point to the intended SBML element or attribute. For example, a parameter change must target the parameter’s value attribute, not a similarly named species or a different parameter. Check the target against the exact source model rather than assuming that names alone are sufficient.
Worked Example: Recording a One-Compartment Time Course
Suppose a hypothetical SBML model describes a one-compartment concentration after a single dose. The model has a fixed initial concentration \(C_0=10\) mg/L and first-order elimination with \(k=0.20\) h\(^{-1}\). The planned simulation begins at \(t=0\) h and requests a time course through \(t=8\) h. The concentration is
The SED-ML model element points to the intended SBML source and declares SBML as its language. A uniform time-course simulation records the time interval and requested output grid, along with the chosen numerical algorithm and any specified algorithm parameters. A task links that simulation to the model. A data generator refers to the task’s time and concentration, and a plot uses time on the x-axis and concentration on the y-axis.
For a hand check at \(t=4\) h,
At the end of the requested interval,
These values are checks on the expected model behaviour, not extra outputs guaranteed by SED-ML. The protocol must request a grid that includes the times of interest, or an output that supports extracting them. The calculation assumes the stated model equation, initial concentration, and elimination rate apply throughout the interval; it does not include additional dosing or events.
Changing a Parameter and Running a Dose Sweep
A fixed parameter change and a repeated parameter sweep are different instructions. A model-level change declares a new value for a model attribute before a task runs. A repeated task instead runs a referenced task repeatedly, changing a specified value according to a range on each iteration. This is useful for a dose-response simulation because the model and simulation can stay fixed while the dose changes.
A repeated task contains one or more subtasks and a range. For a dose sweep, the range can be a vector of dose values or a uniform range, and a set-value instruction links each range value to the dose parameter’s target in the model. The repeated task should reset the model between iterations when each dose is intended to start from the same initial state. Otherwise, residual state from a preceding run could contaminate the next dose condition.
To produce a dose-response plot, define data generators for the dose and the response, each referring to the repeated task’s results. The dose is the x quantity and the response is the y quantity. Specify what response is requested—for example, concentration at a particular time—rather than relying on a plot label to convey the calculation. If response is defined as a maximum or a derived quantity, the protocol must express that calculation in the data-generator mathematics or make the intended extraction otherwise explicit.
Worked Example: A Five-Condition Dose-Response Simulation
Consider a hypothetical model whose endpoint response, expressed as a percentage of its maximum, follows
where \(D\) is dose in mg. The requested doses are 0, 10, 50, 100, and 200 mg. In SED-ML, a repeated task can reference the task that runs the model, use a vector range containing those five doses, and set the model’s dose parameter to the current range value for each iteration. Resetting the model between iterations ensures that each result corresponds to the same initial state. A data generator for dose and one for endpoint response can then define the x and y data of a plot.
The expected endpoint values are calculated as follows:
These values are a consistency check under the stated response equation. In a real QSP workflow, the endpoint values would come from the simulated model and the data-generator definition, not from this illustrative equation unless that equation were itself the model. The units, meaning, and sampling time of the response must be stated alongside the dose range.
Parameter Changes and Numerical Settings
Suppose a protocol needs to test a different elimination rate rather than vary dose. A model change can set the parameter value before execution. The change must name the source model element and the exact target attribute. It should also be documented in the protocol description or surrounding project records why the value differs from the source model; recording a number is not the same as recording its scientific provenance.
Numerical settings matter too. A task’s simulation identifies an algorithm, and algorithm parameters can specify details such as tolerances when the chosen algorithm and software support them. These settings affect numerical accuracy and sometimes runtime. A protocol should not imply that two executions are numerically identical merely because both name a broad solver family: implementations, supported settings, and default values can differ. Record settings that are important to the intended result, and inspect the executed results for evidence that the simulation completed as expected.
Worked Example: Declaring a Changed Elimination Rate
Use the one-compartment model from the earlier example, but change its elimination parameter from \(k=0.10\) h\(^{-1}\) in the source SBML model to \(k=0.20\) h\(^{-1}\) for this experiment. Keep \(C_0=8\) mg/L and request the concentration at \(t=5\) h. The model change targets the elimination parameter’s value attribute. The task then links the changed model to a time-course simulation, and the data generator requests concentration at the specified time.
Under the changed parameter value, the model predicts
For comparison, the unchanged source value would give
The difference is consistent with faster elimination under the changed value. This check assumes the same initial concentration and model structure in both runs; it does not show that the changed parameter is biologically justified. The protocol describes the computational change, while the evidence and rationale for that change belong in the model documentation and provenance records.
Why the Protocol-to-Result Mapping Works
The core logic can be stated as a sequence. First, the model reference and declared changes define the model presented to the simulation. Second, the simulation settings define the numerical experiment to perform on that model. Third, the task joins the two. Finally, data generators and outputs specify which results to extract and how to display them. If any link is missing or points to the wrong identifier, a file may be syntactically readable yet fail to represent the intended experiment.
Resolve the source and confirm the model language, identifiers, units, initial conditions, and any intended parameter changes.
Record simulation type, time settings or other relevant settings, algorithm identifier, and supported algorithm parameters.
Create a task that references the intended model and simulation. For a sweep, define a repeated task, range, and set-value target.
Define data generators and outputs, execute with a compatible tool, and check that the returned variables, units, and range match the plan.
This sequence also explains why a plot alone is not a complete protocol. A graph may display a curve, but without the model, simulation, task, and data-generator references, the computation that produced it may be ambiguous. Conversely, a protocol can define a task without defining a useful output; in that case, an execution may occur but fail to return the result needed for review.
Diagnostics, Alternatives, and Limitations
Several checks catch common failures. Confirm that every model source resolves and every identifier reference points to an existing element. Check that XPath targets select the intended model attribute and that units agree across model values, ranges, and labels. For repeated tasks, verify the range values, reset behaviour, and parameter target. For time courses, confirm the start, output start, end, and requested grid. Finally, inspect execution results: a missing curve, unexpected constant output, or implausible scale can indicate a bad reference, an unapplied change, or a mismatch between the requested and returned quantity.
SED-ML is not the only way to record simulation procedures. A script can express custom logic, data processing, and software-specific settings in great detail, but its execution may depend on code, libraries, and environment assumptions that need to be managed separately. A written protocol can be accessible to human readers but may leave choices open to interpretation. SED-ML provides a structured, machine-readable description of common simulation experiments, but tool support varies and some workflows may require features or transformations that a particular implementation does not support.
The format also does not itself validate a model, establish the scientific credibility of parameter values, guarantee numerical convergence, or ensure that a requested calculation has the right biological interpretation. It records instructions and output definitions. Reproducibility still depends on an available model source, compatible software, explicit settings, suitable diagnostics, and documentation of the scientific choices behind the experiment.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions below.
- What role does a SED-ML task play, and how does it differ from a simulation element?
- A repeated task varies dose across five conditions. Why might resetting the model between iterations be necessary?
- For the response equation \(R(D)=100D/(50+D)\), what response is expected at \(D=50\) mg?
- Name two checks that can reveal a mismatch between a protocol and the intended simulation.
Solutions. (1) A simulation specifies the numerical experiment settings; a task connects a particular model to that simulation for execution. (2) Resetting restores the common starting state so that a run at one dose does not inherit state from the preceding dose. (3) \(R(50)=100(50)/(50+50)=50\%\). (4) Examples include resolving every model source and identifier, verifying the XPath target selects the intended parameter attribute, checking units and range values, and inspecting whether the returned variables and time grid match the request.