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.

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)

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

path of the datasets of the simulation experiments.

 required

experiments property 

experiments

The instantiated simulation experiments by id.

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)

Get a filter which selects the fit mappings of the given ids.

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.

Parameters:

Name Type Description Default
keys Iterable[str]

ids of the fit mappings to select.

 required

Returns:

Type Description
MappingFilter

A filter which passes exactly those mappings.

select_mapping_collections 

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

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

path 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

Returns:

Type Description
dict[str, list[FitMappingCollection]]

The fit mapping collections of all kinds by experiment id.

mapping_kinds_info 

mapping_kinds_info(df)

Summarize how the fit mappings of a metadata table are used.

Parameters:

Name Type Description Default
df DataFrame

metadata table of a MappingSelection.

 required

Returns:

Type Description
str

One line with the number of mappings per MappingKind.