acteval 0.1.1__tar.gz → 0.1.2__tar.gz

{acteval-0.1.1 → acteval-0.1.2}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: acteval
-Version: 0.1.1
+Version: 0.1.2
 Summary: Standalone library for evaluating activity sequences
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Requires-Dist: matplotlib
 Requires-Dist: numpy
 Requires-Dist: pandas

{acteval-0.1.1 → acteval-0.1.2}/README.md

@@ -14,6 +14,36 @@ Or with [uv](https://github.com/astral-sh/uv):
 uv add acteval
 ```
 
+## CLI
+
+`acteval` ships with a command-line interface for comparing models without writing Python.
+
+```bash
+# Compare one model to observed data
+acteval observed.csv --model my_model synthetic.csv
+
+# Compare multiple models side-by-side
+acteval observed.csv \
+  --model model_a synthetic_a.csv \
+  --model model_b synthetic_b.csv
+
+# Save full results to CSV files
+acteval observed.csv --model my_model synthetic.csv --output results/
+
+# Show group-level detail instead of domain summary
+acteval observed.csv --model my_model synthetic.csv --level groups
+
+# Split evaluation by attribute (e.g. gender)
+acteval observed.csv \
+  --target-attrs target_attrs.csv --split-on gender \
+  --model my_model synthetic.csv --attrs my_model synth_attrs.csv
+
+# Use a custom config file
+acteval observed.csv --model my_model synthetic.csv --config custom.toml
+```
+
+Input files can be CSV or Parquet (detected by extension). Run `acteval --help` for the full option list.
+
 ## Quick start
 
 ```python
@@ -59,6 +89,9 @@ Data is passed as a pandas DataFrame with one row per activity episode:
 | `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`); can be omitted when both `start` and `end` are provided |
+
+Any two of `start`, `end`, and `duration` are sufficient — the third is derived automatically.
 
 
 ```python
@@ -89,18 +122,7 @@ result = compare(observed, synthetic)
 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.
+`result` is an `EvalResult` object. See [Reading the results](#reading-the-results) for how to access distances and descriptions at feature, group, and domain level.
 
 ### `Evaluator`
 
@@ -115,14 +137,6 @@ result_v1 = evaluator.compare({"v1": synthetic_v1})
 result_v2 = evaluator.compare({"v2": synthetic_v2})
 ```
 
-For fine-grained control, compare one model at a time then assemble:
-
-```python
-evaluator.compare_population("v1", synthetic_v1)
-evaluator.compare_population("v2", synthetic_v2)
-result = evaluator.report()
-```
-
 ### `pairwise_distances(schedules, specs=None)`
 
 Compute a single NxN distance matrix between individual schedules. Useful for clustering, outlier detection, or directly comparing a small batch of schedules.
@@ -190,18 +204,20 @@ print(pop.durations)  # durations as numpy array
 
 ## Reading the results
 
-### The six DataFrames
+### Accessing results
 
-`compare()` returns an `EvalResult` with six DataFrames at three levels of aggregation:
+`compare()` returns an `EvalResult` with distances and descriptions at three levels of aggregation. Each level is accessed via a property that returns a view object with `.distances` and `.descriptions` DataFrames:
 
 | Property | Index | Content |
 |----------|-------|---------|
-| `result.distances` | `(domain, feature, segment)` | Per-feature distances — lower is closer to observed |
-| `result.descriptions` | `(domain, feature, segment)` | Per-feature descriptive statistics (e.g. average start time) |
-| `result.group_distances` | `(domain, feature)` | Distances averaged across segments |
-| `result.group_descriptions` | `(domain, feature)` | Descriptions averaged across segments |
-| `result.domain_distances` | `(domain,)` | Distances averaged across features — one row per domain |
-| `result.domain_descriptions` | `(domain,)` | Descriptions averaged across features |
+| `result.features.combined.distances` | `(domain, feature, segment)` | Per-feature distances — lower is closer to observed |
+| `result.features.combined.descriptions` | `(domain, feature, segment)` | Per-feature descriptive statistics (e.g. average start time) |
+| `result.groups.combined.distances` | `(domain, feature)` | Distances averaged across segments |
+| `result.groups.combined.descriptions` | `(domain, feature)` | Descriptions averaged across segments |
+| `result.domains.combined.distances` | `(domain,)` | Distances averaged across features — one row per domain |
+| `result.domains.combined.descriptions` | `(domain,)` | Descriptions averaged across features |
+
+Save all levels to CSV at once with `result.save("output_dir/")`.
 
 Distances are in the range **0–1** (lower is better). A distance of `0.0` means the synthetic distribution perfectly matches observed; `1.0` is the maximum penalty.
 

acteval-0.1.2/llms.txt

@@ -0,0 +1,68 @@
+# acteval
+
+> Python library for evaluating synthetic activity schedules: given daily sequences of who-did-what-and-when, measures how well a synthetic population reproduces observed distributions across frequencies, timing, transitions, participation rates, and novelty. Distances are 0–1 (lower is better).
+
+## Install
+
+pip install acteval
+
+## Input format
+
+pandas DataFrame, one row per activity episode:
+- pid — person identifier (int or str)
+- act — activity label (str, e.g. "home", "work", "shop")
+- start — episode start time (numeric, any consistent unit)
+- end — episode end time (numeric)
+- duration — episode duration (numeric)
+
+## Key API
+
+- compare(observed, synthetic, **kwargs) → EvalResult
+  Compare one or more synthetic DataFrames to observed.
+  synthetic can be a single DataFrame or {"name": df, ...} dict.
+
+- Evaluator(observed) — cache observed features for repeated comparisons.
+  evaluator.compare({"v1": df_v1}) re-uses cached observed features.
+
+- pairwise_distances(schedules, specs=None) → PairwiseResult
+  NxN distance matrix between individual schedules.
+  result.matrix (numpy), result.to_dataframe() (labeled).
+
+## EvalResult structure
+
+Six DataFrames at three aggregation levels:
+- distances / descriptions              — per-feature (index: domain, feature, segment)
+- group_distances / group_descriptions  — per feature group (index: domain, feature)
+- domain_distances / domain_descriptions — per domain (index: domain)
+
+Convenience: result.summary(), result.rank_models(), result.best_model
+
+## Evaluation domains
+
+- participations — who does what and how often; participation rates, joint participation
+- transitions    — activity sequence patterns (2-, 3-, 4-gram bigrams)
+- timing         — start times and durations (EMD via Wasserstein distance)
+- creativity     — novelty and diversity of synthetic schedules vs observed
+- feasibility    — structural validity: home-based, no consecutive duplicate activities
+
+Missing activity penalty: 1.0 (maximum) for timing; None (compute on available data) for participation/transitions.
+
+## Pairwise distance specs
+
+from acteval.pairwise import chamfer_spec, soft_dtw_spec, default_pairwise_specs
+- default_pairwise_specs() — MAE on participation counts, bigram counts, mean durations
+- chamfer_spec(max_len, weight) — Chamfer on EOS-padded (N, L, 2) sequences
+- soft_dtw_spec(max_len, gamma, weight) — Soft-DTW on EOS-padded sequences
+
+## Source layout
+
+src/acteval/
+- evaluate.py       — public API: compare(), Evaluator, evaluate()
+- _pipeline.py      — evaluation engine; builds features → groups → domains output
+- population.py     — Population: core data structure, integer-encodes activities/persons
+- _jobs.py          — JobSpec dataclass, get_jobs(); reads config.toml
+- pairwise.py       — pairwise_distances(), PairwiseResult, spec factories
+- features/         — structural, frequency, times, transitions, participation, creativity
+- distance/         — wasserstein.py (EMD via POT), scalar.py (MAE/MSE/MAPE)
+- describe/         — descriptive stats alongside distance metrics
+- _filters.py       — filter_novel(): removes sequences seen in base population

