Skip to content

interpolation

Interpolation of data points, as a model of its own or driving a model.

A table of data points becomes assignment rules which evaluate a constant, linear or natural cubic spline interpolation of every column against the first. The rules make a standalone model (Interpolation.write_sbml_to_file), drive the quantities of an existing model in place (Interpolation.drive) or through a comp model which leaves the original untouched (Interpolation.drive_comp), or go into a model definition of the factory (Interpolation.assignment_rules). See the guide docs/interpolation.md.

InterpolationMethod

Bases: StrEnum

Available interpolation methods.

The members are strings, so the plain value ("linear") is accepted and compares equal wherever a method is expected.

Interpolator 

Interpolator(x, y, method=CONSTANT)

The interpolation of one data series y against x.

Outside the data the first value is held before it and the last value after it, for every method.

Initialize Interpolator.

Parameters:

Name Type Description Default
x Series

The independent variable, strictly increasing, named as x is named in the model (time for the simulation time).

 required
y Series

The values interpolated against x.

 required
method InterpolationMethod | str

The interpolation method.

 CONSTANT

Raises:

Type Description
ValueError

If the method is not an interpolation method or the series cannot be interpolated, see _check_series.

xid property 

xid

X id.

yid property 

yid

Y id.

formula 

formula()

Get the formula of the interpolation as an SBML L3 formula string.

Every number is written as the repr of its float, so ast holds it exactly.

ast 

ast()

Get the formula as the libsbml AST the writers use.

Raises:

Type Description
ValueError

If libsbml cannot parse the formula, which happens only for a name of x which is not an SBML id.

Interpolation 

Interpolation(data, method=LINEAR)

The interpolation of a table of data points.

The first column is x, every other column is interpolated against it. time as x is the simulation time, any other name the quantity of the model of that id.

Initialize Interpolation.

Parameters:

Name Type Description Default
data DataFrame

The data points, x in the first column.

 required
method InterpolationMethod | str

The interpolation method of every column.

 LINEAR

Raises:

Type Description
ValueError

If the method is not an interpolation method or the data cannot be interpolated, see validate_data.

xid property 

xid

The name of x, the first column.

interpolators property 

interpolators

The interpolators of the columns after the first, in column order.

validate_data 

validate_data()

Validate the data, and sort it by x if it is not ascending.

Raises:

Type Description
ValueError

If the data has fewer than 2 columns, a column name which is not a string or which repeats, a first column whose name is not an SBML id, or a column which cannot be interpolated (see Interpolator).

from_csv staticmethod 

from_csv(csv_file, method=LINEAR, sep=',')

Interpolation of the data of a csv file, x in the first column.

from_tsv staticmethod 

from_tsv(tsv_file, method=LINEAR)

Interpolation of the data of a tsv file, x in the first column.

write_sbml_to_file 

write_sbml_to_file(sbml_out)

Write the SBML file.

:param sbml_out: Path to SBML file :return:

write_sbml_to_string 

write_sbml_to_string()

Write the SBML file.

:return: SBML str

drive 

drive(source, targets=None, filepath=None)

Drive quantities of a model with the data, in place.

Every driven element gets the assignment rule of its column. A parameter or a compartment becomes non constant, a species a non constant boundary species, so it stays a reactant or product; the data of a species is its concentration, or its amount if it has only substance units. The data is in the units of the element it drives. An initial assignment of a driven element is removed. x is time or the quantity of the model named like the first column.

Parameters:

Name Type Description Default
source Path | str | SBMLDocument

the model, an SBML file, an SBML string or a document, which is changed and returned

 required
targets Mapping[str, str] | None

the column which drives an element, to the id of the element; None for every column driving the element of its own id

 None
filepath Path | None

the file to write the driven model into, if given

 None

Returns:

Type Description
SBMLDocument

The document of the driven model, SBML Level and Version unchanged.

Raises:

Type Description
ValueError

for a column which is not in the data, two columns driving one element, an element which is not in the model, is not a parameter, species or compartment, or is determined by a rule or an event assignment already, or an x which is not in the model; the document is unchanged then.

drive_comp 

drive_comp(
    source, targets=None, filepath=None, embed=False
)

Drive quantities of a model with the data through a comp model.

The comp document has the original as the submodel <model id> of the top model <model id>_driven, which holds the interpolation. A driven element is replaced by an element of its class in the top model, which the assignment rule of its column determines; a species keeps its compartment, which reads the compartment of the original, and x other than time reads the quantity of the original. After flattening the elements of the original are named <model id>__<id>, the driven elements and x keep their ids, and the model simulates as the one of drive. An original without an id is named model, or model_1, ... if one of its elements is model. The data is in the units of the element it drives, the top model takes over the units of the original. With embed=True a model with fbc content is copied without its fbc:strict, which libsbml cannot write on a model definition.

Parameters:

Name Type Description Default
source Path | str | SBMLDocument

the model, an SBML Level 3 file, or with embed=True also an SBML string or a document; it is never changed

 required
targets Mapping[str, str] | None

the column which drives an element, to the id of the element; None for every column driving the element of its own id

 None
filepath Path | None

the file to write the comp model into, if given; the reference to the original is relative to its directory

 None
embed bool

copy the original into the comp document as a model definition instead of referencing its file

 False

Returns:

Type Description
SBMLDocument

The comp document.

Raises:

Type Description
ValueError

as drive, and for an original which is not SBML Level 3, a string or a document without embed=True, a hierarchical original with embed=True, or an initial assignment of a driven element without a metaid.

assignment_rules 

assignment_rules(targets=None)

The interpolation as assignment rules of a model definition.

A model definition of sbmlutils.factory takes them with model.rules += interpolation.assignment_rules(...); it declares the driven elements itself, non constant and with their units.

Parameters:

Name Type Description Default
targets Mapping[str, str] | None

the column which drives an element, to the id of the element; None for every column driving the element of its own id

 None

Returns:

Type Description
list[AssignmentRule]

One AssignmentRule per driven element.

Raises:

Type Description
ValueError

for a column which is not in the data, two columns driving one element or a target which is not an SBML id.