khipu-null 0.1.0__tar.gz

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.
@@ -0,0 +1,20 @@
1
+ name: ci
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ jobs:
9
+ test:
10
+ runs-on: ubuntu-latest
11
+ strategy:
12
+ matrix:
13
+ python: ["3.11", "3.12", "3.13"]
14
+ steps:
15
+ - uses: actions/checkout@v7.0.1
16
+ - uses: astral-sh/setup-uv@v10.3.3
17
+ with:
18
+ python-version: ${{ matrix.python }}
19
+ - run: uv sync --locked
20
+ - run: uv run pytest -q
@@ -0,0 +1,36 @@
1
+ name: release
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+
7
+ jobs:
8
+ build:
9
+ runs-on: ubuntu-latest
10
+ steps:
11
+ - uses: actions/checkout@v7.0.1
12
+ - uses: astral-sh/setup-uv@v10.3.3
13
+ - name: Check tag matches version
14
+ run: |
15
+ version=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
16
+ test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != version $version"; exit 1; }
17
+ - run: uv sync --locked
18
+ - run: uv run pytest -q
19
+ - run: uv build
20
+ - uses: actions/upload-artifact@v7.0.2
21
+ with:
22
+ name: dist
23
+ path: dist/
24
+
25
+ publish:
26
+ needs: build
27
+ runs-on: ubuntu-latest
28
+ environment: pypi
29
+ permissions:
30
+ id-token: write
31
+ steps:
32
+ - uses: actions/download-artifact@v8.0.2
33
+ with:
34
+ name: dist
35
+ path: dist/
36
+ - uses: pypa/gh-action-pypi-publish@v1.14.3
@@ -0,0 +1,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.egg-info/
4
+ dist/
5
+ data/
6
+ out/
@@ -0,0 +1,12 @@
1
+ cff-version: 1.2.0
2
+ message: "If you use khipu-null, please cite it as below."
3
+ title: "khipu-null: structure-preserving permutation tests for khipu pattern matching"
4
+ authors:
5
+ - name: "Crafter Research"
6
+ - family-names: "Hugo Quispe"
7
+ given-names: "Railly"
8
+ version: 0.1.0
9
+ date-released: 2026-11-19
10
+ repository-code: "https://github.com/crafter-research/khipu-null"
11
+ license: MIT
12
+ type: software
@@ -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.
@@ -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,97 @@
1
+ <p align="center">
2
+ <a href="https://crafter.ing"><picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="assets/crafter-glyph-dark.svg">
4
+ <img src="assets/crafter-glyph-light.svg" alt="Crafter Research" width="72">
5
+ </picture></a>
6
+ </p>
7
+
8
+ <h1 align="center">khipu-null</h1>
9
+
10
+ <p align="center">Rank khipus against a reference pattern and test whether the match is chance.</p>
11
+
12
+ <p align="center">
13
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-2f5d4a"></a>
14
+ <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-2f5d4a">
15
+ </p>
16
+
17
+ 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.
18
+
19
+ 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?
20
+
21
+ 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).
22
+
23
+ ## Quickstart
24
+
25
+ Requires [uv](https://docs.astral.sh/uv/).
26
+
27
+ ```bash
28
+ uvx --from git+https://github.com/crafter-research/khipu-null khipu-null --help
29
+ ```
30
+
31
+ Try it on the public Open Khipu Repository:
32
+
33
+ ```bash
34
+ curl -sL -o khipu.db https://raw.githubusercontent.com/khipulab/open-khipu-repository/v2.1.0/data/khipu.db
35
+ uvx --from git+https://github.com/crafter-research/khipu-null khipu-null import-okr khipu.db -o okr.csv --errata confirmed
36
+ curl -sLO https://raw.githubusercontent.com/crafter-research/khipu-null/main/examples/santa-valley.yaml
37
+ uvx --from git+https://github.com/crafter-research/khipu-null khipu-null rank okr.csv santa-valley.yaml -o out --top 6
38
+ ```
39
+
40
+ `out/` gets `report.md`, `ranking.csv` and `summary.json`.
41
+
42
+ ## Input format
43
+
44
+ Any CSV with one row per cord works:
45
+
46
+ | Column | Meaning |
47
+ |---|---|
48
+ | khipu_id | khipu identifier |
49
+ | cord_id | cord identifier, unique |
50
+ | group_id | cord group (cluster) |
51
+ | position | order along the khipu |
52
+ | level | 1 pendant, 2+ subsidiary |
53
+ | color | colour code as recorded |
54
+ | value | decoded knot value, empty if no knots |
55
+ | attachment | optional, recto/verso code |
56
+
57
+ ## Patterns and nulls
58
+
59
+ Start from `examples/template.yaml`. Keep only the features your model predicts.
60
+
61
+ | Feature | Question | Null |
62
+ |---|---|---|
63
+ | `first_cord_range` | Are the first cords of runs in [min, max] more often than cords at random? | values shuffled across the khipu |
64
+ | `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 |
65
+ | `color_repeat` | Do colours repeat with this period? Single-colour groups are excluded. | colours rotated along the khipu (bands kept) |
66
+ | `attachment_split` | Are run-first cords tied with this code more than cords at random places? | attachments rotated along the khipu |
67
+ | `group_size` | Are groups made of whole units of this size? | none (structure) |
68
+ | `value_range` | Share of values in [min, max] | none (whole-khipu distribution) |
69
+
70
+ A feature spec can override its null with `null: within_khipu | within_group | within_slot | rotate`.
71
+
72
+ ## Reading the report
73
+
74
+ - Per khipu: score, null mean, p (one-sided permutation) and q (Benjamini-Hochberg across all scored khipus).
75
+ - 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?".
76
+ - `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.
77
+
78
+ 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.
79
+
80
+ ## Limits
81
+
82
+ - A low p says the match is unlikely under that null, given each khipu's structure. It does not say what a khipu means.
83
+ - Structural features cannot be tested by permuting a khipu. They rank, they do not prove.
84
+ - Shuffling colours cord by cord breaks colour bands and makes chance matches look rare. That is why colours rotate.
85
+ - Shuffling values across the whole khipu ignores position effects, such as larger first cords. That is why `group_sum` shuffles within slots.
86
+
87
+ ## Data notes
88
+
89
+ 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).
90
+
91
+ ## Citation
92
+
93
+ 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
94
+
95
+ ## License
96
+
97
+ Code: MIT. Documentation and examples: CC BY 4.0.
@@ -0,0 +1,3 @@
1
+ <svg width="258" height="258" viewBox="0 0 258 258" xmlns="http://www.w3.org/2000/svg">
2
+ <path fill="#cfe7d2" d="M118.238 16.262C111.482 11.4 99.9003 5.62505 92.2517 3.26931C74.9754 -2.31209 61.2312 0.473844 52.1188 3.50057C34.3839 9.3909 23.1637 17.3398 12.9798 32.0237C-3.018 54.7384 -1.30627 92.0001 17.4396 113.282C21.6313 118.385 23.9203 117.58 40.6062 105.794C41.1838 105.243 38.9626 101.57 35.6118 97.3194C28.0736 87.6862 23.7841 70.2632 26.209 60.5011C34.074 29.8239 72.1683 13.8835 96.3841 31.0488C101.735 34.7695 118.578 50.1432 133.719 65.2112C156.435 87.3932 163.188 92.535 168.887 92.0615C174.586 91.588 176.608 89.6589 177.27 83.5096C178.226 76.8049 175.724 72.8474 162.814 60.893C154.116 52.642 147.113 45.2566 147.134 43.8571C147.151 42.7375 153.199 38.0697 160.665 33.7035C208.922 4.47877 259.519 64.8793 219.089 103.462C213.891 108.422 204.705 113.602 198.705 115.191C191.85 116.767 160.245 117.687 120.978 117.092C47.5669 115.979 43.5706 116.758 23.9629 133.539C-1.12747 155.276 -7.39134 192.976 9.54962 220.67C31.485 256.839 79.721 266.529 114.252 241.576L126.916 232.249L141.283 241.986C164.663 258.018 183.68 261.387 206.842 254.179C253.172 239.483 271.118 182.082 241.827 143.002C238.477 138.752 236.774 138.446 232.187 140.616C218.126 148.242 218.419 147.686 226.416 164.606C232.48 177.576 233.542 182.632 231.971 192.407C227.614 216.978 208.584 233.207 184.682 232.845C166.187 232.564 160.267 228.835 126.619 195.569C108.947 178.502 92.6562 164.257 90.3799 164.222C86.1118 164.158 76.8749 172.697 76.8113 176.895C76.7943 178.015 84.341 187.088 93.8711 196.752L110.969 214.089L100.607 221.771C64.0584 248.374 13.049 215.124 25.6449 172.76C29.5392 159.94 42.8446 145.864 55.4323 141.575C60.2992 139.689 90.1929 139.023 130.598 139.635C204.863 140.762 213.705 139.496 230.998 125.2C282.576 83.4269 254.198 2.92565 187.611 2.19579C168.262 1.90235 157.675 5.66133 139.549 18.5449L130.342 25.1245L118.238 16.262Z"/>
3
+ </svg>
@@ -0,0 +1,3 @@
1
+ <svg width="258" height="258" viewBox="0 0 258 258" xmlns="http://www.w3.org/2000/svg">
2
+ <path fill="#07100d" d="M118.238 16.262C111.482 11.4 99.9003 5.62505 92.2517 3.26931C74.9754 -2.31209 61.2312 0.473844 52.1188 3.50057C34.3839 9.3909 23.1637 17.3398 12.9798 32.0237C-3.018 54.7384 -1.30627 92.0001 17.4396 113.282C21.6313 118.385 23.9203 117.58 40.6062 105.794C41.1838 105.243 38.9626 101.57 35.6118 97.3194C28.0736 87.6862 23.7841 70.2632 26.209 60.5011C34.074 29.8239 72.1683 13.8835 96.3841 31.0488C101.735 34.7695 118.578 50.1432 133.719 65.2112C156.435 87.3932 163.188 92.535 168.887 92.0615C174.586 91.588 176.608 89.6589 177.27 83.5096C178.226 76.8049 175.724 72.8474 162.814 60.893C154.116 52.642 147.113 45.2566 147.134 43.8571C147.151 42.7375 153.199 38.0697 160.665 33.7035C208.922 4.47877 259.519 64.8793 219.089 103.462C213.891 108.422 204.705 113.602 198.705 115.191C191.85 116.767 160.245 117.687 120.978 117.092C47.5669 115.979 43.5706 116.758 23.9629 133.539C-1.12747 155.276 -7.39134 192.976 9.54962 220.67C31.485 256.839 79.721 266.529 114.252 241.576L126.916 232.249L141.283 241.986C164.663 258.018 183.68 261.387 206.842 254.179C253.172 239.483 271.118 182.082 241.827 143.002C238.477 138.752 236.774 138.446 232.187 140.616C218.126 148.242 218.419 147.686 226.416 164.606C232.48 177.576 233.542 182.632 231.971 192.407C227.614 216.978 208.584 233.207 184.682 232.845C166.187 232.564 160.267 228.835 126.619 195.569C108.947 178.502 92.6562 164.257 90.3799 164.222C86.1118 164.158 76.8749 172.697 76.8113 176.895C76.7943 178.015 84.341 187.088 93.8711 196.752L110.969 214.089L100.607 221.771C64.0584 248.374 13.049 215.124 25.6449 172.76C29.5392 159.94 42.8446 145.864 55.4323 141.575C60.2992 139.689 90.1929 139.023 130.598 139.635C204.863 140.762 213.705 139.496 230.998 125.2C282.576 83.4269 254.198 2.92565 187.611 2.19579C168.262 1.90235 157.675 5.66133 139.549 18.5449L130.342 25.1245L118.238 16.262Z"/>
3
+ </svg>
@@ -0,0 +1,15 @@
1
+ # Sanity check, not a discovery: a pattern written from the Santa Valley khipus
2
+ # (Medrano and Urton 2018; Urton 2017, ch. 12). The tool should rank them near the top.
3
+ name: santa-valley-six-cord-tribute
4
+ level: 1 # pendants
5
+ min_cords: 30
6
+ features:
7
+ - type: group_size # colour bands made of whole groups of six cords
8
+ size: 6
9
+ - type: first_cord_range # the first cord of each group of six records 0 to 13 (pesos)
10
+ size: 6
11
+ min: 0
12
+ max: 13
13
+ null:
14
+ draws: auto
15
+ seed: 0
@@ -0,0 +1,27 @@
1
+ # Template: describe your reference model as features.
2
+ # Keep only the features your model actually predicts. Each tested feature has its own null.
3
+ name: my-reference-model
4
+ level: 1 # 1 = pendants, 2 = subsidiaries
5
+ min_cords: 20 # skip khipus with fewer cords at this level
6
+ features:
7
+ - type: group_size # untested: structure only
8
+ size: 6 # groups made of whole units of 6 cords
9
+ - type: first_cord_range # tested: first cords of runs vs cords at random (values within_khipu)
10
+ size: 6
11
+ min: 0
12
+ max: 13
13
+ - type: group_sum # tested: the sum relation, keeping each slot's values (within_slot)
14
+ sum_position: first # or last
15
+ size: 6 # optional: test runs of 6 instead of whole groups
16
+ - type: color_repeat # tested: repeat survives rotating colours along the khipu (rotate)
17
+ period: 3
18
+ - type: attachment_split # tested: run-first cords tied with this code more than at random
19
+ size: 6
20
+ code: V
21
+ - type: value_range # untested: whole-khipu distribution
22
+ min: 0
23
+ max: 99
24
+ weight: 0.5 # optional weight in the combined score (default 1)
25
+ null:
26
+ draws: auto # enough draws for the top-k to reach q <= 0.05 if it beats every draw
27
+ seed: 0
@@ -0,0 +1,27 @@
1
+ [project]
2
+ name = "khipu-null"
3
+ version = "0.1.0"
4
+ description = "Rank khipus against a reference pattern and test whether the match is chance, with structure-preserving permutation nulls."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ requires-python = ">=3.11"
8
+ authors = [{ name = "Crafter Research" }]
9
+ dependencies = ["numpy>=1.26", "pandas>=2.1", "pyyaml>=6.0"]
10
+
11
+ [project.scripts]
12
+ khipu-null = "khipu_null.cli:main"
13
+
14
+ [project.urls]
15
+ Homepage = "https://crafter.ing/research/khipu-colour-legend"
16
+ Repository = "https://github.com/crafter-research/khipu-null"
17
+
18
+ [dependency-groups]
19
+ dev = ["pytest>=8"]
20
+
21
+ [build-system]
22
+ requires = ["hatchling"]
23
+ build-backend = "hatchling.build"
24
+
25
+ [[tool.uv.index]]
26
+ url = "https://pypi.org/simple"
27
+ default = true
@@ -0,0 +1,3 @@
1
+ """Rank khipus against a reference pattern and test whether the match is chance."""
2
+
3
+ __version__ = "0.1.0"
@@ -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())
@@ -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)