Observation data & utilities

Building observation data

ObsDataCreator is the builder for the observation-data structure (the in-memory equivalent of an obs_data.json file) consumed by CVS0DParamID.set_ground_truth_data and SensitivityAnalysis.set_ground_truth_data.

utilities.obs_data_helpers.ObsDataCreator

ObsDataCreator()

Builder for the observation-data structure used by calibration and SA.

Produces the same structure as an obs_data.json file, in memory. Add the protocol info first, then one data item per observable, then retrieve the dict with get_obs_data_dict (or write it to disk with dump_to_path)::

obs = ObsDataCreator()
obs.add_protocol_info(pre_times, sim_times, params_to_change)
obs.add_data_item(entry)
obs_data_dict = obs.get_obs_data_dict()

The result is consumed by CVS0DParamID.set_ground_truth_data and SensitivityAnalysis.set_ground_truth_data.

add_protocol_info

add_protocol_info(
    pre_times,
    sim_times,
    params_to_change,
    experiment_labels=None,
    offline_pre_time=None,
)

Add protocol information to the dictionary. pre_times: list of pre-simulation times for each experiment sim_times: 2D list of lists of simulation times for each experiment and subexperiment params_to_change: dictionary with parameter names as keys and list of lists of values Each parameter should have a value entry the same shape as sim_times. experiment_labels: list of labels for each experiment offline_pre_time: optional scalar; unlogged warmup before experiments (see parameter-identification docs)

add_prediction_item

add_prediction_item(variable, unit, experiment_idx)

Add a prediction item to the dictionary. variable: name of the variable to predict unit: unit of the variable experiment_idx: index of the experiment this prediction item belongs to

add_data_item

add_data_item(entry)

Add a data item to the dictionary. entry: dictionary containing the data item

get_obs_data_dict

get_obs_data_dict()

Returns the observation data dictionary.

dump_to_path

dump_to_path(output_path)

Dumps the observation data dictionary to a JSON file.

load_from_json_file

load_from_json_file(input_path)

Loads the observation data dictionary from a JSON file. input_path: path to the JSON file

Configuration and helper functions

utilities.utility_funcs.get_default_inp_data_dict

get_default_inp_data_dict(
    file_prefix, input_param_file, resources_dir
)

Build the default configuration dict (equivalent to user_inputs.yaml).

This is the starting point for driving the pipeline from Python: it returns a config dict pre-populated with the defaults, which you then mutate in code (e.g. inp["sim_time"] = 2) before passing to the generate/simulate/ calibrate stages.

Parameters:

Name	Description	Default
`file_prefix`	Model name prefix; ties together the `{prefix}_*` resource files in `resources_dir`.	required
`input_param_file`	Name of the parameters CSV file.	required
`resources_dir`	Directory holding the input resources.	required

Returns:

Name	Type	Description
`dict`		The configuration dict with default values filled in.

utilities.utility_funcs.change_parameter_values_and_save

change_parameter_values_and_save(
    cellml_file,
    parameter_names,
    parameter_values,
    output_file,
)

Load a CellML model, change initial values of specified variables, then serialize and save the updated model.

Parameters:

Name	Description	Default
`cellml_file`	Path to the .cellml file to modify.	required
`parameter_names`	List of variable names to change.	required
`parameter_values`	Corresponding list of new initial values.	required
`output_file`	Optional; where to write the new model. Overwrites original if None.	required

utilities.utility_funcs.calculate_hessian

calculate_hessian(
    param_id, AD=False, method="parabola_fit"
)

Calculate the Hessian matrix of the cost function at the best parameter values.

Parameters:

Name	Description	Default
`param_id`	An instance of the parameter identification class with a get_cost_from_params method and best_param_vals attribute.	required
`AD`	If True, use automatic differentiation to compute the Hessian.	`False`
`method`	The method to use for computing the Hessian if AD is False. Options are "numdofftools", "parabola_fit", or "finite_difference".	`'parabola_fit'`

Returns:

Type	Description
	Hessian matrix as a 2D numpy array.

utilities.utility_funcs.latin_hypercube_sample_and_evaluate

latin_hypercube_sample_and_evaluate(
    fun,
    center,
    radius,
    n_samples,
    param_norm_obj=None,
    half_width=None,
)

Generate Latin Hypercube samples around a center point, run the function, and return samples and results. The range for each parameter is set as: scan_min = center[i] - radius * center[i] scan_max = center[i] + radius * center[i] unless half_width is given, in which case an absolute per-parameter half-width is used: scan_min = center[i] - half_width[i] scan_max = center[i] + half_width[i] (used to sample a fixed fraction of each parameter's range rather than of its value, so a wide magnitude range does not make the box collapse for the large-magnitude parameters). Args: fun: Callable that takes a parameter vector and returns a scalar result. center (np.ndarray): Center point for sampling. radius (float): Fractional range for each parameter (param_range_factor). n_samples (int): Number of samples. param_norm_obj (optional): If provided, used to clip samples to parameter bounds. half_width (optional): Absolute per-parameter half-width; overrides radius. Returns: samples (np.ndarray), results (np.ndarray)

utilities.utility_funcs.Normalise_class

Normalise_class(
    param_mins,
    param_maxs,
    mod_first_variables=0,
    modVal=1.0,
)