fit.records¶

The records of the adopted fits of a project: the fitted values and their uncertainty.

A fit becomes part of a model in two steps:

Adopt the fit: the fit kind of sbmlsim.run with adopt copies the record of the finished fit (its parameters, the profile likelihood and the Fisher information, its report) into the directory fits/<fit id> of its output and writes adopted.json there, the adopted fits of the project with the fit adopted for its subset (adopt_fit). A person commits both into the project (Project.fits_dir, Project.adopted_file).
Use it in the factory: a model file takes the value of a fitted parameter from the record, together with its uncertainty, see AdoptedRecords.parameter:

# not executed
FITS = PROJECT.fit_records()
Parameter("k", **FITS.parameter("k", unit=U.per_min), name="rate")

The uncertainty is a distrib Uncertainty on the SBML parameter: the confidence interval of the profile likelihood (the Fisher information when the fit has no profile), the standard error of the Fisher information, the distribution the draws of the parameter come from and the provenance in its notes, see ParameterUncertainty. The distributions are read back from the SBML by sbmlsim.simulation.sampling.parameter_distributions.

The records of one fit which its report is built from are sbmlsim.fit.cli.FitRecords (load_fit_records); an AdoptedRecord is the fitted parameters of an adopted fit with their uncertainty.

UncertaintyMethod ¶

Bases: StrEnum

Where the uncertainty of a fitted parameter comes from.

ParameterUncertainty `dataclass` ¶

ParameterUncertainty(
    *,
    pid,
    value,
    unit,
    lower_bound,
    upper_bound,
    scale,
    alpha,
    z,
    method,
    ci_lower,
    ci_upper,
    identifiability=None,
    standard_error=None,
    fisher_ci=None,
    fit_id,
    cost,
    n_data=None,
    record,
)

The fitted value of a parameter and its uncertainty, from the record of a fit.

All numbers are in the unit of the model (unit); the scale is the space the fit searched the parameter in.

Attributes:

Name	Type	Description
`pid`	`str`	the id of the parameter in the flat model.
`value`	`float`	the fitted value.
`unit`	`str \| None`	the unit of the model, as the fit wrote it.
`lower_bound`	`float`	the lower bound of the fit.
`upper_bound`	`float`	the upper bound of the fit.
`scale`	`ParameterScaleType`	the space the fit searched the parameter in.
`alpha`	`float`	the confidence level of the intervals.
`z`	`float`	the quantile of the standard normal of the confidence level of the profile, `sqrt(chi2(alpha, df))`.
`method`	`UncertaintyMethod`	where the confidence interval and the distribution come from.
`ci_lower`	`float \| None`	the lower end of the confidence interval, `None` if it is open (the profile reaches the bound).
`ci_upper`	`float \| None`	the upper end of the confidence interval, `None` if open.
`identifiability`	`str \| None`	the class of the profile likelihood, `None` without.
`standard_error`	`float \| None`	the standard error of the Fisher information in the space of the fit (`scale`), `None` without.
`fisher_ci`	`tuple[float, float] \| None`	the confidence interval of the Fisher information.
`fit_id`	`str`	the id of the fit.
`cost`	`float`	the cost of the fit.
`n_data`	`int \| None`	the number of data points of the fit, `None` if unknown.
`record`	`str`	the path of the record, relative to the folder of the fits.

sigma ¶

sigma()

Get the standard deviation of the distribution in the space of the fit.

From the profile it is the mean of the closed half widths of the confidence interval divided by z; from the Fisher information its standard error. None if neither side of the profile is closed.

interval ¶

interval()

Get the confidence interval, an open side at the bound of the fit.

standard_error_model ¶

standard_error_model()

Get the standard error in the unit of the model (delta method).

distribution ¶

distribution()

Get the distribution of the draws as a formula of distrib.

Returns:

Type	Description
`str`	On a logarithmic scale `lognormal(ln(value), sigma, lb, ub)` with
`str`	sigma in natural logarithms, on the linear scale `normal(value,
`str`	sigma, lb, ub)`, both truncated to the bounds of the fit; without a
`str`	closed side of the profile `uniform(lb, ub)`.

notes ¶

notes()

Get the provenance of the value and of its uncertainty as markdown.

uncertainty ¶

uncertainty(unit=None)

Get the distrib uncertainty of the parameter.

Parameters:

Name	Type	Description	Default
`unit`	`UnitType`	the unit of the values, the unit of the parameter in the model definition (`sbmlutils.factory` unit).	`None`

Returns:

Type	Description
`Uncertainty`	The uncertainty: the confidence interval, the standard error of
`Uncertainty`	the Fisher information if there is one and the distribution of the
`Uncertainty`	draws, the provenance in its notes.

AdoptedRecord `dataclass` ¶

AdoptedRecord(directory, parameters)

