khipu-null 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- khipu_null/__init__.py +3 -0
- khipu_null/cli.py +90 -0
- khipu_null/corpus.py +95 -0
- khipu_null/features.py +121 -0
- khipu_null/rank.py +153 -0
- khipu_null-0.1.0.dist-info/METADATA +112 -0
- khipu_null-0.1.0.dist-info/RECORD +10 -0
- khipu_null-0.1.0.dist-info/WHEEL +4 -0
- khipu_null-0.1.0.dist-info/entry_points.txt +2 -0
- khipu_null-0.1.0.dist-info/licenses/LICENSE +21 -0
khipu_null/__init__.py
ADDED
khipu_null/cli.py
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
"""khipu-null command line."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import argparse
|
|
6
|
+
import json
|
|
7
|
+
import sys
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
import yaml
|
|
11
|
+
|
|
12
|
+
from . import __version__
|
|
13
|
+
from .corpus import import_okr, load
|
|
14
|
+
from .rank import rank
|
|
15
|
+
|
|
16
|
+
LIMITS = """## What this does not prove
|
|
17
|
+
|
|
18
|
+
- A low p-value says the match is unlikely under this null, given the structure of each khipu. It does not say what the khipu means.
|
|
19
|
+
- Each feature is tested against its own null, which keeps groups, positions and levels fixed and moves only the field it reads. Structural features and whole-khipu distributions cannot be tested this way; they rank but never reach a low p-value.
|
|
20
|
+
- Colours are rotated along the khipu by default, which keeps colour bands intact. Shuffling colours cord by cord breaks bands and makes chance matches look rare.
|
|
21
|
+
- Choosing the best 5 of many khipus inflates scores. Read the top-k test and the q-values, not the raw scores.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _report(res: dict, pattern: dict, out: Path, top: int) -> None:
|
|
26
|
+
out.mkdir(parents=True, exist_ok=True)
|
|
27
|
+
t, s = res["table"], res["summary"]
|
|
28
|
+
t.to_csv(out / "ranking.csv", index=False)
|
|
29
|
+
(out / "summary.json").write_text(json.dumps(s, indent=2))
|
|
30
|
+
lines = [f"# khipu-null report: {pattern.get('name', 'pattern')}", "",
|
|
31
|
+
f"khipu-null {__version__}. {s.get('khipus', 0)} khipus scored, {s.get('draws', 0)} null draws each.", ""]
|
|
32
|
+
if s.get("khipus"):
|
|
33
|
+
lines += [
|
|
34
|
+
"Tested features (field:null): " + (", ".join(f"{k} ({v})" for k, v in s["tested_features"].items()) or "none") + ".",
|
|
35
|
+
"Untested features (structure or whole-khipu distributions; they rank but cannot reach a low p): " + (", ".join(s["untested_features"]) or "none") + ".",
|
|
36
|
+
"",
|
|
37
|
+
f"Top {top} mean score {s['top_mean_score']:.3f}. Picking the top {top} from null versions of every khipu gives "
|
|
38
|
+
f"[{s['null_top_mean_95'][0]:.3f}, {s['null_top_mean_95'][1]:.3f}] (95%), p = {s['top_p']:.3f}.",
|
|
39
|
+
f"Khipus with q <= 0.05 (Benjamini-Hochberg): {s['significant_at_q05']}.",
|
|
40
|
+
"",
|
|
41
|
+
"| Rank | Khipu | Cords | Score | Null mean | p | q |",
|
|
42
|
+
"|---:|---|---:|---:|---:|---:|---:|",
|
|
43
|
+
]
|
|
44
|
+
for r in t.head(max(top, 10)).itertuples():
|
|
45
|
+
lines.append(f"| {r.rank} | {r.khipu_id} | {r.cords} | {r.score:.3f} | {r.null_mean:.3f} | {r.p:.3f} | {r.q:.3f} |")
|
|
46
|
+
lines.append("")
|
|
47
|
+
lines.append(LIMITS)
|
|
48
|
+
lines.append("If you use khipu-null, please cite it (see CITATION.cff): Crafter Research (2026), khipu-null, https://github.com/crafter-research/khipu-null")
|
|
49
|
+
(out / "report.md").write_text("\n".join(lines) + "\n")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def main(argv: list[str] | None = None) -> int:
|
|
53
|
+
ap = argparse.ArgumentParser(prog="khipu-null", description=__doc__)
|
|
54
|
+
ap.add_argument("--version", action="version", version=f"khipu-null {__version__}")
|
|
55
|
+
sub = ap.add_subparsers(dest="cmd", required=True)
|
|
56
|
+
|
|
57
|
+
imp = sub.add_parser("import-okr", help="build a corpus CSV from the Open Khipu Repository SQLite file")
|
|
58
|
+
imp.add_argument("db")
|
|
59
|
+
imp.add_argument("-o", "--out", default="corpus.csv")
|
|
60
|
+
imp.add_argument("--errata", choices=["none", "confirmed", "all"], default="none",
|
|
61
|
+
help="apply the Khipu Field Guide decimal reading where it disagrees with OKR: confirmed = KH0326; all = also KH0472")
|
|
62
|
+
|
|
63
|
+
rk = sub.add_parser("rank", help="rank khipus against a pattern and test against the null")
|
|
64
|
+
rk.add_argument("corpus")
|
|
65
|
+
rk.add_argument("pattern")
|
|
66
|
+
rk.add_argument("-o", "--out", default="out")
|
|
67
|
+
rk.add_argument("--top", type=int, default=5)
|
|
68
|
+
rk.add_argument("--draws", type=int, help="override null draws")
|
|
69
|
+
rk.add_argument("--seed", type=int, help="override null seed")
|
|
70
|
+
|
|
71
|
+
a = ap.parse_args(argv)
|
|
72
|
+
if a.cmd == "import-okr":
|
|
73
|
+
df = import_okr(a.db, a.errata)
|
|
74
|
+
df.to_csv(a.out, index=False)
|
|
75
|
+
print(f"{a.out}: {df['khipu_id'].nunique()} khipus, {len(df)} cords (errata: {a.errata})")
|
|
76
|
+
return 0
|
|
77
|
+
pattern = yaml.safe_load(Path(a.pattern).read_text())
|
|
78
|
+
pattern.setdefault("null", {})
|
|
79
|
+
if a.draws:
|
|
80
|
+
pattern["null"]["draws"] = a.draws
|
|
81
|
+
if a.seed is not None:
|
|
82
|
+
pattern["null"]["seed"] = a.seed
|
|
83
|
+
res = rank(load(a.corpus), pattern, top=a.top)
|
|
84
|
+
_report(res, pattern, Path(a.out), a.top)
|
|
85
|
+
print((Path(a.out) / "report.md").read_text())
|
|
86
|
+
return 0
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
if __name__ == "__main__":
|
|
90
|
+
sys.exit(main())
|
khipu_null/corpus.py
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"""Corpus loading. A corpus is one row per cord with these columns:
|
|
2
|
+
|
|
3
|
+
khipu_id identifier of the khipu
|
|
4
|
+
cord_id identifier of the cord, unique within the corpus
|
|
5
|
+
group_id identifier of the cord group (cluster) the cord belongs to
|
|
6
|
+
position order of the cord along the khipu (numeric, increasing from the start)
|
|
7
|
+
level 1 for pendants hanging from the primary cord, 2+ for subsidiaries
|
|
8
|
+
color colour code as recorded (any string)
|
|
9
|
+
value decoded knot value (number; empty means no knots)
|
|
10
|
+
|
|
11
|
+
Optional: attachment (recto/verso code), and any other columns, which are kept.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import re
|
|
17
|
+
import sqlite3
|
|
18
|
+
from pathlib import Path
|
|
19
|
+
|
|
20
|
+
import numpy as np
|
|
21
|
+
import pandas as pd
|
|
22
|
+
|
|
23
|
+
REQUIRED = ["khipu_id", "cord_id", "group_id", "position", "level", "color", "value"]
|
|
24
|
+
|
|
25
|
+
# OKR v2.1.0 and the Khipu Field Guide disagree on the decimal place of single knots on these
|
|
26
|
+
# khipus (OKR 100, Field Guide 10). The errata option applies the Field Guide reading. KH0326 is
|
|
27
|
+
# supported by Urton (2017, Appendix B); KH0472 only by the Field Guide. Not a confirmed OKR error.
|
|
28
|
+
OKR_TENS_AS_HUNDREDS = {"KH0326": "urton-appendix", "KH0472": "kfg-only"}
|
|
29
|
+
|
|
30
|
+
_SEG = re.compile(r"([^/()]+)\(([\d.]+)-([\d.]+)\)")
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def main_color(c: str) -> str:
|
|
34
|
+
"""Colour covering the longest stretch of a multi-segment cord, as the Khipu Field Guide shows it."""
|
|
35
|
+
segs = _SEG.findall(c or "")
|
|
36
|
+
if not segs:
|
|
37
|
+
return (c or "").strip()
|
|
38
|
+
span: dict[str, float] = {}
|
|
39
|
+
for col, a, b in segs:
|
|
40
|
+
span[col] = span.get(col, 0.0) + float(b) - float(a)
|
|
41
|
+
return max(span, key=span.get)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def load(path: str | Path) -> pd.DataFrame:
|
|
45
|
+
df = pd.read_csv(path)
|
|
46
|
+
missing = [c for c in REQUIRED if c not in df.columns]
|
|
47
|
+
if missing:
|
|
48
|
+
raise ValueError(f"corpus is missing columns: {', '.join(missing)}")
|
|
49
|
+
df["color"] = df["color"].fillna("").astype(str)
|
|
50
|
+
df["value"] = pd.to_numeric(df["value"], errors="coerce")
|
|
51
|
+
df["level"] = pd.to_numeric(df["level"], errors="coerce").fillna(1).astype(int)
|
|
52
|
+
df["position"] = pd.to_numeric(df["position"], errors="coerce")
|
|
53
|
+
if df["cord_id"].duplicated().any():
|
|
54
|
+
raise ValueError("cord_id must be unique")
|
|
55
|
+
return df.sort_values(["khipu_id", "position"]).reset_index(drop=True)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def _shift_tens(v: float) -> float:
|
|
59
|
+
if np.isnan(v):
|
|
60
|
+
return v
|
|
61
|
+
v = int(v)
|
|
62
|
+
h, t = v // 100 % 10, v // 10 % 10
|
|
63
|
+
return float(v - h * 90) if t == 0 and h > 0 and v < 1000 else float(v)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def import_okr(db: str | Path, errata: str = "none") -> pd.DataFrame:
|
|
67
|
+
"""Build a corpus from the Open Khipu Repository SQLite file (v2.1.0).
|
|
68
|
+
|
|
69
|
+
errata: "none" keeps OKR values; "confirmed" applies the Field Guide reading to KH0326 only;
|
|
70
|
+
"all" also applies it to KH0472. Cords with two single-knot clusters (KH0326 p100, p106)
|
|
71
|
+
are not fully corrected by this rule.
|
|
72
|
+
"""
|
|
73
|
+
con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
|
|
74
|
+
cords = pd.read_sql(
|
|
75
|
+
"""
|
|
76
|
+
select m.OKR_NUM khipu_id, c.CORD_ID cord_id, c.CLUSTER_ID group_id, c.CORD_ORDINAL position,
|
|
77
|
+
c.CORD_LEVEL level, c.ATTACHMENT_TYPE attachment,
|
|
78
|
+
(select sum(k.knot_value_type) from knot k where k.CORD_ID = c.CORD_ID) value,
|
|
79
|
+
(select count(*) from knot k where k.CORD_ID = c.CORD_ID) n_knots
|
|
80
|
+
from cord c join khipu_main m on m.KHIPU_ID = c.KHIPU_ID
|
|
81
|
+
""",
|
|
82
|
+
con,
|
|
83
|
+
)
|
|
84
|
+
colors = pd.read_sql(
|
|
85
|
+
"select rowid rid, color_id, CORD_ID cord_id, FULL_COLOR color from ascher_cord_color", con
|
|
86
|
+
)
|
|
87
|
+
con.close()
|
|
88
|
+
colors = colors.sort_values(["cord_id", "color_id", "rid"]).drop_duplicates("cord_id")
|
|
89
|
+
df = cords.merge(colors[["cord_id", "color"]], on="cord_id", how="left")
|
|
90
|
+
df["color"] = df["color"].fillna("").map(main_color)
|
|
91
|
+
df.loc[df["n_knots"] == 0, "value"] = np.nan
|
|
92
|
+
fix = {"none": set(), "confirmed": {"KH0326"}, "all": set(OKR_TENS_AS_HUNDREDS)}[errata]
|
|
93
|
+
mask = df["khipu_id"].isin(fix)
|
|
94
|
+
df.loc[mask, "value"] = df.loc[mask, "value"].map(_shift_tens)
|
|
95
|
+
return df.drop(columns=["n_knots"]).sort_values(["khipu_id", "position"]).reset_index(drop=True)
|
khipu_null/features.py
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
"""Pattern features. Each feature scores one khipu between 0 and 1, or returns None when it does
|
|
2
|
+
not apply (for example, no group is large enough).
|
|
3
|
+
|
|
4
|
+
A khipu is a `Khipu`: arrays of its cords at the pattern's level, in position order, plus the
|
|
5
|
+
index arrays of its groups."""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from collections.abc import Callable
|
|
10
|
+
from dataclasses import dataclass, replace
|
|
11
|
+
|
|
12
|
+
import numpy as np
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True)
|
|
16
|
+
class Khipu:
|
|
17
|
+
id: str
|
|
18
|
+
values: np.ndarray # float, NaN when the cord has no knots
|
|
19
|
+
colors: np.ndarray # object (str)
|
|
20
|
+
attachment: np.ndarray | None
|
|
21
|
+
groups: tuple[np.ndarray, ...] # cord indices of each group, in position order
|
|
22
|
+
slots: np.ndarray # index of each cord inside its group (0 = first)
|
|
23
|
+
|
|
24
|
+
def with_(self, **kw) -> "Khipu":
|
|
25
|
+
return replace(self, **kw)
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
Feature = Callable[[Khipu, dict], float | None]
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _runs(idx: np.ndarray, size: int):
|
|
32
|
+
for i in range(len(idx) // size):
|
|
33
|
+
yield idx[i * size:(i + 1) * size]
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def group_size(k: Khipu, spec: dict) -> float | None:
|
|
37
|
+
"""Share of cords that sit in groups whose size is a multiple of `size`."""
|
|
38
|
+
size = int(spec["size"])
|
|
39
|
+
n = sum(len(g) for g in k.groups)
|
|
40
|
+
return sum(len(g) for g in k.groups if len(g) % size == 0) / n if n else None
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def first_cord_range(k: Khipu, spec: dict) -> float | None:
|
|
44
|
+
"""Share of consecutive runs of `size` cords (within groups) whose first cord value is in [min, max]."""
|
|
45
|
+
size, lo, hi = int(spec["size"]), float(spec["min"]), float(spec["max"])
|
|
46
|
+
firsts = np.array([k.values[r[0]] for g in k.groups for r in _runs(g, size)], dtype=float)
|
|
47
|
+
firsts = firsts[~np.isnan(firsts)]
|
|
48
|
+
return float(((firsts >= lo) & (firsts <= hi)).mean()) if len(firsts) else None
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def value_range(k: Khipu, spec: dict) -> float | None:
|
|
52
|
+
"""Share of valued cords whose value is in [min, max]."""
|
|
53
|
+
v = k.values[~np.isnan(k.values)]
|
|
54
|
+
return float(((v >= float(spec["min"])) & (v <= float(spec["max"]))).mean()) if len(v) else None
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def group_sum(k: Khipu, spec: dict) -> float | None:
|
|
58
|
+
"""Share of groups (or runs of `size`, if given) where the cord at `sum_position` (first or last)
|
|
59
|
+
equals the sum of the other cords. Units need at least two other valued cords and a non-zero total."""
|
|
60
|
+
first = spec.get("sum_position", "first") == "first"
|
|
61
|
+
size = spec.get("size")
|
|
62
|
+
hits = []
|
|
63
|
+
for g in k.groups:
|
|
64
|
+
for u in (_runs(g, int(size)) if size else [g]):
|
|
65
|
+
if len(u) < 3:
|
|
66
|
+
continue
|
|
67
|
+
v = k.values[u]
|
|
68
|
+
s, rest = (v[0], v[1:]) if first else (v[-1], v[:-1])
|
|
69
|
+
rest = rest[~np.isnan(rest)]
|
|
70
|
+
if np.isnan(s) or len(rest) < 2 or rest.sum() == 0:
|
|
71
|
+
continue
|
|
72
|
+
hits.append(s == rest.sum())
|
|
73
|
+
return float(np.mean(hits)) if hits else None
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def color_repeat(k: Khipu, spec: dict) -> float | None:
|
|
77
|
+
"""Share of groups (with at least two full periods) whose colours repeat with `period` and that
|
|
78
|
+
use at least two colours inside one period. Single-colour groups repeat with any period, so they
|
|
79
|
+
are excluded rather than counted as matches."""
|
|
80
|
+
p = int(spec["period"])
|
|
81
|
+
hits = []
|
|
82
|
+
for g in k.groups:
|
|
83
|
+
c = k.colors[g]
|
|
84
|
+
if len(c) < 2 * p or len(set(c[:p])) < 2:
|
|
85
|
+
continue
|
|
86
|
+
n = len(c) // p * p
|
|
87
|
+
hits.append(bool(np.all(c[: n - p] == c[p:n])))
|
|
88
|
+
return float(np.mean(hits)) if hits else None
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def attachment_split(k: Khipu, spec: dict) -> float | None:
|
|
92
|
+
"""Share of runs of `size` whose first cord has attachment `code` (for example V or R)."""
|
|
93
|
+
if k.attachment is None:
|
|
94
|
+
return None
|
|
95
|
+
size, code = int(spec["size"]), str(spec["code"])
|
|
96
|
+
firsts = [k.attachment[r[0]] for g in k.groups for r in _runs(g, size)]
|
|
97
|
+
return float(np.mean([a == code for a in firsts])) if firsts else None
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
FEATURES: dict[str, Feature] = {
|
|
101
|
+
"group_size": group_size,
|
|
102
|
+
"first_cord_range": first_cord_range,
|
|
103
|
+
"value_range": value_range,
|
|
104
|
+
"group_sum": group_sum,
|
|
105
|
+
"color_repeat": color_repeat,
|
|
106
|
+
"attachment_split": attachment_split,
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
# The null each feature is tested against: (field it moves, how). Features with no entry describe
|
|
110
|
+
# structure or a whole-khipu distribution, which no permutation of that khipu can change, so they
|
|
111
|
+
# filter and rank but cannot reach a low p-value. A feature spec can override with `null: <mode>`.
|
|
112
|
+
# first_cord_range: are the first cords of runs more in range than cords picked at random?
|
|
113
|
+
# group_sum: given each slot's values, is the sum relation more frequent than chance?
|
|
114
|
+
# color_repeat: does the repeat survive rotating colours along the khipu (bands kept)?
|
|
115
|
+
# attachment_split: are run-first cords tied with `code` more than cords at random places?
|
|
116
|
+
NULLS = {
|
|
117
|
+
"first_cord_range": ("value", "within_khipu"),
|
|
118
|
+
"group_sum": ("value", "within_slot"),
|
|
119
|
+
"color_repeat": ("color", "rotate"),
|
|
120
|
+
"attachment_split": ("attachment", "rotate"),
|
|
121
|
+
}
|
khipu_null/rank.py
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
"""Scoring, structure-preserving nulls, and ranking with multiple-comparison control."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import math
|
|
6
|
+
|
|
7
|
+
import numpy as np
|
|
8
|
+
import pandas as pd
|
|
9
|
+
|
|
10
|
+
from .features import FEATURES, NULLS, Khipu
|
|
11
|
+
|
|
12
|
+
NULL_DEFAULTS = {"draws": "auto", "seed": 0}
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def to_khipus(corpus: pd.DataFrame, level: int, min_cords: int) -> list[Khipu]:
|
|
16
|
+
out = []
|
|
17
|
+
cords = corpus[corpus["level"] == level]
|
|
18
|
+
for kid, k in cords.groupby("khipu_id", sort=True):
|
|
19
|
+
k = k.sort_values("position").reset_index(drop=True)
|
|
20
|
+
if len(k) < min_cords:
|
|
21
|
+
continue
|
|
22
|
+
groups = tuple(sorted((np.asarray(ix) for ix in k.groupby("group_id", sort=False).indices.values()),
|
|
23
|
+
key=lambda g: g[0]))
|
|
24
|
+
slots = np.zeros(len(k), dtype=int)
|
|
25
|
+
for g in groups:
|
|
26
|
+
slots[g] = np.arange(len(g))
|
|
27
|
+
att = k["attachment"].astype(str).to_numpy(dtype=object) if "attachment" in k else None
|
|
28
|
+
out.append(Khipu(str(kid), k["value"].to_numpy(dtype=float), k["color"].astype(str).to_numpy(dtype=object),
|
|
29
|
+
att, groups, slots))
|
|
30
|
+
return out
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def null_of(f: dict) -> tuple[str, str] | None:
|
|
34
|
+
base = NULLS.get(f["type"])
|
|
35
|
+
if base is None:
|
|
36
|
+
return None
|
|
37
|
+
return (base[0], f.get("null", base[1]))
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def move(k: Khipu, field: str, mode: str, rng: np.random.Generator) -> Khipu:
|
|
41
|
+
"""Return a copy of the khipu with one field permuted. Groups, positions and levels stay fixed.
|
|
42
|
+
|
|
43
|
+
within_khipu: shuffle across the khipu. within_group: shuffle inside each group.
|
|
44
|
+
within_slot: shuffle among cords in the same slot of their group (all first cords together).
|
|
45
|
+
rotate: circular shift along the khipu, which keeps runs and bands intact."""
|
|
46
|
+
arr = {"value": k.values, "color": k.colors, "attachment": k.attachment}[field]
|
|
47
|
+
if arr is None:
|
|
48
|
+
return k
|
|
49
|
+
n = len(arr)
|
|
50
|
+
if mode == "within_khipu":
|
|
51
|
+
new = arr[rng.permutation(n)]
|
|
52
|
+
elif mode == "within_group":
|
|
53
|
+
new = arr.copy()
|
|
54
|
+
for g in k.groups:
|
|
55
|
+
new[g] = arr[rng.permutation(g)]
|
|
56
|
+
elif mode == "within_slot":
|
|
57
|
+
new = arr.copy()
|
|
58
|
+
for sl in np.unique(k.slots):
|
|
59
|
+
ix = np.flatnonzero(k.slots == sl)
|
|
60
|
+
new[ix] = arr[ix[rng.permutation(len(ix))]]
|
|
61
|
+
elif mode == "rotate":
|
|
62
|
+
new = np.roll(arr, int(rng.integers(1, n))) if n > 1 else arr
|
|
63
|
+
else:
|
|
64
|
+
raise ValueError(f"unknown null mode: {mode}")
|
|
65
|
+
key = {"value": "values", "color": "colors", "attachment": "attachment"}[field]
|
|
66
|
+
return k.with_(**{key: new})
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def combine(parts: list[tuple[float | None, float]]) -> float | None:
|
|
70
|
+
num = sum(w * s for s, w in parts if s is not None)
|
|
71
|
+
den = sum(w for s, w in parts if s is not None)
|
|
72
|
+
return num / den if den else None
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def score(k: Khipu, pattern: dict) -> tuple[float | None, dict]:
|
|
76
|
+
parts = {f["type"]: FEATURES[f["type"]](k, f) for f in pattern["features"]}
|
|
77
|
+
return combine([(parts[f["type"]], float(f.get("weight", 1.0))) for f in pattern["features"]]), parts
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def null_score(k: Khipu, pattern: dict, rng: np.random.Generator) -> float | None:
|
|
81
|
+
"""Each feature is evaluated on its own null version of the khipu. Features without a null
|
|
82
|
+
keep their observed value, so they shift both sides equally."""
|
|
83
|
+
parts = []
|
|
84
|
+
for f in pattern["features"]:
|
|
85
|
+
nm = null_of(f)
|
|
86
|
+
kk = move(k, *nm, rng) if nm else k
|
|
87
|
+
parts.append((FEATURES[f["type"]](kk, f), float(f.get("weight", 1.0))))
|
|
88
|
+
return combine(parts)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
def bh(p: np.ndarray) -> np.ndarray:
|
|
92
|
+
"""Benjamini-Hochberg q-values."""
|
|
93
|
+
n = len(p)
|
|
94
|
+
order = np.argsort(p)
|
|
95
|
+
q = np.empty(n)
|
|
96
|
+
prev = 1.0
|
|
97
|
+
for rank_, i in enumerate(order[::-1]):
|
|
98
|
+
prev = min(prev, p[i] * n / (n - rank_))
|
|
99
|
+
q[i] = prev
|
|
100
|
+
return q
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def auto_draws(n_khipus: int, top: int, alpha: float = 0.05) -> int:
|
|
104
|
+
"""Enough draws that the top `top` khipus could reach q <= alpha if they beat every draw:
|
|
105
|
+
q_min = n / (top * (draws + 1)), so draws >= n / (top * alpha). At least 200."""
|
|
106
|
+
return max(200, math.ceil(n_khipus / (top * alpha)))
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def rank(corpus: pd.DataFrame, pattern: dict, top: int = 5) -> dict:
|
|
110
|
+
null = {**NULL_DEFAULTS, **pattern.get("null", {})}
|
|
111
|
+
khipus = to_khipus(corpus, int(pattern.get("level", 1)), int(pattern.get("min_cords", 1)))
|
|
112
|
+
scored = [(k, *score(k, pattern)) for k in khipus]
|
|
113
|
+
scored = [(k, s, parts) for k, s, parts in scored if s is not None]
|
|
114
|
+
if not scored:
|
|
115
|
+
return {"table": pd.DataFrame(), "summary": {"khipus": 0}}
|
|
116
|
+
draws = auto_draws(len(scored), top) if null["draws"] == "auto" else int(null["draws"])
|
|
117
|
+
tested = [f for f in pattern["features"] if null_of(f)]
|
|
118
|
+
rng = np.random.default_rng(int(null["seed"]))
|
|
119
|
+
sims = np.full((len(scored), draws), np.nan)
|
|
120
|
+
rows = []
|
|
121
|
+
for i, (k, obs, parts) in enumerate(scored):
|
|
122
|
+
for d in range(draws):
|
|
123
|
+
s = null_score(k, pattern, rng)
|
|
124
|
+
sims[i, d] = np.nan if s is None else s
|
|
125
|
+
ok = sims[i][~np.isnan(sims[i])]
|
|
126
|
+
p = (1 + np.sum(ok >= obs - 1e-12)) / (1 + len(ok)) if tested else 1.0
|
|
127
|
+
rows.append({"khipu_id": k.id, "cords": len(k.values), "score": obs,
|
|
128
|
+
"null_mean": float(ok.mean()) if len(ok) else np.nan, "p": float(p),
|
|
129
|
+
**{f"f_{n}": v for n, v in parts.items()}})
|
|
130
|
+
table = pd.DataFrame(rows)
|
|
131
|
+
table["q"] = bh(table["p"].to_numpy())
|
|
132
|
+
order = table.sort_values(["score", "p"], ascending=[False, True]).index.to_numpy()
|
|
133
|
+
table = table.loc[order].reset_index(drop=True)
|
|
134
|
+
sims = sims[order]
|
|
135
|
+
table.insert(0, "rank", range(1, len(table) + 1))
|
|
136
|
+
|
|
137
|
+
# Selection test: is our top-k better than the top-k picked from null versions of every khipu?
|
|
138
|
+
filled = np.where(np.isnan(sims), -np.inf, sims)
|
|
139
|
+
null_top = np.sort(filled, axis=0)[::-1][:top].mean(axis=0)
|
|
140
|
+
obs_top = float(table["score"].head(top).mean())
|
|
141
|
+
summary = {
|
|
142
|
+
"khipus": len(table),
|
|
143
|
+
"draws": draws,
|
|
144
|
+
"min_attainable_p": 1 / (draws + 1),
|
|
145
|
+
"tested_features": {f["type"]: "{}:{}".format(*null_of(f)) for f in tested},
|
|
146
|
+
"untested_features": [f["type"] for f in pattern["features"] if not null_of(f)],
|
|
147
|
+
"top": top,
|
|
148
|
+
"top_mean_score": obs_top,
|
|
149
|
+
"null_top_mean_95": [float(np.percentile(null_top, 2.5)), float(np.percentile(null_top, 97.5))],
|
|
150
|
+
"top_p": float((1 + np.sum(null_top >= obs_top - 1e-12)) / (1 + len(null_top))),
|
|
151
|
+
"significant_at_q05": int((table["q"] <= 0.05).sum()),
|
|
152
|
+
}
|
|
153
|
+
return {"table": table, "summary": summary}
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: khipu-null
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Rank khipus against a reference pattern and test whether the match is chance, with structure-preserving permutation nulls.
|
|
5
|
+
Project-URL: Homepage, https://crafter.ing/research/khipu-colour-legend
|
|
6
|
+
Project-URL: Repository, https://github.com/crafter-research/khipu-null
|
|
7
|
+
Author: Crafter Research
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Requires-Python: >=3.11
|
|
11
|
+
Requires-Dist: numpy>=1.26
|
|
12
|
+
Requires-Dist: pandas>=2.1
|
|
13
|
+
Requires-Dist: pyyaml>=6.0
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<a href="https://crafter.ing"><picture>
|
|
18
|
+
<source media="(prefers-color-scheme: dark)" srcset="assets/crafter-glyph-dark.svg">
|
|
19
|
+
<img src="assets/crafter-glyph-light.svg" alt="Crafter Research" width="72">
|
|
20
|
+
</picture></a>
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
<h1 align="center">khipu-null</h1>
|
|
24
|
+
|
|
25
|
+
<p align="center">Rank khipus against a reference pattern and test whether the match is chance.</p>
|
|
26
|
+
|
|
27
|
+
<p align="center">
|
|
28
|
+
<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-2f5d4a"></a>
|
|
29
|
+
<img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-2f5d4a">
|
|
30
|
+
</p>
|
|
31
|
+
|
|
32
|
+
You describe a pattern (group sizes, which cords hold totals, colour repeats, attachment, value ranges). khipu-null scores every khipu in a corpus, ranks them, and compares each score against null versions of the same khipu where only the field that feature reads is permuted. Groups, positions and levels never move.
|
|
33
|
+
|
|
34
|
+
It answers three questions directly. Which khipus match the pattern? Which top k are the best candidates, and is that top k better than what you would pick by chance from the same corpus? Is any single match unlikely to be a coincidence, after correcting for testing hundreds of khipus?
|
|
35
|
+
|
|
36
|
+
Developed by [Crafter Research](https://crafter.ing) from the null designs validated in the [khipu colour and number analyses](https://crafter.ing/research/khipu-colour-legend).
|
|
37
|
+
|
|
38
|
+
## Quickstart
|
|
39
|
+
|
|
40
|
+
Requires [uv](https://docs.astral.sh/uv/).
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
uvx --from git+https://github.com/crafter-research/khipu-null khipu-null --help
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Try it on the public Open Khipu Repository:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
curl -sL -o khipu.db https://raw.githubusercontent.com/khipulab/open-khipu-repository/v2.1.0/data/khipu.db
|
|
50
|
+
uvx --from git+https://github.com/crafter-research/khipu-null khipu-null import-okr khipu.db -o okr.csv --errata confirmed
|
|
51
|
+
curl -sLO https://raw.githubusercontent.com/crafter-research/khipu-null/main/examples/santa-valley.yaml
|
|
52
|
+
uvx --from git+https://github.com/crafter-research/khipu-null khipu-null rank okr.csv santa-valley.yaml -o out --top 6
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`out/` gets `report.md`, `ranking.csv` and `summary.json`.
|
|
56
|
+
|
|
57
|
+
## Input format
|
|
58
|
+
|
|
59
|
+
Any CSV with one row per cord works:
|
|
60
|
+
|
|
61
|
+
| Column | Meaning |
|
|
62
|
+
|---|---|
|
|
63
|
+
| khipu_id | khipu identifier |
|
|
64
|
+
| cord_id | cord identifier, unique |
|
|
65
|
+
| group_id | cord group (cluster) |
|
|
66
|
+
| position | order along the khipu |
|
|
67
|
+
| level | 1 pendant, 2+ subsidiary |
|
|
68
|
+
| color | colour code as recorded |
|
|
69
|
+
| value | decoded knot value, empty if no knots |
|
|
70
|
+
| attachment | optional, recto/verso code |
|
|
71
|
+
|
|
72
|
+
## Patterns and nulls
|
|
73
|
+
|
|
74
|
+
Start from `examples/template.yaml`. Keep only the features your model predicts.
|
|
75
|
+
|
|
76
|
+
| Feature | Question | Null |
|
|
77
|
+
|---|---|---|
|
|
78
|
+
| `first_cord_range` | Are the first cords of runs in [min, max] more often than cords at random? | values shuffled across the khipu |
|
|
79
|
+
| `group_sum` | Does the first (or last) cord equal the sum of the others? | values shuffled among cords in the same slot of their group |
|
|
80
|
+
| `color_repeat` | Do colours repeat with this period? Single-colour groups are excluded. | colours rotated along the khipu (bands kept) |
|
|
81
|
+
| `attachment_split` | Are run-first cords tied with this code more than cords at random places? | attachments rotated along the khipu |
|
|
82
|
+
| `group_size` | Are groups made of whole units of this size? | none (structure) |
|
|
83
|
+
| `value_range` | Share of values in [min, max] | none (whole-khipu distribution) |
|
|
84
|
+
|
|
85
|
+
A feature spec can override its null with `null: within_khipu | within_group | within_slot | rotate`.
|
|
86
|
+
|
|
87
|
+
## Reading the report
|
|
88
|
+
|
|
89
|
+
- Per khipu: score, null mean, p (one-sided permutation) and q (Benjamini-Hochberg across all scored khipus).
|
|
90
|
+
- Top-k test: the mean score of your top k against the top k picked from null versions of every khipu. This is the honest answer to "are these five special, or would any five look this good?".
|
|
91
|
+
- `draws: auto` uses enough draws that a top-k khipu could reach q <= 0.05 if it beat every draw. With fewer draws, no khipu can be significant across a large corpus.
|
|
92
|
+
|
|
93
|
+
Example on the OKR (v2.1.0, KH0326 errata fixed), with a pattern written from the Santa Valley khipus. This is a sanity check, since the pattern comes from those khipus. Five of the six Santa khipus rank in the top 6 of 328; the top-6 mean is 0.994 against a null of [0.954, 0.986], p = 0.001; no single khipu reaches q <= 0.05.
|
|
94
|
+
|
|
95
|
+
## Limits
|
|
96
|
+
|
|
97
|
+
- A low p says the match is unlikely under that null, given each khipu's structure. It does not say what a khipu means.
|
|
98
|
+
- Structural features cannot be tested by permuting a khipu. They rank, they do not prove.
|
|
99
|
+
- Shuffling colours cord by cord breaks colour bands and makes chance matches look rare. That is why colours rotate.
|
|
100
|
+
- Shuffling values across the whole khipu ignores position effects, such as larger first cords. That is why `group_sum` shuffles within slots.
|
|
101
|
+
|
|
102
|
+
## Data notes
|
|
103
|
+
|
|
104
|
+
OKR v2.1.0 and the Khipu Field Guide give single knots a different decimal place on KH0326 and KH0472 (OKR 100, Field Guide 10). `import-okr --errata confirmed` applies the Field Guide reading to KH0326, which Urton (2017, Appendix B) supports; `--errata all` also applies it to KH0472. This is an open discrepancy, not a confirmed error in OKR. Details: [audit-okr-kfg.md](https://github.com/crafter-research/khipu/blob/main/notes/audit-okr-kfg.md).
|
|
105
|
+
|
|
106
|
+
## Citation
|
|
107
|
+
|
|
108
|
+
If you use khipu-null, please cite it (GitHub's "Cite this repository" button reads `CITATION.cff`): Crafter Research (2026), khipu-null, https://github.com/crafter-research/khipu-null
|
|
109
|
+
|
|
110
|
+
## License
|
|
111
|
+
|
|
112
|
+
Code: MIT. Documentation and examples: CC BY 4.0.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
khipu_null/__init__.py,sha256=rRFX0M_XGg_LLG3JB_MhrJ9OLsfBPOE3LT1iNhcjVMI,107
|
|
2
|
+
khipu_null/cli.py,sha256=_0jbzcxJEMCUAwWyv4j4HJCi0EMNdwYN-6aPzSiRm0A,4434
|
|
3
|
+
khipu_null/corpus.py,sha256=ySQaFjwdb_VGKfA-tsFwWhQJ6Ew4UZwDC6Ymc4OmMRQ,4103
|
|
4
|
+
khipu_null/features.py,sha256=8H1DJSmNTDrXKWthfXyptSYq4md3w-hsfOI765wBgFk,4981
|
|
5
|
+
khipu_null/rank.py,sha256=XDBPQm1n4podK3WIOQBc7RJcdvZLT-ijS1IQT5X-AOw,6523
|
|
6
|
+
khipu_null-0.1.0.dist-info/METADATA,sha256=4mOdvS3HYPuwzuiGnPZLXFaui1o__MlVoQ3PD2Cg2rE,6061
|
|
7
|
+
khipu_null-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
8
|
+
khipu_null-0.1.0.dist-info/entry_points.txt,sha256=2vXSJOUyBMEQa6ZqX0-l0jDAYIODAJv7RP3cg-5L7DA,51
|
|
9
|
+
khipu_null-0.1.0.dist-info/licenses/LICENSE,sha256=7IrZWxH6gotmEdSb7cquCpYmSAFYWjs0UJvpsTcUfo0,1073
|
|
10
|
+
khipu_null-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Crafter Research
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|