{acteval-0.1.1 → acteval-0.1.2}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "acteval"
-version = "0.1.1"
+version = "0.1.2"
 description = "Standalone library for evaluating activity sequences"
-requires-python = ">=3.8"
+requires-python = ">=3.10"
 dependencies = [
     "pandas",
     "numpy",
@@ -26,6 +26,9 @@ dev-dependencies = [
     "polars>=1.8.2",
 ]
 
+[project.scripts]
+acteval = "acteval.cli:main"
+
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -38,7 +41,7 @@ testpaths = ["tests"]
 addopts = "--ignore=tests/test_bench_evaluate.py --ignore=tests/test_bench_pairwise.py --benchmark-columns=mean,stddev,rounds --benchmark-sort=name"
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py310"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "W"]
@@ -48,4 +51,4 @@ ignore = ["E501"]
 "tests/test_distance_emd.py" = ["E402"]
 
 [tool.black]
-target-version = ["py39"]
+target-version = ["py310"]

acteval-0.1.2/src/acteval/__main__.py

@@ -0,0 +1,4 @@
+from acteval.cli import main
+
+if __name__ == "__main__":
+    main()

acteval-0.1.2/src/acteval/cli.py

@@ -0,0 +1,206 @@
+import argparse
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from acteval._report import print_markdown
+from acteval.evaluate import Evaluator
+
+_REQUIRED_SCHEDULE_COLS = {"pid", "act"}
+_TIMING_COLS = {"start", "end", "duration"}
+
+
+def _load_df(path: str) -> pd.DataFrame:
+    p = Path(path)
+    if p.suffix in (".parquet", ".pq"):
+        try:
+            return pd.read_parquet(p)
+        except ImportError:
+            sys.exit(f"Reading {p} requires pyarrow: pip install pyarrow")
+    return pd.read_csv(p)
+
+
+def _validate_schedule(df: pd.DataFrame, path: str) -> None:
+    cols = set(df.columns)
+    missing_required = _REQUIRED_SCHEDULE_COLS - cols
+    if missing_required:
+        sys.exit(f"{path}: missing required columns {sorted(missing_required)}")
+    timing_present = _TIMING_COLS & cols
+    if len(timing_present) < 2:
+        sys.exit(
+            f"{path}: at least two of {sorted(_TIMING_COLS)} are required; "
+            f"found only {sorted(timing_present)}"
+        )
+
+
+def _derive_timing(df: pd.DataFrame) -> pd.DataFrame:
+    """Derive the missing timing column when only two of start/end/duration are present."""
+    has_start = "start" in df.columns
+    has_end = "end" in df.columns
+    has_dur = "duration" in df.columns
+    if has_start and has_end and not has_dur:
+        df = df.copy()
+        df["duration"] = df["end"] - df["start"]
+    elif has_start and has_dur and not has_end:
+        df = df.copy()
+        df["end"] = df["start"] + df["duration"]
+    elif has_end and has_dur and not has_start:
+        df = df.copy()
+        df["start"] = df["end"] - df["duration"]
+    return df
+
+
+def _validate_attrs(df: pd.DataFrame, path: str, split_on: list | None = None) -> None:
+    if "pid" not in df.columns:
+        sys.exit(f"{path}: attributes file missing required column 'pid'")
+    if split_on:
+        missing = [c for c in split_on if c not in df.columns]
+        if missing:
+            sys.exit(f"{path}: missing split-on columns {missing}")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="acteval",
+        description="Compare synthetic activity schedules against observed data.",
+    )
+    p.add_argument("target", help="Path to observed schedules (CSV or Parquet)")
+    p.add_argument(
+        "--model",
+        nargs=2,
+        metavar=("NAME", "PATH"),
+        action="append",
+        required=True,
+        help="Synthetic model to compare (repeatable)",
+    )
+    p.add_argument(
+        "--attrs",
+        nargs=2,
+        metavar=("NAME", "PATH"),
+        action="append",
+        help="Per-model attributes file (repeatable; NAME must match a --model NAME)",
+    )
+    p.add_argument(
+        "--target-attrs", metavar="PATH", help="Attributes for the target population"
+    )
+    p.add_argument(
+        "--split-on",
+        nargs="+",
+        metavar="COL",
+        help="Attribute columns to split evaluation on (requires --target-attrs)",
+    )
+    p.add_argument("--config", metavar="PATH", help="Path to custom config.toml")
+    p.add_argument(
+        "--level",
+        choices=["domains", "groups", "features"],
+        default="domains",
+        help="Aggregation level to display (default: domains)",
+    )
+    p.add_argument("--output", metavar="DIR", help="Directory to save CSV results")
+    p.add_argument(
+        "--verbose", action="store_true", help="Print all aggregation levels"
+    )
+    return p
+
+
+def _run(args: argparse.Namespace) -> None:
+    # --- load target ---
+    target = _load_df(args.target)
+    _validate_schedule(target, args.target)
+    target = _derive_timing(target)
+
+    # --- load synthetic models ---
+    synthetic: dict[str, pd.DataFrame] = {}
+    for name, path in args.model:
+        if name in synthetic:
+            sys.exit(f"Duplicate --model name '{name}'")
+        df = _load_df(path)
+        _validate_schedule(df, path)
+        synthetic[name] = _derive_timing(df)
+
+    # --- load per-model attributes ---
+    attributes: dict[str, pd.DataFrame] | None = None
+    if args.attrs:
+        attributes = {}
+        for name, path in args.attrs:
+            if name not in synthetic:
+                sys.exit(f"--attrs NAME '{name}' does not match any --model NAME")
+            if name in attributes:
+                sys.exit(f"Duplicate --attrs name '{name}'")
+            df = _load_df(path)
+            if args.split_on:
+                _validate_attrs(df, path, args.split_on)
+            else:
+                _validate_attrs(df, path)
+            attributes[name] = df
+
+    # --- validate split-on consistency ---
+    if bool(args.split_on) != bool(args.target_attrs):
+        sys.exit("--split-on and --target-attrs must be supplied together")
+
+    if args.split_on:
+        missing_attrs = [n for n in synthetic if n not in (attributes or {})]
+        if missing_attrs:
+            sys.exit(
+                f"--split-on requires --attrs for every model; missing: {missing_attrs}"
+            )
+
+    # --- load target attributes ---
+    target_attributes: pd.DataFrame | None = None
+    if args.target_attrs:
+        target_attributes = _load_df(args.target_attrs)
+        _validate_attrs(target_attributes, args.target_attrs, args.split_on)
+
+    # --- evaluate ---
+    print(f"acteval — comparing {len(synthetic)} model(s) to {args.target}\n")
+    evaluator = Evaluator(
+        target,
+        target_attributes=target_attributes,
+        split_on=args.split_on,
+        config_path=args.config,
+    )
+    result = evaluator.compare(synthetic, attributes=attributes, verbose=args.verbose)
+
+    # --- print results ---
+    levels_to_print = {"domains"}
+    if args.verbose:
+        levels_to_print = {"features", "groups", "domains"}
+    elif args.level != "domains":
+        levels_to_print = {args.level, "domains"}
+
+    if "features" in levels_to_print:
+        print("Feature distances:")
+        print_markdown(result.features.combined.distances)
+        if result.has_splits:
+            print("\nFeature distances by attribute:")
+            print_markdown(result.features.by_attribute.distances)
+
+    if "groups" in levels_to_print:
+        print("\nGroup distances:")
+        print_markdown(result.groups.combined.distances)
+        if result.has_splits:
+            print("\nGroup distances by attribute:")
+            print_markdown(result.groups.by_attribute.distances)
+
+    if "domains" in levels_to_print:
+        print("\nDomain distances (lower is better):")
+        print_markdown(result.domains.combined.distances)
+        if result.has_splits:
+            print("\nDomain distances by attribute:")
+            print_markdown(result.domains.by_attribute.distances)
+
+    ranked = result.rank_models()
+    print(f"\nMean distance: {dict(ranked)}")
+    print(f"Best model: {result.best_model}")
+
+    # --- save ---
+    if args.output:
+        result.save(args.output)
+        print(f"\nResults saved to {args.output}")
+
+
+def main() -> None:
+    parser = _build_parser()
+    args = parser.parse_args()
+    _run(args)

