acteval 0.1.0__py3-none-any.whl

acteval/__init__.py

@@ -0,0 +1,10 @@
+from acteval.evaluate import (
+    Evaluator as Evaluator,
+)
+from acteval.evaluate import (
+    compare as compare,
+)
+from acteval.evaluate import (
+    compare_splits as compare_splits,
+)
+from acteval.population import Population as Population

acteval/config.toml

@@ -0,0 +1,24 @@
+[ngrams]
+min_count = 3
+
+[jobs.participations]
+lengths     = true
+rates       = true
+pair_rates  = true
+
+[jobs.transitions]
+"2-gram" = true
+"3-gram" = true
+"4-gram" = true
+
+[jobs.timing]
+start_times     = true
+durations       = true
+start_durations = true
+joint_durations = true
+
+[jobs.creativity]
+enabled = true
+
+[jobs.structural]
+enabled = true

acteval/creativity/__init__.py

@@ -0,0 +1,2 @@
+"""Creativity metrics — diversity, novelty, conservatism, and homogeneity of
+synthetic schedules relative to the observed population."""

acteval/creativity/features/creativity.py

@@ -0,0 +1,88 @@
+from pandas import DataFrame
+
+
+def hash_schedule(schedule: DataFrame) -> list[str]:
+    """Hash a schedule. We first create strings of combined activities and durations.
+
+    Args:
+        schedule (DataFrame): Input schedule.
+
+    Returns:
+        str: hashed schedule.
+    """
+    act_hash = schedule.act.astype(str) + schedule.duration.astype(str)
+    return "".join(act_hash)
+
+
+def hash_population(population: DataFrame) -> set[str]:
+    """Hash a population of sequences. We first create strings of combined activities and durations.
+    Then create a python set of these strings. This will remove duplicates.
+
+    Args:
+        population (DataFrame): Input population of sequences.
+
+    Returns:
+        set[str]: set of hashed sequences.
+    """
+    act_hash = population.act.astype(str) + population.duration.astype(str)
+    return set(act_hash.groupby(population.pid).apply("".join))
+
+
+def diversity(population: DataFrame, hashed: set[str]) -> float:
+    """Measure the internal diversity of a population of sequences. This is the ratio of unique
+    sequences to the total number of sequences.
+
+    Args:
+        population (DataFrame): Input population of sequences.
+        hashed (set[str]): Hashed population of sequences.
+
+    Returns:
+        float: Diversity of the population.
+    """
+    n = population.pid.nunique()
+    if n == 0:
+        return 0
+    unique = len(hashed)
+    return unique / n
+
+
+def homogeneity(population: DataFrame, hashed: set[str]) -> float:
+    """Measure the internal homogeneity of a population of sequences. This is 1-diversity.
+
+    Args:
+        population (DataFrame): Input population of sequences.
+        hashed (set[str]): Hashed population of sequences.
+
+    Returns:
+        float: Homogeneity of the synthetic sample.
+    """
+    return 1 - diversity(population, hashed)
+
+
+def novelty(observed_hashed: set[str], synthetic_hashed: set[str]) -> float:
+    """Measure the novelty of a population by comparing it to an observed population.
+
+    Args:
+        observed_hashed (set[str]): Hashed observed population.
+        synthetic_hashed (set[str]): Hashed synthetic population.
+
+    Returns:
+        float: Novelty of the synthetic population.
+    """
+    n = len(synthetic_hashed)
+    if n == 0:
+        return 0
+    return len(synthetic_hashed - observed_hashed) / n
+
+
+def conservatism(observed_hashed: set[str], synthetic_hashed: set[str]) -> float:
+    """Measure the conservatism of a population as 1-novelty.
+
+    Args:
+        observed_hashed (set[str]): Hashed observed population.
+        synthetic_hashed (set[str]): Hashed synthetic population.
+
+    Returns:
+        float: Conservatism of the synthetic population.
+    """
+    return 1 - novelty(observed_hashed, synthetic_hashed)

