activitymodel 0.1.0__py3-none-any.whl

activitymodel/diagnostics/profiles.py

@@ -0,0 +1,59 @@
+"""Per-slot activity probability matrices (144 x activities)."""
+
+from __future__ import annotations
+
+import numpy as np
+import polars as pl
+
+from ..taxonomy import get_level
+
+
+def activity_probability_matrix(
+    codes: np.ndarray, level: str = "detailed", weights: np.ndarray | None = None
+) -> np.ndarray:
+    """Share of (weighted) days in each activity at each slot; rows sum to 1.
+
+    Args:
+        codes: ``uint8`` matrix ``(n_days, n_slots)`` of detailed codes.
+        level: taxonomy level of the output columns.
+        weights: optional per-day weights.
+    """
+    lvl = get_level(level)
+    projected = lvl.project(np.asarray(codes, dtype=np.uint8))
+    n_days, n_slots = projected.shape
+    w = np.ones(n_days) if weights is None else np.asarray(weights, dtype=float)
+    matrix = np.zeros((n_slots, lvl.n_activities))
+    for a in range(lvl.n_activities):
+        matrix[:, a] = ((projected == a) * w[:, None]).sum(axis=0)
+    totals = matrix.sum(axis=1, keepdims=True)
+    totals[totals == 0] = 1.0
+    return matrix / totals
+
+
+def profile_frame(
+    matrix: np.ndarray, level: str = "detailed", slot_minutes: int = 10
+) -> pl.DataFrame:
+    """Long frame ``slot``, ``hour``, ``activity``, ``share`` from a probability matrix."""
+    lvl = get_level(level)
+    n_slots = matrix.shape[0]
+    return pl.DataFrame(
+        {
+            "slot": np.repeat(np.arange(n_slots), lvl.n_activities),
+            "hour": np.repeat(np.arange(n_slots) * slot_minutes / 60, lvl.n_activities),
+            "activity": np.tile(np.array(lvl.activities, dtype=object), n_slots),
+            "share": matrix.ravel(),
+        }
+    )
+
+
+def calendar_profile(calendar, day_type: str | None = None, level: str = "detailed") -> np.ndarray:
+    """Mean daily profile of an :class:`~activitymodel.calendar.AnnualCalendar`.
+
+    Every (occupant, date) pair counts once; ``day_type`` restricts the dates.
+    """
+    from ..calendar import day_types_for_dates
+
+    idx = calendar.day_index
+    if day_type is not None:
+        idx = idx[:, day_types_for_dates(calendar.dates) == day_type]
+    return activity_probability_matrix(calendar.library.codes[idx.ravel()], level=level)

activitymodel/exceptions.py

@@ -0,0 +1,21 @@
+"""Typed exceptions so callers can tell a bad input from a broken contract."""
+
+
+class ActivityModelError(Exception):
+    """Base class for every error raised by activitymodel."""
+
+
+class VocabularyError(ActivityModelError):
+    """A frame carries a value outside the shared socio-demographic vocabulary."""
+
+
+class TaxonomyError(ActivityModelError):
+    """An activity code or activity name is unknown to the taxonomy."""
+
+
+class LibraryValidationError(ActivityModelError):
+    """A diary library breaks the published dataset contract."""
+
+
+class MatchingError(ActivityModelError):
+    """Occupants could not be assigned a cluster even at the coarsest ladder level."""

activitymodel/harmonise.py

@@ -0,0 +1,269 @@
+"""Map the survey and the census onto the shared vocabulary.
+
+Two public functions, one per source, both *adding* the harmonised columns of
+:data:`activitymodel.vocabulary.HARMONISED_COLUMNS` to the frame they receive so
+that identifiers and passthrough columns survive:
+
+* :func:`harmonise_survey_individuals` - Enquete Emploi du temps ``individu``
+  (+ ``menage`` for the household size).
+* :func:`harmonise_census_individuals` - INSEE RP ``indcvi`` individual file
+  (the "Fichier detail individus localises au canton-ou-ville").
+
+Both are total: an input code outside the documented code list is an error,
+not a null, because a null on either side silently removes the person from
+every matching level but the last.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import polars as pl
+
+from .exceptions import VocabularyError
+from .vocabulary import (
+    CSP_GROUP,
+    DEFAULT_AGE_CLASSES,
+    AgeClasses,
+    check_vocabulary,
+    employment_status_expr,
+    household_size_class_expr,
+)
+
+# --------------------------------------------------------------------------- #
+# Survey side (EDT 2009-2010)
+# --------------------------------------------------------------------------- #
+
+#: ``situa`` -> activity status (codebook: 1 employed, 2 apprentice, 3 student
+#: or unpaid intern, 4 unemployed, 5 retired, 6 homemaker, 7 other).
+_SITUA_TO_STATUS = {
+    "1": "employed",
+    "2": "employed",
+    "3": "student",
+    "4": "unemployed",
+    "5": "retired",
+    "6": "homemaker",
+    "7": "other_inactive",
+}
+
+#: First digit of ``cs24`` -> socio-professional group of the employed.
+_CS_DIGIT_TO_GROUP = {str(i + 1): g for i, g in enumerate(CSP_GROUP)}
+
+#: ``lienpref`` -> household position (00 reference person, 01 partner,
+#: 02 child; every other code is another relative or unrelated member).
+_LIENPREF_TO_POSITION = {"00": "reference_person", "01": "partner", "02": "child"}
+
+#: Census age below which a person is "under 14" (TACT 23). Applied to the
+#: survey so the two ``child`` classes mean the same thing.
+CHILD_AGE_LIMIT = 14
+
+
+def _strip(column: str) -> pl.Expr:
+    return pl.col(column).cast(pl.String).str.strip_chars()
+
+
+def harmonise_survey_individuals(
+    individuals: pl.DataFrame,
+    households: pl.DataFrame,
+    age_classes: AgeClasses = DEFAULT_AGE_CLASSES,
+) -> pl.DataFrame:
+    """Add the shared vocabulary columns to the survey ``individu`` table.
+
+    Args:
+        individuals: the ``individu`` table with at least ``idind``, ``idmen``,
+            ``sexe``, ``age``, ``situa``, ``cs24``, ``couple``, ``lienpref``
+            and ``pond_qi``.
+        households: the ``menage`` table with ``idmen`` and ``npers``.
+        age_classes: age bands to use.
+
+    Returns:
+        ``individuals`` plus ``person_id``, ``household_id``, ``weight`` and
+        the harmonised columns.
+
+    Raises:
+        VocabularyError: a required column is missing or a code is unknown.
+    """
+    required = {"idind", "idmen", "sexe", "age", "situa", "cs24", "couple", "lienpref"}
+    missing = required - set(individuals.columns)
+    if missing:
+        raise VocabularyError(f"survey individuals are missing columns {sorted(missing)}")
+    if not {"idmen", "npers"} <= set(households.columns):
+        raise VocabularyError("survey households need columns 'idmen' and 'npers'")
+
+    sizes = households.select(
+        pl.col("idmen").cast(pl.String), pl.col("npers").cast(pl.Int64).alias("household_size")
+    ).unique("idmen")
+    weight = pl.col("pond_qi").cast(pl.Float64) if "pond_qi" in individuals.columns else pl.lit(1.0)
+
+    out = (
+        individuals.with_columns(pl.col("idmen").cast(pl.String))
+        .join(sizes, on="idmen", how="left")
+        .with_columns(
+            person_id=pl.col("idind").cast(pl.String),
+            household_id=pl.col("idmen"),
+            weight=weight,
+            sex=_strip("sexe").replace_strict({"1": "male", "2": "female"}, default=None),
+            age=pl.col("age").cast(pl.Float64).round(0).cast(pl.Int64),
+            activity_status=_strip("situa").replace_strict(_SITUA_TO_STATUS, default=None),
+            csp_group=_strip("cs24")
+            .str.slice(0, 1)
+            .replace_strict(_CS_DIGIT_TO_GROUP, default=None),
+            couple_status=pl.when(_strip("couple") == "1")
+            .then(pl.lit("in_couple"))
+            .otherwise(pl.lit("not_in_couple")),
+            household_position=_strip("lienpref").replace_strict(
+                _LIENPREF_TO_POSITION, default="other"
+            ),
+        )
+        .with_columns(
+            activity_status=pl.when(pl.col("age") < CHILD_AGE_LIMIT)
+            .then(pl.lit("child"))
+            .otherwise(pl.col("activity_status")),
+            age_class=age_classes.expr("age"),
+            household_size_class=household_size_class_expr("household_size"),
+        )
+        .with_columns(employment_status=employment_status_expr())
+    )
+    check_vocabulary(
+        out,
+        columns=(
+            "sex",
+            "age_class",
+            "activity_status",
+            "csp_group",
+            "employment_status",
+            "couple_status",
+            "household_position",
+            "household_size_class",
+        ),
+        age_classes=age_classes,
+        allow_null=("csp_group",),
+        name="survey individuals",
+    )
+    return out
+
+
+# --------------------------------------------------------------------------- #
+# Census side (INSEE RP indcvi)
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class CensusColumns:
+    """Column names of the individual census file (INSEE vintage-dependent)."""
+
+    sex: str = "SEXE"
+    age: str = "AGED"
+    activity: str = "TACT"
+    csp: str = "CS1"
+    couple: str = "COUPLE"
+    position: str = "LPRM"
+    household_size: str = "INPER"
+    weight: str = "IPONDI"
+
+    def required(self) -> tuple[str, ...]:
+        return (
+            self.sex,
+            self.age,
+            self.activity,
+            self.csp,
+            self.couple,
+            self.position,
+            self.household_size,
+        )
+
+
+DEFAULT_CENSUS_COLUMNS = CensusColumns()
+
+#: ``TACT`` -> activity status (11 employed, 12 unemployed, 21 retired,
+#: 22 pupils/students 14+, 23 under 14, 24 homemakers, 25 other inactive).
+_TACT_TO_STATUS = {
+    "11": "employed",
+    "12": "unemployed",
+    "21": "retired",
+    "22": "student",
+    "23": "child",
+    "24": "homemaker",
+    "25": "other_inactive",
+}
+
+#: ``LPRM`` -> household position (1 reference person, 2 partner, 3 child,
+#: 4-8 other relatives and non relatives). ``Z`` = not in an ordinary
+#: household (communities), dropped by the caller or here.
+_LPRM_TO_POSITION = {"1": "reference_person", "2": "partner", "3": "child"}
+
+
+def harmonise_census_individuals(
+    census: pl.DataFrame,
+    age_classes: AgeClasses = DEFAULT_AGE_CLASSES,
+    columns: CensusColumns = DEFAULT_CENSUS_COLUMNS,
+    drop_out_of_household: bool = True,
+) -> pl.DataFrame:
+    """Add the shared vocabulary columns to an INSEE ``indcvi`` frame.
+
+    Args:
+        census: individual census rows (any subset of columns is kept).
+        age_classes: age bands to use.
+        columns: source column names, see :class:`CensusColumns`.
+        drop_out_of_household: drop people living in communities (``LPRM == Z``),
+            who have no dwelling to be matched to.
+
+    Returns:
+        ``census`` plus ``weight`` and the harmonised columns.
+
+    Raises:
+        VocabularyError: a required column is missing or a code is unknown.
+    """
+    missing = set(columns.required()) - set(census.columns)
+    if missing:
+        raise VocabularyError(f"census individuals are missing columns {sorted(missing)}")
+
+    out = census
+    if drop_out_of_household:
+        out = out.filter(_strip(columns.position) != "Z")
+    weight = (
+        pl.col(columns.weight).cast(pl.Float64) if columns.weight in out.columns else pl.lit(1.0)
+    )
+    out = (
+        out.with_columns(
+            weight=weight,
+            sex=_strip(columns.sex).replace_strict({"1": "male", "2": "female"}, default=None),
+            age=_strip(columns.age).cast(pl.Int64, strict=False),
+            activity_status=_strip(columns.activity).replace_strict(_TACT_TO_STATUS, default=None),
+            csp_group=_strip(columns.csp).replace_strict(_CS_DIGIT_TO_GROUP, default=None),
+            couple_status=pl.when(_strip(columns.couple) == "1")
+            .then(pl.lit("in_couple"))
+            .otherwise(pl.lit("not_in_couple")),
+            household_position=_strip(columns.position).replace_strict(
+                _LPRM_TO_POSITION, default="other"
+            ),
+            household_size=_strip(columns.household_size).cast(pl.Int64, strict=False),
+        )
+        .with_columns(
+            age_class=age_classes.expr("age"),
+            household_size_class=household_size_class_expr("household_size"),
+        )
+        .with_columns(employment_status=employment_status_expr())
+    )
+    if out.get_column("age").null_count():
+        raise VocabularyError(f"census column {columns.age!r} holds non-numeric ages")
+    check_vocabulary(
+        out,
+        columns=(
+            "sex",
+            "age_class",
+            "activity_status",
+            "csp_group",
+            "employment_status",
+            "couple_status",
+            "household_position",
+            "household_size_class",
+        ),
+        age_classes=age_classes,
+        # Household size is unknown for people outside ordinary households
+        # (kept only on request); a null key falls through to the coarser
+        # ladder levels instead of failing the harmonisation.
+        allow_null=("csp_group", "household_size_class"),
+        name="census individuals",
+    )
+    return out

activitymodel/library.py

@@ -0,0 +1,325 @@
+"""The diary library: the dataset activitymodel publishes and consumes.
+
+A :class:`DiaryLibrary` is what the buildingdata pipeline builds from the
+survey and what building_eload downloads. It is made of three tables and a
+manifest, each stored as its own parquet blob (buildingdata's one-blob-per-table
+convention):
+
+``days``
+    One row per survey day kept in the pool: ``day_id``, ``day_type``,
+    ``cluster_id``, ``weight`` and the 144 ``slot_000..slot_143`` ``UInt8``
+    detailed activity codes. No survey identifier and no socio-demographic
+    attribute is attached to a day.
+``clusters``
+    One row per cluster: ``cluster_id``, ``day_type``, ``cluster_index``,
+    ``n_days``, ``weight_sum``.
+``patterns``
+    The aggregate link between people and clusters: one row per combination of
+    matching-key values and per-day-type cluster triple, with the summed person
+    weight and person count. Coarser matching levels are obtained by summing
+    rows, so only the finest level is stored.
+``manifest``
+    Key/value table (JSON-encoded values) recording the taxonomy, the day
+    types, the matching keys, the clustering parameters and the provenance.
+
+The three tables together contain no row of survey microdata: the days are
+detached from the people, the people are aggregated into cells.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+import polars as pl
+
+from .exceptions import LibraryValidationError
+from .taxonomy import DETAILED_ACTIVITIES, N_DETAILED, get_level
+from .vocabulary import AgeClasses
+
+SLOTS_PER_DAY = 144
+SLOT_MINUTES = 10
+#: Clock the slot columns are expressed in: the survey records local time.
+CLOCK = "Europe/Paris"
+
+SLOT_COLUMNS: tuple[str, ...] = tuple(f"slot_{i:03d}" for i in range(SLOTS_PER_DAY))
+
+DAY_META_SCHEMA = {
+    "day_id": pl.UInt32,
+    "day_type": pl.String,
+    "cluster_id": pl.Int16,
+    "weight": pl.Float64,
+}
+CLUSTER_SCHEMA = {
+    "cluster_id": pl.Int16,
+    "day_type": pl.String,
+    "cluster_index": pl.Int16,
+    "n_days": pl.UInt32,
+    "weight_sum": pl.Float64,
+}
+PATTERN_VALUE_SCHEMA = {"weight": pl.Float64, "n_persons": pl.UInt32}
+
+TABLE_NAMES = ("days", "clusters", "patterns", "manifest")
+
+
+def cluster_column(day_type: str) -> str:
+    return f"cluster_{day_type}"
+
+
+@dataclass
+class DiaryLibrary:
+    """Clustered diary pool plus the aggregate socio-demographic link to it."""
+
+    days: pl.DataFrame
+    clusters: pl.DataFrame
+    patterns: pl.DataFrame
+    manifest: dict
+    _codes: np.ndarray | None = field(default=None, repr=False, compare=False)
+
+    # ------------------------------------------------------------------ #
+    # Manifest-backed properties
+    # ------------------------------------------------------------------ #
+    @property
+    def day_types(self) -> tuple[str, ...]:
+        return tuple(self.manifest["day_types"])
+
+    @property
+    def matching_keys(self) -> tuple[str, ...]:
+        return tuple(self.manifest["matching_keys"])
+
+    @property
+    def activities(self) -> tuple[str, ...]:
+        return tuple(self.manifest["activities"])
+
+    @property
+    def age_classes(self) -> AgeClasses:
+        return AgeClasses(bounds=tuple(self.manifest["age_class_bounds"]))
+
+    @property
+    def cluster_columns(self) -> list[str]:
+        return [cluster_column(d) for d in self.day_types]
+
+    @property
+    def codes(self) -> np.ndarray:
+        """``uint8`` matrix ``(n_days, 144)`` of detailed activity codes (cached)."""
+        if self._codes is None:
+            self._codes = np.ascontiguousarray(
+                self.days.select(list(SLOT_COLUMNS)).to_numpy().astype(np.uint8)
+            )
+        return self._codes
+
+    @property
+    def n_days(self) -> int:
+        return self.days.height
+
+    # ------------------------------------------------------------------ #
+    # Construction and IO
+    # ------------------------------------------------------------------ #
+    @classmethod
+    def from_frames(
+        cls,
+        days: pl.DataFrame,
+        clusters: pl.DataFrame,
+        patterns: pl.DataFrame,
+        manifest: pl.DataFrame | dict,
+        validate: bool = True,
+    ) -> DiaryLibrary:
+        """Assemble a library from its tables (as read from buildingdata)."""
+        if isinstance(manifest, pl.DataFrame):
+            manifest = manifest_from_frame(manifest)
+        library = cls(days=days, clusters=clusters, patterns=patterns, manifest=dict(manifest))
+        if validate:
+            library.validate()
+        return library
+
+    def to_frames(self) -> dict[str, pl.DataFrame]:
+        """The four tables keyed by :data:`TABLE_NAMES`, manifest as a key/value frame."""
+        return {
+            "days": self.days,
+            "clusters": self.clusters,
+            "patterns": self.patterns,
+            "manifest": manifest_to_frame(self.manifest),
+        }
+
+    def write(self, directory: str | Path) -> dict[str, Path]:
+        """Write ``<table>.parquet`` for each table plus a readable ``manifest.json``."""
+        directory = Path(directory)
+        directory.mkdir(parents=True, exist_ok=True)
+        paths = {}
+        for name, frame in self.to_frames().items():
+            paths[name] = directory / f"{name}.parquet"
+            frame.write_parquet(paths[name])
+        (directory / "manifest.json").write_text(
+            json.dumps(self.manifest, indent=2, sort_keys=True)
+        )
+        return paths
+
+    @classmethod
+    def read(cls, directory: str | Path, validate: bool = True) -> DiaryLibrary:
+        """Read a library written by :meth:`write`."""
+        directory = Path(directory)
+        frames = {name: pl.read_parquet(directory / f"{name}.parquet") for name in TABLE_NAMES}
+        return cls.from_frames(validate=validate, **frames)
+
+    # ------------------------------------------------------------------ #
+    # Contract
+    # ------------------------------------------------------------------ #
+    def validate(self) -> None:
+        """Check the published contract; raise :class:`LibraryValidationError`.
+
+        Every clause names the silent downstream failure it prevents.
+        """
+        m = self.manifest
+        for key in ("activities", "day_types", "matching_keys", "age_class_bounds", "slot_minutes"):
+            if key not in m:
+                raise LibraryValidationError(f"manifest lacks {key!r}")
+        if tuple(m["activities"]) != DETAILED_ACTIVITIES:
+            # A library built with another taxonomy would be decoded with the
+            # wrong names by every consumer.
+            raise LibraryValidationError(
+                "manifest activities differ from this activitymodel taxonomy; "
+                "rebuild the library or upgrade activitymodel"
+            )
+        if int(m["slot_minutes"]) != SLOT_MINUTES:
+            raise LibraryValidationError(
+                "only 10-minute slots are supported (building_eload hardcodes 144/day)"
+            )
+
+        _require_schema(self.days, DAY_META_SCHEMA, "days")
+        missing = [c for c in SLOT_COLUMNS if c not in self.days.columns]
+        if missing:
+            raise LibraryValidationError(
+                f"days lacks {len(missing)} slot columns (first {missing[:3]})"
+            )
+        slot_dtypes = {self.days.schema[c] for c in SLOT_COLUMNS}
+        if slot_dtypes != {pl.UInt8}:
+            raise LibraryValidationError(f"slot columns must be UInt8, found {slot_dtypes}")
+        if self.days.height == 0:
+            raise LibraryValidationError("days is empty")
+        if self.days.get_column("day_id").n_unique() != self.days.height:
+            raise LibraryValidationError("day_id is not unique")
+        if (
+            self.days.select(
+                pl.any_horizontal(
+                    [pl.col(c).is_null() for c in list(DAY_META_SCHEMA) + list(SLOT_COLUMNS)]
+                )
+            )
+            .to_series()
+            .any()
+        ):
+            raise LibraryValidationError(
+                "days holds nulls; a null slot would become an unknown activity"
+            )
+        if (
+            int(self.days.select(pl.max_horizontal([pl.col(c).max() for c in SLOT_COLUMNS])).item())
+            >= N_DETAILED
+        ):
+            # Codes outside the taxonomy decode to garbage names downstream.
+            raise LibraryValidationError(f"slot codes must be < {N_DETAILED}")
+        if (self.days.get_column("weight") <= 0).any():
+            raise LibraryValidationError(
+                "day weights must be strictly positive (they drive the draw)"
+            )
+        bad_types = set(self.days.get_column("day_type").unique().to_list()) - set(self.day_types)
+        if bad_types:
+            raise LibraryValidationError(
+                f"days holds day types outside the manifest: {sorted(bad_types)}"
+            )
+
+        _require_schema(self.clusters, CLUSTER_SCHEMA, "clusters")
+        if self.clusters.get_column("cluster_id").n_unique() != self.clusters.height:
+            raise LibraryValidationError("cluster_id is not unique")
+        day_clusters = self.days.select("cluster_id", "day_type").unique()
+        joined = day_clusters.join(self.clusters, on="cluster_id", how="left", suffix="_c")
+        if joined.get_column("day_type_c").null_count():
+            raise LibraryValidationError("days reference cluster_ids absent from clusters")
+        if (joined.get_column("day_type") != joined.get_column("day_type_c")).any():
+            raise LibraryValidationError("a day's day_type differs from its cluster's day_type")
+        for day_type in self.day_types:
+            if self.clusters.filter(pl.col("day_type") == day_type).height == 0:
+                # Occupants would have no pool to draw that day type from.
+                raise LibraryValidationError(f"no cluster for day type {day_type!r}")
+
+        for key in self.matching_keys:
+            if key not in self.patterns.columns:
+                raise LibraryValidationError(f"patterns lacks matching key {key!r}")
+            if self.patterns.schema[key] != pl.String:
+                raise LibraryValidationError(f"patterns.{key} must be String")
+        _require_schema(self.patterns, PATTERN_VALUE_SCHEMA, "patterns")
+        for column in self.cluster_columns:
+            if column not in self.patterns.columns:
+                raise LibraryValidationError(f"patterns lacks {column!r}")
+            if self.patterns.schema[column] != pl.Int16:
+                raise LibraryValidationError(f"patterns.{column} must be Int16")
+            referenced = set(self.patterns.get_column(column).drop_nulls().unique().to_list())
+            known = set(self.clusters.get_column("cluster_id").to_list())
+            if referenced - known:
+                raise LibraryValidationError(f"patterns.{column} references unknown clusters")
+        if (
+            self.patterns.select(
+                pl.all_horizontal([pl.col(c).is_null() for c in self.cluster_columns])
+            )
+            .to_series()
+            .any()
+        ):
+            raise LibraryValidationError("a pattern row has no cluster for any day type")
+        if (self.patterns.get_column("weight") <= 0).any():
+            raise LibraryValidationError("pattern weights must be strictly positive")
+
+    # ------------------------------------------------------------------ #
+    # Convenience
+    # ------------------------------------------------------------------ #
+    def cluster_rows(self, cluster_id: int) -> np.ndarray:
+        """Row positions in :attr:`codes` of the days of ``cluster_id``."""
+        return np.flatnonzero(self.days.get_column("cluster_id").to_numpy() == cluster_id)
+
+    def cluster_profile(self, cluster_id: int, level: str = "detailed") -> np.ndarray:
+        """Weighted activity-probability matrix ``(144, activities)`` of a cluster."""
+        from .diagnostics.profiles import activity_probability_matrix
+
+        rows = self.cluster_rows(cluster_id)
+        weights = self.days.get_column("weight").to_numpy()[rows]
+        return activity_probability_matrix(self.codes[rows], level=level, weights=weights)
+
+    def summary(self) -> str:
+        lines = [
+            f"DiaryLibrary: {self.n_days} days, {self.clusters.height} clusters, "
+            f"{self.patterns.height} pattern rows",
+            f"  day types     : {', '.join(self.day_types)}",
+            f"  matching keys : {', '.join(self.matching_keys)}",
+            f"  source        : {self.manifest.get('source', {}).get('name', '?')}",
+        ]
+        for row in self.clusters.group_by("day_type").agg(pl.len()).sort("day_type").iter_rows():
+            lines.append(f"  clusters[{row[0]}] = {row[1]}")
+        return "\n".join(lines)
+
+
+def _require_schema(frame: pl.DataFrame, schema: dict, name: str) -> None:
+    for column, dtype in schema.items():
+        if column not in frame.columns:
+            raise LibraryValidationError(f"{name} lacks column {column!r}")
+        if frame.schema[column] != dtype:
+            raise LibraryValidationError(
+                f"{name}.{column} must be {dtype}, found {frame.schema[column]}"
+            )
+
+
+def manifest_to_frame(manifest: dict) -> pl.DataFrame:
+    keys = sorted(manifest)
+    return pl.DataFrame(
+        {"key": keys, "value": [json.dumps(manifest[k], sort_keys=True) for k in keys]}
+    )
+
+
+def manifest_from_frame(frame: pl.DataFrame) -> dict:
+    return {
+        k: json.loads(v)
+        for k, v in zip(frame.get_column("key"), frame.get_column("value"), strict=True)
+    }
+
+
+def project_codes(codes: np.ndarray, level: str) -> np.ndarray:
+    """Project detailed ``uint8`` codes to another taxonomy level."""
+    return get_level(level).project(codes)