The record of an adopted fit: the fitted parameters with their uncertainty.

Attributes:

Name	Type	Description
`directory`	`Path`	the directory of the record, named by the id of the fit.
`parameters`	`Mapping[str, ParameterUncertainty]`	the uncertainty of every fitted parameter by pid.

fit_id `property` ¶

fit_id

The id of the fit.

load `classmethod` ¶

load(directory)

Read the record of an adopted fit.

The value of a parameter is the best parameter set of the fit (parameters.json), the bounds and the scale are those of the problem (optimization_result.json); the confidence interval is the one of the profile likelihood (identifiability.json), the Fisher information (fisher.json) gives the standard error and is the fallback for a parameter without a profile.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	the directory of the record.	required

Returns:

Type	Description
`AdoptedRecord`	The record.

Raises:

Type	Description
`FileNotFoundError`	if the record lacks a required file or has neither a profile nor a Fisher information.
`ValueError`	if a fitted parameter has neither a profile nor a Fisher information.

AdoptedRecords ¶

AdoptedRecords(directory, fit_ids)

The adopted fits of a project: the fitted values and their uncertainty.

A model file of the factory takes the value of a fitted parameter from the record of its fit, so the value, its uncertainty and its provenance come from one place, see sbmlsim.project.Project.fit_records:

# not executed
FITS = PROJECT.fit_records()
Parameter("HCTZEX_f", **FITS.parameter("KI__HCTZEX_f", unit=U.dimensionless))

Read the records of the adopted fits.

Parameters:

Name	Type	Description	Default
`directory`	`Path`	the folder of the adopted fits.	required
`fit_ids`	`Sequence[str]`	the ids of the adopted fits.	required

Raises:

Type	Description
`FileNotFoundError`	if a record does not exist.
`ValueError`	if a parameter is in two fits.

parameter ¶

parameter(pid, unit=None)

Get the keyword arguments of a sbmlutils.factory.Parameter of a fitted parameter.

Parameters:

Name	Type	Description	Default
`pid`	`str`	the id of the parameter in the flat model, as the fit names it.	required
`unit`	`UnitType`	the unit of the parameter in the model definition, set on the parameter and its uncertainty.	`None`

Returns:

Type	Description
`dict[str, Any]`	`value` and `uncertainties`, and `unit` if given.

Raises:

Type	Description
`KeyError`	if no adopted fit has the parameter.

adopt_fit ¶

adopt_fit(fit_dir, fits_dir, *, force=False, fit_id=None)

Copy the record of a finished fit into the folder of the fits of a model.

The record is the part of the results of a fit which the model needs: the parameters, the settings and the problem (optimization_result.json), the profile likelihood and the Fisher information with their tables, the metrics, the text report and the methods report as PDF and Typst source with its references (RECORD_FILES) and the figures the Typst source shows, in plots/, so that report.typ compiles in the record. The report is optional, a record of an older fit without it is adopted as well. The runs, the other figures, the LaTeX sources with the PNG copies of their figures and the HTML report stay in the results of the fit.

The record is copied into a directory of a unique name next to its place, created with the permissions of the umask, and renamed into it, so a reader sees no record or a complete one; a record it replaces is moved aside first and restored if the rename fails.

Parameters:

Name	Type	Description	Default
`fit_dir`	`Path`	the directory of the results of the fit, named by its id.	required
`fits_dir`	`Path`	the folder of the adopted fits of the model.	required
`force`	`bool`	replace a record of the same id.	`False`
`fit_id`	`str \| None`	the id of the fit, the name of `fit_dir` without.	`None`

Returns:

Type	Description
`Path`	The directory of the record.

Raises:

Type	Description
`FileNotFoundError`	if the fit does not exist, lacks a required file or has neither a profile likelihood nor a Fisher information.
`FileExistsError`	if the record exists and `force` is not set.

convert_value ¶

convert_value(value, unit, target)

Convert a number from one unit into another, both units of pint.

Parameters:

Name	Type	Description	Default
`value`	`float`	the number in `unit`.	required
`unit`	`str \| None`	the unit of the number, `None` for the unit of the target.	required
`target`	`str \| None`	the unit to convert into, `None` for the unit of the number.	required

Returns:

Type	Description
`float`	The number in `target`, the number itself if a unit is missing or
`float`	both are the same.

fit.records¶

UncertaintyMethod ¶

ParameterUncertainty dataclass ¶

sigma ¶

interval ¶

standard_error_model ¶

distribution ¶

notes ¶

uncertainty ¶

AdoptedRecord dataclass ¶

fit_id property ¶

load classmethod ¶

AdoptedRecords ¶

parameter ¶

adopt_fit ¶

convert_value ¶

ParameterUncertainty `dataclass` ¶

AdoptedRecord `dataclass` ¶

fit_id `property` ¶

load `classmethod` ¶