acteval 0.1.0__py3-none-any.whl

acteval/filters.py

@@ -0,0 +1,16 @@
+from pandas import DataFrame
+
+from acteval.creativity.features import creativity
+
+
+def no_filter(scenario: DataFrame, base: DataFrame) -> DataFrame:
+    return scenario
+
+
+def filter_novel(scenario: DataFrame, base: DataFrame) -> DataFrame:
+    base_hashed = creativity.hash_population(base)
+    # Vectorized: hash all synthetic schedules at once
+    act_hash = scenario.act.astype(str) + scenario.duration.astype(str)
+    synth_hashes = act_hash.groupby(scenario.pid).agg("".join)
+    novel_pids = synth_hashes.index[~synth_hashes.isin(base_hashed)]
+    return scenario[scenario.pid.isin(novel_pids)].reset_index(drop=True)

acteval/jobs.py

@@ -0,0 +1,215 @@
+import sys
+from functools import partial
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+from acteval.density.features import participation, times, transitions
+from acteval.distance import emd
+from acteval.ops import average, average2d, feature_weight
+from acteval.structural.features import structural
+
+_DEFAULT_CONFIG = Path(__file__).parent / "config.toml"
+
+
+def load_config(path=None) -> dict:
+    if path is None:
+        path = _DEFAULT_CONFIG
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def build_density_jobs(cfg: dict) -> list[tuple]:
+    """Returns active jobs for participations, transitions, and timing domains.
+
+    Each job is a 4-tuple of ``(feature, size, description_job, distance_job)``
+    where *feature* is a 3-tuple ``(name, fn, per_pid_fn | None)``.
+    The per-pid function, when present, returns a ``PidFeatures`` instance.
+    """
+    ngram_min_count = cfg.get("ngrams", {}).get("min_count", 3)
+    participations_cfg = cfg.get("jobs", {}).get("participations", {})
+    transitions_cfg = cfg.get("jobs", {}).get("transitions", {})
+    timing_cfg = cfg.get("jobs", {}).get("timing", {})
+
+    participation_rate_jobs = []
+    if participations_cfg.get("lengths", True):
+        participation_rate_jobs.append(
+            (
+                (
+                    "lengths",
+                    structural.sequence_lengths,
+                    structural.sequence_lengths_per_pid,
+                ),
+                (feature_weight),
+                ("length.", average),
+                ("EMD", emd),
+            )
+        )
+    if participations_cfg.get("rates", True):
+        participation_rate_jobs.append(
+            (
+                (
+                    "participation rate",
+                    participation.participation_rates_by_act,
+                    participation.participation_rates_by_act_per_pid,
+                ),
+                (feature_weight),
+                ("av. rate", average),
+                ("EMD", emd),
+            )
+        )
+    if participations_cfg.get("pair_rates", True):
+        participation_rate_jobs.append(
+            (
+                (
+                    "pair participation rate",
+                    participation.joint_participation_rate,
+                    participation.joint_participation_rate_per_pid,
+                ),
+                (feature_weight),
+                ("av rate.", average),
+                ("EMD", emd),
+            )
+        )
+
+    transition_jobs = []
+    if transitions_cfg.get("2-gram", True):
+        transition_jobs.append(
+            (
+                (
+                    "2-gram",
+                    partial(transitions.transitions_by_act, min_count=ngram_min_count),
+                    partial(
+                        transitions.transitions_by_act_per_pid,
+                        min_count=ngram_min_count,
+                    ),
+                ),
+                (feature_weight),
+                ("av. rate", average),
+                ("EMD", emd),
+            )
+        )
+    if transitions_cfg.get("3-gram", True):
+        transition_jobs.append(
+            (
+                (
+                    "3-gram",
+                    partial(
+                        transitions.transition_3s_by_act, min_count=ngram_min_count
+                    ),
+                    partial(
+                        transitions.transition_3s_by_act_per_pid,
+                        min_count=ngram_min_count,
+                    ),
+                ),
+                (feature_weight),
+                ("av. rate", average),
+                ("EMD", emd),
+            )
+        )
+    if transitions_cfg.get("4-gram", True):
+        transition_jobs.append(
+            (
+                (
+                    "4-gram",
+                    partial(
+                        transitions.transition_4s_by_act, min_count=ngram_min_count
+                    ),
+                    partial(
+                        transitions.transition_4s_by_act_per_pid,
+                        min_count=ngram_min_count,
+                    ),
+                ),
+                (feature_weight),
+                ("av. rate", average),
+                ("EMD", emd),
+            )
+        )
+
+    time_jobs = []
+    if timing_cfg.get("start_times", True):
+        time_jobs.append(
+            (
+                (
+                    "start times",
+                    times.start_times_by_act_plan_enum,
+                    times.start_times_by_act_plan_enum_per_pid,
+                ),
+                (feature_weight),
+                ("average", average),
+                ("EMD", emd),
+            )
+        )
+    if timing_cfg.get("durations", True):
+        time_jobs.append(
+            (
+                (
+                    "durations",
+                    times.durations_by_act_plan_enum,
+                    times.durations_by_act_plan_enum_per_pid,
+                ),
+                (feature_weight),
+                ("average", average),
+                ("EMD", emd),
+            )
+        )
+    if timing_cfg.get("start_durations", True):
+        time_jobs.append(
+            (
+                (
+                    "start-durations",
+                    times.start_and_duration_by_act_bins,
+                    times.start_and_duration_by_act_bins_per_pid,
+                ),
+                (feature_weight),
+                ("average", average2d),
+                ("EMD", emd),
+            )
+        )
+    if timing_cfg.get("joint_durations", True):
+        time_jobs.append(
+            (
+                (
+                    "joint-durations",
+                    times.joint_durations_by_act_bins,
+                    times.joint_durations_by_act_bins_per_pid,
+                ),
+                (feature_weight),
+                ("average", average2d),
+                ("EMD", emd),
+            )
+        )
+
+    return [
+        ("participations", participation_rate_jobs),
+        ("transitions", transition_jobs),
+        ("timing", time_jobs),
+    ]
+
+
+def build_creativity_jobs(cfg: dict) -> bool:
+    """Returns whether to run creativity evaluation."""
+    return cfg.get("jobs", {}).get("creativity", {}).get("enabled", True)
+
+
+def build_structural_jobs(cfg: dict) -> bool:
+    """Returns whether to run structural/feasibility evaluation."""
+    return cfg.get("jobs", {}).get("structural", {}).get("enabled", True)
+
+
+def get_jobs(config_path=None):
+    """Load config and return active job specification.
+
+    Returns:
+        tuple of (density_domain_jobs, run_creativity, run_structural)
+        where density_domain_jobs is [(domain_name, [jobs])].
+    """
+    cfg = load_config(config_path)
+    return (
+        build_density_jobs(cfg),
+        build_creativity_jobs(cfg),
+        build_structural_jobs(cfg),
+    )

