Skip to content

fit.helpers

Selection of the data of a fit.

A fit selects its data from the fit mappings of its simulation experiments. FitMappings is the complete list of these mappings, i.e., every curve which is mapped to a simulation, and FitMappings.select decides what a fit does with every one of them in three steps, each setting a MappingKind:

  1. The filters select the training data. A mapping which passes every filter is training data of the fit. A mapping which fails a filter is EXCLUDED: the fit does not use it at all, e.g. the data of a route the fit is not about or an arm with a coadministration the model does not describe.
  2. The outliers are named by their keys. An outlier is training data whose values are not usable, e.g. a curve which contradicts the rest of the data, so it is tagged once for the complete list of mappings and not per fit. It is OUTLIER in every fit whose filters select it: it is not fitted, but simulated and evaluated so that a report shows where it sits relative to the model. An outlier the filters exclude stays excluded.
  3. Part of the training data is the validation data. The validation data is selected from what is left by its keys or by a filter, it is VALIDATION: not fitted, but simulated and evaluated so that a report shows how the fit describes data it was not fitted on. Everything else is TRAINING and enters the cost.

The three steps are ordered, so a mapping which hits several has one kind: excluded beats outlier, outlier beats validation and validation beats training. The kind belongs to the selection of the data, not to the fit mappings of a simulation experiment: the MappingMetaData of a mapping describes its curve, and the same curve is training data of one fit and validation data of another.

The filters of the mappings are the ones of sbmlsim.fit.filters (by the metadata, the observable, the key and the study), which this module exports as well; select_mappings selects the data of a fit of a sbmlsim.project.Project with its paths.

KeyFilter dataclass 

KeyFilter(keys)

A filter of fit mappings by their key alone, in whichever study.

Attributes:

Name Type Description
keys frozenset[str]

the keys of the mappings which pass.

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; the value of a field is the one of MappingMetaData.filter_value. Build it with metadata_filter.

Attributes:

Name Type Description
metadata_type type[MappingMetaData]

the metadata class of the mappings.
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.

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.

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

MappingSelection dataclass 

MappingSelection(kinds, collections, df)

The kind of every fit mapping, i.e., what a fit does with the data.

A selection is created by FitMappings.select. It is the result of the three steps of the selection for every fit mapping of every experiment.

Attributes:

Name Type Description
kinds dict[str, dict[str, MappingKind]]

the MappingKind of every fit mapping by experiment id and key.
collections dict[str, list[FitMappingCollection]]

the FitMappingCollection per experiment and kind, in the order of MappingKind, which is what a FitDefinition is defined with. Every fit mapping is in exactly one collection.
df DataFrame

one row per fit mapping with experiment, fm_key, yid (the observable), kind and the fields of its MappingMetaData; the overview display.print_data prints.

kind 

kind(experiment_id, key)

Get the kind of a fit mapping.

Parameters:

Name Type Description Default
experiment_id str

id of the simulation experiment.

 required
key str

key of the fit mapping.

 required

kinds_of 

kinds_of(experiment_id)

Get the kinds of the fit mappings of an experiment.

Parameters:

Name Type Description Default
experiment_id str

id of the simulation experiment.

 required

print 

print(detail=True)

Print the overview of the selected data.

Parameters:

Name Type Description Default
detail bool

list the single fit mappings, not only the counts.

 True

FitMappings 

FitMappings(
    experiment_classes,
    base_path,
    data_path,
    jit_optimization=None,
)

The fit mappings of simulation experiments, i.e., the data a fit selects from.

The experiments are instantiated once, which loads their models and their datasets and is the expensive part, and are selected from several times, once per fit problem.

Attributes:

Name Type Description
runner

runner with the instantiated simulation experiments.
keys dict[str, list[str]]

the keys of the fit mappings of every experiment by experiment id.

Instantiate the simulation experiments.

Parameters:

Name Type Description Default
experiment_classes Iterable[type[SimulationExperiment]]

simulation experiment classes with fit mappings.

 required
base_path Path

base path of the simulation experiments.

 required
data_path Path | Iterable[Path] | None

