How to create and edit a computational model ?

  • updated yesterday

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

  • 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 and the filters (in the Actions column) to help browse the model. 

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. 


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. 

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 : vafFalse (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. 

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 {.


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


In the beta version, only two types of scoped tags are available. 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

Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular

Don't have a jinkō account yet?

-> Request a demo today :)


-> Meet modelers from the community