lzsuite 0.1.0__tar.gz

lzsuite-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv*/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store

lzsuite-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0 (2026-11-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* simplify single-sequence results and enable interactive parallelism
+
+### Features
+
+* create initial array analysis and discretization library ([0c1ae2f](https://github.com/El3ssar/lzsuite/commit/0c1ae2f63ab8f201cd529dc24ded8e092b6cf89c))
+* simplify single-sequence results and enable interactive parallelism ([02b189f](https://github.com/El3ssar/lzsuite/commit/02b189f290b25a6c331c5ff11b2b222a383e9c97))
+
+
+### Bug Fixes
+
+* **api:** expose only user functions and privatize implementation modules ([3baa1fc](https://github.com/El3ssar/lzsuite/commit/3baa1fcf9c48aa9ab637a2de0b8e84dc681d5745))
+* **release:** bootstrap the first release without a synthetic previous version ([89beb7a](https://github.com/El3ssar/lzsuite/commit/89beb7aa8fd6b2ff8730ecdc13ad3952c96ea769))
+
+## Changelog
+
+Changes will be recorded here by release-please. Initial local development: 0.1.0.

lzsuite-0.1.0/CITATION.cff

@@ -0,0 +1,12 @@
+cff-version: 1.2.0
+message: "If you use lzsuite, please cite this software and the underlying lzcomplexity engine as appropriate."
+type: software
+title: "lzsuite: Array-oriented Lempel–Ziv analysis and discretization"
+authors:
+  - family-names: "Estévez Moya"
+    given-names: "Daniel"
+    alias: "El3ssar"
+repository-code: "https://github.com/El3ssar/lzsuite"
+url: "https://github.com/El3ssar/lzsuite"
+license: MIT
+abstract: "A Python wrapper around lzcomplexity for multidimensional arrays, signal discretization, parallel sequence analysis, and information distances."

lzsuite-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to lzsuite
+
+## Set up once
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then:
+
+```sh
+git clone https://github.com/El3ssar/lzsuite.git
+cd lzsuite
+uv sync --locked
+uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
+uv run ipython
+```
+
+Or run `make setup`. Everything lives in the repository's `.venv` and uv cache;
+no global Python packages or manual virtual-environment activation are needed.
+The editable install reflects source edits immediately. Restart an interactive
+session after changing already-imported modules.
+
+`.python-version` selects Python 3.12 for routine development. `requires-python`
+in `pyproject.toml` sets the supported minimum to 3.10. `uv.lock` records the exact
+development dependency versions across supported interpreters.
+
+## Everyday workflow
+
+```sh
+git switch -c fix/describe-the-change
+# Edit source, tests, documentation, or examples.
+make check
+make build
+git add <changed-files>
+git commit -m "fix: describe the resulting behavior"
+git push -u origin HEAD
+```
+
+The individual checks are:
+
+```sh
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+uv run --locked pytest --cov=lzsuite
+uv build
+uv run --locked twine check dist/*
+```
+
+Use `uv run ruff format .` to format edits, and `uv run ruff check . --fix` for
+automatic lint fixes. Local hooks run lint/format checks and validate commit
+subjects. CI also checks the PR title; use a Conventional Commit title so squash
+merging preserves the release intent.
+
+## Code map
+
+```text
+src/lzsuite/
+  __init__.py          Public function exports and installed package version
+  _analysis.py         Complexity, h, factorization, E, full results
+  _distance.py         All-pairs and corresponding-pair NID
+  _discretization.py   Built-ins, registry, callable validation
+  _arrays.py           Axis handling and sequence preparation
+  _encoding.py         Byte encodings and shared distance codebooks
+  _execution.py        Inline execution and joblib/loky process workers
+tests/                 Backend comparisons, contracts, execution, namespace
+examples/overview.py   Commented executable walkthrough
+docs/                  API and maintenance guides
+.github/workflows/     CI and release automation
+```
+
+Keep implementation modules private. Add a top-level export only when it is a
+function users should call, and update `tests/test_public_api.py` deliberately.
+Avoid adding helper imports to the public namespace.
+
+## Tests that matter
+
+Tests compare against the real installed lzcomplexity engine, including both E
+estimators. Cover scientific encoding choices, arbitrary axes, shape preservation,
+1D native return types, registry behavior, warning/error cases, and agreement
+between serial and parallel execution.
+
+When changing execution, check both the result and the process/thread budget.
+Workers use one Rayon thread; the caller's configuration must remain unchanged.
+When changing a discretizer, include meaningful edge cases such as ties, constant
+signals, and shortened output. Custom methods need no output-length declaration.
+
+CI runs Python 3.10–3.14 on Linux and Python 3.12 on macOS and Windows. To test
+another interpreter locally without replacing the default environment:
+
+```sh
+UV_PROJECT_ENVIRONMENT=.venv-py310 uv run --locked --python 3.10 pytest
+UV_PROJECT_ENVIRONMENT=.venv-py314 uv run --locked --python 3.14 pytest
+```
+
+CI also checks an installed wheel and the minimum NumPy/joblib dependencies.
+For interactive smoke testing, `uv run ipython` can call `lzs.h(data)` directly,
+including its default parallel path.
+
+## Dependencies and versioning
+
+Runtime requirements live in `pyproject.toml`; reproducible development versions
+live in `uv.lock`. Commit both files when a requirement changes. A lockfile pin
+is not the same as a published package requirement.
+
+Use Conventional Commits:
+
+```text
+feat(discretization): add fixed-edge binning
+fix(distance): preserve category meanings across inputs
+perf: reuse calculation work
+refactor: simplify internal array handling
+docs: explain normalization
+feat!: change public result shapes
+```
+
+`feat` proposes a minor bump; `fix` and `perf` propose patch bumps. A `!` or
+`BREAKING CHANGE:` footer declares a breaking change. Under the current default
+policy, breaking changes bump the major version even while the version is 0.x.
+Merging a normal feature PR does not publish a release: release-please prepares
+a separate release PR for review.
+
+See [docs/maintenance.md](docs/maintenance.md) for the exact dependency-update
+commands, release procedure, and remaining PyPI/Zenodo setup. Do not hand-edit
+versions in several files: release-please updates `pyproject.toml`, `uv.lock`,
+the release manifest, and the changelog together.
+
+## Reporting problems
+
+Open an [issue](https://github.com/El3ssar/lzsuite/issues) with a small input,
+its dtype and shape, the call and parameters, the expected/actual behavior,
+Python/platform information, and the lzsuite/lzcomplexity/NumPy versions. Include
+`n_jobs` when reporting parallel-execution issues. Keep scientific data private
+unless you have permission to share it.

lzsuite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lzsuite contributors
+
+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.

lzsuite-0.1.0/Makefile

@@ -0,0 +1,41 @@
+.PHONY: help setup check test lint format build deps-backend deps-update
+
+help:
+	@echo "setup         Install locked dev environment and local hooks"
+	@echo "check         Run lint, format checks, and tests"
+	@echo "test          Run tests with coverage"
+	@echo "lint          Check lint and formatting"
+	@echo "format        Apply lint fixes and formatting"
+	@echo "build         Build and validate wheel and source archive"
+	@echo "deps-backend  Update lzcomplexity within its declared range"
+	@echo "deps-update   Update all dependency locks within declared ranges"
+
+setup:
+	uv sync --locked
+	uv run --no-sync pre-commit install --hook-type pre-commit --hook-type commit-msg
+
+check: lint test
+
+lint:
+	uv run --locked ruff check .
+	uv run --locked ruff format --check .
+
+test:
+	uv run --locked pytest --cov=lzsuite
+
+format:
+	uv run --locked ruff check . --fix
+	uv run --locked ruff format .
+
+build:
+	uv build
+	uv run --locked twine check dist/*
+
+deps-backend:
+	uv lock --upgrade-package lzcomplexity
+	uv sync --locked
+
+# Review the lockfile diff and run make check/build before committing updates.
+deps-update:
+	uv lock --upgrade
+	uv sync --locked

lzsuite-0.1.0/PKG-INFO

@@ -0,0 +1,281 @@
+Metadata-Version: 2.5
+Name: lzsuite
+Version: 0.1.0
+Summary: Array-oriented Lempel–Ziv analysis and signal discretization.
+Project-URL: Homepage, https://github.com/El3ssar/lzsuite
+Project-URL: Repository, https://github.com/El3ssar/lzsuite
+Project-URL: Documentation, https://github.com/El3ssar/lzsuite#readme
+Project-URL: Issues, https://github.com/El3ssar/lzsuite/issues
+Project-URL: Changelog, https://github.com/El3ssar/lzsuite/blob/main/CHANGELOG.md
+Author: Daniel Estévez Moya
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: joblib<2,>=1.5
+Requires-Dist: lzcomplexity<4,>=3.0.0
+Requires-Dist: numpy>=1.24
+Description-Content-Type: text/markdown
+
+# lzsuite
+
+[![CI](https://github.com/El3ssar/lzsuite/actions/workflows/ci.yml/badge.svg)](https://github.com/El3ssar/lzsuite/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://github.com/El3ssar/lzsuite/blob/main/pyproject.toml)
+[![MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Lempel–Ziv analysis for multidimensional NumPy arrays. Choose the axis containing
+observations, optionally discretize continuous signals, and calculate complexity,
+entropy density, effective measure complexity, or information distances across
+all remaining positions.
+
+[lzcomplexity](https://github.com/pleros-ai/lzcomplexity) supplies the numerical
+engine. lzsuite adds array handling, discretization, shared symbol encodings,
+and parallel calculation across sequences.
+
+**Early development:** the API can evolve. The repository is available on GitHub;
+PyPI publication and Zenodo registration are planned separately.
+
+## Install and try it
+
+From the repository, using [uv](https://docs.astral.sh/uv/):
+
+```sh
+git clone https://github.com/El3ssar/lzsuite.git
+cd lzsuite
+uv sync --locked
+uv run ipython
+```
+
+This creates a local `.venv`, installs lzsuite in editable mode, and installs the
+locked development tools. No activation or global Python packages are needed.
+For a regular environment without uv, use `python -m pip install .` after cloning.
+Python 3.10+ is required; development defaults to Python 3.12.
+
+## Quick start
+
+These are separate snippets you can run in the same IPython session.
+
+```python
+import numpy as np
+import lzsuite as lzs
+
+rng = np.random.default_rng(42)
+signal = rng.normal(size=1000)
+data = rng.normal(size=(1000, 4, 3))  # observations × channels × trials
+```
+
+One sequence returns an ordinary Python value. No scalar extraction is needed:
+
+```python
+entropy = lzs.h(signal)  # float
+count = lzs.complexity(signal)  # int
+count, boundaries = lzs.factorization(signal)
+score, increments = lzs.emc(signal)  # float and list
+result = lzs.lz76(signal)  # dict
+```
+
+Arrays retain the dimensions outside the sequence axis, which defaults to 0:
+
+```python
+entropy = lzs.h(data)  # shape (4, 3)
+counts = lzs.complexity(data)  # shape (4, 3)
+scores, profiles = lzs.emc(data, max_block_size=8)
+results = lzs.lz76(data, max_block_size=8)
+results[0, 0]["emc"]["value"]  # first channel, first trial
+```
+
+Other axes and noncontiguous views work too:
+
+```python
+observations_last = np.moveaxis(data, 0, -1)  # shape (4, 3, 1000)
+np.allclose(entropy, lzs.h(observations_last, axis=-1))  # True
+```
+
+A singleton batch dimension is preserved: input `(1000, 1)` returns shape `(1,)`.
+Only a truly 1D input gets the direct Python result. See the full
+[API reference](docs/api.md) for return types.
+
+## Discretization
+
+Float arrays use mean binarization by default, independently for each sequence.
+Integers, booleans, and string-array elements are already symbols. An explicitly
+selected discretizer overrides the default for numeric inputs; strings cannot
+be passed to a discretizer.
+
+```python
+lzs.available_discretizers()
+# ('bins', 'mean', 'median', 'permutation', 'quantile')
+
+labels = lzs.discretize(signal, method="median")  # use a method directly
+entropy = lzs.h(data, discretization="median")  # or inside a calculation
+entropy = lzs.h(data, discretization="bins", discretization_kwargs={"n_bins": 4})
+```
+
+| Method | Rule | Parameters |
+|---|---|---|
+| `mean` | Above the sequence mean → 1; equality/below → 0 | — |
+| `median` | Above the sequence median → 1; equality/below → 0 | — |
+| `bins` | Equally wide bins spanning the sequence's range | `n_bins=2` |
+| `quantile` | Bins using empirical quantile edges | `n_bins=2` |
+| `permutation` | Labels for the ordering within delayed windows | `order=3`, `delay=1` |
+
+Values on internal bin edges go right. Repeated quantile edges collapse, and
+constant signals yield zero labels. Bin edges are fitted separately per sequence;
+pass a custom method using fixed edges if comparisons require shared thresholds.
+Permutation ties are ordered by position, earlier first. Permutation output has
+`len(signal) - (order - 1) * delay` entries; it is a discretization, not a
+permutation-entropy calculation.
+
+### Your own methods
+
+A method receives a numeric 1D array and returns a nonempty 1D array of integer
+labels. Its output length can change. The input is copied before calling it, so
+in-place changes do not modify your original data.
+
+```python
+def threshold(values, *, level=0.0):
+    return (values > level).astype(np.uint8)
+
+
+lzs.h(data, discretization=threshold)  # directly supplied callable
+```
+
+Register the same function for reuse by name:
+
+```python
+lzs.register_discretizer("threshold", threshold, replace=True)
+lzs.h(data, discretization="threshold", discretization_kwargs={"level": 0.5})
+```
+
+Decorator registration is also supported:
+
+```python
+@lzs.register_discretizer("every_other", replace=True)
+def every_other(values):
+    return (values[::2] > 0).astype(np.uint8)
+
+
+lzs.h(data, discretization="every_other")
+```
+
+Registration is local to the Python session. Existing names require
+`replace=True` to overwrite. Discretization runs in the calling process, so
+functions defined interactively work with parallel calculations too.
+
+## Information distances
+
+One input calculates every pair of sequences:
+
+```python
+matrix = lzs.distance(data)  # shape (12, 12)
+```
+
+Rows and columns follow C-order flattening of `(channel, trial)`. Here,
+`(channel, trial)` corresponds to row `channel * 3 + trial`. The matrix is
+symmetric and retains actual self-distances, which may be nonzero.
+
+Two inputs compare corresponding sequences:
+
+```python
+other = rng.normal(size=(800, 4, 3))
+paired = lzs.distance(data, other)  # shape (4, 3)
+single = lzs.nid(signal, other[:, 0, 0])  # float; nid is an alias for distance
+```
+
+Shapes outside the sequence axis must match exactly; sequence lengths may differ.
+There is no broadcasting. A shared codebook keeps category meanings consistent
+across the inputs. The two-input mode does not compute all cross-pairs.
+A single 1D input to `distance` still gives a `(1, 1)` all-pairs matrix.
+
+Both modes accept `axis`, `discretization`, `discretization_kwargs`, and `n_jobs`.
+For float inputs, the default mean threshold is fitted independently to each
+sequence in each input.
+
+## Parallel execution and Rayon
+
+**Default: up to four worker processes**, capped by available CPUs and the number
+of calculations. This works in scripts, IPython, and notebooks using joblib's
+loky process runner. Workers are reused across calls to reduce repeated startup.
+
+```python
+lzs.h(data)  # up to 4 processes
+lzs.h(data, n_jobs=1)  # inline calculation; no worker processes
+lzs.h(data, n_jobs=2)  # up to 2 processes
+lzs.distance(data, n_jobs=-1)  # all available CPUs, capped by pair count
+```
+
+Each worker uses **one Rayon thread**. Thus four worker processes share the
+calculation workload without each starting a full native thread pool. Worker
+configuration is local to those processes; lzsuite does not change the calling
+process's `RAYON_NUM_THREADS` or initialized Rayon pool. Other common native
+thread pools are also limited to one thread per worker.
+
+The inline path (`n_jobs=1`, a single calculation, or one available CPU) preserves
+the calling process's existing native configuration, so lzcomplexity can still
+use Rayon internally there. Discretization, validation, and encoding happen in
+the calling process before native work is distributed.
+
+Parallelism can use more memory and is not necessarily faster for small inputs.
+Use `n_jobs=1` when process startup outweighs the calculation. All-pairs matrices
+require quadratic result storage.
+
+## Scientific conventions and validation
+
+- The logarithm base defaults to each discretized sequence's distinct-symbol
+  count, with a minimum of 2. Use `log_base=2` for explicit bit units. Different
+  observed alphabet sizes imply different normalization bases.
+- E defaults to Chao–Shen. `method="shuffle"` selects the alternative estimator
+  in `emc` and `lz76`; this option is separate from `discretization`.
+- Numeric symbols are encoded as individual bytes. Each string-array element is
+  one category, including multi-character strings. To analyze text characters,
+  use `np.array(list("banana"))`.
+- More than 256 distinct symbols emits `RuntimeWarning` and continues with
+  category codes reduced modulo 256. Some categories then merge, so results do
+  not faithfully describe the original alphabet. Analysis normalization still
+  uses the original symbol count; distances check the shared vocabulary.
+- Empty sequences, NaN, infinity, complex values, and object arrays are rejected.
+  Empty collections with a nonempty sequence axis return empty arrays.
+- Factor boundaries retain the backend's final-tail convention and can extend
+  beyond the sequence end. NID does not force self-distance to zero.
+
+Save the discretization settings, sequence length, log base, E method/range,
+package versions, and input data or fingerprint with scientific results.
+
+## Development and maintenance
+
+```sh
+make setup    # editable install plus local lint/commit hooks
+make check    # lint, formatting, tests
+make build    # wheel, source archive, package metadata checks
+```
+
+The commands are also listed individually in [CONTRIBUTING.md](CONTRIBUTING.md).
+The development environment is locked in `uv.lock`; runtime compatibility ranges
+are declared in `pyproject.toml`. The backend dependency is currently
+`lzcomplexity>=3.0.0,<4`, preventing an unreviewed major-version upgrade. See the
+[maintenance and release guide](docs/maintenance.md) for dependency updates,
+versioning, GitHub releases, and the future PyPI/Zenodo steps.
+
+Conventional Commits drive release-please version/changelog PRs. Merging a release
+PR creates the `vX.Y.Z` tag and GitHub release. CI checks Python 3.10–3.14 on Linux,
+plus macOS and Windows, and builds package distributions. **There is no PyPI
+upload or Zenodo registration in the current workflows.**
+
+The public API contains only callable user functions; implementation modules are
+private. `lzs.__version__` gives the installed version. A complete executable
+walkthrough is in [examples/overview.py](examples/overview.py).
+
+## License and attribution
+
+MIT licensed; see [LICENSE](LICENSE). The LZ76 engine and estimator implementation
+are provided by [lzcomplexity](https://github.com/pleros-ai/lzcomplexity), with its
+own authorship and scientific references. Software citation metadata for this
+wrapper is in [CITATION.cff](CITATION.cff).