# Input Format for yaml2sbml

## General scope

yaml2sbml: translate ODEs (initial value problems) of the form x’ = f(t, x, p) with time t, states x and (potentially) unknown parameters p into an SBML file for simulation purpose.

yaml2PEtab: define a fitting problem of the form y(t_i) = h(x(t_i), p) + eps_i with independent normal- or Laplace-distributed error terms eps. h denotes the mapping from system states to observables. PEtab allows one to formulate MLE and MAP based fitting problems.

## General remarks

All identifiers of states, parameters etc. need to be valid SBML identifiers. Therefore, identifiers must consist of only upper and lower case letters, digits and underscores, and must not start with a digit.

Mathematical equations are parsed by libsbml`s `parseL3Formula. Hence for correct syntax see its documentation and the corresponding section of the format specification.

Equations starting with a minus must be surrounded by brackets or quotation marks, since a leading minus also has a syntactic meaning in YAML and the YAML file will not be valid otherwise.

## time [optional]

```
time:
variable: t
```

Define the **time variable**, in case the right hand side of the ODE is time-dependent.

## parameters [optional]

```
parameters:
- parameterId: p_1
nominalValue: 1
- parameterId: p_2
...
```

Define **parameters**. nominalValue is optional for SBML/PEtab generation, but will be needed for model simulation. Further optional entries are parameterName, parameterScale, lowerBound, upperBound, estimate and entries regarding priors. These entries will be written in the corresponding column of the _parameter table_ by yaml2PEtab.

For a detailed description see the documentation of the PEtab parameter table “PEtab parameter table documentation”).

Further entries are possible and will be written to the _parameter table_ as well but are currently not part of the PEtab standard.

## odes

```
odes:
- stateId: x_1
rightHandSide: p_1 * x_1
initialValue: 1
- stateId: x_2
...
```

Define **ODEs** (and states). An ODE consists of a stateId (string), a rightHandSide (string, encoding a mathematical expression), and an initial value. Initial values can be either numerical values or parameter Ids.

For a more detailed description of the parsing of mathematical expressions ( for rightHandSide) we refer to the corresponding section of this documentation.

## assignments [optional]

```
assignments:
- assignmentId: sum_of_states
formula: x_1 + x_2
- assignmentId: ...
...
```

**Assign** the mathematical expression formula to the term assignmentId. The value is dynamically updated and can depend on parameters, states and time. In SBML, assignments are represented via parameter assignment rules.

For a more detailed description of the parsing of mathematical expressions (e.g. for formula) we refer to the [corresponding section](#parsing-of-mathematical-equations) of this documentation.

## functions [optional]

```
functions:
- functionId: g_1
arguments: x_1, s
formula: s * x_1 + 1
- functionId: g_2
...
```

Define **functions**, which can be called in other parts of the ODE definitions, e.g. in the example above via g_1(x_1, s).

**Please note** that all unknowns appearing in the formula (e.g. also parameters or the time variable) also have to be arguments of the function.

For a more detailed description of the parsing of mathematical expressions (e.g. for formula) we refer to the [corresponding section](#parsing-of-mathematical-equations) of this documentation.

## observables [optional]

```
observables:
- observableId: Obs_1
observableFormula: x_1 + x_2
noiseFormula: noiseParameter1
noiseDistribution: normal
- observableId: Obs_2
...
```

Define **observables**. Observables are not part of the SBML standard. If the SBML is generated via the yaml2sbml.yaml2sbml command and the observables_as_assignments flag is set to True, observables are represented as assignments to parameters of the form observable_<observable_id>.
If the SBML is created via yaml2sbml.yaml2petab, observables are represented in the PEtab observables table. The entries are written to the corresponding columns of the PEtab observable table. According to the PEtab standard, an observable table can take the following entries: observableId, observableName, observableFormula, observableTransformation, noiseFormula, noiseDistribution.

For a detailed discussion see the corresponding part of the PEtab documentation <https://github.com/PEtab-dev/PEtab/blob/master/doc/documentation_data_format.rst#observables-table>`_.

## conditions [optional]

```
conditions:
- conditionId: condition1
p_1: 1
x_1: 2
...
```

Conditions allow one to set parameters or initial conditions of states to a numeric value/unknown parameter. This allows for the specification of different experimental setups in the data generation (e.g. different initial conditions for different runs of an experiment).

The “trivial condition table” (if only one setup exists) is generated by:

```
conditions:
- conditionId: condition1
```

For a detailed discussion see the corresponding part of the PEtab documentation.

## Parsing of mathematical equations

Throughout yaml2sbml formulas are parsed by libsbml’s parseL3Formula function. Further information on the syntax are given by:

the working with math - section of the libsbml documentation.

the documentation of libsbml.parseL3Formula.

This gives access to e.g.:

+, -, *, /, and `power;

trigonometric/hyperbolic functions;

exponential/logarithmic functions;

piecewise defined functions (via piecewise); and

boolean expressions like “<”.