pyadata-cli 0.7.0__tar.gz → 0.8.0__tar.gz

{pyadata_cli-0.7.0 → pyadata_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyadata-cli
-Version: 0.7.0
+Version: 0.8.0
 Summary: Streaming CLI for exploring and editing large AnnData .h5ad and .zarr stores
 Keywords: anndata,h5ad,zarr,bioinformatics,single-cell,cli
 Author: Aljes Binkevich
@@ -48,7 +48,7 @@ A command-line tool for exploring huge AnnData stores (`.h5ad` and `.zarr`) with
 - Auto-detects `.h5ad` files vs `.zarr` directories
 - Chunked processing for dense and sparse matrices (CSR/CSC)
 - Reads every AnnData on-disk layout, from 0.7.x through the current spec, and always writes the current one
-- Converts between HDF5 and Zarr (v2 and v3) in either direction with `adata convert`, and to and from 10x Genomics HDF5 matrices
+- Converts between HDF5 and Zarr (v2 and v3) in either direction with `adata convert`, and to and from 10x Genomics HDF5 matrices and 10x / STARsolo MTX folders
 - Rich terminal output with progress indicators, kept on stderr so results pipe cleanly
 
 **Documentation: [cellgeni.github.io/adata-cli](https://cellgeni.github.io/adata-cli/)**
@@ -96,7 +96,7 @@ Run help at any level (e.g. `adata --help`, `adata export --help`).
 - `subset` – stream and write a filtered copy, selected by obs/var name lists (`--obs`/`--var`) or by expression (`--obs-query`/`--var-query`).
 - `split` – write one store per distinct value of an annotation column, with a CSV manifest.
 - `concat` – concatenate stores along the obs axis, with `--join inner|outer` and merge strategies for var and uns.
-- `convert` – change a store's format: h5ad ↔ Zarr v2/v3, and 10x Genomics HDF5 (Cell Ranger's `*_feature_bc_matrix.h5`) in and out, streaming, with the output written beside its destination and moved into place only once complete.
+- `convert` – change a store's format: h5ad ↔ Zarr v2/v3, 10x Genomics HDF5 (Cell Ranger's `*_feature_bc_matrix.h5`) and 10x / STARsolo MTX folders in and out, streaming, with the output written beside its destination and moved into place only once complete.
 - `recast` – change a matrix's dtype, layout (CSR/CSC/dense) or density, streaming; refuses a lossy cast or a large size increase unless forced. Called `convert` until 0.7.0.
 - `export` – extract data from a store; subcommands: `dataframe` (any dataframe group to CSV), `array` (dense to `.npy`), `sparse` (CSR/CSC to `.mtx`), `dict` (JSON), `image` (PNG). Results go to stdout when no `--output` is given.
 - `import` – write new data into a store at any path; subcommands: `dataframe` (CSV), `array` (`.npy`), `sparse` (`.mtx`), `dict` (JSON), `image` (PNG/JPEG/TIFF).
@@ -140,6 +140,7 @@ adata convert data.h5ad -o data.zarr
 adata convert data.zarr -o data.h5ad --compression gzip
 adata convert filtered_feature_bc_matrix.h5 -o counts.h5ad --feature-type "Gene Expression"
 adata convert counts.h5ad -o for_cellbender.h5 --layer counts
+adata convert Solo.out/Velocyto/raw -o velocyto.h5ad
 ```
 
 ## Documentation

{pyadata_cli-0.7.0 → pyadata_cli-0.8.0}/README.md

@@ -8,7 +8,7 @@ A command-line tool for exploring huge AnnData stores (`.h5ad` and `.zarr`) with
 - Auto-detects `.h5ad` files vs `.zarr` directories
 - Chunked processing for dense and sparse matrices (CSR/CSC)
 - Reads every AnnData on-disk layout, from 0.7.x through the current spec, and always writes the current one
-- Converts between HDF5 and Zarr (v2 and v3) in either direction with `adata convert`, and to and from 10x Genomics HDF5 matrices
+- Converts between HDF5 and Zarr (v2 and v3) in either direction with `adata convert`, and to and from 10x Genomics HDF5 matrices and 10x / STARsolo MTX folders
 - Rich terminal output with progress indicators, kept on stderr so results pipe cleanly
 
 **Documentation: [cellgeni.github.io/adata-cli](https://cellgeni.github.io/adata-cli/)**
@@ -56,7 +56,7 @@ Run help at any level (e.g. `adata --help`, `adata export --help`).
 - `subset` – stream and write a filtered copy, selected by obs/var name lists (`--obs`/`--var`) or by expression (`--obs-query`/`--var-query`).
 - `split` – write one store per distinct value of an annotation column, with a CSV manifest.
 - `concat` – concatenate stores along the obs axis, with `--join inner|outer` and merge strategies for var and uns.
-- `convert` – change a store's format: h5ad ↔ Zarr v2/v3, and 10x Genomics HDF5 (Cell Ranger's `*_feature_bc_matrix.h5`) in and out, streaming, with the output written beside its destination and moved into place only once complete.
+- `convert` – change a store's format: h5ad ↔ Zarr v2/v3, 10x Genomics HDF5 (Cell Ranger's `*_feature_bc_matrix.h5`) and 10x / STARsolo MTX folders in and out, streaming, with the output written beside its destination and moved into place only once complete.
 - `recast` – change a matrix's dtype, layout (CSR/CSC/dense) or density, streaming; refuses a lossy cast or a large size increase unless forced. Called `convert` until 0.7.0.
 - `export` – extract data from a store; subcommands: `dataframe` (any dataframe group to CSV), `array` (dense to `.npy`), `sparse` (CSR/CSC to `.mtx`), `dict` (JSON), `image` (PNG). Results go to stdout when no `--output` is given.
 - `import` – write new data into a store at any path; subcommands: `dataframe` (CSV), `array` (`.npy`), `sparse` (`.mtx`), `dict` (JSON), `image` (PNG/JPEG/TIFF).
@@ -100,6 +100,7 @@ adata convert data.h5ad -o data.zarr
 adata convert data.zarr -o data.h5ad --compression gzip
 adata convert filtered_feature_bc_matrix.h5 -o counts.h5ad --feature-type "Gene Expression"
 adata convert counts.h5ad -o for_cellbender.h5 --layer counts
+adata convert Solo.out/Velocyto/raw -o velocyto.h5ad
 ```
 
 ## Documentation

{pyadata_cli-0.7.0 → pyadata_cli-0.8.0}/pyproject.toml

@@ -3,7 +3,7 @@
 # so the distribution is published as `pyadata-cli`. The import package
 # and the command are both still `adata`.
 name = "pyadata-cli"
-version = "0.7.0"
+version = "0.8.0"
 description = "Streaming CLI for exploring and editing large AnnData .h5ad and .zarr stores"
 readme = "README.md"
 requires-python = ">=3.12"

{pyadata_cli-0.7.0 → pyadata_cli-0.8.0}/src/adata/cli.py

@@ -347,6 +347,10 @@ def subset(
         adata subset data.h5ad -o out.h5ad -q "n_counts > 1000 and cluster in A,B"
         adata subset data.h5ad -o out.h5ad --var-query "highly_variable == True"
     """
+    if zarr_format is not None and zarr_format not in (2, 3):
+        console.print("[bold red]Error:[/] --zarr-format must be 2 or 3.")
+        raise typer.Exit(code=1)
+
     if obs is None and var is None and obs_query is None and var_query is None:
         console.print(
             "[bold red]Error:[/] Provide at least one of --obs, --var, "
@@ -433,7 +437,9 @@ def concat(
         1024, "--chunk", "-C", help="Row chunk size while streaming"
     ),
     zarr_format: Optional[int] = typer.Option(
-        None, "--zarr-format", help="Zarr spec version to write (2 or 3)"
+        None,
+        "--zarr-format",
+        help="Zarr spec version to write (defaults to the inputs' when they agree)",
     ),
 ) -> None:
     """
@@ -447,6 +453,10 @@ def concat(
         adata concat *.h5ad -o merged.h5ad --join outer --label sample
         adata concat a.h5ad b.h5ad -o m.h5ad --keys a,b --index-unique - --uns-merge same
     """
+    if zarr_format is not None and zarr_format not in (2, 3):
+        console.print("[bold red]Error:[/] --zarr-format must be 2 or 3.")
+        raise typer.Exit(code=1)
+
     for name, value in (("--merge", merge), ("--uns-merge", uns_merge)):
         if value is not None and value not in MERGE_CHOICES:
             console.print(
@@ -543,7 +553,7 @@ def convert(
     ctx: typer.Context,
     file: Path = typer.Argument(
         ...,
-        help="Input file or store",
+        help="Input file, store, or 10x/STARsolo matrix folder",
         exists=True,
         readable=True,
         dir_okay=True,
@@ -553,7 +563,8 @@ def convert(
         None,
         "--output",
         "-o",
-        help="Output path; its extension picks the format (.h5ad, .zarr, .h5)",
+        help="Output path; its extension picks the format (.h5ad, .zarr, .h5), "
+        "or a folder with --to 10x-mtx",
         dir_okay=True,
         file_okay=True,
     ),
@@ -576,7 +587,7 @@ def convert(
         None,
         "--compression",
         help="none, gzip or lzf for h5ad; none, gzip, zstd or blosc for zarr "
-        "(defaults to the source's)",
+        "(defaults to the source's); gzip or none for a 10x-mtx folder",
     ),
     force: bool = typer.Option(
         False,
@@ -591,7 +602,8 @@ def convert(
     genome: Optional[str] = typer.Option(
         None,
         "--genome",
-        help="10x input: the genome to keep (picks the group in a Cell Ranger 2 file)",
+        help="10x input: the genome to keep (picks the group or subfolder of a "
+        "Cell Ranger 2 matrix)",
     ),
     var_names: str = typer.Option(
         "gene_symbols",
@@ -647,11 +659,13 @@ def convert(
     Convert a store to another format.
 
     The output's extension picks the format: .h5ad, .zarr, or .h5 for a 10x
-    Genomics matrix (Cell Ranger's *_feature_bc_matrix.h5). Between h5ad and
-    zarr every element is copied, streamed, keeping the source's chunking and
-    compression where the target can express them. A 10x matrix is read as
-    scanpy.read_10x_h5(gex_only=False) reads it, keeping integer counts, and
-    written as Cell Ranger writes it.
+    Genomics matrix (Cell Ranger's *_feature_bc_matrix.h5); --to 10x-mtx
+    writes a Matrix Market folder. Between h5ad and zarr every element is
+    copied, streamed, keeping the source's chunking and compression where the
+    target can express them. A 10x matrix is read as scanpy's read_10x_h5 or
+    read_10x_mtx (gex_only=False) reads it, keeping integer counts, and
+    written as Cell Ranger writes it. MTX folders from Cell Ranger and
+    STARsolo, velocyto's included, are read in two streaming passes.
 
     Nothing is written until every check has passed, and the output is moved
     into place only once complete: a failed conversion leaves nothing
@@ -667,6 +681,9 @@ def convert(
         adata convert filtered_feature_bc_matrix.h5 -o counts.h5ad
         adata convert raw_feature_bc_matrix.h5 -o rna.h5ad --feature-type "Gene Expression"
         adata convert counts.h5ad -o for_cellbender.h5 --layer counts
+        adata convert Solo.out/Gene/filtered -o counts.h5ad
+        adata convert Solo.out/Velocyto/raw -o velocyto.h5ad
+        adata convert counts.h5ad -o counts_mtx --to 10x-mtx --layer counts
     """
     entries = list(ctx.args)
     recast_flags = _given(ctx, _RECAST_FLAGS)
@@ -1107,7 +1124,7 @@ def export_sparse(
         "--output",
         "-o",
         writable=True,
-        help="Output .mtx file path (defaults to stdout)",
+        help="Output .mtx file path; .mtx.gz gzips it (defaults to stdout)",
     ),
     head: Optional[int] = typer.Option(
         None, "--head", "-n", help="Output only the first n entries of mtx file"
@@ -1129,9 +1146,9 @@ def export_sparse(
     Export a sparse matrix (CSR/CSC) to Matrix Market (.mtx) format.
 
     Examples:
-        h5ad export sparse data.h5ad X matrix.mtx
-        h5ad export sparse data.h5ad layers/counts counts.mtx
-        h5ad export sparse data.h5ad X --head 100
+        adata export sparse data.h5ad X -o matrix.mtx
+        adata export sparse data.h5ad layers/counts -o counts.mtx
+        adata export sparse data.h5ad X --head 100
     """
 
     try:
@@ -1179,8 +1196,8 @@ def export_dict(
     Export a dict/group or scalar to JSON format.
 
     Examples:
-        h5ad export dict data.h5ad uns metadata.json
-        h5ad export dict data.h5ad uns/colors colors.json
+        adata export dict data.h5ad uns metadata.json
+        adata export dict data.h5ad uns/colors colors.json
     """
 
     try:
@@ -1219,7 +1236,7 @@ def export_image(
     The array should be 2D (H,W) or 3D (H,W,C) with C in {1,3,4}.
 
     Examples:
-        h5ad export image data.h5ad uns/spatial/image tissue.png
+        adata export image data.h5ad uns/spatial/image -o tissue.png
     """
 
     try:
@@ -1363,8 +1380,8 @@ def import_array(
     Dimensions are validated against existing obs/var.
 
     Examples:
-        h5ad import array data.h5ad obsm/X_pca pca.npy -o output.h5ad
-        h5ad import array data.h5ad X matrix.npy --inplace
+        adata import array data.h5ad obsm/X_pca pca.npy -o output.h5ad
+        adata import array data.h5ad X matrix.npy --inplace
     """
     from adata.commands.import_data import _import_npy
 
@@ -1397,7 +1414,7 @@ def import_sparse(
         ..., help="Object path to create/replace (e.g., 'X', 'layers/counts')"
     ),
     input_file: Path = typer.Argument(
-        ..., help="Input .mtx file", exists=True, readable=True
+        ..., help="Input .mtx or .mtx.gz file", exists=True, readable=True
     ),
     output: Optional[Path] = typer.Option(
         None,
@@ -1419,8 +1436,8 @@ def import_sparse(
     Dimensions are validated against existing obs/var.
 
     Examples:
-        h5ad import sparse data.h5ad X matrix.mtx -o output.h5ad
-        h5ad import sparse data.h5ad layers/counts counts.mtx --inplace
+        adata import sparse data.h5ad X matrix.mtx -o output.h5ad
+        adata import sparse data.h5ad layers/counts counts.mtx --inplace
     """
     from adata.commands.import_data import _import_mtx
 
@@ -1473,8 +1490,8 @@ def import_dict(
     Import a JSON file into uns or other dict-like groups.
 
     Examples:
-        h5ad import dict data.h5ad uns/metadata config.json -o output.h5ad
-        h5ad import dict data.h5ad uns settings.json --inplace
+        adata import dict data.h5ad uns/metadata config.json -o output.h5ad
+        adata import dict data.h5ad uns settings.json --inplace
     """
     from adata.commands.import_data import _import_json
 

{pyadata_cli-0.7.0 → pyadata_cli-0.8.0}/src/adata/commands/convert.py

@@ -20,16 +20,10 @@ from adata.conversion import (
     detect_format,
     output_format,
 )
+from adata.util.path import same_path
 from adata.util.staging import staged_outputs
 
 
-def _same_path(left: Path, right: Path) -> bool:
-    try:
-        return left.resolve() == right.resolve()
-    except OSError:
-        return False
-
-
 def convert_store(
     file: Path,
     output: Path,
@@ -56,7 +50,7 @@ def convert_store(
 
     plan = converter.plan(file, output, src_format, dst_format, options)
     for out in plan.outputs:
-        if _same_path(file, out):
+        if same_path(file, out):
             # Writing a Zarr store over its own source empties it before a
             # single element has been read.
             raise ValueError(f"Output path is the input: {out}")

{pyadata_cli-0.7.0 → pyadata_cli-0.8.0}/src/adata/commands/import_data.py

@@ -60,7 +60,9 @@ def import_object(
     console: Console,
 ) -> None:
     target_file = _prepare_target_path(file, output_file, inplace, console)
-    ext = input_file.suffix.lower()
+    suffixes = [x.lower() for x in input_file.suffixes]
+    # A gzipped matrix is still a matrix: `counts.mtx.gz` imports as `.mtx`.
+    ext = suffixes[-2] if len(suffixes) > 1 and suffixes[-1] == ".gz" else input_file.suffix.lower()
 
     if ext not in EXTENSION_FORMAT:
         raise ValueError(

{pyadata_cli-0.7.0 → pyadata_cli-0.8.0}/src/adata/commands/recast.py

@@ -2,13 +2,14 @@
 
 Writes a whole new store rather than editing one in place, for the same
 reason `subset` does: a conversion that fails half way leaves the original
-untouched, and `--inplace` becomes an atomic swap of a finished file rather
-than a partial edit of a live one.
+untouched. The new store is written beside its destination and renamed into
+place only once complete (see `adata.util.staging`), so `--inplace` replaces a
+finished file rather than editing a live one, and the original is deleted only
+after its successor is in place.
 """
 
 from __future__ import annotations
 
-import shutil
 from pathlib import Path
 from typing import Any, List, Optional
 
@@ -25,15 +26,16 @@ from adata.core.recast import (
 from adata.elements import spec
 from adata.elements.write import ensure_anndata_skeleton
 from adata.storage import copy_tree, detect_backend, is_group, open_store
-
-#: What `--all` means. The matrices an AnnData object is built from, not
-#: every 2-D array in the file: obsm/varm hold embeddings, whose dtype is
-#: rarely what anyone is trying to shrink. Those still convert by path.
-ALL_PREFIXES = ("X", "layers", "raw/X")
-
+from adata.util.path import same_path
+from adata.util.staging import staged_outputs
 
 def discover_matrices(root: Any) -> List[str]:
-    """Entry paths `--all` resolves to, in a stable order."""
+    """Entry paths `--all` resolves to, in a stable order.
+
+    The matrices an AnnData object is built from, not every 2-D array in the
+    file: obsm/varm hold embeddings, whose dtype is rarely what anyone is
+    trying to shrink. Those still convert by path.
+    """
     found: List[str] = []
     if "X" in root:
         found.append("X")
@@ -44,14 +46,6 @@ def discover_matrices(root: Any) -> List[str]:
     return found
 
 
-def _same_path(left: Path, right: Path) -> bool:
-    """Do these name the same store, through symlinks and `..` alike?"""
-    try:
-        return left.resolve() == right.resolve()
-    except OSError:  # pragma: no cover - unresolvable path
-        return left.absolute() == right.absolute()
-
-
 def _resolve(root: Any, path: str) -> Any:
     obj = root
     for part in path.split("/"):
@@ -96,7 +90,7 @@ def recast_store(
         else None
     )
 
-    if output is not None and not inplace and _same_path(file, output):
+    if output is not None and not inplace and same_path(file, output):
         # Opening the destination "w" clears it while the source is still
         # being read from it. HDF5 refuses; Zarr does not, and quietly
         # produced an empty store where the data used to be.
@@ -105,69 +99,54 @@ def recast_store(
             "it, which writes to a temporary file first."
         )
 
-    if inplace:
-        backend = detect_backend(file)
-        if backend == "zarr":
-            base = file.stem if file.suffix else file.name
-            dst_path = file.with_name(f"{base}.recast-tmp.zarr")
-        else:
-            dst_path = file.with_name(f"{file.name}.recast-tmp")
-        if dst_path.exists():
-            raise FileExistsError(f"Temporary path already exists: {dst_path}")
-    else:
-        dst_path = output
+    dst_path = file if inplace else Path(output)
 
     if zarr_format is None and detect_backend(file) == "zarr":
         with open_store(file, "r") as probe:
             zarr_format = probe.zarr_format
 
-    with open_store(file, "r") as src_store:
-        src = src_store.root
-        targets = discover_matrices(src) if convert_all else list(entries or [])
-        if not targets:
-            raise ValueError(
-                "No matrices selected. Name one (e.g. `X`) or pass --all."
-            )
-        # Every check first, before the destination exists. A refusal must
-        # not leave behind a store holding a copy of obs and var and nothing
-        # else -- the caller cannot tell that from a finished conversion.
-        plans = {
-            path: plan_conversion(
-                _resolve(src, path),
-                path,
-                dtype=data_dtype,
-                index_dtype=index_dtype,
-                layout=layout,
-                chunk=chunk,
-                force=force,
-                console=console,
+    # The source is opened inside the staging block, so it is closed before
+    # `--inplace` renames it aside.
+    with staged_outputs([dst_path]) as (temp,):
+        with open_store(file, "r") as src_store:
+            src = src_store.root
+            targets = discover_matrices(src) if convert_all else list(entries or [])
+            if not targets:
+                raise ValueError(
+                    "No matrices selected. Name one (e.g. `X`) or pass --all."
+                )
+            # Every check first, before the destination exists. A refusal must
+            # not leave behind a store holding a copy of obs and var and nothing
+            # else -- the caller cannot tell that from a finished conversion.
+            plans = {
+                path: plan_conversion(
+                    _resolve(src, path),
+                    path,
+                    dtype=data_dtype,
+                    index_dtype=index_dtype,
+                    layout=layout,
+                    chunk=chunk,
+                    force=force,
+                    console=console,
+                )
+                for path in targets
+            }
+
+            console.print(
+                f"[cyan]Converting {len(targets)} matrix/matrices:[/] "
+                + ", ".join(targets)
             )
-            for path in targets
-        }
-
-        console.print(
-            f"[cyan]Converting {len(targets)} matrix/matrices:[/] "
-            + ", ".join(targets)
-        )
 
-        with open_store(dst_path, "w", zarr_format=zarr_format) as dst_store:
-            dst = dst_store.root
-            _write(
-                src, dst, plans,
-                chunk=chunk, chunk_rows=chunk_rows, in_memory=in_memory,
-                console=console,
-            )
-            ensure_anndata_skeleton(dst)
+            with open_store(temp, "w", zarr_format=zarr_format) as dst_store:
+                dst = dst_store.root
+                _write(
+                    src, dst, plans,
+                    chunk=chunk, chunk_rows=chunk_rows, in_memory=in_memory,
+                    console=console,
+                )
+                ensure_anndata_skeleton(dst)
 
     if inplace:
-        if file.is_dir():
-            shutil.rmtree(file)
-        elif file.exists():
-            file.unlink()
-        if dst_path.is_dir():
-            shutil.move(str(dst_path), str(file))
-        else:
-            dst_path.replace(file)
         console.print(f"[green]Converted[/] {file}")
     else:
         console.print(f"[green]Wrote[/] {dst_path}")

{pyadata_cli-0.7.0 → pyadata_cli-0.8.0}/src/adata/commands/split.py

@@ -4,6 +4,11 @@ Requested in issue #2, modelled on cellgeni/scraft's `split_h5ad` but
 streaming: the source is never loaded into memory, only the column being split
 on is read, and each output is produced by the same subset machinery used by
 `adata subset`, fanned out so every matrix is read once for all groups.
+
+Every output is written beside its destination and renamed into place only
+once all of them are complete, so a split that fails leaves no partial stores
+(and existing outputs as they were). The manifest is written last, so it
+exists only when everything it lists does.
 """
 
 from __future__ import annotations
@@ -19,6 +24,8 @@ from adata.core.select import group_indices
 from adata.core.subset import split_h5ad
 from adata.storage import detect_backend, open_store
 from adata.util.names import unique_names
+from adata.util.path import same_path
+from adata.util.staging import staged_outputs
 
 
 def split_store(
@@ -78,6 +85,13 @@ def split_store(
     for label, out_path, count in planned:
         console.print(f"  {label!r} -> {out_path} ({count} {axis})")
 
+    for _, out_path, _ in planned:
+        if same_path(file, out_path):
+            raise ValueError(
+                f"Output path is the input: {out_path}. Choose another "
+                "--output-dir."
+            )
+
     if dry_run:
         console.print("[yellow]Dry run: nothing written.[/]")
         return planned
@@ -86,20 +100,21 @@ def split_store(
 
     # One call for every group, so each matrix is read once rather than once
     # per group.
-    split_h5ad(
-        file,
-        [
-            (
-                out_path,
-                np.sort(groups[label]) if axis == "obs" else None,
-                np.sort(groups[label]) if axis == "var" else None,
-            )
-            for label, out_path, _ in planned
-        ],
-        chunk_rows=chunk_rows,
-        console=console,
-        zarr_format=zarr_format,
-    )
+    with staged_outputs([out_path for _, out_path, _ in planned]) as temps:
+        split_h5ad(
+            file,
+            [
+                (
+                    temp,
+                    np.sort(groups[label]) if axis == "obs" else None,
+                    np.sort(groups[label]) if axis == "var" else None,
+                )
+                for (label, _, _), temp in zip(planned, temps)
+            ],
+            chunk_rows=chunk_rows,
+            console=console,
+            zarr_format=zarr_format,
+        )
 
     if manifest:
         _write_manifest(file, output_dir, column, planned, console)

{pyadata_cli-0.7.0 → pyadata_cli-0.8.0}/src/adata/conversion/__init__.py

@@ -17,7 +17,7 @@ from typing import Dict, FrozenSet, List, Optional
 
 import h5py
 
-from adata.conversion import tenx
+from adata.conversion import mtx, tenx
 from adata.conversion.anndata_copy import AnnDataCopy
 from adata.conversion.base import ConversionPlan, Converter, Format, Options
 from adata.storage import has_valid_anndata_root_attrs, is_zarr_path
@@ -74,6 +74,15 @@ FORMATS: Dict[str, Format] = {
         importer=tenx.TenxImport(),
         exporter=tenx.TenxExport(),
     ),
+    # A folder, so no extension: chosen as output with `--to 10x-mtx`.
+    "10x-mtx": Format(
+        name="10x-mtx",
+        description="10x Genomics / STARsolo Matrix Market folder",
+        extensions=(),
+        sniff=mtx.sniff,
+        importer=mtx.MtxImport(),
+        exporter=mtx.MtxExport(),
+    ),
 }
 
 _ANNDATA_COPY = AnnDataCopy()
@@ -106,6 +115,12 @@ def detect_format(path: Path) -> str:
     for fmt in FORMATS.values():
         if (fmt.anndata or fmt.sniff is None) and suffix in fmt.extensions:
             return fmt.name
+    if suffix in (".mtx", ".gz") and path.name.lower().endswith((".mtx", ".mtx.gz")):
+        raise ValueError(
+            f"'{path.name}' is a single Matrix Market file, which `convert` "
+            "does not read on its own: give the folder holding it with its "
+            "barcodes and features, or use `adata import sparse`."
+        )
     raise ValueError(
         f"Cannot tell what format '{path}' is. Pass --from, one of: {_names()}."
     )
@@ -130,15 +145,21 @@ def output_format(path: Path, requested: Optional[str] = None) -> str:
         if by_extension is None:
             raise ValueError(
                 f"Cannot tell the output format from '{path.name}'. "
-                f"Use a known extension or pass --to, one of: {_names()}."
+                f"Use a known extension or pass --to, one of: {_names()} "
+                "(--to 10x-mtx for a folder)."
             )
         return by_extension
 
     if by_extension is not None and by_extension != requested:
+        extensions = FORMATS[requested].extensions
         raise ValueError(
             f"--to {requested} contradicts the output's extension, which means "
-            f"{by_extension}. Name the output with one of: "
-            f"{', '.join(FORMATS[requested].extensions)}."
+            f"{by_extension}. Name the output "
+            + (
+                f"with one of: {', '.join(extensions)}."
+                if extensions
+                else "as a folder, without an extension."
+            )
         )
     if (requested == "zarr") != (suffix == ".zarr"):
         raise ValueError(