acteval/ops.py

@@ -0,0 +1,49 @@
+import numpy as np
+from numpy import ndarray
+from pandas import Series
+
+
+def actual(features: dict[str, float]) -> Series:
+    return Series(features)
+
+
+def feature_value(features: dict[str, tuple[ndarray, ndarray]]) -> Series:
+    return Series({k: v[0] for k, (v, w) in features.items()}, dtype=int)
+
+
+def feature_length(features: dict[str, tuple[ndarray, ndarray]]) -> Series:
+    return Series({k: len(v) for k, (v, w) in features.items()}, dtype=int)
+
+
+def feature_weight(features: dict[str, tuple[ndarray, ndarray]]) -> Series:
+    return Series({k: w.sum() for k, (v, w) in features.items()}, dtype=int)
+
+
+def average_weight(features: dict[str, tuple[ndarray, ndarray]]) -> Series:
+    return Series({k: w.mean() for k, (v, w) in features.items()}, dtype=float)
+
+
+def average_density(features: dict[str, tuple[ndarray, ndarray]]) -> Series:
+    total = sum(w.sum() for _, w in features.values())
+    return Series({k: w.sum() / total for k, (v, w) in features.items()}, dtype=float)
+
+
+def average(features: dict[str, tuple[ndarray, ndarray]]) -> Series:
+    weighted_average = {}
+    for k, (v, w) in features.items():
+        if w.sum() > 0:
+            weighted_average[k] = np.average(v, axis=0, weights=w).sum()
+        else:
+            weighted_average[k] = 0
+    return Series(weighted_average, dtype=float)
+
+
+def average2d(features: dict[str, tuple[ndarray, ndarray]]) -> Series:
+    return Series(
+        {
+            k: np.average(v, axis=0, weights=w).sum().sum()
+            for k, (v, w) in features.items()
+            if w.sum() > 0
+        },
+        dtype=float,
+    )

