cld-reducer 0.2.0__py3-none-any.whl

cld_reducer/NOTICE

@@ -0,0 +1,35 @@
+Example data sources and reuse record
+
+The MIT license covers the package code. The examples below contain public
+summary data from the cited papers. On 2026-10-10, John Ennis confirmed that
+the data are public and approved their inclusion in these distributions.
+This record does not assign a new license to the source publications.
+
+piepho2004_wheat_pairs.csv / piepho2004_wheat
+Source: Piepho (2004), An Algorithm for a Letter-Based Representation of All-
+Pairwise Comparisons, doi:10.1198/1061860043515; reproduced in Table 7 of
+Ennis, Fayle, and Ennis (2012), Assignment-Minimum Clique Coverings,
+doi:10.1145/2133803.2275596.
+Content: significant/non-significant decisions for the 190 unordered pairs of
+20 wheat treatments. The repository stores these decisions as CSV rows.
+R data-raw/datasets.R reads labels as text and decisions as logical values,
+then saves the same rows as piepho2004_wheat.rda. Python examples copy the CSV.
+Reuse record: maintainer confirmation and approval on 2026-10-10.
+
+simple_abc_to_ac_pairs.csv / simple_abc_pairs
+simple_abc_to_ac_means.csv / simple_abc_means
+Source: Ennis, Fayle, and Ennis (2012), Assignment-Minimum Clique Coverings,
+doi:10.1145/2133803.2275596. The R help pages attribute the five-group
+ABC-to-AC teaching example and its means to this paper.
+Content: ten pairwise decisions and five numeric means. R data-raw/datasets.R
+reads the CSV files and saves the corresponding data frames. Python examples
+copy the CSV files.
+Reuse record: maintainer confirmation and approval on 2026-10-10.
+
+Retain this source record with the example data.
+
+Distribution scope
+The R archive contains both example data sets. The Python source archive contains
+their CSV files. The Python wheel omits the CSV files but includes simple-example
+output from the README in its metadata. The npm archive contains no wheat data,
+but its README reproduces the simple five-group example.

cld_reducer/__init__.py

@@ -0,0 +1,16 @@
+"""Tools for reducing compact letter displays."""
+
+from .api import reduce_from_adjacency, reduce_letters
+from .exceptions import CLDReducerError, InvalidInputError, SolverError
+from .result import CLDReductionResult
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "CLDReducerError",
+    "CLDReductionResult",
+    "InvalidInputError",
+    "SolverError",
+    "reduce_from_adjacency",
+    "reduce_letters",
+]

cld_reducer/_solver.py

