Reference

A lightweight, serialisable version of a Metrics instance.

This dataclass is designed to capture and store the purely numeric, non-NaN scalar values from a live Metrics object, making it suitable for JSON serialization, saving to disk, or comparing historical simulation runs.

Attributes:

Name	Type	Description
label	str	A human-readable identifier or name for this specific snapshot.
values	dict	A dictionary containing the numeric scalar metrics extracted from a Metrics instance, where keys are metric names and values are floats.

Source code in src/stroke_ward_model/metrics.py

@dataclass
class MetricsSnapshot:
    """
    A lightweight, serialisable version of a Metrics instance.

    This dataclass is designed to capture and store the purely numeric, non-NaN
    scalar values from a live `Metrics` object, making it suitable for JSON
    serialization, saving to disk, or comparing historical simulation runs.

    Attributes
    ----------
    label : str
        A human-readable identifier or name for this specific snapshot.
    values : dict
        A dictionary containing the numeric scalar metrics extracted from a
        `Metrics` instance, where keys are metric names and values are floats.
    """

    label: str
    values: dict  # the numeric scalars from Metrics.diff / vars()

    def diff(self, other: "Metrics | MetricsSnapshot") -> dict:
        """
        Computes the numerical difference between the metric values of this
        snapshot and another `Metrics` or `MetricsSnapshot` instance.

        Parameters
        ----------
        other : Metrics or MetricsSnapshot
            The target object to compare against. Must contain compatible
            numeric attributes or a `values` dictionary.

        Returns
        -------
        dict
            A dictionary where each key is a metric name, mapping to a nested
            dictionary containing 'self' (current snapshot value), 'other'
            (comparison value), and 'difference' (self - other).

        Raises
        ------
        TypeError
            If the provided `other` argument is not an instance of `Metrics`
            or `MetricsSnapshot`.
        """
        if hasattr(other, "values"):  # MetricsSnapshot
            other_values = other.values
        elif hasattr(other, "__dict__"):  # Metrics
            other_values = {
                attr: float(getattr(other, attr))
                for attr in vars(other)
                if isinstance(
                    getattr(other, attr), (int, float, np.integer, np.floating)
                )
                and not np.isnan(getattr(other, attr))
            }
        else:
            raise TypeError(f"Cannot diff against {type(other)}")

        results = {}
        for key, self_val in self.values.items():
            other_val = other_values.get(key)
            if other_val is None:
                continue
            results[key] = {
                "self": self_val,
                "other": other_val,
                "difference": self_val - other_val,
            }
        return results

    def to_dict(self) -> dict:
        """
        Serializes the snapshot instance into a standard Python dictionary.

        Returns
        -------
        dict
            A dictionary representation of the snapshot, containing the 'label'
            and 'values' keys.
        """
        return {"label": self.label, "values": self.values}

    @classmethod
    def from_dict(cls, data: dict) -> "MetricsSnapshot":
        """
        Constructs a `MetricsSnapshot` instance from a dictionary representation.

        Parameters
        ----------
        data : dict
            A dictionary containing at least the keys 'label' (str) and
            'values' (dict).

        Returns
        -------
        MetricsSnapshot
            A newly initialized snapshot instance populated with the provided data.
        """
        return cls(label=data["label"], values=data["values"])

    @classmethod
    def from_metrics(cls, metrics: "Metrics", label: str) -> "MetricsSnapshot":
        """
        Builds a lightweight snapshot from a live `Metrics` instance.

        Iterates through the attributes of a `Metrics` object, extracting only
        the valid (non-NaN) integer and floating-point values, casting them to
        standard Python floats to ensure JSON compatibility.

        Parameters
        ----------
        metrics : Metrics
            The live `Metrics` object to be serialized.
        label : str
            A string identifier to assign to the newly created snapshot.

        Returns
        -------
        MetricsSnapshot
            A snapshot instance containing the extracted numeric values.
        """
        values = {}
        for attr in vars(metrics):
            val = getattr(metrics, attr)
            if not isinstance(val, (int, float, np.integer, np.floating)):
                continue
            if np.isnan(val):
                continue
            values[attr] = float(val)  # ensure plain Python float for JSON
        return cls(label=label, values=values)

diff(other)

Computes the numerical difference between the metric values of this snapshot and another Metrics or MetricsSnapshot instance.

Parameters:

Name	Type	Description	Default
other	Metrics or MetricsSnapshot	The target object to compare against. Must contain compatible numeric attributes or a values dictionary.	required

Returns:

