Skip to content

Rename matrix convert to recast, and add the adata convert format framework #21

Description

@Claptar

Part of #20.

Why

adata convert currently means "change a matrix's dtype, layout or density" (commands/convert.py, core/convert.py). Format conversion is the more natural meaning of the name, and users will look for it there.

Plan

  1. Add adata recast, identical to today's convert. Move commands/convert.py → commands/recast.py and core/convert.py → core/recast.py; move tests (test_convert.py) and the COMMANDS.md section with them.
  2. Transition period (0.7.x until 1.0, the same release that drops the h5ad alias):
    • adata convert called with the old matrix flags (--dtype, --layout, --dense, --sparse, --inplace) on AnnData → AnnData of the same backend forwards to recast and prints a deprecation warning.
    • Otherwise it runs format conversion.
    • Ambiguous case — backend change (h5ad → zarr) and matrix flags: convert the format, then recast, and warn.
  3. Framework: the reader/writer registry, sniffing, the ConversionPlan dataclass and the common options described in the epic. Ship it together with the h5ad ↔ zarr converter (Convert: h5ad ↔ zarr #22) so the framework has one real user from day one.
  4. Update CHANGELOG.md, docs/COMMANDS.md, README, and keep test_docs_are_accurate.py green.
  5. Small fix on the way: _require_zarr still suggests uv sync --extra zarr, but that extra no longer exists.

Open questions

  • Is recast the right name? Alternatives: retype, reformat, matrix.
  • Should format-specific options live on convert directly, or be namespaced (--10x-genome, --loom-obs-names)? Flat options are friendlier; namespacing avoids clashes as formats grow.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions