pyadata-cli 0.7.1__tar.gz → 0.9.0__tar.gz

{pyadata_cli-0.7.1 → pyadata_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyadata-cli
-Version: 0.7.1
+Version: 0.9.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, and from CellBender output
 - 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, CellBender output in, 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.1 → pyadata_cli-0.9.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, and from CellBender output
 - 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, CellBender output in, 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.1 → pyadata_cli-0.9.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.1"
+version = "0.9.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.1 → pyadata_cli-0.9.0}/src/adata/cli.py

@@ -522,6 +522,8 @@ _CONVERT_FLAGS = {
     "gene_ids_column": "--gene-ids-column",
     "gene_names_column": "--gene-names-column",
     "feature_types_column": "--feature-types-column",
+    "raw": "--raw",
+    "min_cell_probability": "--min-cell-probability",
 }
 
 #: Flags that only make sense for format conversion; with recast's flags,
@@ -553,7 +555,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,
@@ -563,7 +565,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,
     ),
@@ -586,7 +589,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,
@@ -601,7 +604,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",
@@ -643,6 +647,21 @@ def convert(
         "--feature-types-column",
         help="10x output: var column holding feature types (default feature_types)",
     ),
+    raw: Optional[Path] = typer.Option(
+        None,
+        "--raw",
+        help="CellBender input: the raw Cell Ranger .h5 it ran on, added as "
+        "layers['cellranger']",
+        exists=True,
+        dir_okay=False,
+        readable=True,
+    ),
+    min_cell_probability: Optional[float] = typer.Option(
+        None,
+        "--min-cell-probability",
+        help="CellBender input: keep droplets with cell_probability at least "
+        "this (CellBender's own cutoff is 0.5)",
+    ),
     # Deprecated: recast's flags, so `convert` keeps working as it did until
     # 1.0.0. Hidden from --help; the old matrix paths arrive in ctx.args.
     inplace: bool = typer.Option(False, "--inplace", hidden=True),
@@ -657,11 +676,14 @@ 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. CellBender output keeps its latent variables, as
+    CellBender's own loader names 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
@@ -677,6 +699,11 @@ 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
+        adata convert cellbender_output.h5 -o cb.h5ad --raw raw_feature_bc_matrix.h5
+        adata convert cellbender_output.h5 -o cells.h5ad --min-cell-probability 0.5
     """
     entries = list(ctx.args)
     recast_flags = _given(ctx, _RECAST_FLAGS)
@@ -760,6 +787,8 @@ def convert(
                 gene_ids_column=gene_ids_column,
                 gene_names_column=gene_names_column,
                 feature_types_column=feature_types_column,
+                raw=raw,
+                min_cell_probability=min_cell_probability,
             ),
         )
     except Exception as e:
@@ -1117,7 +1146,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"
@@ -1407,7 +1436,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,

{pyadata_cli-0.7.1 → pyadata_cli-0.9.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.1 → pyadata_cli-0.9.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 cellbender, 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
@@ -66,6 +66,15 @@ FORMATS: Dict[str, Format] = {
         anndata=True,
         sniff=is_zarr_path,
     ),
+    # Before 10x-h5: a CellBender file is a 10x matrix too, and the first
+    # sniffer to match wins. `--from 10x-h5` still reads one as plain 10x.
+    "cellbender": Format(
+        name="cellbender",
+        description="CellBender remove-background output (0.2 and later)",
+        extensions=(".h5",),
+        sniff=cellbender.sniff,
+        importer=cellbender.CellbenderImport(),
+    ),
     "10x-h5": Format(
         name="10x-h5",
         description="10x Genomics feature-barcode matrix (Cell Ranger v2 or v3)",
@@ -74,6 +83,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 +124,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()}."
     )
@@ -121,24 +145,41 @@ def output_format(path: Path, requested: Optional[str] = None) -> str:
     path = Path(path)
     if requested is not None and requested not in FORMATS:
         raise ValueError(f"Unknown format {requested!r}; use one of: {_names()}.")
+    if requested is not None and not (
+        FORMATS[requested].anndata or FORMATS[requested].exporter is not None
+    ):
+        raise ValueError(f"{requested} can be read but not written.")
 
     suffix = path.suffix.lower()
+    # Only formats that can be written: `.h5` names CellBender output too,
+    # but an `.h5` output is a 10x matrix.
     by_extension = next(
-        (fmt.name for fmt in FORMATS.values() if suffix in fmt.extensions), None
+        (
+            fmt.name
+            for fmt in FORMATS.values()
+            if suffix in fmt.extensions and (fmt.anndata or fmt.exporter is not None)
+        ),
+        None,
     )
     if requested is None:
         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(

{pyadata_cli-0.7.1 → pyadata_cli-0.9.0}/src/adata/conversion/base.py

@@ -35,6 +35,10 @@ class Options:
     gene_names_column: Optional[str] = None
     feature_types_column: Optional[str] = None
 
+    # Reading CellBender output.
+    raw: Optional[Path] = None
+    min_cell_probability: Optional[float] = None
+
 
 @dataclass
 class ConversionPlan: