fit¶

The fit settings, the metadata filters and the selection of the mappings.

The models of pkdb_models share their fit settings apart from the integrator tolerances (default_fit_settings). Every mapping_collections.py checks the type of the metadata of a mapping (mapping_metadata), reads the observable of a mapping (observable_id) and selects the training data by the values of the metadata (metadata_filter) or the observable (observable_filter). select_mappings selects the data of a fit with the paths of the model object, see sbmlsim.fit.helpers.FitMappings.select for the filters, outliers and validation data.

FIT_ID `module-attribute` ¶

FIT_ID = re.compile(
    "^(?P<subset>.+)_(?P<date>\\d{8})_\\d{6}__[0-9a-f]{5}$"
)

The form of the id of a fit, <subset>_<date>_<time>__<hash>.

MetadataFilter `dataclass` ¶

MetadataFilter(metadata_type, allowed, excluded)

A filter of fit mappings by the values of their metadata.

A mapping passes when every allowed field has one of its values and no excluded field has one of its values. Build it with metadata_filter.

Attributes:

Name	Type	Description
`metadata_type`	`type[MappingMetaData]`	the metadata class, `PKPDMappingMetaData` unless a model extends it.
`allowed`	`tuple[tuple[str, frozenset[Hashable]], ...]`	the fields with the values a mapping must have.
`excluded`	`tuple[tuple[str, frozenset[Hashable]], ...]`	the fields with the values a mapping must not have.

ObservableFilter `dataclass` ¶

ObservableFilter(observables)

A filter of fit mappings by their observable, see observable_id.

Attributes:

Name	Type	Description
`observables`	`frozenset[str]`	the ids of the observables a mapping may have, the index of the data (`Data.index`).

NamedFilter `dataclass` ¶

NamedFilter(mappings)

A filter of fit mappings by their key and study, see named.

Attributes:

Name	Type	Description
`mappings`	`tuple[tuple[str, frozenset[str]], ...]`	the study ids with their mapping keys, sorted, so that the filter compares, pickles and describes the same for equal mappings.

LeveledFitDefinition `dataclass` ¶

LeveledFitDefinition(jit_optimization=None)

Bases: FitDefinition

A fit definition whose problems load their models at an optimization level.

sbmlsim builds the problem of a definition without a level, so it takes the level of the environment variable SBMLSIM_JIT_OPTIMIZATION of the process which builds it. The problem resolves its level once and carries it into every worker of a pool (OptimizationProblem.__getstate__), which loads the models with it: the problems of this definition get the level of the model, in the process and in every worker, whatever the environment of the process and of a forkserver which started the workers.

Attributes:

Name	Type	Description
`jit_optimization`	`str \| None`	the level of LLJIT (`"O0"` to `"O3"`).

default_fit_settings ¶

default_fit_settings(
    absolute_tolerance, relative_tolerance=1e-06
)

Get the settings of the fits of a model.

Normalized residuals with a linear loss; the curves are weighted by the weights of their mappings and by their number of points, the points by their errors (a mapping without errors is weighted with a CV of 0.5); the integrator takes variable steps; a data point at the time of a change after the start is compared with the state before the change (data_at_change), sbmlsim's default, written out so that a change of the default does not change the fits.

Parameters:

Name	Type	Description	Default
`absolute_tolerance`	`float \| AbsoluteTolerance`	the absolute tolerance of the integrator, one value or an `AbsoluteTolerance` per kind and state.	required
`relative_tolerance`	`float`	the relative tolerance of the integrator.	`1e-06`

Returns:

Type	Description
`FitSettings`	The settings, stored with the result of a fit and read back by its report.

mapping_metadata ¶

mapping_metadata(
    fit_mapping: FitMapping,
) -> PKPDMappingMetaData

mapping_metadata(
    fit_mapping: FitMapping, metadata_type: type[M]
) -> M

mapping_metadata(
    fit_mapping, metadata_type=PKPDMappingMetaData
)

Get the metadata of a fit mapping, checked against the type of the model.

Parameters:

Name	Type	Description	Default
`fit_mapping`	`FitMapping`	the fit mapping.	required
`metadata_type`	`type[MappingMetaData]`	the metadata class, `PKPDMappingMetaData` unless a model extends it.	`PKPDMappingMetaData`

Returns:

Type	Description
`MappingMetaData`	The metadata.

Raises:

Type	Description
`TypeError`	if the mapping has no metadata of the type.

observable_id ¶

observable_id(fit_mapping)

Get the observable of a fit mapping, the index of its data.

The index of the y data of the observable (sbmlsim.data.Data.index): the selection without the brackets of a concentration, Cve_hctz for [Cve_hctz], Aurine_hctz for Aurine_hctz. sbmlsim 0.9 writes the concentration into the id of the data (<task>__conc__Cve_hctz), so the id is no longer read.

Parameters:

Name	Type	Description	Default
`fit_mapping`	`FitMapping`	the fit mapping.	required

Returns:

Type	Description
`str`	The id of the observable, e.g. `Cve_hctz`.

check_sampling_sites ¶

check_sampling_sites(
    fit_mappings, sites, metadata_type=PKPDMappingMetaData
)

Check the sampling site of the mappings against their observable.

Parameters:

Name	Type	Description	Default
`fit_mappings`	`FitMappings \| Iterable[FitMapping]`	the fit mappings, or the instantiated experiments of a model (`FitMappings`, every fit mapping of every experiment).	required
`sites`	`Mapping[str, SamplingSite]`	the sampling site of every observable by observable id, e.g. `Carm_hctz` is `ARM_VEIN` and `Aurine_hctz` is `NOT_APPLICABLE`.	required
`metadata_type`	`type[PKPDMappingMetaData]`	the metadata class, `PKPDMappingMetaData` unless a model extends it.	`PKPDMappingMetaData`

Returns:

Type	Description
`list[str]`	One problem per mapping whose site differs from the site of its
`list[str]`	observable or whose observable is not in `sites`; empty if all fit.

metadata_filter ¶

metadata_filter(
    metadata_type=PKPDMappingMetaData,
    /,
    *,
    excluded=None,
    **allowed,
)

Build a filter of fit mappings by the values of their metadata.

# not executed
filter_control = metadata_filter(
    route={Route.PO, Route.IV},
    coadministration={Coadministration.NONE},
    excluded={"dosing": {Dosing.MULTIPLE}},
)

Parameters:

Name	Type	Description	Default
`metadata_type`	`type[MappingMetaData]`	the metadata class, `PKPDMappingMetaData` unless a model extends it; a dataclass.	`PKPDMappingMetaData`
`excluded`	`Mapping[str, Collection[Hashable]] \| None`	the fields with the values a mapping must not have.	`None`
`**allowed`	`Collection[Hashable]`	the fields with the values a mapping must have.	`{}`

Returns:

Type	Description
`MetadataFilter`	The filter, called by the selection of the mappings of a fit.

Raises:

Type	Description
`TypeError`	if the metadata class is no dataclass (or an instance of one), has no field of a given name, or the values of a field are not a collection (a single value, also a string or `None`), i.e. when the module of the filters is imported.
`ValueError`	for a filter without clauses, with an empty set of allowed values, which would select nothing, or with an empty set of excluded values, which would exclude nothing.

observable_filter ¶

observable_filter(observables)

Build a filter of fit mappings by their observable, e.g. the PK data.

Parameters:

Name	Type	Description	Default
`observables`	`Collection[str]`	the ids of the observables, the index of the data (`Data.index`), e.g. `Cve_hctz`.	required

Returns:

Type	Description
`ObservableFilter`	The filter.

Raises:

Type	Description
`TypeError`	if the observables are a single id or not a collection.
`ValueError`	for no observables, which would select nothing.

study ¶

study(fit_mapping)

Get the study of a fit mapping, the id of its experiment.

named ¶

named(mappings, fit_mapping_key, fit_mapping)

Check whether a fit mapping is one of the named mappings of its study.

The key alone is not enough: two studies can share a key, so it counts only for the study it is named with.

named_filter ¶

named_filter(mappings)

Build a filter of the fit mappings named with their study.

Parameters:

Name	Type	Description	Default
`mappings`	`NamedMappings`	the mapping keys by study id.	required

Returns:

Type	Description
`NamedFilter`	The filter.

select_mappings ¶

select_mappings(
    model,
    experiment_classes,
    filters=(),
    outliers=(),
    validation=(),
)

Select the data of a fit of a model, see sbmlsim.fit.helpers.FitMappings.

The experiments are created with the paths of the model object; the counts of the selected mappings per experiment and kind are printed.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model object.	required
`experiment_classes`	`Iterable[type[SimulationExperiment]]`	the experiments with the fit mappings.	required
`filters`	`MappingFilter \| Iterable[MappingFilter]`	the filters of the training data.	`()`
`outliers`	`Iterable[str]`	the keys of the training data which is not usable.	`()`
`validation`	`Iterable[str] \| MappingFilter`	the keys or a filter of the validation data.	`()`

Returns:

Type	Description
`dict[str, list[FitMappingCollection]]`	The fit mapping collections of all kinds by experiment id.

fit_subset ¶

fit_subset(fit_id)

Get the fit problem a fit belongs to from its id.

Parameters:

Name	Type	Description	Default
`fit_id`	`str`	the id of a fit, e.g. `PK_20261016_185018__3efe3` (`sbmlsim.fit.result.fit_id`).	required

Returns:

Type	Description
`str`	The subset, e.g. `PK`. It may contain underscores, `PK_X_...` is `PK_X`.

Raises:

Type	Description
`ValueError`	if the id does not have the form of the id of a fit, also if it holds a path separator or `..`, so that the id is safe as the name of a directory.

fit_date ¶

fit_date(fit_id)

Get the day a fit ran from its id.

Parameters:

Name	Type	Description	Default
`fit_id`	`str`	the id of a fit, e.g. `PK_20261016_185018__3efe3`.	required

Returns:

Type	Description
`date`	The date of the id, e.g. 2026-10-16.

Raises:

Type	Description
`ValueError`	if the id does not have the form of the id of a fit, see `fit_subset`, or its date is no date.

remainder_problems ¶

remainder_problems(
    sbml_path, parameters, fixed_values=None
)

Check that the fitted fractions of a remainder cannot sum above 1.

A remainder is the initial assignment 1 - a - b - ... of a constant of the model (the remainder REST of the product fractions of a metabolism of pkpdsim.pbpk, f_<p>_<s>): it keeps the sum of the fractions at 1, and is negative, a product formed at a negative rate, when the other fractions sum above 1. run_fit refuses a fit whose bounds allow it before it starts: the upper bounds of the fitted fractions of a remainder and the values of the others (the fixed values of the adopted fits, else those of the model) sum to at most 1.

Parameters:

Name	Type	Description	Default
`sbml_path`	`Path`	the model the fit simulates.	required
`parameters`	`Iterable[FitParameter]`	the parameters of the fit.	required
`fixed_values`	`Mapping[str, float] \| None`	the values of parameters the fit keeps fixed, by id.	`None`

Returns:

Type	Description
`list[str]`	The problems, naming the remainder, the fitted parameters and their
`list[str]`	upper bounds.

at_level ¶

at_level(definition, level)

Get a fit definition whose problems load their models at a level.

Parameters:

Name	Type	Description	Default
`definition`	`FitDefinition`	the fit definition of the model.	required
`level`	`str \| None`	the optimization level of the model (`SimulatorSettings.jit_optimization`), `None` for the level of sbmlsim.	required

Returns:

Type	Description
`FitDefinition`	The definition itself without a level, else a `LeveledFitDefinition`
`FitDefinition`	with its fields.

leveled_definitions ¶

leveled_definitions(model)

Get the fit definitions of a model at its optimization level, see at_level.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required

Returns:

Type	Description
`dict[str, FitDefinition]`	The fit definitions by name.

start_point ¶

start_point(model, definition, start, output_dir)

Get the parameters a fit starts from (run_fit --start).

The start is a json file of the values by parameter id, in the units of the fit parameters (FitParameter.unit), or the id of a fit: an adopted fit of the model (PKPDModel.fits_dir) or else a finished fit in the output directory of the fits, whose best parameters (parameters.json, in the units of the model) are converted into the units of the fit parameters. A fit of another problem gives the parameters which the definition fits. A parameter which the start does not give keeps its own start value.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`definition`	`FitDefinition`	the fit problem.	required
`start`	`str`	the json file or the fit id.	required
`output_dir`	`Path`	the directory of the finished fits.	required

Returns:

Type	Description
`dict[str, float]`	The start value of every parameter the start gives which the
`dict[str, float]`	definition fits.

Raises:

Type	Description
`ValueError`	if the start is neither a file nor a fit, a value is not a number, a parameter of the file is not fitted, a value of a fit has no unit for a fit parameter with one, or a value is outside of the bounds of its parameter.

with_start ¶

with_start(definition, point)

Get a fit problem whose parameters start from a point.

The parameters are copies, so the definition of the model keeps its start values (the definitions are objects of the module of the model).

Parameters:

Name	Type	Description	Default
`definition`	`FitDefinition`	the fit problem.	required
`point`	`Mapping[str, float]`	the start value by parameter id.	required

Returns:

Type	Description
`FitDefinition`	The fit problem with the start values of the point.

fixed_values ¶

fixed_values(model, subset, definition)

Get what a fit of a subset keeps fixed: the adopted fits of the other problems.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`subset`	`str`	the fit problem, e.g. `PK`.	required
`definition`	`FitDefinition`	its definition, whose parameters are fitted and not fixed.	required

Returns:

Type	Description
`list[str]`	The adopted fits of the other subsets (`current_fixed_fits`) and the
`dict[str, float]`	values of their parameters in the units of the model, without the
`tuple[list[str], dict[str, float]]`	parameters the definition fits.

current_fixed_fits ¶

current_fixed_fits(model, subset)

Get the adopted fits whose parameters a fit of a subset keeps fixed.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`subset`	`str`	the fit problem, e.g. `PK`.	required

Returns:

Type	Description
`list[str]`	The adopted fits of the model of the other subsets, in the order of
`list[str]`	`model.fits`.

recorded_fixed_fits ¶

recorded_fixed_fits(records)

Get the fixed adopted fits which the provenance of a fit records.

run_fit records them in the arguments of the provenance (FIXED_FITS).

Parameters:

Name	Type	Description	Default
`records`	`FitRecords`	the records of the fit (`sbmlsim.fit.cli.load_fit_records`).	required

Returns:

Type	Description
`str`	The ids of the fixed fits, none for a fit without a result, without a
`...`	provenance or of an older pkpdsim, which did not record them.

report_context ¶

report_context(model, subset, definition, *, fixed_fits)

Get what the report of a fit says about the model beyond the fit itself.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required
`subset`	`str`	the fit problem, e.g. `PK`.	required
`definition`	`FitDefinition`	the definition of the fit problem.	required
`fixed_fits`	`Sequence[str]`	the adopted fits whose parameters the fit kept fixed, the current ones for a fit which runs (`current_fixed_fits`), the recorded ones for a report from a record (`recorded_fixed_fits`).	required

Returns:

Type	Description
`ReportContext`	The title of the model and the fit, the description of the fit and of
`ReportContext`	its parameters, and a note on the fixed adopted fits, none without
`ReportContext`	them.

records_context ¶

records_context(model)

Get the context of the report of a fit from its records.

It is the context of sbmlsim.fit.cli.report_cli and of sbmlsim.fit.cli.report_from_records for a model: the fixed adopted fits are those the provenance of the record names (recorded_fixed_fits), not the adopted fits of the model now.

Parameters:

Name	Type	Description	Default
`model`	`PKPDModel`	the model.	required

Returns:

Type	Description
`Callable[[str, FitDefinition, FitRecords], ReportContext]`	A function of the subset, its definition and the records of the fit
`Callable[[str, FitDefinition, FitRecords], ReportContext]`	which returns the context of its report (`report_context`).

fit¶

FIT_ID module-attribute ¶

MetadataFilter dataclass ¶

ObservableFilter dataclass ¶

NamedFilter dataclass ¶

LeveledFitDefinition dataclass ¶

default_fit_settings ¶

mapping_metadata ¶

observable_id ¶

check_sampling_sites ¶

metadata_filter ¶

observable_filter ¶

study ¶

named ¶

named_filter ¶

select_mappings ¶

fit_subset ¶

fit_date ¶

remainder_problems ¶

at_level ¶

leveled_definitions ¶

start_point ¶

with_start ¶

fixed_values ¶

current_fixed_fits ¶

recorded_fixed_fits ¶

report_context ¶

records_context ¶

FIT_ID `module-attribute` ¶

MetadataFilter `dataclass` ¶

ObservableFilter `dataclass` ¶

NamedFilter `dataclass` ¶

LeveledFitDefinition `dataclass` ¶