How to create and edit a computational model ?

Table view of the model

The table view of the model is composed of one row per model component. For each component are displayed:

• Its Type: see next paragraph

• Its ID: must be an SBML compliant ID (see SBML documentation)

• Its Display Name (optional): a more readable name that will be used in particular in the Trial visualization. In formulas, the ID must be used. 

• Its Preview: specific to each type, the preview aims at giving the most important information on the component. 

• Its Description (optional)

• Its Links (optional): URIs to the source knowledge that was used to build this component. Used for traceability.

• Its Tags: See paragraph "Tags"

• Its diagnostics: Error messages or warnings sent by jinkō, for example for dimension or dependencies checking. 

• Possible user actions: Duplicate, delete or filter by dependencies (upstream or downstream). 

You can use the search bar or the advanced search to help browse the model. You can also filter by the dependencies of a component in the Actions column, to see where this component impacts others ("is used by"), or on the opposite, which components impact this one ("depends on").  

Different types of components 

Inputs: Parameters, compartments and Species

Parameters, compartments and species can be defined by a numerical value or a formula. Their dynamics can also be defined  by a ODE: In that case the set value or formula is used only as initial condition. 

These inputs also have advanced options:
- Scale σ, defaults to 1. If x is the variable, we introduce the change of variable x′=x/σ and the initial Ode dx/dt=f(x,t) becomes dx′/dt=σ*f(σx′,t) such that the variable we actually solve for, x', has the order of magnitude of x/σ.
- Tolerance, defaults to 1. The tolerance of the scaled variable (in dimensionless units). This value is multiplied by the model-wide tolAbs to get the actual absolute tolerance passed to the solver.

The specificity of compartments is that they can be used in Species. The volume of a compartment is typically in a volume (length³) unit but this is not mandatory - if another dimension is used, this may cause conversion issues for the associated species.

The specificity of species is that they must live in a compartment, and that their dynamics can also be impacted by reactions. Their unit must be of dimension [substance], [substance / volume], or - if a molar mass is defined - [mass] or [mass / volume]. 

Categorical parameters are parameters defined by an unlimited number of available levels (strings) that this parameter can take, and a set level. They can typically be used as conditions for the definitions of other parameters.

Dynamics of the model

An ODE is defined by the following formula d(LeftSide)/dt = RightSide, where
- the left side is the ID of an input
- the right side is a formula defining the derivative of the left side.

A reaction is a biochemical reaction. It allows to consume species (the reactants) and produce other species (the products), at a given rate. The stoechiometric coefficients are used to multiply the rate of consumption or production of each species. The rate can be defined via a formula (General law) or using predefined kinetic laws. A multiplier can optionally be added - it is used to multiply the rate.

Optionally, a filter can be added to ODEs and reactions. The filter is evaluated at tmin and evaluates whether the ODE or reaction should be included or not in the model, for the whole simulation duration. 

Events