acteval/density/__init__.py

@@ -0,0 +1,2 @@
+"""Density estimation jobs — measures how well synthetic activity distributions
+(participation rates, timing, n-gram transitions) match the observed population."""

acteval/density/describe/frequency.py

@@ -0,0 +1,101 @@
+from datetime import datetime, timedelta
+from typing import Optional
+
+from matplotlib import pyplot as plt
+from matplotlib.patches import Patch
+from pandas import DataFrame
+
+from acteval.density.features.frequency import binned_activity_density
+
+
+def frequency_plots(observed: DataFrame, ys: Optional[dict[DataFrame]], **kwargs):
+    if ys is None:
+        ys = dict()
+    acts = list(observed.act.value_counts(ascending=False).index)
+    class_map = {n: i for i, n in enumerate(acts)}
+
+    n_plots = len(ys) + 2
+    ratios = [1 for _ in range(n_plots)]
+    ratios[-1] = 0.3
+
+    cmap = kwargs.pop("cmap", None)
+    if cmap is None:
+        cmap = plt.cm.Set3
+        colors = cmap.colors
+        factor = (len(acts) // len(colors)) + 1
+        cmap = dict(zip(acts, colors * factor))
+
+    fig, axs = plt.subplots(
+        sharex=True,
+        sharey=True,
+        nrows=1,
+        ncols=n_plots,
+        constrained_layout=True,
+        figsize=kwargs.pop("figsize", (15, 4)),
+        gridspec_kw={"width_ratios": ratios},
+    )
+
+    name = kwargs.pop("observed_title", "Observed")
+
+    plot_agg_acts(name, observed, class_map, ax=axs[0], legend=False, **kwargs)
+
+    # now deal with ys
+    for i, (name, y) in enumerate(ys.items()):
+        ax = axs[i + 1]
+        plot_agg_acts(name, y, class_map, ax=ax, legend=False, **kwargs)
+
+    # legend
+    elements = [Patch(facecolor=cmap[act], label=act.title()) for act in acts]
+    axs[-1].axis("off")
+    axs[-1].legend(handles=elements, loc="center left", frameon=False)
+
+    return fig
+
+
+def plot_agg_acts(
+    name: str,
+    population: DataFrame,
+    class_map: dict,
+    duration: int = 1440,
+    step: int = 10,
+    ax=None,
+    legend=True,
+    **kwargs,
+):
+    interval = kwargs.pop("interval", 240)
+    bins = binned_activity_density(
+        population, duration=duration, step=step, class_map=class_map
+    )
+    columns = list(class_map.keys())
+    totals = bins.sum(0)
+    sorted_cols = [x for _, x in sorted(zip(totals, columns))]
+    df = DataFrame(bins, columns=columns)[sorted_cols]
+    df.index = [
+        datetime(2021, 11, 1, 0) + timedelta(minutes=i * step)
+        for i in range(len(df.index))
+    ]
+    fig = df.plot(kind="bar", stacked=True, width=1, ax=ax, legend=legend, **kwargs)
+    if legend:
+        ax.legend(loc="upper right")
+    ax = fig.axes
+    labels = ["" for _ in range(len(df.index))]
+
+    labels[:: int(interval / step)] = [x.strftime("%H:%M") for x in df.index][
+        :: int(interval / step)
+    ]
+    ax.set_xticks(
+        [i / step for i in [0, 240, 480, 720, 960, 1200, 1440]],
+        labels=["00:00", "04:00", "08:00", "12:00", "16:00", "20:00", "24:00"],
+        rotation=90,
+        fontsize=8,
+    )
+
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    ax.spines["bottom"].set_visible(False)
+    ax.spines["left"].set_visible(False)
+
+    ax.set_xlabel("Time of day")
+    ax.set_ylabel("Activity Proportion")
+    ax.set_title(name)
+    return ax

acteval/density/describe/times.py

@@ -0,0 +1,269 @@
+from typing import Optional, Tuple
+
+from matplotlib import colormaps, patches
+from matplotlib import pyplot as plt
+from matplotlib.figure import Axes, Figure
+from pandas import DataFrame
+
+
+def times_distributions_plot(
+    observed: DataFrame, ys: Optional[dict[str, DataFrame]], **kwargs
+) -> Figure:
+    ratios = [1 for _ in range(4)]
+    ratios[0] = 0.2
+    fig, axs = plt.subplots(
+        4,
+        observed.act.nunique(),
+        figsize=kwargs.pop("figsize", (12, 5)),
+        sharex=True,
+        sharey=False,
+        # tight_layout=True,
+        constrained_layout=True,
+        gridspec_kw={"height_ratios": ratios},
+    )
+    acts = list(observed.act.value_counts(ascending=False).index)
+    name = kwargs.pop("observed_title", "Observed")
+    _times_plot(name, observed, acts, axs=axs)
+    if ys is None:
+        return fig
+    for name, y in ys.items():
+        _times_plot(name, y, acts, axs=axs)
+    for ax in axs[0]:
+        ax.tick_params(axis="x", which="both", length=0.0)
+    handles, labels = axs[1][0].get_legend_handles_labels()
+    fig.legend(
+        handles,
+        labels,
+        loc="upper center",
+        fontsize=9,
+        ncol=len(ys) + 1,
+        frameon=False,
+    )
+    return fig
+
+
+def _times_plot(
+    name: str,
+    population: DataFrame,
+    acts: list[str],
+    axs: Axes,
+    xmin: int = 0,
+    xmax: int = 1440,
+    step: int = 30,
+    **kwargs,
+) -> Tuple[Figure, Axes]:
+    starts = population.groupby("act", observed=False).start
+    ends = population.groupby("act", observed=False).end
+    durations = population.groupby("act", observed=False).duration
+    bins = list(range(xmin, xmax, step))
+
+    for i, act in enumerate(acts):
+        if act not in population.act.unique():
+            continue
+        axs[0][i].spines["top"].set_visible(False)
+        axs[0][i].spines["right"].set_visible(False)
+        axs[0][i].spines["bottom"].set_visible(False)
+        axs[0][i].spines["left"].set_visible(False)
+        axs[0][i].set_xticks([])
+        axs[0][i].set_yticks([])
+
+        axs[1][i].set_title(act.title(), fontsize="small")
+        start_group = starts.get_group(act)
+        if len(start_group) < 5:
+            continue
+        axs[1][i].hist(
+            starts.get_group(act),
+            bins=bins,
+            density=True,
+            histtype="step",
+            label=name,
+            linewidth=1.4,
+            **kwargs,
+        )
+        axs[1][i].set_xlim(xmin, xmax)
+        axs[1][i].set_yticklabels([])
+        axs[1][i].set(ylabel=None)
+        axs[1][i].set_xticks([])
+        axs[1][i].set_yticks([])
+
+        axs[2][i].hist(
+            ends.get_group(act),
+            bins=bins,
+            density=True,
+            histtype="step",
+            label=name,
+            linewidth=1.4,
+            **kwargs,
+        )
+        axs[2][i].set_xlim(xmin, xmax)
+        axs[2][i].set_yticklabels([])
+        axs[2][i].set(ylabel=None)
+        axs[2][i].set_xticks([])
+        axs[2][i].set_yticks([])
+
+        axs[3][i].hist(
+            durations.get_group(act),
+            bins=bins,
+            density=True,
+            histtype="step",
+            label=name,
+            linewidth=1.4,
+            **kwargs,
+        )
+        axs[3][i].set_xlim(xmin, xmax)
+        axs[3][i].set_yticklabels([])
+        axs[3][i].set(ylabel=None)
+        axs[3][i].set_xticks(
+            [0, 240, 480, 720, 960, 1200, 1440],
+            labels=[
+                "00:00",
+                "04:00",
+                "08:00",
+                "12:00",
+                "16:00",
+                "20:00",
+                "24:00",
+            ],
+            rotation=90,
+            fontsize=8,
+        )
+        axs[3][i].set_yticks([])
+        axs[3][i].set_xlabel("Time/Duration", fontsize=8)
+
+    axs[1][0].set_ylabel("Start Time\nDensities", fontsize=10)
+    axs[2][0].set_ylabel("End Time\nDensities", fontsize=10)
+    axs[3][0].set_ylabel("Duration\nDensities", fontsize=10)
+
+
+def joint_time_distributions_plot(
+    observed: DataFrame, ys: Optional[dict[DataFrame]], **kwargs
+) -> Figure:
+    if ys is None:
+        ys = dict()
+    acts = list(observed.act.value_counts(ascending=False).index)
+    n_acts = len(acts)
+    rows = len(ys) + 2
+    ratios = [1 for _ in range(rows)]
+    ratios[0] = 0.2
+
+    cmaps = kwargs.pop("cmaps", {})
+    legend = []
+    legend_colours = []
+
+    fig, axs = plt.subplots(
+        rows,
+        observed.act.nunique(),
+        figsize=kwargs.pop("figsize", (12, 5)),
+        sharex=False,
+        sharey=False,
+        constrained_layout=True,
+        gridspec_kw={"height_ratios": ratios},
+    )
+
+    # deal with observed first
+    name = kwargs.pop("observed_title", "Observed")
+
+    legend.append(name)
+    cmap = cmaps.get(0, "Blues")
+    lcolours = colormaps[cmap]([0, 0.5, 1])
+    legend_colours.append(lcolours[int(len(lcolours) / 2)])
+
+    _joint_time_plot(observed, axs[1], acts, cmap=cmap)
+
+    # now deal with ys
+    for i, (name, y) in enumerate(ys.items()):
+
+        legend.append(name)
+        cmap = cmaps.get(i + 1, "Reds")
+        lcolours = colormaps[cmap]([0, 0.5, 1])
+        legend_colours.append(lcolours[int(len(lcolours) / 2)])
+
+        _joint_time_plot(y, axs[i + 2], acts, cmap=cmap)
+
+    # xlabel on bottom row
+    for ax in axs[-1]:
+        ax.set_xlabel("Start times", fontsize=8)
+        ax.set_xticks(
+            [240, 480, 720, 960, 1200, 1440],
+            labels=["04:00", "08:00", "12:00", "16:00", "20:00", "24:00"],
+            rotation=90,
+            fontsize=8,
+        )
+
+    # acts
+    for ax, act in zip(axs[1], acts):
+        ax.set_title(act.title(), fontsize=9)
+
+    # deal with legend
+    for i in range(n_acts):
+        axs[0][i].spines["top"].set_visible(False)
+        axs[0][i].spines["right"].set_visible(False)
+        axs[0][i].spines["bottom"].set_visible(False)
+        axs[0][i].spines["left"].set_visible(False)
+        axs[0][i].set_xticks([])
+        axs[0][i].set_yticks([])
+    for ax in axs[0]:
+        ax.tick_params(axis="x", which="both", length=0.0)
+
+    handles = [
+        patches.Patch(color=c, label=lab) for c, lab in zip(legend_colours, legend)
+    ]
+    fig.legend(
+        handles=handles,
+        loc="upper center",
+        fontsize=9,
+        ncol=len(ys) + 1,
+        frameon=False,
+    )
+
+    return fig
+
+
+def _joint_time_plot(
+    population: DataFrame,
+    axs: Axes,
+    acts: list[str],
+    cmap: str,
+    xmin: int = 240,
+    xmax: int = 1441,
+    ymin: int = 0,
+    ymax: int = 960,
+    xstep: int = 30,
+    ystep: int = 30,
+):
+    starts = population.groupby("act", observed=False).start
+    durations = population.groupby("act", observed=False).duration
+
+    start_bins = list(range(xmin, xmax, xstep))
+    duration_bins = list(range(ymin, ymax, ystep))
+
+    for i, act in enumerate(acts):
+        axs[i].set_xticks([])
+        axs[i].set_yticks([])
+        if act not in population.act.unique():
+            continue
+        act_starts = starts.get_group(act)
+        act_durations = durations.get_group(act)
+        axs[i].hist2d(
+            x=act_starts,
+            y=act_durations,
+            bins=(start_bins, duration_bins),
+            cmap=cmap,
+        )
+    ylabel = "Durations"
+    axs[0].set_ylabel(ylabel, fontsize=8)
+    axs[0].set_yticks(
+        [0, 120, 240, 360, 480, 600, 720, 840, 960],
+        labels=[
+            "00:00",
+            "02:00",
+            "04:00",
+            "06:00",
+            "08:00",
+            "10:00",
+            "12:00",
+            "14:00",
+            "16:00",
+        ],
+        fontsize=8,
+    )

acteval/density/describe/transitions.py

@@ -0,0 +1,93 @@
+from typing import Optional, Tuple
+
+from matplotlib import pyplot as plt
+from matplotlib.axes import Axes
+from matplotlib.colors import ListedColormap as CMap
+from matplotlib.figure import Figure
+from matplotlib.patches import Patch
+from pandas import DataFrame
+
+from acteval.density.features.transitions import sequence_probs
+
+
+def sequence_prob_plot(
+    observed: DataFrame, ys: Optional[dict[DataFrame]], **kwargs
+) -> Figure:
+    acts = list(observed.act.value_counts(ascending=False).index)
+    cmap = kwargs.pop("cmap", None)
+    if cmap is None:
+        cmap = plt.cm.Set3
+        colors = cmap.colors
+        factor = (len(acts) // len(colors)) + 1
+        cmap = dict(zip(acts, colors * factor))
+
+    n_plots = len(ys) + 2
+    ratios = [1 for _ in range(n_plots)]
+    ratios[-1] = 0.3
+
+    fig, axs = plt.subplots(
+        1,
+        n_plots,
+        figsize=kwargs.pop("figsize", (12, 5)),
+        sharex=True,
+        sharey=True,
+        # tight_layout=True,
+        constrained_layout=True,
+        gridspec_kw={"width_ratios": ratios},
+    )
+    acts = list(observed.act.value_counts(ascending=False).index)
+    name = kwargs.pop("observed_title", "Observed")
+    _probs_plot(name, observed, ax=axs[0], cmap=cmap, ylabel=True)
+
+    if ys is None:
+        return fig
+    for i, (name, y) in enumerate(ys.items()):
+        _probs_plot(name, y, ax=axs[i + 1], cmap=cmap)
+        axs[i + 1].set_title(name)
+
+    elements = [Patch(facecolor=cmap[act], label=act.title()) for act in acts]
+    axs[-1].axis("off")
+    axs[-1].legend(handles=elements, loc="center left", frameon=False)
+
+    return fig
+
+
+def _probs_plot(
+    name: str,
+    population: DataFrame,
+    cmap: Optional[CMap],
+    ax=Axes,
+    ylabel=False,
+) -> Tuple[Figure, Axes]:
+    probs = sequence_probs(population)
+    accumulated = probs[::-1].cumsum()[::-1]
+
+    ys = []
+    widths = []
+    heights = []
+    lefts = []
+    cols = []
+    for idx, p, ap in zip(probs.index, probs, accumulated):
+        seq = idx[1].split(">")
+        width = 1 / len(seq)
+        for i, act in enumerate(seq):
+            ys.append(ap - p)
+            widths.append(width)
+            heights.append(p)
+            lefts.append(i * width)
+            cols.append(cmap[act])
+
+    ax.barh(y=ys, width=widths, height=heights, left=lefts, color=cols, align="edge")
+    ax.hlines(ys, xmin=0, xmax=1, color="white", linewidth=0.1)
+
+    ax.spines["top"].set_visible(False)
+    ax.spines["right"].set_visible(False)
+    ax.spines["bottom"].set_visible(False)
+    ax.spines["left"].set_visible(False)
+    ax.set_xlabel("Activity\nSequence")
+    if ylabel:
+        ax.set_ylabel("Sequence Proportion")
+    ax.set_xticklabels([])
+    ax.set_xticks([])
+    ax.set_title(name)
+    return ax

acteval/density/features/_discretise.py

@@ -0,0 +1,97 @@
+"""Pure-numpy discretisation helpers (no torch dependency)."""
+
+from typing import Iterable
+
+import numpy as np
+import pandas as pd
+
+
+def descretise_population(
+    data: pd.DataFrame, duration: int, step_size: int, class_map: dict
+) -> np.ndarray:
+    """Convert given population of activity traces into array [P, C, H, W].
+
+    P is the population size.
+    C (channel) is length 1.
+    H is time steps.
+    W is a one-hot encoding of activity type.
+
+    Args:
+        data (pd.DataFrame): Schedule DataFrame with pid, act, start, end columns.
+        duration (int): Total duration in time units.
+        step_size (int): Step size for discretisation.
+        class_map (dict): Mapping from activity string to integer class index.
+
+    Returns:
+        np.ndarray: Array of shape [P, C, H, W].
+    """
+    persons = data.pid.nunique()
+    num_classes = len(class_map)
+    steps = duration // step_size
+    encoded = np.zeros((persons, steps, num_classes, 1), dtype=np.float32)
+
+    for pid, (_, trace) in enumerate(data.groupby("pid")):
+        trace_encoding = descretise_trace(
+            acts=trace.act,
+            starts=trace.start,
+            ends=trace.end,
+            length=duration,
+            class_map=class_map,
+        )
+        trace_encoding = down_sample(trace_encoding, step_size)
+        trace_encoding = one_hot(trace_encoding, num_classes)
+        trace_encoding = trace_encoding.reshape(steps, num_classes, 1)
+        encoded[pid] = trace_encoding  # [B, H, W, C]
+    encoded = encoded.transpose(0, 3, 1, 2)  # [B, C, H, W]
+    return encoded
+
+
+def descretise_trace(
+    acts: Iterable[str],
+    starts: Iterable[int],
+    ends: Iterable[int],
+    length: int,
+    class_map: dict,
+) -> np.ndarray:
+    """Create categorical encoding from ranges with step of 1.
+
+    Args:
+        acts (Iterable[str]): Activity labels.
+        starts (Iterable[int]): Start times.
+        ends (Iterable[int]): End times.
+        length (int): Total length of encoding.
+        class_map (dict): Mapping from activity string to integer class index.
+
+    Returns:
+        np.ndarray: 1D categorical encoding of length `length`.
+    """
+    encoding = np.zeros((length), dtype=np.int8)
+    for act, start, end in zip(acts, starts, ends):
+        encoding[start:end] = class_map[act]
+    return encoding
+
+
+def down_sample(array: np.ndarray, step: int) -> np.ndarray:
+    """Down-sample by stepping through given array.
+
+    Args:
+        array (np.ndarray): Input array.
+        step (int): Step size.
+
+    Returns:
+        np.ndarray: Down-sampled array.
+    """
+    return array[::step]
+
+
+def one_hot(target: np.ndarray, num_classes: int) -> np.ndarray:
+    """One hot encoding of given categorical array.
+
+    Args:
+        target (np.ndarray): Categorical array.
+        num_classes (int): Number of classes.
+
+    Returns:
+        np.ndarray: One-hot encoded array.
+    """
+    return np.eye(num_classes)[target]