@@ -0,0 +1,140 @@
+"""HiGHS through highspy, with the settings of docs/algorithm.md section 6."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import highspy
+import numpy as np
+
+
+@dataclass
+class Settings:
+    """Presolve is the one setting that differs between languages (R turns it off).
+
+    Tests switch it off to run the conformance suite a second time.
+    """
+
+    presolve: str = "on"
+
+
+settings = Settings()
+# The options of the most recent solve, read back from HiGHS. Tests check them.
+last_options: dict[str, object] = {}
+
+OPTION_NAMES = (
+    "presolve",
+    "mip_rel_gap",
+    "mip_abs_gap",
+    "primal_feasibility_tolerance",
+    "mip_feasibility_tolerance",
+    "threads",
+    "time_limit",
+)
+
+OPTIMAL = "optimal"
+INFEASIBLE = "infeasible"
+TIME_LIMIT = "time_limit"
+FAILED = "failed"
+
+
+@dataclass(frozen=True)
+class Problem:
+    """The model of docs/algorithm.md section 4 in row-wise sparse form.
+
+    The first `num_x` columns are the membership variables x; the rest are the y variables.
+    """
+
+    num_cols: int
+    num_x: int
+    cost: np.ndarray
+    start: np.ndarray
+    index: np.ndarray
+    value: np.ndarray
+    row_lower: np.ndarray
+    row_upper: np.ndarray
+
+
+@dataclass(frozen=True)
+class Outcome:
+    """What one solve returned: a status, the HiGHS status text, and the column values."""
+
+    status: str
+    text: str
+    values: np.ndarray | None = None
+    objective: float | None = None
+
+
+def run(
+    problem: Problem,
+    col_lower: np.ndarray,
+    col_upper: np.ndarray,
+    *,
+    sum_limit: int | None = None,
+    time_limit: float | None = None,
+) -> Outcome:
+    """Solve the model with the given column bounds.
+
+    `sum_limit` adds the row `sum(x) <= sum_limit`. `time_limit` is the HiGHS time limit in
+    seconds for this solve.
+    """
+    start, index, value = problem.start, problem.index, problem.value
+    row_lower, row_upper = problem.row_lower, problem.row_upper
+    if sum_limit is not None:
+        extra = np.arange(problem.num_x, dtype=np.int32)
+        start = np.concatenate([start, [start[-1] + problem.num_x]]).astype(np.int32)
+        index = np.concatenate([index, extra])
+        value = np.concatenate([value, np.ones(problem.num_x)])
+        row_lower = np.concatenate([row_lower, [-highspy.kHighsInf]])
+        row_upper = np.concatenate([row_upper, [float(sum_limit)]])
+
+    lp = highspy.HighsLp()
+    lp.num_col_ = problem.num_cols
+    lp.num_row_ = len(row_lower)
+    lp.col_cost_ = problem.cost
+    lp.col_lower_ = col_lower
+    lp.col_upper_ = col_upper
+    lp.integrality_ = [highspy.HighsVarType.kInteger] * problem.num_cols
+    lp.row_lower_ = row_lower
+    lp.row_upper_ = row_upper
+    lp.a_matrix_.format_ = highspy.MatrixFormat.kRowwise
+    lp.a_matrix_.num_col_ = problem.num_cols
+    lp.a_matrix_.num_row_ = len(row_lower)
+    lp.a_matrix_.start_ = start
+    lp.a_matrix_.index_ = index
+    lp.a_matrix_.value_ = value
+    lp.sense_ = highspy.ObjSense.kMinimize
+
+    h = highspy.Highs()
+    h.setOptionValue("output_flag", False)
+    h.setOptionValue("presolve", settings.presolve)
+    h.setOptionValue("mip_rel_gap", 0.0)
+    h.setOptionValue("mip_abs_gap", 0.0)
+    h.setOptionValue("primal_feasibility_tolerance", 1e-9)
+    h.setOptionValue("mip_feasibility_tolerance", 1e-9)
+    h.setOptionValue("threads", 1)
+    if time_limit is not None:
+        h.setOptionValue("time_limit", float(time_limit))
+    h.passModel(lp)
+    h.run()
+
+    last_options.clear()
+    for name in OPTION_NAMES:
+        option = h.getOptionValue(name)
+        # highspy 1.15 returns (status, value).
+        last_options[name] = option[1] if isinstance(option, tuple) else option
+
+    status = h.getModelStatus()
+    text = h.modelStatusToString(status)
+    if status == highspy.HighsModelStatus.kOptimal:
+        values = np.asarray(h.getSolution().col_value, dtype=np.float64)
+        return Outcome(OPTIMAL, text, values, float(h.getInfo().objective_function_value))
+    # No model here is unbounded, so HiGHS's "unbounded or infeasible" means infeasible.
+    if status in (
+        highspy.HighsModelStatus.kInfeasible,
+        highspy.HighsModelStatus.kUnboundedOrInfeasible,
+    ):
+        return Outcome(INFEASIBLE, text)
+    if status == highspy.HighsModelStatus.kTimeLimit:
+        return Outcome(TIME_LIMIT, text)
+    return Outcome(FAILED, text)

cld_reducer/algorithms/__init__.py

@@ -0,0 +1 @@
+"""CLD reduction algorithm implementations."""

cld_reducer/algorithms/assignment_minimum.py

@@ -0,0 +1,351 @@
+"""Assignment-minimum compact letter display reduction.
+
+Solves the assignment-minimum clique covering problem defined in Ennis, Fayle,
+& Ennis (2012), "Assignment-Minimum Clique Coverings", ACM JEA 17, Art. 1.5
+(https://doi.org/10.1145/2133803.2275596). The paper uses a backtracking
+algorithm (FIND-AM); this module solves the same problem as a binary
+mixed-integer program with HiGHS, then picks the canonical optimum of
+docs/algorithm.md section 5 so that every implementation returns the same display.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from math import isfinite
+from numbers import Integral, Real
+
+import numpy as np
+import pandas as pd
+from highspy import kHighsInf
+
+from .. import _solver
+from ..cliques import maximal_cliques
+from ..exceptions import SolverError
+from ..labels import make_letter_labels
+from ..result import CLDReductionResult
+from ..validation import (
+    count_assignments,
+    normalize_means,
+    reconstruct_adjacency_from_assignments,
+    validate_adjacency,
+)
+
+# The clock behind the shared time budget. Tests replace it.
+_now = time.monotonic
+
+_INTEGRALITY_TOLERANCE = 1e-6
+_INVALID_SOLUTION = "HiGHS returned an invalid solution"
+
+
+@dataclass(frozen=True)
+class _Model:
+    problem: _solver.Problem
+    members: list[tuple[int, int]]  # (clique, group) of each x variable, in canonical order
+    edges: list[tuple[int, int]]
+    group_columns: list[list[int]]  # x variables of each group
+    edge_ends: list[list[tuple[int, int]]]  # per edge: the two x variables of each covering clique
+
+
+def reduce_assignment_minimum(
+    adjacency: np.ndarray,
+    groups: list[str],
+    means: pd.Series | None = None,
+    *,
+    method: str = "assignment_minimum",
+    time_limit: float | None = None,
+    max_cliques: int | None = 10_000,
+) -> CLDReductionResult:
+    """Reduce a CLD by minimizing total letter assignments.
+
+    Parameters
+    ----------
+    adjacency:
+        Symmetric boolean matrix where `True` means two groups are not
+        significantly different and may share a letter.
+    groups:
+        Group labels in matrix order.
+    means:
+        Optional group means used only to produce stable, mean-ordered letters.
+    method:
+        Method label stored in the result metadata.
+    time_limit:
+        Optional time budget in seconds, shared by all solves of this call.
+    max_cliques:
+        Optional cap on maximal cliques to enumerate before failing with a
+        controlled `SolverError`. Pass `None` to disable the cap.
+    """
+    adjacency, groups = validate_adjacency(adjacency, groups)
+    means = normalize_means(means, groups)
+    time_limit, max_cliques = _validate_solver_controls(time_limit, max_cliques)
+
+    cliques = maximal_cliques(adjacency, max_cliques=max_cliques)
+    model = _build_model(adjacency, cliques)
+    selected, minimum = _solve_canonical(model, time_limit)
+    columns = _selected_columns(cliques, model, selected)
+    tokens = _assign_letter_tokens(columns, len(groups), means, groups)
+    assignments = {group: tokens[index] for index, group in enumerate(groups)}
+    letters = {group: _format_letter_tokens(value) for group, value in assignments.items()}
+    reconstructed = reconstruct_adjacency_from_assignments(assignments, groups)
+    if not np.array_equal(reconstructed, adjacency):
+        msg = "optimized letters did not preserve the input pairwise relationships"
+        raise SolverError(msg)
+
+    assignments_before = len(model.members)
+    assignments_after = count_assignments(assignments)
+    reduction_pct = (
+        (assignments_before - assignments_after) / assignments_before * 100
+        if assignments_before
+        else 0.0
+    )
+    stats = {
+        "assignments_before": assignments_before,
+        "assignments_after": int(assignments_after),
+        "reduction_pct": reduction_pct,
+        "num_letters_before": len(cliques),
+        "num_letters_after": len(columns),
+        "num_groups": len(groups),
+        "num_edges": len(model.edges),
+        "solver_status": "Optimal",
+        "objective": minimum,
+    }
+
+    return CLDReductionResult(
+        letters=letters,
+        assignments=assignments,
+        stats=stats,
+        method=method,
+        groups=tuple(groups),
+        relationship_preserved=True,
+        adjacency=tuple(tuple(bool(value) for value in row) for row in adjacency),
+    )
+
+
+def _validate_solver_controls(
+    time_limit: float | None, max_cliques: int | None
+) -> tuple[float | None, int | None]:
+    if time_limit is not None and (
+        isinstance(time_limit, bool)
+        or not isinstance(time_limit, Real)
+        or not isfinite(float(time_limit))
+        or time_limit <= 0
+    ):
+        msg = "time_limit must be positive when provided"
+        raise SolverError(msg)
+    if max_cliques is not None and (
+        isinstance(max_cliques, bool) or not isinstance(max_cliques, Integral) or max_cliques < 1
+    ):
+        msg = "max_cliques must be a positive integer or None"
+        raise SolverError(msg)
+    return (
+        float(time_limit) if time_limit is not None else None,
+        int(max_cliques) if max_cliques is not None else None,
+    )
+
+
+def _build_model(adjacency: np.ndarray, cliques: list[tuple[int, ...]]) -> _Model:
+    """Build the model of docs/algorithm.md section 4."""
+    num_groups = adjacency.shape[0]
+    members = [(c, g) for c, clique in enumerate(cliques) for g in clique]
+    x_index = {member: k for k, member in enumerate(members)}
+    cliques_of: list[list[int]] = [[] for _ in range(num_groups)]
+    for c, clique in enumerate(cliques):
+        for g in clique:
+            cliques_of[g].append(c)
+    edges = [(i, j) for i in range(num_groups) for j in range(i + 1, num_groups) if adjacency[i, j]]
+
+    num_x = len(members)
+    y_pairs: list[tuple[int, int]] = []  # (edge, clique)
+    for e, (i, j) in enumerate(edges):
+        shared = sorted(set(cliques_of[i]) & set(cliques_of[j]))
+        y_pairs.extend((e, c) for c in shared)
+
+    rows: list[list[tuple[int, float]]] = []
+    row_lower: list[float] = []
+    row_upper: list[float] = []
+    # Every group is in at least one clique.
+    for g in range(num_groups):
+        rows.append([(x_index[(c, g)], 1.0) for c in cliques_of[g]])
+        row_lower.append(1.0)
+        row_upper.append(kHighsInf)
+    # Every non-significant edge is covered by at least one clique that holds both ends.
+    by_edge: dict[int, list[int]] = {}
+    for k, (e, _) in enumerate(y_pairs):
+        by_edge.setdefault(e, []).append(num_x + k)
+    for e in range(len(edges)):
+        rows.append([(col, 1.0) for col in by_edge[e]])
+        row_lower.append(1.0)
+        row_upper.append(kHighsInf)
+    # A covering clique needs both ends: y <= x for each end.
+    for k, (e, c) in enumerate(y_pairs):
+        i, j = edges[e]
+        for g in (i, j):
+            rows.append([(num_x + k, 1.0), (x_index[(c, g)], -1.0)])
+            row_lower.append(-kHighsInf)
+            row_upper.append(0.0)
+
+    start = [0]
+    index: list[int] = []
+    value: list[float] = []
+    for row in rows:
+        for col, coefficient in row:
+            index.append(col)
+            value.append(coefficient)
+        start.append(len(index))
+    num_cols = num_x + len(y_pairs)
+    cost = np.zeros(num_cols)
+    cost[:num_x] = 1.0
+    problem = _solver.Problem(
+        num_cols=num_cols,
+        num_x=num_x,
+        cost=cost,
+        start=np.asarray(start, dtype=np.int32),
+        index=np.asarray(index, dtype=np.int32),
+        value=np.asarray(value, dtype=np.float64),
+        row_lower=np.asarray(row_lower, dtype=np.float64),
+        row_upper=np.asarray(row_upper, dtype=np.float64),
+    )
+    edge_ends: list[list[tuple[int, int]]] = [[] for _ in edges]
+    for e, c in y_pairs:
+        edge_ends[e].append((x_index[(c, edges[e][0])], x_index[(c, edges[e][1])]))
+    return _Model(
+        problem=problem,
+        members=members,
+        edges=edges,
+        group_columns=[[x_index[(c, g)] for c in cliques_of[g]] for g in range(num_groups)],
+        edge_ends=edge_ends,
+    )
+
+
+def _solve_canonical(model: _Model, time_limit: float | None) -> tuple[np.ndarray, int]:
+    """Solve once for the minimum, then fix the memberships in (clique, group) order.
+
+    This is the sequential fixing procedure of docs/algorithm.md section 5. Returns the
+    selected x variables (a boolean array) and the minimum number of assignments.
+    """
+    problem = model.problem
+    num_x = problem.num_x
+    deadline = _now() + time_limit if time_limit is not None else None
+    col_lower = np.zeros(problem.num_cols)
+    col_upper = np.ones(problem.num_cols)
+
+    outcome = _solve(model, col_lower, col_upper, None, deadline)
+    selected = _check_solution(model, outcome, col_lower, col_upper, None)
+    minimum = int(round(float(outcome.objective)))
+    selected_x = selected
+
+    for v in range(num_x):
+        if selected_x[v]:
+            col_lower[v] = 1.0
+            continue
+        trial_lower = col_lower.copy()
+        trial_lower[v] = 1.0
+        outcome = _solve(model, trial_lower, col_upper, minimum, deadline)
+        if outcome.status == _solver.INFEASIBLE:
+            col_upper[v] = 0.0
+            continue
+        selected_x = _check_solution(model, outcome, trial_lower, col_upper, minimum)
+        col_lower = trial_lower
+    return selected_x, minimum
+
+
+def _solve(
+    model: _Model,
+    col_lower: np.ndarray,
+    col_upper: np.ndarray,
+    sum_limit: int | None,
+    deadline: float | None,
+) -> _solver.Outcome:
+    remaining = None
+    if deadline is not None:
+        remaining = deadline - _now()
+        if remaining <= 0:
+            msg = "assignment-minimum MILP failed: Time limit reached"
+            raise SolverError(msg)
+    outcome = _solver.run(
+        model.problem, col_lower, col_upper, sum_limit=sum_limit, time_limit=remaining
+    )
+    if outcome.status == _solver.INFEASIBLE and sum_limit is not None:
+        return outcome
+    if outcome.status != _solver.OPTIMAL:
+        msg = f"assignment-minimum MILP failed: {outcome.text}"
+        raise SolverError(msg)
+    return outcome
+
+
+def _check_solution(
+    model: _Model,
+    outcome: _solver.Outcome,
+    col_lower: np.ndarray,
+    col_upper: np.ndarray,
+    expected_sum: int | None,
+) -> np.ndarray:
+    """Docs/algorithm.md section 6, checks 2 to 5. Returns the rounded x as booleans."""
+    num_x = model.problem.num_x
+    values = outcome.values
+    if values is None or len(values) != model.problem.num_cols:
+        raise SolverError(_INVALID_SOLUTION)
+    x = np.asarray(values[:num_x], dtype=np.float64)
+    # Each membership must be 0 or 1 within the tolerance; an integral 2 or -1 is invalid too.
+    near_zero = np.abs(x) <= _INTEGRALITY_TOLERANCE
+    near_one = np.abs(x - 1.0) <= _INTEGRALITY_TOLERANCE
+    if not np.all(np.isfinite(x) & (near_zero | near_one)):
+        raise SolverError(_INVALID_SOLUTION)
+    rounded = x > 0.5
+    if np.any(rounded & (col_upper[:num_x] < 0.5)) or np.any(~rounded & (col_lower[:num_x] > 0.5)):
+        raise SolverError(_INVALID_SOLUTION)
+    for columns in model.group_columns:
+        if not any(rounded[k] for k in columns):
+            raise SolverError(_INVALID_SOLUTION)
+    for ends in model.edge_ends:
+        if not any(rounded[a] and rounded[b] for a, b in ends):
+            raise SolverError(_INVALID_SOLUTION)
+    total = int(rounded.sum())
+    wanted = expected_sum if expected_sum is not None else int(round(float(outcome.objective)))
+    if total != wanted:
+        raise SolverError(_INVALID_SOLUTION)
+    return rounded
+
+
+def _selected_columns(
+    cliques: list[tuple[int, ...]], model: _Model, selected: np.ndarray
+) -> list[list[int]]:
+    """Members of each clique's letter, dropping empty columns (canonical clique order)."""
+    columns: list[list[int]] = [[] for _ in cliques]
+    for k, (c, g) in enumerate(model.members):
+        if selected[k]:
+            columns[c].append(g)
+    return [column for column in columns if column]
+
+
+def _assign_letter_tokens(
+    columns: list[list[int]],
+    num_groups: int,
+    means: pd.Series | None,
+    groups: list[str],
+) -> list[tuple[str, ...]]:
+    order = sorted(range(len(columns)), key=lambda c: _column_sort_key(columns[c], groups, means))
+    labels = make_letter_labels(len(order))
+    tokens: list[list[str]] = [[] for _ in range(num_groups)]
+    for label, column in zip(labels, order, strict=True):
+        for group_index in columns[column]:
+            tokens[group_index].append(label)
+    return [tuple(value) for value in tokens]
+
+
+def _format_letter_tokens(tokens: tuple[str, ...]) -> str:
+    if all(len(token) == 1 for token in tokens):
+        return "".join(tokens)
+    return " ".join(tokens)
+
+
+def _column_sort_key(
+    members: list[int],
+    groups: list[str],
+    means: pd.Series | None,
+) -> tuple[float, int]:
+    lowest = min(members)
+    if means is not None:
+        highest_mean = max(float(means[groups[index]]) for index in members)
+        return (-highest_mean, lowest)
+    return (float(lowest), lowest)

cld_reducer/api.py

@@ -0,0 +1,97 @@
+"""Public API for CLD reduction."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+import pandas as pd
+
+from .algorithms.assignment_minimum import reduce_assignment_minimum
+from .exceptions import InvalidInputError
+from .result import CLDReductionResult
+from .validation import (
+    adjacency_from_pairs,
+    groups_from_pairs,
+    normalize_means,
+    normalize_pairwise_frame,
+    validate_adjacency,
+)
+
+
+def reduce_letters(
+    post_hoc_results: pd.DataFrame | Sequence[Mapping[str, Any]],
+    means: Mapping[Any, float] | pd.Series | pd.DataFrame | None = None,
+    *,
+    method: str = "assignment_minimum",
+    group1: str = "group1",
+    group2: str = "group2",
+    significant: str = "significant",
+    time_limit: float | None = None,
+    max_cliques: int | None = 10_000,
+) -> CLDReductionResult:
+    """Reduce compact letter assignments from pairwise post-hoc results.
+
+    Parameters
+    ----------
+    post_hoc_results:
+        Pairwise comparison results. Each row must identify two groups and
+        whether the comparison is statistically significant.
+    means:
+        Optional group means used for stable display ordering.
+    method:
+        Reduction algorithm. Currently only `"assignment_minimum"` is supported.
+    group1, group2, significant:
+        Column names in `post_hoc_results`.
+    time_limit:
+        Optional solver time limit in seconds.
+    max_cliques:
+        Optional cap on maximal cliques to enumerate before failing with a
+        controlled solver error. Pass `None` to disable the cap.
+    """
+    frame = normalize_pairwise_frame(
+        post_hoc_results,
+        group1=group1,
+        group2=group2,
+        significant=significant,
+    )
+    groups = groups_from_pairs(frame, means)
+    normalized_means = normalize_means(means, groups)
+    adjacency = adjacency_from_pairs(frame, groups)
+    return reduce_from_adjacency(
+        adjacency,
+        groups=groups,
+        means=normalized_means,
+        method=method,
+        time_limit=time_limit,
+        max_cliques=max_cliques,
+    )
+
+
+def reduce_from_adjacency(
+    adjacency: Any,
+    groups: Sequence[Any] | None = None,
+    means: Mapping[Any, float] | pd.Series | pd.DataFrame | None = None,
+    *,
+    method: str = "assignment_minimum",
+    time_limit: float | None = None,
+    max_cliques: int | None = 10_000,
+) -> CLDReductionResult:
+    """Reduce compact letters directly from a non-significance adjacency matrix.
+
+    `adjacency[i, j] == True` means groups `i` and `j` are not significantly
+    different and must share at least one letter in the returned CLD.
+    """
+    matrix, normalized_groups = validate_adjacency(adjacency, groups)
+    normalized_means = normalize_means(means, normalized_groups)
+    if method in {"assignment_minimum", "assignment-minimum"}:
+        return reduce_assignment_minimum(
+            matrix,
+            normalized_groups,
+            normalized_means,
+            method="assignment_minimum",
+            time_limit=time_limit,
+            max_cliques=max_cliques,
+        )
+    msg = f"unsupported CLD reduction method: {method!r}"
+    raise InvalidInputError(msg)