An event is a discontinuous change in the model. Its is defined by a set of (ID, update) couples. The ID is the ID of the component that the event should update. Upon triggering of the event, the value of this event will be changed to the value of the update evaluated at that time.
The update is the new value of the "ID to update". Will be evaluated at the time of the event (the "ID to update"'s dynamics remain unchanged otherwise).
Each event can have as many updates as needed. 

Events can be of two types: Time triggered or condition triggered. 

Time triggered event are triggered at a given time point "First time". They can be repeated at "Recurrence time" intervals, either for a fixed "Number of occurrences", or "Until" a given timepoint.
If "Recurrence time" is not completed, the event only happens once. If neither "Number of occurrences" nor "Until" are completed, the event is repeated until tmax.
"First Time", "Recurrence time" and "Until" can be defined as formulas.
A time triggered event can also have a condition which is evaluated at each occurrence of the event. If it evaluates to false, the event is not triggered. 

A condition triggered event is triggered each time the condition is met. 

Optional options linked to the events are:
- Record: If true, the state before and after the event is recorded in the ODE solution, adding 2 timepoints to the results. Defaults to false.
- StopSolver: Defaults to NoStop: the solving goes on until tMax. Other options are: Restart: The solving it stopped and restarted, resetting in particular the  resolution tStep. Stop: The solving is stopped, and the results will show the same values from tEvent to tMax. 

Baseline checks

New: Baseline checks can be used to check that for each patient of your Vpop, the initial conditions are relevant. Typical use cases can be: to restrict the applicability domain of the model, for example ensuring that one is not able to simulate patients with age <18 year old if the model is not adapted to a pediatric population, or if you have a lot of formulaic parameters that depend on parameters of the Vpop, you may want to check that the final values are relevant. 

To use a baseline check, simply define a condition. It will be evaluated at t=0: if the condition is not met, the patient will fail, else the simulation will happen normally. 

Using formulas

Formulas can be used in many fields, such as the values or rates. 

In a formula, you can use MathJS syntax and a subset of the associated operators, as well as reference components using their ID. You can also precise units if needed (typically to use a constant value if your model is unit checked) with the following syntax: u(unit). See How-to for more details on units. 

The most common operators are: (, ), +, -, *, ^, !, and, or, not, ==, !=, <, >, <=, >=, log(), exp(), sin(), cos(), tan() and cond ? valIfTrue : valIfFalse (if-then-else syntax). 

You can do random drawings of values from a normal (respectively uniform) distribution by using rnorm(seed, index, mean, stdev)(respectively runif(seed, index, min, max)) where the seed and index are integers, used for reproducibility. All of these inputs (seed, index, mean, stdev, min, max) can be defined as formulas, using other component's IDs. Note that rnorm and runif are not supported by the conversion from jinko's format to SBML for the moment, so downloading such a model in SBML will trigger an error. 

You can also use conditions on a categorical parameter ID being in a given subset of values with the following syntax: ID in { value1, value2 }. This can be used with the if-then-else syntax, or in any condition or filter field. 

Or you can use casing to define a value as a condition of a categorical parameter ID: case ID of { value1OfID -> value1; value2OfID -> value2; _ -> value3 }where:
- if ID has value1OfID, value1 will be returned
- if ID has value2OfID, value2 will be returned
- else, value3 will be returned.
Make sure you don't forget the space after the {.

We support delay differential equations. To introduce a delay in a formula, the syntax is the following: delay(y,delta) which will evaluate to the arbitrary expression y at time - delta. Note that
- when (time - delta) < tmin, delay(y,delta) will evaluate to y's initial condition. For now, only constant initial conditions are supported, meaning that for t<tmin, y will evaluate to y(t=tmin)
- if delta evaluates to a negative value at any time, it will lead to a runtime error

Options

Different options are available with the model. Most of them are tied to the resolutions of the model: They will be used by default in any trial simulation using this model, but they can be overridden in the Trial simulation itself. The most important ones are the trial duration and the output descriptors, i.e. the descriptors that will be visible in the trial visualization. 

Another important option is ignoreUnits. Setting this to True allows to ignore the unit checking and to avoid conversion of species. More information on this can be found in the How-to. 

Tags

In a CM, you can now create new tags, either with just a Name and a description, or you can use the key::value syntax to create scoped tags. A scoped tag means that a component can only have one tag with a given key: If you add a tag with the same key and a different value, the previous tag with the identical key will be removed. You can use those tags in all the components of your CM. 

Two types of scoped tags are available in all jinko, and can be used in any CM. The inputTag is used for inputs of the model, to give insight on how this input is meant to be used. The status tag can be used for reviews, to evaluate the model.

InputTag::ModelIntrinsic: when the baseline descriptor is assumed to have an unique value independent of the individual

InputTag::PatientDescriptorKnown: when the baseline descriptor is assumed to have a value specific to each individual and whose values are known for each of them

InputTag::PatientDescriptorPartiallyKnown: when the baseline descriptor is assumed to have a value specific to each individual and whose value are not known for each of them but whose distribution is known

InputTag::PatientDescriptorUnknown: when the baseline descriptor is assumed to have a value specific to each individual and whose distribution is not known

InputTag::Formulaic: when the baseline descriptor is a formula whose value depends on the value of other parameter(s)

InputTag::ProtocolSpecific: when the baseline descriptor does not possess an intrinsic value for each individual but whose value depends on external factors that may be changed in the protocol arms

InputTag::Technical: when the baseline descriptor is not a biological parameter and does not fit into one of the above descriptions

Status::Draft: when you are working on a component

Status::NeedReview: when you need a colleague or yourself to review the component definition

Status::Reviewed: when the component definition has been reviewed

Status::Obsolete: if and when a component is no longer needed in a model