This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
FoaPy is a Python library for Formal Order Analysis (FOA) — analysis of symbolic sequences by mapping them to their structural order and extracting intervals between repeated symbols. Core dependency: numpy >= 1.20.
Run all tests:
tox -e defaultRun a single test file or test:
tox -e default -- tests/test_characteristics/test_volume.py -v
tox -e default -- tests/test_characteristics/test_volume.py::TestVolume::test_dataset_1 -vRun tests matching a keyword:
tox -e default -- -k order -qLint (black, isort, flake8):
pipx run pre-commit run --all-files --show-diff-on-failureBuild distribution:
tox -e clean,buildBuild and serve docs:
tox -e docs
tox -e docsserveThe FOA pipeline works in stages:
order(X)— maps a sequence to integer indices (positions in first-appearance alphabet) and optionally returns thealphabetintervals(X, binding, mode)— extracts intervals (distances between consecutive occurrences of the same symbol) from an ordered sequence
intervals() is built from two lower-level primitives:
intervals_chain— computes raw interval chains before boundary handlingintervals_tuple— applies boundary strategy to produce the final result
These two enums control how intervals() handles sequence boundaries:
binding:start(left-to-right) orend(right-to-left)mode:lossy(drop boundary intervals),normal(one boundary),cycle(cyclic wrap),redundant(both boundaries)
Each characteristic is a standalone module (e.g., volume, arithmetic_mean, depth, regularity) that takes an intervals array and returns a scalar. They share no base class — each is a thin function over numpy operations.
foapy.ma mirrors the core API for sequences with missing data (numpy masked arrays): ma.order(), ma.alphabet(), ma.intervals(). The characteristics/ma/ subdirectory provides masked-array variants of each characteristic.
Not1DArrayException— raised when input is not 1-DInconsistentOrderException— raised when order/alphabet pair is incompatible
Tests are in tests/. Characteristics tests share a base class CharacteristicsTest (in tests/test_characteristics/characterisitcs_test.py) providing AssertCase() and AssertBatch() helpers. AssertBatch verifies results across all binding × mode combinations using a nested dict of expected values.
Numerical comparisons use epsilon tolerance — use AssertCase/AssertBatch rather than plain assert for floating-point characteristics.
- Python 3.8+ + numpy >= 1.20 (sole runtime dependency per constitution) (002-decompose-intervals-pipeline)
- Python 3.8+ + numpy >= 1.20 (sole runtime dependency) (002-decompose-intervals-pipeline)
- Python 3.8+ + numpy >= 1.20 (sole runtime dependency; no additions) (004-partials-package)
- 002-decompose-intervals-pipeline: Added Python 3.8+ + numpy >= 1.20 (sole runtime dependency per constitution)