Source code for ws4.patch.accounts

"""Patch accounts: the size distribution of connected patches over a topology.

A **patch** is a connected set of topologically adjacent blocks that all meet a patch
membership criterion (a block value greater than a threshold). The established model
(the Patchworks ``6.7 Patch Accounts`` section) defines, for each size class, five
sub-accounts:

``area``
    The total patch area falling in the size class, in hectares.
``size``
    The area in the size class as a percentage of the total patch area.
``shape``
    The mean compactness of the patches in the class, 0 to 100 (100 is a circle).
``frequency``
    The number of patches in the size class.

The block contribution to a patch is its criterion value times its area, so a half
disturbed block contributes half its area.

``attractor`` is the sixth sub-account the reference reports, and **WS4 refuses it**: what the
reference reports there is a per-patch size statistic that its own exported tables do not
determine (P12.4). WS4 used to write a ``1.0`` flag for it, which is not a value — see
``notes/design/ws4-parity-harness.md``, "The attractor sub-account", and the refusal in
:func:`load_patch_accounts`.
"""

from __future__ import annotations

import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from pathlib import Path

import pandas as pd

from .metrics import connected_patches

DEFAULT_SIZE_CLASSES: tuple[float, ...] = (50.0, 150.0, 250.0, 2500.0, math.inf)


