Skip to content

feat: re-implement n-stage LocalCov on the current n-dimensional API (supersedes PR #27) #130

Description

@t-uda

Context

PR #27 (Sep 2025, bot-authored) implements an n-stage LocalCov algorithm but is now unmergeable: 204 commits behind main, conflicts in every file, CI results predate the Python 3.9 drop, and the code assumes the old 2D-only API. The semantic payload is small (~100 lines + tests), so the decision from the 2026-07 triage is to close #27 and re-implement on the current codebase. See the closing comment on #27 for the full assessment.

What the algorithm does (from PR #27)

  1. LocalCov.__call__ gains an optional precomputed distance matrix d: numpy.ndarray | None = None (defaults to squareform(pdist(X)) as today).
  2. New module-level nstage_local_cov(X, *, k, n_stages):
    • Stage 1 runs the standard LocalCov(k)(X) with Euclidean distances.
    • Each subsequent stage computes the pairwise tangency distance matrix of the current ellipse cloud (pdist_tangencysquareform) and re-runs LocalCov with those distances for neighbour selection, iteratively amplifying anisotropic structure.
  3. EllipseCloud.from_nstage_local_cov(X, *, k=5, n_stages=2) classmethod and a "nstage_local_cov" method string in the from_point_cloud dispatch.

Requirements for the re-implementation

  • Target the current n-dimensional ellcloud API (main has been generalised since the PR was written; do not assume (N, 2)).
  • Update the corresponding .pyi stubs; stubtest (with stubtest-allowlist.txt) must pass.
  • Tests: smoke test, n_stages < 1ValueError, and an n_stages=1 ≡ local_cov equivalence test (port the intent of tests/test_nstage_local_cov.py from PR Feat: Implement n-stage LocalCov algorithm #27).
  • Full CI checklist from AGENTS.md (black / flake8 / mypy / stubtest / pytest).
  • Do not port the noise from PR Feat: Implement n-stage LocalCov algorithm #27: the pyproject.toml version rollback, the broken absolute README links, and the unrelated build_tangency_cpp.py reformat.

Notes for implementing agents

  • Mandatory: read contrib/agent-skill/SKILL.md (and references/) before writing any experiment or test code that exercises the tangency solver — this is a specialised TDA/PH library and naive assumptions routinely fail.
  • Follow the release workflow in CONTRIBUTING.md: base the PR on the current release branch, not main.
  • Depends on the Poetry→uv migration (chore: migrate dependency management from Poetry to uv #121) landing first, since the CI/dev workflow changes underneath.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions