cld-reducer 0.2.0__tar.gz

cld_reducer-0.2.0/.gitignore

@@ -0,0 +1,30 @@
+.DS_Store
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+build/
+dist/
+*.egg-info/
+htmlcov/
+.coverage
+*.csv.tmp
+
+# R
+.Rproj.user
+.Rhistory
+.RData
+.Ruserdata
+*.tar.gz
+*.Rcheck/
+
+# Python
+python/dist/
+python/build/
+
+# JavaScript
+node_modules/
+js/dist/
+*.tgz

cld_reducer-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aigora
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cld_reducer-0.2.0/NOTICE

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

cld_reducer-0.2.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: cld-reducer
+Version: 0.2.0
+Summary: Reduce compact letter displays while preserving pairwise statistical relationships
+Project-URL: Homepage, https://github.com/aigorahub/cld-reducer
+Project-URL: Repository, https://github.com/aigorahub/cld-reducer
+Project-URL: Source, https://github.com/aigorahub/cld-reducer/tree/main/python
+Project-URL: Issues, https://github.com/aigorahub/cld-reducer/issues
+Author: John Ennis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: compact-letter-display,mixed-integer-programming,post-hoc,sensometrics,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: highspy<1.16,>=1.15.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cld-reducer for Python
+
+Reduce compact letter displays (CLDs) while preserving the pairwise statistical relationships they encode. This is the Python package of the [cld-reducer repository](https://github.com/aigorahub/cld-reducer), which also holds an R package and a JavaScript package. All three solve the assignment-minimum clique covering of Ennis, Fayle, and Ennis (2012), <https://doi.org/10.1145/2133803.2275596>, as a mixed-integer program with [HiGHS](https://highs.dev), and they return the same display for the same input. The rules they follow are in `docs/algorithm.md` in the repository.
+
+The solver is HiGHS through `highspy`. The dependencies are `highspy`, NumPy, and pandas.
+
+## Installation
+
+Install from PyPI:
+
+```sh
+pip install cld-reducer
+```
+
+To install the development version from the repository:
+
+```sh
+pip install "git+https://github.com/aigorahub/cld-reducer.git#subdirectory=python"
+```
+
+The `#subdirectory=python` part is needed because the Python package lives in `python/`. Python 3.10 or later. The module is `cld_reducer` and the command line tool is `cld-reduce`.
+
+For development, work from this folder:
+
+```sh
+cd python
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+ruff check . && ruff format --check . && pytest
+```
+
+## Usage
+
+```python
+import pandas as pd
+
+from cld_reducer import reduce_letters
+
+# One row for each pair. True means the groups differ significantly.
+pairs = pd.DataFrame(
+    [
+        ("1", "2", False),
+        ("1", "3", False),
+        ("1", "4", True),
+        ("1", "5", True),
+        ("2", "3", False),
+        ("2", "4", False),
+        ("2", "5", True),
+        ("3", "4", False),
+        ("3", "5", False),
+        ("4", "5", False),
+    ],
+    columns=["group1", "group2", "significant"],
+)
+means = pd.DataFrame({"group": ["1", "2", "3", "4", "5"], "mean": [3.73, 3.57, 3.46, 3.33, 3.30]})
+
+result = reduce_letters(pairs, means)
+print(result.letters)
+# {'1': 'A', '2': 'AB', '3': 'AC', '4': 'BC', '5': 'C'}
+print(result.to_frame())
+#   group letters assignments
+# 0     1       A           A
+# 1     2      AB         A B
+# 2     3      AC         A C
+# 3     4      BC         B C
+# 4     5       C           C
+print(result.stats)
+# {'assignments_before': 9, 'assignments_after': 8, 'reduction_pct': 11.11111111111111, 'num_letters_before': 3, 'num_letters_after': 3, 'num_groups': 5, 'num_edges': 7, 'solver_status': 'Optimal', 'objective': 8}
+```
+
+This example works after package installation and needs no external files. `reduce_letters` takes complete pairwise results: one row for each pair of groups, with a boolean column that tells whether the pair differs significantly. Missing pairs are rejected. `means` is optional and orders the groups and the letters. If you already have the non-significance matrix, use `reduce_from_adjacency`; there, `True` means two groups are not significantly different and must share a letter.
+
+The result, a `CLDReductionResult`, has:
+
+- `letters`: the display of each group, for example `"AC"` (tokens are joined with spaces after `Z`, as in `"Z AA"`)
+- `assignments`: the letters of each group as a tuple, the safe machine-readable form
+- `stats`: the counts before and after the reduction and the solver status; `reduction_pct` is not rounded
+- `relationship_preserved`: always `True` for a returned result
+- `to_frame()`: a tidy `pandas.DataFrame`
+
+The public names are `reduce_letters`, `reduce_from_adjacency`, `CLDReductionResult`, `CLDReducerError`, `InvalidInputError`, and `SolverError`.
+
+When several displays have the same, smallest number of assignments, the package returns the canonical one defined in `docs/algorithm.md`, so R, Python, and JavaScript agree. `time_limit` is one time budget in seconds for all solves of a call, and `max_cliques` (10,000 by default; `None` removes it) bounds the number of maximal cliques.
+
+## Command line
+
+```sh
+cld-reduce examples/simple_abc_to_ac_pairs.csv \
+  --means examples/simple_abc_to_ac_means.csv \
+  --time-limit 30 \
+  --out reduced.csv
+```
+
+The paths above refer to files in a checkout or an extracted source archive. For your own data, pass your CSV paths. The pairs file has the columns `group1`, `group2`, and `significant`; the optional means file has `group` and `mean`. The output CSV has the reduced letters and the summary statistics. Other flags: `--group1`, `--group2`, `--significant`, `--max-cliques`, `--no-max-cliques`, and `--method`.
+
+## Examples
+
+The following scripts and CSV files are included in a repository checkout or the source archive, but not in the installed wheel. Run them from `python/` in a checkout, or from the root of an extracted source archive:
+
+```sh
+python examples/simple_abc_to_ac.py
+python examples/piepho2004_wheat.py
+```
+
+The CSV files in `examples/` are identical copies of the files in `conformance/data/` at the repository root.
+
+## Changes in 0.2.0
+
+The 0.2.0 release moved the package to `python/` and the solver to `highspy`, which can change the display for inputs with several minimal displays and can rename letters. See the root `NEWS.md` for the full list.
+
+## License
+
+MIT. See `LICENSE`.
+
+## Input and release notes
+
+CSV label columns preserve their exact text, including `001`, `NA`, `NaN`, and
+empty strings. A blank CSV label is an empty-string label; missing values in API
+objects still raise `InvalidInputError`. Means must remain finite numbers.
+The means table uses `group` and `mean` when both exist, or its first two columns.
+A list of pair rows preserves each numeric label before conversion to text.
+Uneven adjacency rows raise the package's square-matrix error.
+
+The source distribution contains example scripts and CSV files. The wheel
+contains the importable package and its license and data notice. Shared
+conformance fixtures remain in the repository, so source-distribution tests skip
+those cases when the fixtures are absent. CI tests both installed distributions
+outside the checkout. See `docs/releasing.md` in the repository for release steps.
+Example data reuse remains subject to the conditions in `NOTICE`.

cld_reducer-0.2.0/README.md

@@ -0,0 +1,130 @@
+# cld-reducer for Python
+
+Reduce compact letter displays (CLDs) while preserving the pairwise statistical relationships they encode. This is the Python package of the [cld-reducer repository](https://github.com/aigorahub/cld-reducer), which also holds an R package and a JavaScript package. All three solve the assignment-minimum clique covering of Ennis, Fayle, and Ennis (2012), <https://doi.org/10.1145/2133803.2275596>, as a mixed-integer program with [HiGHS](https://highs.dev), and they return the same display for the same input. The rules they follow are in `docs/algorithm.md` in the repository.
+
+The solver is HiGHS through `highspy`. The dependencies are `highspy`, NumPy, and pandas.
+
+## Installation
+
+Install from PyPI:
+
+```sh
+pip install cld-reducer
+```
+
+To install the development version from the repository:
+
+```sh
+pip install "git+https://github.com/aigorahub/cld-reducer.git#subdirectory=python"
+```
+
+The `#subdirectory=python` part is needed because the Python package lives in `python/`. Python 3.10 or later. The module is `cld_reducer` and the command line tool is `cld-reduce`.
+
+For development, work from this folder:
+
+```sh
+cd python
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+ruff check . && ruff format --check . && pytest
+```
+
+## Usage
+
+```python
+import pandas as pd
+
+from cld_reducer import reduce_letters
+
+# One row for each pair. True means the groups differ significantly.
+pairs = pd.DataFrame(
+    [
+        ("1", "2", False),
+        ("1", "3", False),
+        ("1", "4", True),
+        ("1", "5", True),
+        ("2", "3", False),
+        ("2", "4", False),
+        ("2", "5", True),
+        ("3", "4", False),
+        ("3", "5", False),
+        ("4", "5", False),
+    ],
+    columns=["group1", "group2", "significant"],
+)
+means = pd.DataFrame({"group": ["1", "2", "3", "4", "5"], "mean": [3.73, 3.57, 3.46, 3.33, 3.30]})
+
+result = reduce_letters(pairs, means)
+print(result.letters)
+# {'1': 'A', '2': 'AB', '3': 'AC', '4': 'BC', '5': 'C'}
+print(result.to_frame())
+#   group letters assignments
+# 0     1       A           A
+# 1     2      AB         A B
+# 2     3      AC         A C
+# 3     4      BC         B C
+# 4     5       C           C
+print(result.stats)
+# {'assignments_before': 9, 'assignments_after': 8, 'reduction_pct': 11.11111111111111, 'num_letters_before': 3, 'num_letters_after': 3, 'num_groups': 5, 'num_edges': 7, 'solver_status': 'Optimal', 'objective': 8}
+```
+
+This example works after package installation and needs no external files. `reduce_letters` takes complete pairwise results: one row for each pair of groups, with a boolean column that tells whether the pair differs significantly. Missing pairs are rejected. `means` is optional and orders the groups and the letters. If you already have the non-significance matrix, use `reduce_from_adjacency`; there, `True` means two groups are not significantly different and must share a letter.
+
+The result, a `CLDReductionResult`, has:
+
+- `letters`: the display of each group, for example `"AC"` (tokens are joined with spaces after `Z`, as in `"Z AA"`)
+- `assignments`: the letters of each group as a tuple, the safe machine-readable form
+- `stats`: the counts before and after the reduction and the solver status; `reduction_pct` is not rounded
+- `relationship_preserved`: always `True` for a returned result
+- `to_frame()`: a tidy `pandas.DataFrame`
+
+The public names are `reduce_letters`, `reduce_from_adjacency`, `CLDReductionResult`, `CLDReducerError`, `InvalidInputError`, and `SolverError`.
+
+When several displays have the same, smallest number of assignments, the package returns the canonical one defined in `docs/algorithm.md`, so R, Python, and JavaScript agree. `time_limit` is one time budget in seconds for all solves of a call, and `max_cliques` (10,000 by default; `None` removes it) bounds the number of maximal cliques.
+
+## Command line
+
+```sh
+cld-reduce examples/simple_abc_to_ac_pairs.csv \
+  --means examples/simple_abc_to_ac_means.csv \
+  --time-limit 30 \
+  --out reduced.csv
+```
+
+The paths above refer to files in a checkout or an extracted source archive. For your own data, pass your CSV paths. The pairs file has the columns `group1`, `group2`, and `significant`; the optional means file has `group` and `mean`. The output CSV has the reduced letters and the summary statistics. Other flags: `--group1`, `--group2`, `--significant`, `--max-cliques`, `--no-max-cliques`, and `--method`.
+
+## Examples
+
+The following scripts and CSV files are included in a repository checkout or the source archive, but not in the installed wheel. Run them from `python/` in a checkout, or from the root of an extracted source archive:
+
+```sh
+python examples/simple_abc_to_ac.py
+python examples/piepho2004_wheat.py
+```
+
+The CSV files in `examples/` are identical copies of the files in `conformance/data/` at the repository root.
+
+## Changes in 0.2.0
+
+The 0.2.0 release moved the package to `python/` and the solver to `highspy`, which can change the display for inputs with several minimal displays and can rename letters. See the root `NEWS.md` for the full list.
+
+## License
+
+MIT. See `LICENSE`.
+
+## Input and release notes
+
+CSV label columns preserve their exact text, including `001`, `NA`, `NaN`, and
+empty strings. A blank CSV label is an empty-string label; missing values in API
+objects still raise `InvalidInputError`. Means must remain finite numbers.
+The means table uses `group` and `mean` when both exist, or its first two columns.
+A list of pair rows preserves each numeric label before conversion to text.
+Uneven adjacency rows raise the package's square-matrix error.
+
+The source distribution contains example scripts and CSV files. The wheel
+contains the importable package and its license and data notice. Shared
+conformance fixtures remain in the repository, so source-distribution tests skip
+those cases when the fixtures are absent. CI tests both installed distributions
+outside the checkout. See `docs/releasing.md` in the repository for release steps.
+Example data reuse remains subject to the conditions in `NOTICE`.

cld_reducer-0.2.0/examples/piepho2004_wheat.py

@@ -0,0 +1,40 @@
+"""Run the Piepho (2004) CIMMYT wheat yield experiment example.
+
+Source: 20-treatment multi-environment wheat yield trial reported by Piepho
+(2004), reproduced in Table 7 of Ennis, Fayle, & Ennis (2012),
+"Assignment-Minimum Clique Coverings", ACM JEA 17, Art. 1.5
+(https://doi.org/10.1145/2133803.2275596). The maximal covering has 4 cliques
+and 56 letter assignments; the assignment-minimum reduction has 4 cliques and
+44 letter assignments, matching the result reported in the paper.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from cld_reducer import reduce_letters
+
+
+def main() -> None:
+    example_dir = Path(__file__).resolve().parent
+    pairs = pd.read_csv(example_dir / "piepho2004_wheat_pairs.csv")
+    result = reduce_letters(pairs)
+
+    print(result.to_frame().to_string(index=False))
+    print()
+    print(f"Groups:             {result.stats['num_groups']}")
+    print(f"Non-sig edges:      {result.stats['num_edges']}")
+    print(
+        f"Letters:            {result.stats['num_letters_before']} "
+        f"-> {result.stats['num_letters_after']}"
+    )
+    print(f"Assignments before: {result.stats['assignments_before']}")
+    print(f"Assignments after:  {result.stats['assignments_after']}")
+    print(f"Reduction:          {result.stats['reduction_pct']:.1f}%")
+    print(f"Preserved:          {result.relationship_preserved}")
+
+
+if __name__ == "__main__":
+    main()

cld_reducer-0.2.0/examples/piepho2004_wheat_pairs.csv

@@ -0,0 +1,191 @@
+group1,group2,significant
+1,2,false
+1,3,false
+1,4,false
+1,5,false
+1,6,false
+1,7,false
+1,8,false
+1,9,false
+1,10,false
+1,11,false
+1,12,false
+1,13,false
+1,14,false
+1,15,false
+1,16,false
+1,17,false
+1,18,false
+1,19,false
+1,20,false
+2,3,false
+2,4,false
+2,5,false
+2,6,false
+2,7,false
+2,8,false
+2,9,false
+2,10,false
+2,11,false
+2,12,false
+2,13,false
+2,14,false
+2,15,false
+2,16,false
+2,17,false
+2,18,false
+2,19,false
+2,20,true
+3,4,false
+3,5,false
+3,6,false
+3,7,false
+3,8,false
+3,9,false
+3,10,false
+3,11,false
+3,12,false
+3,13,false
+3,14,false
+3,15,false
+3,16,false
+3,17,false
+3,18,true
+3,19,false
+3,20,true
+4,5,false
+4,6,false
+4,7,false
+4,8,false
+4,9,false
+4,10,false
+4,11,false
+4,12,false
+4,13,false
+4,14,false
+4,15,false
+4,16,false
+4,17,false
+4,18,false
+4,19,false
+4,20,true
+5,6,false
+5,7,false
+5,8,false
+5,9,false
+5,10,false
+5,11,false
+5,12,true
+5,13,false
+5,14,false
+5,15,false
+5,16,false
+5,17,false
+5,18,false
+5,19,false
+5,20,true
+6,7,false
+6,8,false
+6,9,false
+6,10,false
+6,11,false
+6,12,false
+6,13,false
+6,14,false
+6,15,false
+6,16,false
+6,17,false
+6,18,false
+6,19,false
+6,20,true
+7,8,false
+7,9,false
+7,10,false
+7,11,false
+7,12,true
+7,13,false
+7,14,false
+7,15,false
+7,16,false
+7,17,false
+7,18,false
+7,19,false
+7,20,true
+8,9,false
+8,10,false
+8,11,false
+8,12,false
+8,13,false
+8,14,false
+8,15,false
+8,16,false
+8,17,false
+8,18,false
+8,19,false
+8,20,false
+9,10,false
+9,11,false
+9,12,false
+9,13,false
+9,14,false
+9,15,false
+9,16,false
+9,17,false
+9,18,false
+9,19,false
+9,20,true
+10,11,false
+10,12,true
+10,13,false
+10,14,false
+10,15,false
+10,16,false
+10,17,false
+10,18,false
+10,19,false
+10,20,true
+11,12,false
+11,13,false
+11,14,false
+11,15,false
+11,16,false
+11,17,false
+11,18,false
+11,19,false
+11,20,true
+12,13,false
+12,14,false
+12,15,false
+12,16,true
+12,17,false
+12,18,true
+12,19,false
+12,20,false
+13,14,false
+13,15,false
+13,16,false
+13,17,false
+13,18,false
+13,19,false
+13,20,true
+14,15,false
+14,16,false
+14,17,false
+14,18,false
+14,19,false
+14,20,false
+15,16,false
+15,17,false
+15,18,false
+15,19,false
+15,20,false
+16,17,false
+16,18,false
+16,19,false
+16,20,true
+17,18,false
+17,19,false
+17,20,false
+18,19,false
+18,20,true
+19,20,false

cld_reducer-0.2.0/examples/simple_abc_to_ac.py

@@ -0,0 +1,27 @@
+"""Run the simple CLD reduction example where ABC becomes AC."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+
+from cld_reducer import reduce_letters
+
+
+def main() -> None:
+    example_dir = Path(__file__).resolve().parent
+    pairs = pd.read_csv(example_dir / "simple_abc_to_ac_pairs.csv")
+    means = pd.read_csv(example_dir / "simple_abc_to_ac_means.csv")
+    result = reduce_letters(pairs, means)
+
+    print(result.to_frame().to_string(index=False))
+    print()
+    print(f"Assignments before: {result.stats['assignments_before']}")
+    print(f"Assignments after:  {result.stats['assignments_after']}")
+    print(f"Reduction:          {result.stats['reduction_pct']:.1f}%")
+    print(f"Preserved:          {result.relationship_preserved}")
+
+
+if __name__ == "__main__":
+    main()

cld_reducer-0.2.0/examples/simple_abc_to_ac_means.csv

@@ -0,0 +1,6 @@
+group,mean
+1,3.73
+2,3.57
+3,3.46
+4,3.33
+5,3.30

cld_reducer-0.2.0/examples/simple_abc_to_ac_pairs.csv

@@ -0,0 +1,11 @@
+group1,group2,significant
+1,2,false
+1,3,false
+1,4,true
+1,5,true
+2,3,false
+2,4,false
+2,5,true
+3,4,false
+3,5,false
+4,5,false