Compartmental Model

Compartmental Model#

Defining a compartmental model#

class icomo.CompModel(y_dict=None)[source]#

Class to help building a compartmental model.

The model is built by adding flows between compartments. The model is then compiled into a function that can be used in an ODE.

Parameters:

y_dict (PyTree[ArrayLike]) – Dictionary/nested python structure of compartments. Keys are the names of the compartments and values are jax.numpy.arrays that represent their value.

Variables:

  • y (PyTree[jax.Array]) – Dictionary or pytree of compartments. Keys/indices are the names of the compartments and values are jax.Array that represent their value.

  • dy (PyTree[jax.Array]) – Dictionary or pytree of compartments. Keys/indices are the names of the compartments and values are jax.Array that represent their derivative.

  • edges (PyTree[list[tuple[indices, str]]]) – Edges between compartments, saved as the same pytree as the compartments, but as leafs, as a list of tuples. The first element of the tuple is the index of the compartment the flow is going to, the second element is the label of the flow.

flow(start_comp, end_comp, rate, label=None, end_comp_is_erlang=False)[source]#

Add a flow from start_comp to end_comp with rate flow.

Parameters:

  • start_comp (str | int | Sequence[str | int]) – Key/index list of the start compartment.

  • end_comp (str | int | Sequence[str | int]) – Key/index list of the end compartment

  • rate (ArrayLike) – rate of the flow to add between compartments, is multiplied by start_comp, so it should be broadcastable with it.

  • label (str | None, default: None) – label of the edge between the compartments that will be used when displaying a graph of the compartmental model.

  • end_comp_is_erlang (bool, default: False) – If True, end_comp points to a compartment with an Erlang distributed dwelling time, i.e., as the last dimension of the compartment is used for the Erlang distribution modeling. The flow is then only added to the first element of the last dimension, i.e. to self.y[end_comp][...,0].

Return type:

None

Returns:

None

add_deriv(y_key, additive_dy, end_comp_is_erlang=False)[source]#

Add a derivative to a compartment.

Add a derivative to a compartment. This is useful if the derivative is not directly modelled by a flow between compartments.

Parameters:

  • y_key (str | int | Sequence[str | int]) – Key/index list of the compartment

  • additive_dy (ArrayLike) – Derivative to add to the compartment

  • end_comp_is_erlang (bool, default: False) – If True, y_key points to a compartment with an Erlang distributed dwelling time, i.e., as the last dimension of the compartment is used for the Erlang distribution modeling. The derivative is then only added to the first element of the last dimension, i.e. to self.y[end_comp][...,0]

Return type:

None

erlang_flow(start_comp, end_comp, rate, label=None, end_comp_is_erlang=False)[source]#

Add a flow with erlang kernel from start_comp to end_comp.

Uses the function erlang_kernel() to model the flow.

Parameters:

  • start_comp (str | int | Sequence[str | int]) – start compartments of the flow. The length of last dimension the list is the shape of the Erlang kernel.

  • end_comp (str | int | Sequence[str | int]) – end compartment of the flow

  • rate (ArrayLike) – rate of the flow, equal to the inverse of the mean time spent in the Erlang kernel.

  • label (str | None, default: None) – label of the edge between the compartments that will be used when displaying a graph of the compartmental model.

  • end_comp_is_erlang (bool, default: False) – If True, end_comp points to a compartment with an Erlang distributed dwelling time, i.e., as the last dimension of the compartment is used for the Erlang distribution modeling. The flow is then only added to the first element of the last dimension, i.e. to self.y[end_comp][...,0].

Return type:

None

delayed_copy(comp_to_copy, delayed_comp, tau_delay)[source]#

Add a delayed copy of a compartment.

Uses the function delayed_copy_kernel() to model the delayed copy.

Parameters:

  • comp_to_copy (str | int | Sequence[str | int]) – Key/index list of the compartment to copy

  • delayed_comp (str | int | Sequence[str | int]) – Key/index list of the delayed compartment

  • tau_delay (ArrayLike) – The mean delay of the copy, has to be broadcastable with the compartment``comp_to_copyp

Return type:

None

view_graph(on_display=True)[source]#

Display a graph of the compartmental model.

Requires Graphviz (a non-python software) to be installed (https://www.graphviz.org/). It is also available in the conda-forge channel. See xflr6/graphviz.

Parameters:

on_display (bool, default: True) – If True, the graph is displayed in the notebook, otherwise it is saved as a pdf in the current folder and opened with the default pdf viewer.

Return type:

None

Helper functions#

icomo.erlang_kernel(comp, rate, inflow=0)[source]#

Model the compartments delayed by an Erlang kernel.

Utility function to model an Erlang kernel for a compartmental model. The shape is determined by the length of the last dimension of comp. For example, if comp C is an array of shape (…,3), the function implements the following system of ODEs:

\[\begin{split}\begin{align*} \mathrm{rate\_indiv} &= 3 \cdot \mathrm{rate},&\\ \frac{\mathrm dC^{(1)}(t)}{\mathrm dt} &= \mathrm{inflow} &-\mathrm{ rate\_indiv} \cdot C^{(1)},\\ \frac{\mathrm dC^{(2)}(t)}{\mathrm dt} &= \mathrm{rate\_indiv} \cdot C^{(1)} &-\mathrm{rate\_indiv} \cdot C^{(2)},\\ \frac{\mathrm dC^{(3)}(t)}{\mathrm dt} &= \mathrm{rate\_indiv} \cdot C^{(2)} &-\mathrm{rate\_indiv} \cdot C^{(3)},\\ \mathrm{outflow} &= \mathrm{rate\_indiv} \cdot C^{(3)} \end{align*}\end{split}\]
Parameters:

  • comp (ArrayLike) – The compartment of shape (…, n) on which the Erlang kernel is applied. The last dimension n is the length of the kernel.

  • rate (ArrayLike) – The rate of the kernel, 1/rate is the mean time spent in total in all compartments. Has to be broadcastable with comp.

  • inflow (ArrayLike, default: 0)

Return type:

tuple[Array, ArrayLike]

Returns:

  • d_comp – The derivatives of shape (…, n) of the compartments

  • outflow – The outflow of shape (…) from the last compartment

icomo.delayed_copy_kernel(initial_comp, delayed_comp, tau_delay)[source]#

Return the derivative to model the delayed copy of a compartment.

The delay has the form of an Erlang kernel with shape parameter delayed_comp.shape[-1].

Parameters:

  • initial_comp (ArrayLike) – The compartment of shape (…) that is copied

  • delayed_comp (ArrayLike) – Compartment of shape (…, n) that is a delayed copies of initial_var, the last element of the last dimension is the compartment which has the same total content as initial_comp over time, but is delayed by tau_delay.

  • tau_delay (ArrayLike) – The mean delay of the copy, has to be broadcastable with initial_comp.

Return type:

Array

Returns:

d_delayed_vars – The derivatives, of shape (…, n) of the delayed compartments