Source code for morie.research.selective_labels

# SPDX-License-Identifier: AGPL-3.0-or-later
"""Research P18: selective labels (``research/lean/P18Selective.lean``; Lakkaraju et al. 2017; Kleinberg et al. 2018).

* ``Research.P18.observed_rate_is_conditional`` / ``nested_rate_identified``
* ``Research.P18.unobserved_bounds`` / ``unobserved_width`` / ``unobserved_ends_attained``

R parity: ``rmorie`` ``R/selective_labels.R`` (``morie_selective_labels``).
"""

from __future__ import annotations

from morie.fn import _array_core as np

__all__ = ["selective_labels", "selective_labels_judges"]


[docs] def selective_labels(y, released, rule_released, weights=None) -> dict: """What a release rule's failure rate can be known from the cases a judge released. Examples -------- >>> y = [0, 1, 0, 1, 1, 0]; released = [True, True, True, True, False, False] >>> r = selective_labels(y, released, [True, True, True, False, False, False]) >>> (r["identified"], round(r["rule_rate"], 12)) (True, 0.333333333333) >>> r2 = selective_labels(y, released, [True, True, True, True, True, False]) >>> ({k: round(v, 12) for k, v in r2["bounds"].items()}, round(r2["width"], 12)) ({'lower': 0.4, 'upper': 0.6}, 0.2) """ y = np.asarray(y, dtype=float) rel = np.asarray([bool(v) for v in released]) rule = np.asarray([bool(v) for v in rule_released]) n = y.shape[0] if rel.shape[0] != n or rule.shape[0] != n: raise ValueError("y, released and rule_released must have equal length") if not np.all((y[rel] == 0) | (y[rel] == 1)): raise ValueError("y must be 0/1 on the released") w = np.ones(n) if weights is None else np.asarray(weights, dtype=float) if w.shape[0] != n or np.any(w < 0): raise ValueError("weights must be non-negative") wy = np.where(rel, w * y, 0.0) mass_r = float(np.sum(w[rel])) mass_m = float(np.sum(w[rule])) if mass_r <= 0 or mass_m <= 0: raise ValueError("both the released set and the rule's set must have positive mass") obs_rate = float(np.sum(wy[rel])) / mass_r inter = rel & rule fails_inter = float(np.sum(wy[inter])) mass_unobs = float(np.sum(w[rule & ~rel])) identified = mass_unobs == 0 lower = fails_inter / mass_m upper = (fails_inter + mass_unobs) / mass_m mass_inter = float(np.sum(w[inter])) return { "observed_rate": obs_rate, "rule_share_unobserved": mass_unobs / mass_m, "identified": identified, "rule_rate": lower if identified else float("nan"), "bounds": {"lower": lower, "upper": upper}, "width": upper - lower, "naive_rate": fails_inter / mass_inter if mass_inter > 0 else float("nan"), "theorems": [ "Research.P18.observed_rate_is_conditional", "Research.P18.nested_rate_identified", "Research.P18.unobserved_bounds", "Research.P18.unobserved_width", "Research.P18.unobserved_ends_attained", ], }
[docs] def selective_labels_judges(y, released, rule_released, weights=None, names=None) -> dict: """Selective labels across judges ordered from strictest to most lenient (``Research.P18.chain_width_antitone``, ``chain_contraction``, ``chain_width_zero_iff``). ``released`` holds one release indicator per judge (a list of columns, or an n x k matrix). With nested release sets the interval narrows with leniency; the most lenient judge gives the sharpest interval, a point exactly when the rule's set lies inside it. Examples -------- >>> y = [0, 1, 0, 1, 1, 0] >>> judges = [[True, True, False, False, False, False], [True, True, True, True, False, False]] >>> r = selective_labels_judges(y, judges, [True, True, True, False, False, False]) >>> ([round(w, 12) for w in r["widths"]], r["nested"], r["identified"], round(r["rule_rate"], 12)) ([0.333333333333, 0.0], True, True, 0.333333333333) """ y = np.asarray(y, dtype=float) n = y.shape[0] rel = np.asarray([[bool(v) for v in col] for col in released]) if rel.ndim != 2 or rel.shape[1] != n or rel.shape[0] == 0: if rel.ndim == 2 and rel.shape[0] == n: rel = rel.T else: raise ValueError("released must have one entry per defendant for every judge") k = rel.shape[0] if names is None: names = [f"judge{j + 1}" for j in range(k)] w = np.ones(n) if weights is None else np.asarray(weights, dtype=float) nested = all(not np.any(rel[j] & ~rel[j + 1]) for j in range(k - 1)) per = [selective_labels(y, rel[j], rule_released, weights) for j in range(k)] widths = [p["width"] for p in per] best = int(min(range(k), key=lambda j: widths[j])) return { "judges": [ { "judge": names[j], "release_share": float(np.sum(w[rel[j]])) / float(np.sum(w)), "lower": per[j]["bounds"]["lower"], "upper": per[j]["bounds"]["upper"], "width": widths[j], "identified": per[j]["identified"], } for j in range(k) ], "widths": widths, "nested": nested, "best": names[best], "identified": per[best]["identified"], "rule_rate": per[best]["rule_rate"], "bounds": per[best]["bounds"], "width": widths[best], "theorems": [ "Research.P18.unobserved_mass_antitone", "Research.P18.interval_width_antitone", "Research.P18.chain_contraction", "Research.P18.chain_width_antitone", "Research.P18.chain_width_zero_iff", ], }