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 ADDED
@@ -0,0 +1,3 @@
1
+ """Rank khipus against a reference pattern and test whether the match is chance."""
2
+
3
+ __version__ = "0.1.0"
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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ khipu-null = khipu_null.cli:main
@@ -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.