acteval-0.1.2/tests/test_cli.py

@@ -0,0 +1,280 @@
+"""Tests for the acteval CLI (_build_parser and _run)."""
+
+import argparse
+import os
+
+import pandas as pd
+import pytest
+
+from acteval.cli import _build_parser, _run, _validate_schedule
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+_OBSERVED_ROWS = [
+    {"pid": 0, "act": "home", "start": 0, "end": 8, "duration": 8},
+    {"pid": 0, "act": "work", "start": 8, "end": 16, "duration": 8},
+    {"pid": 0, "act": "home", "start": 16, "end": 24, "duration": 8},
+    {"pid": 1, "act": "home", "start": 0, "end": 10, "duration": 10},
+    {"pid": 1, "act": "work", "start": 10, "end": 20, "duration": 10},
+    {"pid": 1, "act": "home", "start": 20, "end": 24, "duration": 4},
+]
+
+_SYNTHETIC_ROWS = [
+    {"pid": 0, "act": "home", "start": 0, "end": 9, "duration": 9},
+    {"pid": 0, "act": "work", "start": 9, "end": 17, "duration": 8},
+    {"pid": 0, "act": "home", "start": 17, "end": 24, "duration": 7},
+    {"pid": 1, "act": "home", "start": 0, "end": 8, "duration": 8},
+    {"pid": 1, "act": "work", "start": 8, "end": 16, "duration": 8},
+    {"pid": 1, "act": "home", "start": 16, "end": 24, "duration": 8},
+]
+
+
+@pytest.fixture
+def csv_files(tmp_path):
+    """Write observed and synthetic schedule CSVs; return their paths."""
+    obs_path = tmp_path / "observed.csv"
+    syn_path = tmp_path / "synthetic.csv"
+    pd.DataFrame(_OBSERVED_ROWS).to_csv(obs_path, index=False)
+    pd.DataFrame(_SYNTHETIC_ROWS).to_csv(syn_path, index=False)
+    return str(obs_path), str(syn_path)
+
+
+@pytest.fixture
+def attrs_csv(tmp_path):
+    """Write a simple attrs CSV and return its path."""
+    attrs = pd.DataFrame({"pid": [0, 1], "gender": ["m", "f"]})
+    p = tmp_path / "attrs.csv"
+    attrs.to_csv(p, index=False)
+    return str(p)
+
+
+def _make_args(target, model_pairs, **kwargs):
+    """Build a minimal argparse.Namespace for _run."""
+    defaults = dict(
+        target=target,
+        model=list(model_pairs),
+        attrs=None,
+        target_attrs=None,
+        split_on=None,
+        config=None,
+        level="domains",
+        output=None,
+        verbose=False,
+    )
+    defaults.update(kwargs)
+    return argparse.Namespace(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# Parser tests
+# ---------------------------------------------------------------------------
+
+
+def test_build_parser_returns_parser():
+    p = _build_parser()
+    assert isinstance(p, argparse.ArgumentParser)
+    assert p.prog == "acteval"
+
+
+def test_parser_requires_target_and_model():
+    p = _build_parser()
+    with pytest.raises(SystemExit):
+        p.parse_args([])
+
+
+def test_parser_minimal():
+    p = _build_parser()
+    args = p.parse_args(["obs.csv", "--model", "m1", "syn.csv"])
+    assert args.target == "obs.csv"
+    assert args.model == [["m1", "syn.csv"]]
+    assert args.level == "domains"
+    assert args.verbose is False
+
+
+def test_parser_multiple_models():
+    p = _build_parser()
+    args = p.parse_args(["obs.csv", "--model", "a", "a.csv", "--model", "b", "b.csv"])
+    assert args.model == [["a", "a.csv"], ["b", "b.csv"]]
+
+
+def test_parser_level_choices():
+    p = _build_parser()
+    for level in ("domains", "groups", "features"):
+        args = p.parse_args(["obs.csv", "--model", "m", "s.csv", "--level", level])
+        assert args.level == level
+
+    with pytest.raises(SystemExit):
+        p.parse_args(["obs.csv", "--model", "m", "s.csv", "--level", "invalid"])
+
+
+# ---------------------------------------------------------------------------
+# _validate_schedule tests
+# ---------------------------------------------------------------------------
+
+
+def test_validate_schedule_all_columns_ok():
+    df = pd.DataFrame(_OBSERVED_ROWS)
+    _validate_schedule(df, "dummy.csv")  # should not raise or exit
+
+
+def test_validate_schedule_start_end_only():
+    df = pd.DataFrame([{"pid": 0, "act": "home", "start": 0, "end": 8}])
+    _validate_schedule(df, "dummy.csv")  # start + end → no error
+
+
+def test_validate_schedule_start_duration_only():
+    df = pd.DataFrame([{"pid": 0, "act": "home", "start": 0, "duration": 8}])
+    _validate_schedule(df, "dummy.csv")  # start + duration → no error
+
+
+def test_validate_schedule_end_duration_only():
+    df = pd.DataFrame([{"pid": 0, "act": "home", "end": 8, "duration": 8}])
+    _validate_schedule(df, "dummy.csv")  # end + duration → no error
+
+
+def test_validate_schedule_missing_pid_exits():
+    df = pd.DataFrame([{"act": "home", "start": 0, "end": 8}])
+    with pytest.raises(SystemExit) as exc:
+        _validate_schedule(df, "bad.csv")
+    assert "pid" in str(exc.value.code)
+
+
+def test_validate_schedule_missing_act_exits():
+    df = pd.DataFrame([{"pid": 0, "start": 0, "end": 8}])
+    with pytest.raises(SystemExit):
+        _validate_schedule(df, "bad.csv")
+
+
+def test_validate_schedule_only_one_timing_col_exits():
+    df = pd.DataFrame([{"pid": 0, "act": "home", "start": 0}])
+    with pytest.raises(SystemExit):
+        _validate_schedule(df, "bad.csv")
+
+
+def test_validate_schedule_no_timing_cols_exits():
+    df = pd.DataFrame([{"pid": 0, "act": "home"}])
+    with pytest.raises(SystemExit):
+        _validate_schedule(df, "bad.csv")
+
+
+# ---------------------------------------------------------------------------
+# _run — success paths
+# ---------------------------------------------------------------------------
+
+
+def test_run_basic(csv_files, capsys):
+    obs_path, syn_path = csv_files
+    args = _make_args(obs_path, [["m1", syn_path]])
+    _run(args)
+    out = capsys.readouterr().out
+    assert "Domain distances" in out
+    assert "Best model" in out
+
+
+def test_run_two_models(csv_files, capsys):
+    obs_path, syn_path = csv_files
+    args = _make_args(obs_path, [["m1", syn_path], ["m2", syn_path]])
+    _run(args)
+    out = capsys.readouterr().out
+    assert "m1" in out
+    assert "m2" in out
+
+
+def test_run_start_end_only_input(tmp_path, capsys):
+    """_run should work with schedules that only have start + end (no duration)."""
+    rows = [
+        {"pid": 0, "act": "home", "start": 0, "end": 8},
+        {"pid": 0, "act": "work", "start": 8, "end": 16},
+        {"pid": 1, "act": "home", "start": 0, "end": 12},
+        {"pid": 1, "act": "work", "start": 12, "end": 24},
+    ]
+    p = tmp_path / "sched.csv"
+    pd.DataFrame(rows).to_csv(p, index=False)
+    args = _make_args(str(p), [["m1", str(p)]])
+    _run(args)
+    out = capsys.readouterr().out
+    assert "Domain distances" in out
+
+
+def test_run_saves_output(csv_files, tmp_path, capsys):
+    obs_path, syn_path = csv_files
+    out_dir = str(tmp_path / "results")
+    args = _make_args(obs_path, [["m1", syn_path]], output=out_dir)
+    _run(args)
+    assert os.path.isdir(out_dir)
+    out = capsys.readouterr().out
+    assert "Results saved" in out
+
+
+# ---------------------------------------------------------------------------
+# _run — validation/error paths
+# ---------------------------------------------------------------------------
+
+
+def test_run_duplicate_model_name_exits(csv_files):
+    obs_path, syn_path = csv_files
+    args = _make_args(obs_path, [["m1", syn_path], ["m1", syn_path]])
+    with pytest.raises(SystemExit):
+        _run(args)
+
+
+def test_run_attrs_name_not_in_model_exits(csv_files, attrs_csv):
+    obs_path, syn_path = csv_files
+    args = _make_args(obs_path, [["m1", syn_path]])
+    args.attrs = [["unknown", attrs_csv]]
+    with pytest.raises(SystemExit):
+        _run(args)
+
+
+def test_run_duplicate_attrs_name_exits(csv_files, attrs_csv):
+    obs_path, syn_path = csv_files
+    args = _make_args(obs_path, [["m1", syn_path]])
+    args.attrs = [["m1", attrs_csv], ["m1", attrs_csv]]
+    with pytest.raises(SystemExit):
+        _run(args)
+
+
+def test_run_split_on_without_target_attrs_exits(csv_files):
+    obs_path, syn_path = csv_files
+    args = _make_args(obs_path, [["m1", syn_path]])
+    args.split_on = ["gender"]
+    with pytest.raises(SystemExit):
+        _run(args)
+
+
+def test_run_target_attrs_without_split_on_exits(csv_files, attrs_csv):
+    obs_path, syn_path = csv_files
+    args = _make_args(obs_path, [["m1", syn_path]])
+    args.target_attrs = attrs_csv
+    with pytest.raises(SystemExit):
+        _run(args)
+
+
+def test_run_split_on_missing_model_attrs_exits(csv_files, attrs_csv):
+    obs_path, syn_path = csv_files
+    args = _make_args(obs_path, [["m1", syn_path]])
+    args.target_attrs = attrs_csv
+    args.split_on = ["gender"]
+    # No per-model attrs supplied — should exit
+    with pytest.raises(SystemExit):
+        _run(args)
+
+
+def test_run_target_schedule_missing_pid_exits(tmp_path, csv_files):
+    _, syn_path = csv_files
+    bad = tmp_path / "bad.csv"
+    pd.DataFrame([{"act": "home", "start": 0, "end": 8}]).to_csv(bad, index=False)
+    args = _make_args(str(bad), [["m1", syn_path]])
+    with pytest.raises(SystemExit):
+        _run(args)
+
+
+def test_run_model_schedule_only_one_timing_col_exits(tmp_path, csv_files):
+    obs_path, _ = csv_files
+    bad = tmp_path / "bad.csv"
+    pd.DataFrame([{"pid": 0, "act": "home", "start": 0}]).to_csv(bad, index=False)
+    args = _make_args(obs_path, [["m1", str(bad)]])
+    with pytest.raises(SystemExit):
+        _run(args)