AbstractMetric

Abstract super‑type for all metric descriptors used by DigiPopData.

Purpose

Group together heterogeneous metrics (Mean, MeanSD, Category, …) so they can share the same dispatch points (mismatch, mismatch_expression, get_loss, ...).

Required interface

• mismatch: Function to calculate the loss for a given metric and simulated data as a value.
• mismatch_expression: Function to calculate the loss for a given metric and simulated data as an expression.
• validate: Function to validate the simulated data against the metric.

The parsing rules for the metric type are defined in the PARSERS dictionary to convert from DataFrame row to specific Metric struture. It is used in the parse_metric_bindings method.

PARSERS["<metric_type>"] = (row) -> begin
    # parsing logic
end

CategoryMetric <: AbstractMetric

CategoryMetric is a metric descriptor for categorical data. It is based on polinomial distribution within the groups.

Fields

• size::Int: The size of the dataset.
• groups::Vector{String}: The names of the groups.
• rates::Vector{Float64}: The probabilities of each group.
• cov_inv::Matrix{Float64}: The inverse of the covariance matrix of the groups.
• group_active::Vector{Bool}: A boolean vector indicating which groups are active (non-zero rates).

Constructor

• CategoryMetric(size::Int, groups::Vector{String}, rates::Vector{Float64}): Creates a new instance of CategoryMetric. It validates the input data and calculates the inverse covariance matrix.

MeanMetric <: AbstractMetric

A metric that compares the mean of a simulated dataset to a target mean.

Fields

• size::Int: The size of the dataset.
• mean::Float64: The target mean value.
• sd::Float64: The target standard deviation value.

MeanSDMetric <: AbstractMetric

A metric that compares the mean and standard deviation (SD) of a simulated dataset to a target mean and SD.

Fields

• size::Int: The size of the dataset.
• mean::Float64: The target mean value.
• sd::Float64: The target standard deviation value.

MetricBinding is container that binds a scenario, an endpoint and a concrete AbstractMetric description into a single unit that can be logged, displayed or passed to optimisation / validation routines.

Fields

QuantileMetric <: AbstractMetric

QuantileMetric is a metric descriptor for quantile data. It is based on the quantiles of the data and their corresponding values.

Fields

• size::Int: The size of the dataset.
• levels::Vector{Float64}: The quantile levels (e.g. 0.25, 0.5, 0.75).
• values::Vector{Float64}: The corresponding values for the quantile levels.
• skip_nan::Bool: If true, NaN values are allowed in simulated data and will be ignored. Iffalse`, NaN values are not allowed.
• cov_inv::Matrix{Float64}: The inverse of the covariance matrix of the groups.
• group_active::Vector{Bool}: A boolean vector indicating which groups are active (non-zero rates).
• rates::Vector{Float64}: The probabilities of each group.

Constructor

• QuantileMetric(size::Int, levels::Vector{Float64}, values::Vector{Float64}; skip_nan::Bool = false): Creates a new instance of QuantileMetric. It validates the input data and calculates the inverse covariance matrix.

" SurvivalMetric <: AbstractMetric

Fields

• size::Int: The size of the dataset.
• levels::Vector{Float64}: The survival levels (e.g. 0.9, 0.8, 0.7).
• values::Vector{Float64}: The corresponding values for the survival levels.
• cov_inv::Matrix{Float64}: The inverse of the covariance matrix of the groups.
• group_active::Vector{Bool}: A boolean vector indicating which groups are active (non-zero rates).
• rates::Vector{Float64}: The probabilities of each group.

Constructor

• SurvivalMetric(size::Int, levels::Vector{Float64}, values::Vector{Float64}): Creates a new instance of SurvivalMetric. It validates the input data and calculates the inverse covariance matrix.

get_loss(simulated::DataFrame, metric_bindings::Vector{MetricBinding}) -> Float64

Calculate the loss for a given set of metric bindings and a simulated DataFrame. The function iterates over the metric bindings, selecting the relevant data from the simulated DataFrame based on the scenario and endpoint specified in each binding. It then computes the loss using the mismatch function defined in the metric.

Arguments

• simulated::DataFrame: A DataFrame containing the simulated data.
• metric_bindings::Vector{MetricBinding}: A vector of MetricBinding objects, each containing a scenario,

endpoint, and metric.

mismatch(sim::AbstractVector{<:Real}, metric::AbstractMetric) -> Float64

Arguments

• sim::AbstractVector{<:Real}: A vector of simulated data.
• metric::AbstractMetric: An instance of a metric descriptor (e.g., MeanMetric, CategoryMetric, etc.).

Return a loss that quantifies the mismatch between simulated data sim and the target metric metric. The concrete formula depends on the subtype of AbstractMetric.

mismatch_expression(sim::AbstractVector{<:Real}, metric::AbstractMetric, X::Vector{VariableRef}, X_len::Int) -> QuadExpr

Arguments

• sim::AbstractVector{<:Real}: A vector of simulated data.
• metric::AbstractMetric: An instance of a metric descriptor (e.g., MeanMetric, CategoryMetric, etc.).
• X::Vector{VariableRef}: A vector of JuMP variable references.
• X_len::Int: The length of the vector of JuMP variable references.

Return an expression that quantifies the mismatch between simulated data sim and the target metric metric. The concrete formula depends on the subtype of AbstractMetric.

parse_metric_bindings(df::DataFrame) -> Vector{MetricBinding}

Parse a DataFrame with metric‑binding definitions and return a vector of MetricBinding objects.

The DataFrame should contain the following columns:

• id: Unique identifier for the metric binding.
• scenario: The scenario to which the metric binding applies.
• endpoint: The observable (endpoint) associated with the metric binding.
• active: (optional) A boolean indicating whether the metric binding is active (default is true).
• metric.type: The type of metric (e.g., "mean", "category", etc.).
• metric.<parameter>: Additional parameters for the metric, depending on its type.

The function uses the PARSERS dictionary to find the appropriate parser for the metric type. The function iterates over each row of the DataFrame, extracting the relevant information and creating a MetricBinding object.

validate(sim::AbstractVector{<:Real}, metric::AbstractMetric)

Arguments

• sim::AbstractVector{<:Real}: A vector of simulated data.
• metric::AbstractMetric: An instance of a metric descriptor (e.g., MeanMetric, CategoryMetric, etc.).

Validate the simulated data sim against the target metric metric. It throws an error if the validation fails. The concrete validation rules depend on the subtype of AbstractMetric.