Type	Description
dict	A dictionary where each key is a metric name, mapping to a nested dictionary containing 'self' (current snapshot value), 'other' (comparison value), and 'difference' (self - other).

Raises:

Type	Description
TypeError	If the provided other argument is not an instance of Metrics or MetricsSnapshot.

Source code in src/stroke_ward_model/metrics.py

def diff(self, other: "Metrics | MetricsSnapshot") -> dict:
    """
    Computes the numerical difference between the metric values of this
    snapshot and another `Metrics` or `MetricsSnapshot` instance.

    Parameters
    ----------
    other : Metrics or MetricsSnapshot
        The target object to compare against. Must contain compatible
        numeric attributes or a `values` dictionary.

    Returns
    -------
    dict
        A dictionary where each key is a metric name, mapping to a nested
        dictionary containing 'self' (current snapshot value), 'other'
        (comparison value), and 'difference' (self - other).

    Raises
    ------
    TypeError
        If the provided `other` argument is not an instance of `Metrics`
        or `MetricsSnapshot`.
    """
    if hasattr(other, "values"):  # MetricsSnapshot
        other_values = other.values
    elif hasattr(other, "__dict__"):  # Metrics
        other_values = {
            attr: float(getattr(other, attr))
            for attr in vars(other)
            if isinstance(
                getattr(other, attr), (int, float, np.integer, np.floating)
            )
            and not np.isnan(getattr(other, attr))
        }
    else:
        raise TypeError(f"Cannot diff against {type(other)}")

    results = {}
    for key, self_val in self.values.items():
        other_val = other_values.get(key)
        if other_val is None:
            continue
        results[key] = {
            "self": self_val,
            "other": other_val,
            "difference": self_val - other_val,
        }
    return results

from_dict(data) classmethod

Constructs a MetricsSnapshot instance from a dictionary representation.

Parameters:

Name	Type	Description	Default
data	dict	A dictionary containing at least the keys 'label' (str) and 'values' (dict).	required

Returns:

Type	Description
MetricsSnapshot	A newly initialized snapshot instance populated with the provided data.

Source code in src/stroke_ward_model/metrics.py

@classmethod
def from_dict(cls, data: dict) -> "MetricsSnapshot":
    """
    Constructs a `MetricsSnapshot` instance from a dictionary representation.

    Parameters
    ----------
    data : dict
        A dictionary containing at least the keys 'label' (str) and
        'values' (dict).

    Returns
    -------
    MetricsSnapshot
        A newly initialized snapshot instance populated with the provided data.
    """
    return cls(label=data["label"], values=data["values"])

from_metrics(metrics, label) classmethod

Builds a lightweight snapshot from a live Metrics instance.

Iterates through the attributes of a Metrics object, extracting only the valid (non-NaN) integer and floating-point values, casting them to standard Python floats to ensure JSON compatibility.

Parameters:

Name	Type	Description	Default
metrics	Metrics	The live Metrics object to be serialized.	required
label	str	A string identifier to assign to the newly created snapshot.	required

Returns:

Type	Description
MetricsSnapshot	A snapshot instance containing the extracted numeric values.

Source code in src/stroke_ward_model/metrics.py

@classmethod
def from_metrics(cls, metrics: "Metrics", label: str) -> "MetricsSnapshot":
    """
    Builds a lightweight snapshot from a live `Metrics` instance.

    Iterates through the attributes of a `Metrics` object, extracting only
    the valid (non-NaN) integer and floating-point values, casting them to
    standard Python floats to ensure JSON compatibility.

    Parameters
    ----------
    metrics : Metrics
        The live `Metrics` object to be serialized.
    label : str
        A string identifier to assign to the newly created snapshot.

    Returns
    -------
    MetricsSnapshot
        A snapshot instance containing the extracted numeric values.
    """
    values = {}
    for attr in vars(metrics):
        val = getattr(metrics, attr)
        if not isinstance(val, (int, float, np.integer, np.floating)):
            continue
        if np.isnan(val):
            continue
        values[attr] = float(val)  # ensure plain Python float for JSON
    return cls(label=label, values=values)

to_dict()

Serializes the snapshot instance into a standard Python dictionary.

Returns:

Type	Description
dict	A dictionary representation of the snapshot, containing the 'label' and 'values' keys.

Source code in src/stroke_ward_model/metrics.py

def to_dict(self) -> dict:
    """
    Serializes the snapshot instance into a standard Python dictionary.

    Returns
    -------
    dict
        A dictionary representation of the snapshot, containing the 'label'
        and 'values' keys.
    """
    return {"label": self.label, "values": self.values}