[docs] @dataclass(frozen=True) class PatchAccount: """A patch account definition. Attributes ---------- name : str The account name. criteria : str The feature label used as the patch membership criterion. threshold : float The criterion value a block must exceed to join a patch. size_classes : tuple of float The size-class upper bounds, in hectares, ascending. The last may be ``inf``. search_distance : float or None The topology search distance, in metres: only edges whose endpoints are no further apart than it join a patch. The default ``0.0`` joins only blocks that literally touch (their polygons share a vertex); None considers every edge in the topology. """ name: str criteria: str threshold: float = 0.0 size_classes: tuple[float, ...] = DEFAULT_SIZE_CLASSES search_distance: float | None = 0.0
[docs] def size_class_labels(size_classes: Sequence[float]) -> tuple[str, ...]: """Return the size-class labels, such as ``('0_50', '50_150', ..., '2500_9999999')``. Parameters ---------- size_classes : sequence of float The upper bounds, ascending. Returns ------- tuple of str One label per class. """ labels: list[str] = [] lower = 0.0 for upper in size_classes: top = 9999999 if math.isinf(upper) else int(upper) labels.append(f"{int(lower)}_{top}") lower = upper return tuple(labels)
def _compactness(area_ha: float, perimeter_m: float) -> float: """Return a patch's compactness from 0 to 100 (100 is a circle). The area is converted from hectares to square metres so that it is commensurate with the perimeter, which is in metres. """ area_m2 = area_ha * 10000.0 if area_m2 <= 0.0 or perimeter_m <= 0.0: return 0.0 return min(100.0, 100.0 * 4.0 * math.pi * area_m2 / (perimeter_m * perimeter_m)) def _size_class_index(area: float, size_classes: Sequence[float]) -> int | None: """Return the index of the size class an area falls in, or None when it falls in none. Parameters ---------- area : float The patch's area, in hectares. size_classes : sequence of float The class upper bounds, ascending. Returns ------- int or None The class index, or None for an area no class contains — a zero area, or one above the last bound when that bound is finite. """ for class_index, upper in enumerate(size_classes): lower = 0.0 if class_index == 0 else size_classes[class_index - 1] if lower < area <= upper: return class_index return None
[docs] def patch_account_values( account: PatchAccount, values: Mapping[int, float], edges: Sequence[tuple[int, int, float]], block_area: Mapping[int, float], ) -> dict[str, float]: """Compute one period's patch sub-account values. Parameters ---------- account : PatchAccount The account definition. values : mapping of int to float The criterion value per block, in ``[0, 1]``. edges : sequence of (int, int, float) The adjacency edges ``(src, dst, shared_length)``. block_area : mapping of int to float The area of each block. Returns ------- dict of str to float The sub-account values, keyed ``"<class>.<sub>"`` plus ``"TOTAL.area"`` and ``"TOTAL.frequency"``. """ members = {block for block, value in values.items() if value > account.threshold} adjacency = [(source, target) for source, target, _ in edges] patches = connected_patches(members, adjacency) patch_of: dict[int, int] = {} for index, patch in enumerate(patches): for block in patch: patch_of[block] = index patch_area = [0.0] * len(patches) for block, index in patch_of.items(): patch_area[index] += values.get(block, 0.0) * block_area.get(block, 0.0) # One pass over the edges gives every patch's perimeter (the edges with exactly one # member end), instead of re-scanning all edges per patch. patch_perimeter_length = [0.0] * len(patches) for source, target, length in edges: source_patch = patch_of.get(source) target_patch = patch_of.get(target) if source_patch is not None and target_patch is None: patch_perimeter_length[source_patch] += length elif target_patch is not None and source_patch is None: patch_perimeter_length[target_patch] += length total_area = sum(patch_area) labels = size_class_labels(account.size_classes) result: dict[str, float] = {} by_label: dict[str, list[tuple[float, float, int]]] = {label: [] for label in labels} for index, area in enumerate(patch_area): compactness = _compactness(area, patch_perimeter_length[index]) class_index = _size_class_index(area, account.size_classes) if class_index is not None: by_label[labels[class_index]].append((area, compactness, len(patches[index]))) for label in labels: members_in_class = by_label[label] class_area = sum(area for area, _, _ in members_in_class) result[f"{label}.area"] = class_area result[f"{label}.size"] = (100.0 * class_area / total_area) if total_area > 0.0 else 0.0 result[f"{label}.frequency"] = float(len(members_in_class)) result[f"{label}.freqpercent"] = ( 100.0 * len(members_in_class) / len(patches) if patches else 0.0 ) result[f"{label}.blocks"] = ( sum(blocks for _, _, blocks in members_in_class) / len(members_in_class) if members_in_class else 0.0 ) result[f"{label}.shape"] = ( sum(shape for _, shape, _ in members_in_class) / len(members_in_class) if members_in_class else 0.0 ) result["TOTAL.area"] = total_area result["TOTAL.frequency"] = float(len(patches)) return result
def patch_account_values_indexed( account: PatchAccount, values: Mapping[int, float], neighbours: Mapping[int, Sequence[tuple[int, float]]], block_area: Mapping[int, float], ) -> dict[str, float]: """Compute one period's patch sub-account values from an indexed adjacency. This is :func:`patch_account_values` with the adjacency pre-grouped by block, so a period costs O(members x degree) instead of scanning every edge in the topology. The two agree exactly. Parameters ---------- account : PatchAccount The account definition. values : mapping of int to float The criterion value per block (already restricted to the members). neighbours : mapping of int to sequence of (int, float) The adjacency ``(neighbour, shared_length)`` per block. block_area : mapping of int to float The area of each block. Returns ------- dict of str to float The sub-account values, keyed ``"<class>.<sub>"`` plus ``"TOTAL.area"`` and ``"TOTAL.frequency"``. """ members = values component: dict[int, int] = {} areas: list[float] = [] perimeters: list[float] = [] blocks_per_patch: list[int] = [] for start in members: if start in component: continue index = len(areas) stack = [start] component[start] = index area = 0.0 perimeter = 0.0 blocks = 0 while stack: block = stack.pop() blocks += 1 area += values[block] * block_area.get(block, 0.0) for other, length in neighbours.get(block, ()): if other in members: if other not in component: component[other] = index stack.append(other) else: perimeter += length areas.append(area) perimeters.append(perimeter) blocks_per_patch.append(blocks) total_area = math.fsum(areas) labels = size_class_labels(account.size_classes) by_label: dict[str, list[tuple[float, float, int]]] = {label: [] for label in labels} for index, area in enumerate(areas): compactness = _compactness(area, perimeters[index]) class_index = _size_class_index(area, account.size_classes) if class_index is not None: by_label[labels[class_index]].append((area, compactness, blocks_per_patch[index])) result: dict[str, float] = {} for label in labels: members_in_class = by_label[label] class_area = sum(area for area, _, _ in members_in_class) result[f"{label}.area"] = class_area result[f"{label}.size"] = (100.0 * class_area / total_area) if total_area > 0.0 else 0.0 result[f"{label}.frequency"] = float(len(members_in_class)) result[f"{label}.freqpercent"] = ( 100.0 * len(members_in_class) / len(areas) if areas else 0.0 ) result[f"{label}.blocks"] = ( sum(blocks for _, _, blocks in members_in_class) / len(members_in_class) if members_in_class else 0.0 ) result[f"{label}.shape"] = ( sum(shape for _, shape, _ in members_in_class) / len(members_in_class) if members_in_class else 0.0 ) result["TOTAL.area"] = total_area result["TOTAL.frequency"] = float(len(areas)) return result def _refuse_attractor(account: str) -> None: """Refuse an ``attractor`` sub-account, with what was measured about it. Parameters ---------- account : str The account's name, for the message. Raises ------ ValueError Always: WS4 does not report this sub-account. """ raise ValueError( f"{account}: the attractor sub-account is refused. What the reference reports for it is " "a per-patch size statistic that its own exported tables do not determine: it is zero " "exactly when the class holds no patches, and it tracks a fraction of the class's mean " "patch area — 0.52 to 0.69 within one class, falling to 0.015 in the largest — which no " "product or ratio of the reported area, blocks, size, shape, frequency and freqpercent " "reproduces (a log-linear fit against all six leaves a 9% median and a 58% worst " "residual). The class's size share, which one reading of the reference's documentation " "has it mimic, is 0.26 to 2.57 times its value cell by cell. So WS4 reports no number it " "cannot stand behind, and keeps no flag: what is missing is the per-patch distribution, " "the same export the patch-component comparison waits on." ) def load_patch_accounts(path: Path) -> tuple[PatchAccount, ...]: """Load patch account definitions from YAML. The file is a mapping with an ``accounts`` list; each entry has ``name``, ``criteria``, and any of ``threshold``, ``size_classes``, and ``search_distance``. An ``attractor`` entry is refused rather than ignored: see :func:`_refuse_attractor`. Parameters ---------- path : Path The YAML file. Returns ------- tuple of PatchAccount The definitions. """ import yaml raw = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {} entries = raw.get("accounts", []) if isinstance(raw, dict) else [] accounts: list[PatchAccount] = [] for entry in entries: if "attractor" in entry: _refuse_attractor(str(entry.get("name", "a patch account"))) classes = tuple(float(value) for value in entry.get("size_classes", DEFAULT_SIZE_CLASSES)) raw_distance = entry.get("search_distance", 0.0) accounts.append( PatchAccount( name=str(entry["name"]), criteria=str(entry["criteria"]), threshold=float(entry.get("threshold", 0.0)), size_classes=classes, search_distance=None if raw_distance is None else float(raw_distance), ) ) return tuple(accounts) @dataclass(frozen=True) class PatchComponent: """One patch: the blocks it holds and what it measures. Attributes ---------- account : str The patch account's name. period : int The year the patch was formed in. blocks : tuple of int The member blocks, ascending. area : float The patch's area, in hectares: its member blocks' criterion-weighted areas. klass : str The size class the patch falls in, or an empty string when no class contains it. """ account: str period: int blocks: tuple[int, ...] area: float klass: str def patch_components( account: PatchAccount, values: Mapping[int, float], edges: Sequence[tuple[int, int, float]], block_area: Mapping[int, float], period: int = 0, ) -> tuple[PatchComponent, ...]: """Return the patches a criterion forms, one entry per patch. This is the structure the sub-account values are aggregates of, stated so it can be compared: which blocks formed a patch, how large it is, and which size class it falls in. WS4's patch member ids are its own — they are arbitrary, and two tools' ids never need to agree for their partitions to be comparable. Parameters ---------- account : PatchAccount The account definition: its criteria, threshold, and size classes. values : mapping of int to float The criterion value per block. edges : sequence of (int, int, float) The adjacency edges ``(src, dst, shared_length)``. block_area : mapping of int to float The area of each block. period : int, optional The year the patches were formed in (default 0). Returns ------- tuple of PatchComponent One entry per patch, with its member blocks ascending. """ members = {block for block, value in values.items() if value > account.threshold} labels = size_class_labels(account.size_classes) components: list[PatchComponent] = [] for patch in connected_patches(members, [(source, target) for source, target, _ in edges]): area = sum(values.get(block, 0.0) * block_area.get(block, 0.0) for block in patch) index = _size_class_index(area, account.size_classes) components.append( PatchComponent( account=account.name, period=period, blocks=tuple(sorted(patch)), area=area, klass=labels[index] if index is not None else "", ) ) return tuple(components)
[docs] @dataclass class PatchLedger: """Accumulate patch accounts over a run. Parameters ---------- accounts : sequence of PatchAccount The patch account definitions. edges : sequence of (int, int, float, float) The adjacency edges ``(src, dst, shared_length, distance)``. Each account keeps only the edges within its own ``search_distance``. block_area : mapping of int to float The area of each block. period_width : int, optional The planning-period width, in years. membership : bool, optional When True, also keep which blocks formed which patch, and write it beside the accounts. A run wants it — the membership is what a component comparison reads — while a search prices the accounts alone, and keeping it costs a second pass over the topology a period. """ accounts: Sequence[PatchAccount] edges: Sequence[tuple[int, int, float, float]] block_area: Mapping[int, float] period_width: int = 1 membership: bool = False _records: list[dict[str, float]] = field(default_factory=list) _by_account: list[list[tuple[int, int, float]]] = field(init=False, default_factory=list) _components: list[PatchComponent] = field(default_factory=list) def __post_init__(self) -> None: """Keep, per account, only the edges within that account's search distance.""" self._by_account = [ [ (source, target, length) for source, target, length, distance in self.edges if account.search_distance is None or distance <= account.search_distance ] for account in self.accounts ]
[docs] def record(self, year: int, criteria: Mapping[str, Mapping[int, float]]) -> None: """Record one period's patch accounts. Parameters ---------- year : int The year. criteria : mapping of str to mapping of int to float The criterion values per block, keyed by the criteria feature label. """ row: dict[str, float] = {"offset": float(year), "period": float(year), "year": float(year)} for account, edges in zip(self.accounts, self._by_account, strict=True): values = criteria.get(account.criteria, {}) for key, value in patch_account_values(account, values, edges, self.block_area).items(): row[f"{account.name}.{key}"] = value if self.membership: self._components.extend( patch_components(account, values, edges, self.block_area, year) ) self._records.append(row)
[docs] def frame(self) -> pd.DataFrame: """Return the patch accounts as a frame, one row per period. Returns ------- pandas.DataFrame One row per accounted period, with the patch sub-account columns. """ return pd.DataFrame(self._records)
[docs] def membership_frame(self) -> pd.DataFrame: """Return the patch membership: one row per member block of every patch. Returns ------- pandas.DataFrame ``period``, ``year``, ``account``, ``class``, ``patch``, ``block`` and ``area_ha``, where a patch's area is repeated on each of its members' rows. The patch ids are WS4's own and mean nothing to another tool: what two listings are compared on is the partition, not the labels. """ rows: list[dict[str, object]] = [] for index, component in enumerate(self._components): for block in component.blocks: rows.append( { "offset": component.period, "period": component.period, "year": component.period, "account": component.account, "class": component.klass, "patch": index, "block": block, "area_ha": component.area, } ) return pd.DataFrame( rows, columns=["offset", "period", "year", "account", "class", "patch", "block", "area_ha"], )
[docs] def write(self, out_dir: Path) -> None: """Write ``patch_accounts.csv``, and ``patch_membership.csv`` when it was kept, into a run. Parameters ---------- out_dir : Path The run directory; it is created when missing. """ out_dir = Path(out_dir) out_dir.mkdir(parents=True, exist_ok=True) self.frame().to_csv(out_dir / "patch_accounts.csv", index=False) if self.membership: self.membership_frame().to_csv(out_dir / "patch_membership.csv", index=False)
def load_patch_edges_detailed( csv_path: Path, ) -> list[tuple[int, int, float, float]]: """Load a proximal topology with both shared length and block distance. Parameters ---------- csv_path : Path The topology CSV. Returns ------- list of (int, int, float, float) The undirected edges ``(src, dst, shared_length, distance)``; the distance is 0.0 when the file has no distance column. """ frame = pd.read_csv(csv_path) columns = {name.lower(): name for name in frame.columns} def pick(*names: str) -> str | None: for name in names: if name in columns: return columns[name] return None source = pick("src_block", "block1", "source") target = pick("dst_block", "block2", "target") if source is None or target is None: raise ValueError(f"no block columns in {csv_path}") length = pick("shared_length", "length_m", "length") distance = pick("distance_m", "distance") edges: list[tuple[int, int, float, float]] = [] for row in frame.itertuples(index=False): left = int(getattr(row, source)) right = int(getattr(row, target)) if left < 0 or right < 0: continue shared = float(getattr(row, length)) if length is not None else 0.0 span = float(getattr(row, distance)) if distance is not None else 0.0 edges.append((left, right, shared, span)) return edges
[docs] def load_patch_edges(csv_path: Path) -> list[tuple[int, int, float]]: """Load a proximal topology edge list, accepting the established column names. The established file is ``BLOCK1,BLOCK2,DISTANCE,LENGTH``; the sentinel block ``-9999`` marks a boundary and is dropped. WS4's names are ``src_block,dst_block`` with ``distance_m`` or ``length_m``. Parameters ---------- csv_path : Path The topology CSV. Returns ------- list of (int, int, float) The undirected edges with their shared boundary length. """ frame = pd.read_csv(csv_path) columns = {name.lower(): name for name in frame.columns} def pick(*names: str) -> str | None: for name in names: if name in columns: return columns[name] return None source = pick("src_block", "block1", "source") target = pick("dst_block", "block2", "target") if source is None or target is None: raise ValueError(f"no block columns in {csv_path}") length = pick("shared_length", "length_m", "length", "distance_m", "distance") edges: list[tuple[int, int, float]] = [] for row in frame.itertuples(index=False): left = int(getattr(row, source)) right = int(getattr(row, target)) if left < 0 or right < 0: continue shared = float(getattr(row, length)) if length is not None else 0.0 edges.append((left, right, shared)) return edges