acteval/population.py

@@ -0,0 +1,165 @@
+"""Population: precomputed numpy representation of a schedule population DataFrame."""
+
+import numpy as np
+from numpy import ndarray
+from pandas import DataFrame
+
+from acteval.density.features.utils import _cumcount
+
+
+class Population:
+    """Precomputed numpy representation of a schedule population DataFrame.
+
+    Converts a DataFrame once and caches all derived quantities to avoid
+    redundant computation across feature extraction functions.
+
+    Eager attributes (always computed):
+        acts: activity strings.
+        act_codes: integer-encoded activities (0, 1, ...).
+        starts: start times.
+        ends: end times.
+        durations: durations.
+        pids: dense integer-encoded pids (0, 1, ...).
+        unique_acts: sorted unique activity strings.
+        n_act_types: number of unique activity types.
+        act_to_int: dict mapping activity string → int code.
+        int_to_act: ndarray indexed by int code → activity string.
+        n: number of unique persons.
+        pid_counts: activity count per pid.
+        pid_starts: first row index per pid.
+        pid_ends: exclusive end row index per pid.
+        pid_boundaries: row indices where pid changes (== pid_starts[1:]).
+        first_idx: first row index per pid (== pid_starts).
+        last_idx: last row index per pid (== pid_ends - 1).
+
+    Lazy properties (computed on first access):
+        act_enum_key: cumcount within (pid, act), e.g. "home0", "work0", "home1".
+        seq_key: cumcount within pid, e.g. "0home", "1work", "2home".
+        count_matrix: shape (n, n_act_types) — activity counts per pid.
+    """
+
+    def __init__(self, df: DataFrame):
+        """Construct a Population from a schedule DataFrame.
+
+        Args:
+            df: DataFrame with columns pid, act, start, end, duration.
+                Rows are assumed sorted by pid; a defensive sort is applied if not.
+                The act, start, end, and duration columns are optional — absent
+                columns result in empty arrays.
+        """
+        if len(df) == 0:
+            self._init_empty()
+            return
+
+        raw_pids = df["pid"].values
+
+        # Sort by pid if needed (defensive)
+        if len(raw_pids) > 1 and not np.all(raw_pids[:-1] <= raw_pids[1:]):
+            order = np.argsort(raw_pids, kind="stable")
+            raw_pids = raw_pids[order]
+        else:
+            order = None
+
+        def _col(name, default_dtype=float):
+            if name not in df.columns:
+                return np.empty(0, dtype=default_dtype)
+            vals = df[name].values
+            return vals[order] if order is not None else vals
+
+        self.acts = _col("act", object)
+        self.starts = _col("start", float)
+        self.ends = _col("end", float)
+        self.durations = _col("duration", float)
+
+        # Activity encoding
+        if len(self.acts) > 0:
+            self.unique_acts, self.act_codes = np.unique(self.acts, return_inverse=True)
+        else:
+            self.unique_acts = np.array([], dtype=object)
+            self.act_codes = np.array([], dtype=np.int64)
+        self.n_act_types = len(self.unique_acts)
+        self.act_to_int = {a: i for i, a in enumerate(self.unique_acts)}
+        self.int_to_act = self.unique_acts  # indexed by int code → act string
+
+        # Pid grouping
+        self.unique_pids_original, self.pids, self.pid_counts = np.unique(
+            raw_pids, return_inverse=True, return_counts=True
+        )
+        self.n = len(self.pid_counts)
+        self.pid_starts = np.concatenate([[0], np.cumsum(self.pid_counts)[:-1]])
+        self.pid_ends = self.pid_starts + self.pid_counts
+        self.pid_boundaries = self.pid_starts[1:]  # free — no extra computation
+        self.first_idx = self.pid_starts
+        self.last_idx = self.pid_ends - 1
+
+        self._lazy_act_enum_key = None
+        self._lazy_seq_key = None
+        self._lazy_count_matrix = None
+
+    def _init_empty(self) -> None:
+        """Initialise all arrays to empty for an empty DataFrame."""
+        self.acts = np.array([], dtype=object)
+        self.starts = np.empty(0, dtype=float)
+        self.ends = np.empty(0, dtype=float)
+        self.durations = np.empty(0, dtype=float)
+        self.unique_acts = np.array([], dtype=object)
+        self.act_codes = np.array([], dtype=np.int64)
+        self.n_act_types = 0
+        self.act_to_int = {}
+        self.int_to_act = np.array([], dtype=object)
+        self.unique_pids_original = np.array([], dtype=object)
+        self.pids = np.array([], dtype=np.int64)
+        self.pid_counts = np.array([], dtype=np.int64)
+        self.n = 0
+        self.pid_starts = np.array([], dtype=np.int64)
+        self.pid_ends = np.array([], dtype=np.int64)
+        self.pid_boundaries = np.array([], dtype=np.int64)
+        self.first_idx = np.array([], dtype=np.int64)
+        self.last_idx = np.array([], dtype=np.int64)
+        self._lazy_act_enum_key = None
+        self._lazy_seq_key = None
+        self._lazy_count_matrix = None
+
+    def __len__(self) -> int:
+        """Return total number of activity rows."""
+        return len(self.acts)
+
+    def __bool__(self) -> bool:
+        """Return False for an empty population."""
+        return len(self.acts) > 0
+
+    @property
+    def is_empty(self) -> bool:
+        """True when the population contains no rows."""
+        return len(self.acts) == 0
+
+    @property
+    def act_enum_key(self) -> ndarray:
+        """Cumcount within (pid, act) group, e.g. ["home0", "work0", "home1", ...]."""
+        if self._lazy_act_enum_key is None:
+            compound = self.pids * self.n_act_types + self.act_codes
+            cumcounts = _cumcount(compound)
+            self._lazy_act_enum_key = np.array(
+                [str(a) + str(c) for a, c in zip(self.acts, cumcounts)], dtype=object
+            )
+        return self._lazy_act_enum_key
+
+    @property
+    def seq_key(self) -> ndarray:
+        """Cumcount within pid group, e.g. ["0home", "1work", "2home", ...]."""
+        if self._lazy_seq_key is None:
+            cumcounts = _cumcount(self.pids)
+            self._lazy_seq_key = np.array(
+                [str(c) + str(a) for c, a in zip(cumcounts, self.acts)], dtype=object
+            )
+        return self._lazy_seq_key
+
+    @property
+    def count_matrix(self) -> ndarray:
+        """Activity count matrix, shape (n, n_act_types)."""
+        if self._lazy_count_matrix is None:
+            matrix = np.zeros((self.n, self.n_act_types), dtype=np.int64)
+            if self.n > 0 and self.n_act_types > 0:
+                np.add.at(matrix, (self.pids, self.act_codes), 1)
+            self._lazy_count_matrix = matrix
+        return self._lazy_count_matrix

