[codex] Modernize Python compatibility, dependencies, tests, and docs

[tuhulab]

Summary

This PR modernizes QUICHE for current Python tooling while preserving the existing public API surface (quiche.pp, quiche.tl, quiche.pl) and stabilizing install/test workflows.

It addresses compatibility and maintenance pain points caused by old grammar-era packaging metadata, outdated pins, and eager imports of heavy optional dependencies.

Problem and user impact

Before this change:

• Project metadata used legacy fields and did not declare runtime dependencies in pyproject.toml.
• Python support targeted only 3.7-3.9.
• Import/runtime paths could fail early when optional heavy dependencies were not installed.
• No automated test suite or CI matrix existed to protect compatibility changes.

This made installation brittle, especially for users on modern Python versions, and increased regression risk.

Root causes

• Packaging configuration was incomplete for modern PEP 621 workflows.
• Optional stacks (scanpy/squidpy/pertpy/muon/sketchKH/R-driven workflows) were imported eagerly.
• A few runtime bugs (parameter mismatch and row-alignment issues) were hidden due limited test coverage.

What this PR changes

1) Packaging and dependency modernization

• Modernized pyproject.toml metadata to PEP 621 format.
• Declared explicit runtime dependencies.
• Set supported Python range to >=3.10,<3.13.
• Added extras:
  • plot
  • full
  • dev
• Updated venv_quiche.yml to align with Python 3.10-3.12 and modern stack versions.
• Kept R dependencies in conda for edgeR/R workflows.

2) Compatibility and correctness fixes (API-preserving)

• Replaced bare except: handlers with explicit handling.
• Removed outdated boolean-style checks.
• Added optional dependency guards with actionable ImportErrors.
• Fixed concrete runtime bugs:
  • compute_spatial_niches(khop=...) now passes k correctly.
  • compute_spatial_niches now preserves row alignment via obs_names.
  • Fixed chained assignment in annotation update path.
  • Fixed undefined metric variable in plotting defaults.
  • Fixed list-color handling in generate_colors.
  • Fixed incorrect call-site argument in plotting metadata helper.

3) Test suite + CI

• Added tests/ with deterministic synthetic fixtures and coverage for:
  • imports
  • preprocessing
  • graph helpers
  • metrics helpers
  • QUICHE smoke paths
• Added GitHub Actions matrix for Python 3.10/3.11/3.12.

4) Documentation

• Updated README installation guidance for pip extras and conda/R workflows.
• Added quick smoke-test command.
• Added known limitations for heavy optional stacks.
• Added migration report and changelog entry.

Validation performed

Local validation on Python 3.11:

• pytest -q -> 19 passed
• pytest --cov=quiche --cov-report=term-missing -> 19 passed

(One pandas FutureWarning remains in an existing statistical helper; behavior is unaffected.)

Backward compatibility statement

• Public module/function/class import paths are preserved.
• Heavy optional workflows now fail fast with clear install guidance instead of breaking base imports.
• pip install . stays lightweight; conda remains the recommended route for R-backed analysis.

Commit structure

• packaging/deps: modernize metadata and env
• code-compat: guard optional deps and fix runtime bugs
• tests-ci: add synthetic tests and py3.10-3.12 matrix
• docs: document migration, install paths, and limits

[AtlasMaroc]

@tuhulab i tried using your suggestion for installing the full environment using pip install .e [full], but i got an error regarding version availability such as muon !

[jranek]

Wow, thank you @tuhulab for all of these updates, this is super helpful!! I will work on reviewing the changes.

As a note, pip install .[full] breaks for me due to a sketchKH dependency issue. We should only be using sketchKH >= 0.1.2, which requires python>=3.6, <3.10 which is currently incompatible with these updates. I will work on updating the python dependencies in the sketchKH package to enable the python modernization here.

Jolene

[jranek]

Should now be resolved with sketchKH==0.1.3

[Nerdobyte]

I ran into an issue with the demo workflow on this PR branch that did not occur with the original QUICHE setup when I first ran the demo notebook after the initial release.

Using the same demo dataset (spain_preprocessed), QUICHE.subsample() consistently fails with:

ValueError: Not enough unique indices to sample.

This occurs even with very small sketch_size values (e.g. 20), and despite all Patient_ID groups having >1000 niches after compute_spatial_niches().

This behavior appears in the PR15 environment (Python ≥3.10, updated dependency stack, using sketchKH==0.1.3). I attempted to recreate the original environment (venv_quiche.yml on main, Python 3.9, sketchKH==0.1.2) for comparison, but some of the older pinned dependencies are no longer compatible with the current HPC environment.

Based on prior use of the original release environment, this workflow previously ran successfully on the same demo data without this error.

This suggests a potential regression or compatibility issue introduced by the updated environment, rather than a data-size or parameter issue.

Happy to provide a minimal reproducible example if helpful. Any suggestions would be much appreciated.