Calibration

Model Versioning

Contains MLflow compatible models for versioning and deployment.

This module defines MLflow compatible models for versioning and deployment as microservices.

class deeprootgen.calibration.model_versioning.AbcModel

An Approximate Bayesian Computation calibration model.

load_context(context: Context) → None

Load the model context.

Args:

context (Context):

The model context.

predict(context: Context, model_input: DataFrame, params: dict | None = None) → DataFrame

Make a model prediction.

Args:

context (Context):

The model context.

model_input (pd.DataFrame):

The model input data.

params (dict, optional):

Optional model parameters. Defaults to None.

Raises:

ValueError:

Error raised when the calibrator has not been loaded.

Returns:

pd.DataFrame:

The model prediction.

class deeprootgen.calibration.model_versioning.GraphFlowFeatureExtractor(theta_dim: int, organ_keys: list[str], hidden_features: tuple[float], transforms: tuple[float], organ_features: list[str])

A graph feature extractor for density estimation.

encode(x: Tensor) → Tensor

Construct graph embeddings from nodes and edges.

Args:

x (torch.Tensor):

The node features.

Returns:

torch.Tensor:

The graph embeddings.

flow(x: tuple[Tensor]) → Distribution

Evaluate the normalising flow.

Args:

x (torch.Tensor):

The node and edge data.

Returns:

dist.Distribution:

The normalising flow.

forward(theta: Tensor, x: Tensor) → Tensor

The forward pass.

Args:

theta (torch.Tensor):

The batch of parameter vectors.

x (torch.Tensor):

The batch tensor data.

Returns:

torch.Tensor:

The normalising flow.

class deeprootgen.calibration.model_versioning.OptimisationModel

An optimisation calibration model.

load_context(context: Context) → None

Load the model context.

Args:

context (Context):

The model context.

predict(context: Context, model_input: DataFrame, params: dict | None = None) → DataFrame

Make a model prediction.

Args:

context (Context):

The model context.

model_input (pd.DataFrame):

The model input data.

params (dict, optional):

Optional model parameters. Defaults to None.

Raises:

ValueError:

Error raised when the calibrator has not been loaded.

Returns:

pd.DataFrame:

The model prediction.

class deeprootgen.calibration.model_versioning.SensitivityAnalysisModel

A sensitivity analysis calibration model.

load_context(context: Context) → None

Load the model context.

Args:

context (Context):

The model context.

predict(context: Context, model_input: DataFrame, params: dict | None = None) → DataFrame

Make a model prediction.

Args:

context (Context):

The model context.

model_input (pd.DataFrame):

The model input data.

params (dict, optional):

Optional model parameters. Defaults to None.

Raises:

ValueError:

Error raised when the calibrator has not been loaded.

Returns:

pd.DataFrame:

The model prediction.

class deeprootgen.calibration.model_versioning.SnpeModel

A Sequential neural posterior estimation calibration model.

load_context(context: Context) → None

Load the model context.

Args:

context (Context):

The model context.

predict(context: Context, model_input: DataFrame, params: dict | None = None) → DataFrame

Make a model prediction.

Args:

context (Context):

The model context.

model_input (pd.DataFrame):

The model input data.

params (dict, optional):

Optional model parameters. Defaults to None.

Raises:

ValueError:

Error raised when the calibrator has not been loaded.

Returns:

pd.DataFrame:

The model prediction.

class deeprootgen.calibration.model_versioning.SurrogateModel

A surrogate calibration model.

load_context(context: Context) → None

Load the model context.

Args:

context (Context):

The model context.

predict(context: Context, model_input: DataFrame, params: dict | None = None) → DataFrame

Make a model prediction.

Args:

context (Context):

The model context.

model_input (pd.DataFrame):

The model input data.

params (dict, optional):

Optional model parameters. Defaults to None.

Raises:

ValueError:

Error raised when the calibrator has not been loaded.

Returns:

pd.DataFrame:

The model prediction.

deeprootgen.calibration.model_versioning.log_model(task: str, input_parameters: RootCalibrationModel, calibration_model: PythonModel, artifacts: dict, simulation_uuid: str, signature_x: DataFrame | ndarray | list | None = None, signature_y: DataFrame | ndarray | list | None = None, model_config: dict | None = None) → None

Log the calibrator model to the registry.

Args:

task (str):

The name of the current task for the experiment.

input_parameters (RootCalibrationModel):

The root calibration data model.

calibration_model (mlflow.pyfunc.PythonModel):

The calibrator to log.

artifacts (dict):

Experiment artifacts to log.

simulation_uuid (str):

The simulation uuid.

signature_x (pd.DataFrame | np.ndarray | list | None, optional):

The signature for data inputs. Defaults to None.

signature_y (pd.DataFrame | np.ndarray | list | None, optional):

The signature for data outputs. Defaults to None.

model_config (dict, optional):

The model configuration. Defaults to None.

Parameters

Contains utilities for working with simulation parameters and their distributions.

This module defines various utlities for working with distributions of simulation parameters.

class deeprootgen.calibration.parameters.PriorCollection(priors: list[Distribution])

A wrapper around a collection of priors.

sample(batch_shape: tuple = ()) → Tensor

Sample from the priors.

Args:

batch_shape (tuple, optional):

The batch shape of the sampled priors. Defaults to ().

Returns:

torch.Tensor:

The sampled priors.

deeprootgen.calibration.parameters.get_simulation_parameters(parameter_form_name: str = 'calibration_form') → list[dict]

Get a list of available simulation parameters and labels.

Args:

parameter_form_name (str, optional):

The name of the parameter form components specification. Defaults to “simulation_form”.

Returns:

list[dict]:

A list of available simulation parameters and labels.

deeprootgen.calibration.parameters.lhc_sample(input_parameters: RootCalibrationModel) → DataFrame

Sample from the parameter space.

Args:

input_parameters (RootCalibrationModel):

The root calibration data model.

Returns:

pd.DataFrame:

The sample dataframe.

Summary Statistics

Contains utilities for calibrating models from summary statistics.

This module defines utility functions for calibrating simulation models from summary statistics.

deeprootgen.calibration.summary_statistics.calculate_summary_statistic_discrepancy(parameter_specs: dict, input_parameters: RootCalibrationModel, statistics_list: list[SummaryStatisticsModel], distances: list[DistanceMetricBase]) → float

Calculate the discrepancy between simulated and observed data.

Args:

parameter_specs (dict):

The simulation parameter specification.

input_parameters (RootCalibrationModel):

The root calibration data model.

statistics_list (list[SummaryStatisticsModel]):

The list of summary statistics.

distances (list[DistanceMetricBase]):

The distance metric object.

Returns:

float:

The discrepancy between simulated and observed data.

deeprootgen.calibration.summary_statistics.calculate_summary_statistics(parameter_specs: dict, input_parameters: RootCalibrationModel, statistics_list: list[SummaryStatisticsModel]) → tuple

Calculate summary statistics for observed and simulated data.

Args:

parameter_specs (dict):

The simulation parameter specification.

input_parameters (RootCalibrationModel):

The root calibration data model.

statistics_list (list[SummaryStatisticsModel]):

The list of summary statistics.

Returns:

tuple:

The simulated and observed data.

deeprootgen.calibration.summary_statistics.get_calibration_summary_stats(input_parameters: RootCalibrationModel) → tuple

Extract summary statistics needed for model calibration.

Args:

input_parameters (RootCalibrationModel):

The root calibration data model.

Raises:

ValueError:

Error thrown when the summary statistic list is empty.

Returns:

tuple:

The calibration distance metric and summary statistics.

deeprootgen.calibration.summary_statistics.run_calibration_simulation(parameter_specs: dict, input_parameters: RootCalibrationModel) → tuple

Run a simulation for model calibration purposes.

Args:

parameter_specs (dict):

The simulation parameter specification.

input_parameters (RootCalibrationModel):

The root calibration data model.

Returns:

tuple:

The simulation and its parameters.

Surrogates

Contains methods for implementing surrogate models for the root generator.

This module defines various utlities and methods for working with surrogate models.

class deeprootgen.calibration.surrogates.EarlyStopper(patience: int = 1, min_delta: float = 0)

Early stopping for training.

class deeprootgen.calibration.surrogates.SingleTaskVariationalGPModel(inducing_points: Tensor)

A variational Gaussian process for single task regression.

forward(x: Tensor) → MultivariateNormal

The forward pass.

Args:

x (torch.Tensor):

The input data.

Returns:

gpytorch.distributions.MultivariateNormal:

A multivariate Gaussian distribution.

deeprootgen.calibration.surrogates.prepare_surrogate_data(sample_df: DataFrame, output_names: list[str] | None = None, batch_size: int = 1024) → tuple

Prepare data for training the surrogate model.

Args:

sample_df (pd.DataFrame):

The dataframe of sample simulation data.

output_names (list[str], optional):

The list of output names. Defaults to None.

batch_size (int, optional):

The tensor data batch size. Defaults to 1024.

Returns:

tuple:

The processed data for the surrogate.