acteval/structural/__init__.py

@@ -0,0 +1,2 @@
+"""Structural / feasibility evaluation — checks schedule validity constraints
+(home-based sequences, no consecutive duplicate activities)."""

acteval/structural/features/structural.py

@@ -0,0 +1,210 @@
+from typing import List
+
+import numpy as np
+from numpy import array, ndarray
+from pandas import DataFrame, MultiIndex, Series
+
+from acteval.density.features.pid_features import PidFeatures
+from acteval.density.features.utils import (
+    _grouped_sum,
+    weighted_features,
+)
+from acteval.population import Population
+
+
+def feasibility_eval(population: Population, name: str) -> tuple[Series, Series]:
+    index = MultiIndex.from_tuples(
+        [
+            ("feasibility", "invalid", "all"),
+            ("feasibility", "not home based", "all"),
+            ("feasibility", "not home based", "starts"),
+            ("feasibility", "not home based", "ends"),
+            ("feasibility", "consecutive", "all"),
+            ("feasibility", "consecutive", "home"),
+            ("feasibility", "consecutive", "work"),
+            ("feasibility", "consecutive", "education"),
+        ],
+        names=["domain", "feature", "segment"],
+    )
+
+    if population.is_empty:
+        print(f"Warning: {name} has no novel schedules for quality evaluation.")
+        weights = Series([0] * len(index), index=index, name=f"{name}__weight")
+        metrics = Series([0] * len(index), index=index, name=name)
+        return weights, metrics
+
+    pids = population.pids
+    acts = population.acts
+    unique_pids = np.arange(population.n)
+
+    # home based feasibility
+    first_acts = acts[population.first_idx]
+    last_acts = acts[population.last_idx]
+
+    not_start_at_home = first_acts != "home"
+    not_end_at_home = last_acts != "home"
+    not_home_based = not_start_at_home | not_end_at_home
+
+    # consecutive feasibility
+    consecutive_home = _get_consecutives(pids, acts, unique_pids, "home")
+    consecutive_work = _get_consecutives(pids, acts, unique_pids, "work")
+    consecutive_education = _get_consecutives(pids, acts, unique_pids, "education")
+
+    consecutive = consecutive_home | consecutive_work | consecutive_education
+
+    # combined
+    invalid = not_home_based | consecutive
+
+    n = population.n
+
+    metrics = Series(
+        [
+            invalid.sum() / n,
+            not_home_based.sum() / n,
+            not_start_at_home.sum() / n,
+            not_end_at_home.sum() / n,
+            consecutive.sum() / n,
+            consecutive_home.sum() / n,
+            consecutive_work.sum() / n,
+            consecutive_education.sum() / n,
+        ],
+        index=index,
+        name=name,
+        dtype=float,
+    )
+    weights = Series([n] * len(index), index=index, name=f"{name}__weight", dtype=int)
+    return weights, metrics
+
+
+def _get_consecutives(
+    pids: ndarray, acts: ndarray, unique_pids: ndarray, target: str
+) -> ndarray:
+    """Check which pids have consecutive occurrences of target activity.
+
+    Args:
+        pids: 1D array of pid values (in schedule order).
+        acts: 1D array of activity values (in schedule order).
+        unique_pids: 1D array of unique pid values.
+        target: Activity to check for consecutive occurrences.
+
+    Returns:
+        Boolean array of length len(unique_pids), True if pid has consecutive target.
+    """
+    is_target = acts == target
+    # Previous row is same pid and also target
+    prev_same_pid = np.empty(len(pids), dtype=bool)
+    prev_same_pid[0] = False
+    prev_same_pid[1:] = pids[1:] == pids[:-1]
+
+    prev_is_target = np.empty(len(is_target), dtype=bool)
+    prev_is_target[0] = False
+    prev_is_target[1:] = is_target[:-1]
+
+    consecutive = is_target & prev_is_target & prev_same_pid
+    if consecutive.any():
+        bad_pids = np.unique(pids[consecutive])
+        return np.isin(unique_pids, bad_pids)
+    return np.zeros(len(unique_pids), dtype=bool)
+
+
+def get_consecutives(population: DataFrame, act: str) -> Series:
+    """Legacy wrapper for backwards compatibility."""
+    pids = population.pid.values
+    acts = population.act.values
+    unique_pids = np.unique(pids)
+    result = _get_consecutives(pids, acts, unique_pids, act)
+    return Series(result, index=unique_pids, name="consecutive")
+
+
+def start_and_end_acts(
+    population: Population, target: str = "home"
+) -> dict[str, tuple[ndarray, ndarray]]:
+    acts = population.acts
+    n = population.n
+    first = int((acts[population.first_idx] == target).sum())
+    last = int((acts[population.last_idx] == target).sum())
+    return {
+        f"first act {target}": (array([0, 1]), array([(n - first), first])),
+        f"last act {target}": (array([0, 1]), array([(n - last), last])),
+    }
+
+
+def act_consecutive(
+    population: Population, targets: List[str] = ["home", "work", "education"]
+) -> dict[str, tuple[ndarray, ndarray]]:
+    pids = population.pids
+    acts = population.acts
+    unique_pids = np.arange(population.n)
+    n = population.n
+    result = {}
+    for target in targets:
+        consecutive_mask = _get_consecutives(pids, acts, unique_pids, target)
+        c = int(consecutive_mask.sum())
+        result[f"consecutive {target}"] = (
+            array([0, 1]),
+            array([n - c, c]),
+        )
+    return result
+
+
+def contains_consecutive(schedule: DataFrame, act: str) -> int:
+    mask = schedule.act.eq(act)
+    consecutive = mask == mask.shift(1)
+    return (mask & consecutive).sum() > 0
+
+
+def time_consistency(
+    population: Population, target: int = 1440
+) -> dict[str, tuple[ndarray, ndarray]]:
+    pids = population.pids
+    n = population.n
+
+    starts_val = population.starts
+    ends_val = population.ends
+    durations_val = population.durations
+
+    starts = int((starts_val[population.first_idx] == 0).sum())
+    ends = int((ends_val[population.last_idx] == target).sum())
+
+    _, dur_sums = _grouped_sum(pids, durations_val)
+    duration = int((dur_sums == target).sum())
+
+    return {
+        "starts at 0": (array([0, 1]), array([(n - starts), starts])),
+        f"ends at {target}": (array([0, 1]), array([(n - ends), ends])),
+        f"duration is {target}": (
+            array([0, 1]),
+            array([(n - duration), duration]),
+        ),
+    }
+
+
+def duration_consistency(
+    population: Population, factor: int = 1440
+) -> dict[str, tuple[ndarray, ndarray]]:
+    _, dur_sums = _grouped_sum(population.pids, population.durations)
+    return weighted_features({"total duration": dur_sums / factor})
+
+
+def sequence_lengths(
+    population: Population,
+) -> dict[str, tuple[ndarray, ndarray]]:
+    lengths, length_counts = np.unique(population.pid_counts, return_counts=True)
+    return {"sequence lengths": (lengths, length_counts)}
+
+
+def sequence_lengths_per_pid(
+    population: Population,
+) -> PidFeatures:
+    pids = np.arange(population.n)
+    return PidFeatures(
+        data={"sequence lengths": (population.pid_counts, pids)},
+        bin_size=None,
+        factor=1,
+    )
+
+
+def trip_consistency(
+    population: Population,
+) -> dict[str, tuple[ndarray, ndarray]]:
+    raise NotImplementedError

acteval-0.1.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: acteval
+Version: 0.1.0
+Summary: Standalone library for evaluating activity sequences
+Requires-Python: >=3.8
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pot
+Requires-Dist: scipy<=1.13
+Requires-Dist: tabulate
+Requires-Dist: tomli>=1.1.0; python_version < '3.11'