acteval 0.1.0__tar.gz

acteval-0.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(find /home/fred/projects/acteval -maxdepth 2 -type f -name \"*.md\" -o -name \"*.toml\" -o -name \"*.txt\" -o -name \"Makefile\" 2>/dev/null | grep -v \".venv\")",
+      "Bash(uv sync:*)",
+      "Bash(pytest tests/ 2>&1)",
+      "Bash(python -c \"import acteval; print\\('ok'\\)\")",
+      "Bash(which python:*)",
+      "Bash(uv run:*)",
+      "Bash(python -m pytest tests/ -v 2>&1)",
+      "Bash(python -m pytest tests/ -x -q 2>&1)",
+      "Bash(find /home/fred/projects/acteval -type f -name \"*.toml\" -o -type f -name \"*.yaml\" -o -type f -name \"*.yml\" | grep -E \"\\\\.\\(toml|ya?ml\\)$\" | head -20)",
+      "Bash(python3 --version && python3 -m pip list | grep -E \"pytest|ruff|black|mypy\" | head -10)"
+    ]
+  }
+}

acteval-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Check formatting
+        run: uv run black --check src/ tests/
+
+      - name: Run tests
+        run: uv run pytest tests/ --cov=src/acteval

acteval-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v4
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

acteval-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+ss
+
+# OS-specific
+.DS_Store
+
+# Editors
+*~
+\#*\#
+**/.vscode
+.spyderproject
+.spyproject
+.idea/
+
+# Byte-compiled files
+__pycache__
+*.pyc
+
+# Build output
+build/
+*.egg-info
+dist/
+.cruft.json
+tmp/
+
+# Virtual environment
+venv/
+.venv
+
+# Reports
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+reports/
+logs
+
+# Caches
+.*[cC]ache*
+
+# Documentation
+.docs
+mike-*.yml
+
+# Jupyter notebooks
+.ipynb_checkpoints

acteval-0.1.0/CLAUDE.md

@@ -0,0 +1,60 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+pytest tests/
+
+# Run a single test file
+pytest tests/test_compare.py
+
+# Run with coverage
+pytest --cov=src/acteval tests/
+
+# Build
+uv build
+```
+
+## Architecture
+
+`acteval` is a Python library for evaluating synthetic activity schedules (daily time-use data) by comparing them to observed data.
+
+### Data Flow
+
+1. **Input**: pandas DataFrames with columns `pid` (person ID), `act` (activity), `start`, `end`, `duration`
+2. **`Population`** (`population.py`): Converts DataFrames to numpy arrays once at construction; uses lazy properties for expensive derived quantities (act_enum_key, count_matrix, seq_key). Integer-encodes activities and person IDs for vectorized operations.
+3. **Feature extraction** (`features/`): Each function takes a `Population` and returns `dict[str, tuple[ndarray, ndarray]]` — `{label: (values, weights)}`. Weights enable weighted aggregation across persons.
+4. **Distance metrics** (`distance/`): `wasserstein.py` uses the POT library for EMD/optimal transport; `scalar.py` provides MAE, MSE, MAPE for scalar values.
+5. **Evaluation pipeline** (`evaluate.py`): Organized into "jobs" — tuples of `(feature_fn, size_fn, description_job, distance_job)`. Target features are computed once; multiple synthetic populations are compared against them.
+6. **Output**: Nested DataFrames with individual features, feature groups, and domain summaries, with per-synthetic-model statistics.
+
+### Key Modules
+
+- **`evaluate.py`**: Main engine — `evaluate()`, `compare()`, `Evaluator` class, `subsample_and_evaluate()`. The `Evaluator` class caches target features for repeated comparisons.
+- **`population.py`**: Core data structure. Pre-computes pid groupings and person boundaries.
+- **`features/`**: `structural.py` (sequence properties, feasibility), `frequency.py` (activity densities), `times.py` (start/end times, durations), `transitions.py` (n-gram patterns up to 4-grams), `participation.py` (activity rates), `creativity.py` (novelty detection via hashing).
+- **`describe/`**: Aggregate statistics for frequency, timing, and transition patterns — used for reporting alongside distance metrics.
+- **`filters.py`**: `filter_novel()` removes sequences already seen in the base population.
+- **`ops.py`**: Aggregation operations (`average`, `feature_weight`).
+
+### Public API
+
+```python
+from acteval import compare, evaluate, Evaluator
+
+# Single comparison
+result = compare(observed_df, synthetic_df, report_stats=True)
+
+# Multiple models
+result = compare(observed_df, {"model_a": df_a, "model_b": df_b})
+
+# Reuse target features across comparisons
+evaluator = Evaluator(observed_df)
+result = evaluator.compare({"model_a": df_a})
+```

acteval-0.1.0/PKG-INFO

@@ -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'

acteval-0.1.0/README.md

@@ -0,0 +1,118 @@
+# acteval
+
+A Python library for evaluating synthetic activity schedules by comparing them to observed data. Given a population of daily activity sequences (who did what and when), `acteval` measures how well a synthetic population reproduces the observed distribution across multiple dimensions: activity frequencies, timing, transitions, participation rates, and novelty.
+
+## Install
+
+```bash
+pip install acteval
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```bash
+uv add acteval
+```
+
+## Development
+
+```bash
+# Install dependencies (including dev tools)
+uv sync
+
+# Run tests
+pytest tests/
+
+# Run tests with coverage
+pytest --cov=src/acteval tests/
+
+# Lint with ruff
+ruff check src/ tests/
+
+# Auto-fix lint issues
+ruff check --fix src/ tests/
+
+# Check formatting with black
+black --check src/ tests/
+
+# Auto-format
+black src/ tests/
+```
+
+## Input format
+
+Data is passed as a pandas DataFrame with one row per activity episode:
+
+| column | type | description |
+|--------|------|-------------|
+| `pid` | int/str | Person identifier |
+| `act` | str | Activity label (e.g. `"home"`, `"work"`, `"shop"`) |
+| `start` | numeric | Start time (any consistent unit, e.g. hours) |
+| `end` | numeric | End time |
+| `duration` | numeric | Duration (`end - start`) |
+
+```python
+import pandas as pd
+
+observed = pd.DataFrame([
+    {"pid": 0, "act": "home", "start": 0,  "end": 6,  "duration": 6},
+    {"pid": 0, "act": "work", "start": 6,  "end": 14, "duration": 8},
+    {"pid": 0, "act": "home", "start": 14, "end": 24, "duration": 10},
+    {"pid": 1, "act": "home", "start": 0,  "end": 10, "duration": 10},
+    {"pid": 1, "act": "work", "start": 10, "end": 24, "duration": 14},
+])
+```
+
+## API
+
+### `compare(observed, synthetic, **kwargs)`
+
+Compare one or more synthetic populations to an observed population.
+
+```python
+from acteval import compare
+
+# Single synthetic population
+result = compare(observed, synthetic)
+
+# Multiple models side-by-side
+result = compare(observed, {"model_a": synthetic_a, "model_b": synthetic_b})
+```
+
+`result` is a dict with six DataFrames:
+
+| key | description |
+|-----|-------------|
+| `"distances"` | Per-feature distances |
+| `"group_distances"` | Distances aggregated by feature group |
+| `"domain_distances"` | Distances aggregated by domain (participations, transitions, timing) |
+| `"descriptions"` | Per-feature descriptive statistics |
+| `"group_descriptions"` | Group-level descriptive statistics |
+| `"domain_descriptions"` | Domain-level descriptive statistics |
+
+Pass `report_stats=True` to include additional statistics in the output.
+
+### `Evaluator`
+
+Use `Evaluator` when comparing multiple synthetic populations against the same observed data — it computes and caches the observed features once.
+
+```python
+from acteval import Evaluator
+
+evaluator = Evaluator(observed)
+
+result_v1 = evaluator.compare({"v1": synthetic_v1})
+result_v2 = evaluator.compare({"v2": synthetic_v2})
+```
+
+### `Population`
+
+For direct access to the underlying data structure:
+
+```python
+from acteval import Population
+
+pop = Population(observed)
+print(pop.acts)       # activity labels per episode
+print(pop.durations)  # durations as numpy array
+```

acteval-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "acteval"
+version = "0.1.0"
+description = "Standalone library for evaluating activity sequences"
+requires-python = ">=3.8"
+dependencies = [
+    "pandas",
+    "numpy",
+    "scipy<=1.13",
+    "pot",
+    "matplotlib",
+    "tabulate",
+    "tomli>=1.1.0; python_version < '3.11'",
+]
+
+[tool.uv]
+dev-dependencies = ["pytest", "pytest-cov", "ruff", "black"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/acteval"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/test_distance_emd.py" = ["E402"]
+
+[tool.black]
+target-version = ["py39"]

acteval-0.1.0/src/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-0.1.0/src/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-0.1.0/src/acteval/creativity/__init__.py

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

acteval-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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