path or paths of the datasets of the simulation experiments, none without datasets.

 required
jit_optimization JitOptimization | str | None

the optimization level the models of the experiments are compiled at, see ExperimentRunner; the level of a project is SimulatorSettings.jit_optimization.

 None

experiments property 

experiments

The instantiated simulation experiments by id.

for_project classmethod 

for_project(project, experiment_classes)

Instantiate the experiments of a project, as its runs do.

The experiments get the paths of the project (its base_path, else its root, and its data_path) and its models are compiled at its level (SimulatorSettings.jit_optimization).

Parameters:

Name Type Description Default
project Project

the project.

 required
experiment_classes Iterable[type[SimulationExperiment]]

simulation experiment classes with fit mappings.

 required

Returns:

Type Description
FitMappings

The fit mappings of the experiments.

select 

select(
    filters=(), outliers=(), validation=(), print_info=True
)

Select the data of a fit, see the module for the three steps.

Parameters:

Name Type Description Default
filters MappingFilter | Iterable[MappingFilter]

filters of the training data. A mapping which passes every filter is training data, a mapping which fails one is excluded. No filters select every mapping.

 ()
outliers Iterable[str]

keys of the outliers, i.e., of the training data which is not usable and not fitted. An outlier is a decision about the data, so it is named for the complete list of mappings, not per fit; an outlier the filters exclude stays excluded.

 ()
validation Iterable[str] | MappingFilter

the validation data, i.e., the training data which is not fitted but evaluated, as the keys of the mappings or as a filter of the training data which is left after the outliers.

 ()
print_info bool

print the overview of the selected data.

 True

Returns:

Type Description
MappingSelection

The selection with the kind of every fit mapping and the collections
MappingSelection

a fit is defined with.

Raises:

Type Description
ValueError

for an outlier or validation key which is no fit mapping of any experiment.

filter_keys 

filter_keys(keys)

Build a filter which selects the fit mappings of the given keys.

A selector written by hand says what it means, e.g. "the tablets"; this one says which mappings it resolved to and is what a problem read from PEtab uses, because a condition stores the resolution and not the rule. A key selects the mapping of that key in every study, named_filter names the study as well.

Parameters:

Name Type Description Default
keys Iterable[str]

the keys of the fit mappings to select.

 required

Returns:

Type Description
KeyFilter

A filter which passes exactly those mappings.

metadata_filter 

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

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

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

Parameters:

Name Type Description Default
metadata_type type[MappingMetaData]

the metadata class of the mappings, a dataclass derived from MappingMetaData.

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

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.

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.

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.

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.

study 

study(fit_mapping)

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

select_mapping_collections 

select_mapping_collections(
    experiment_classes,
    base_path,
    data_path,
    filters=(),
    outliers=(),
    validation=(),
    print_info=True,
    jit_optimization=None,
)

Select the data of a fit in one call, see FitMappings.select.

This instantiates the experiments and selects from them once, which is what the mapping_collections of a FitDefinition does.

Parameters:

Name Type Description Default
experiment_classes Iterable[type[SimulationExperiment]]

simulation experiment classes with fit mappings.

 required
base_path Path

base path of the simulation experiments.

 required
data_path Path | Iterable[Path]

path or paths of the datasets of the simulation experiments.

 required
filters MappingFilter | Iterable[MappingFilter]

filters of the training data.

 ()
outliers Iterable[str]

keys of the outliers.

 ()
validation Iterable[str] | MappingFilter

keys or filter of the validation data.

 ()
print_info bool

print the overview of the selected data.

 True
jit_optimization JitOptimization | str | None

the optimization level the models of the experiments are compiled at, see FitMappings.

 None

Returns:

Type Description
dict[str, list[FitMappingCollection]]

The fit mapping collections of all kinds by experiment id.

select_mappings 

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

Select the data of a fit of a project, see FitMappings.select.

The experiments are created as the runs of the project create them (FitMappings.for_project); the counts of the selected mappings per experiment and kind are printed.

Parameters:

Name Type Description Default
project Project

the project.

 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.