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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyadata-cli
-Version: 0.7.1
+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.1 → 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.1 → 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.1"
+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.1 → pyadata_cli-0.8.0}/src/adata/cli.py

@@ -553,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,
@@ -563,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,
     ),
@@ -586,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,
@@ -601,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",
@@ -657,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
@@ -677,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)
@@ -1117,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"
@@ -1407,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,

{pyadata_cli-0.7.1 → 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.1 → 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(

pyadata_cli-0.8.0/src/adata/conversion/features.py

@@ -0,0 +1,380 @@
+"""The feature table shared by every 10x-style format.
+
+A 10x HDF5 matrix and a 10x MTX folder record the same things about each
+feature -- an id, a name, a type -- and import and export them the same way.
+What is common lives here, so `tenx` and `mtx` differ only in how they read
+and write their files:
+
+* import: which features each output keeps (`plan_targets`), how they are
+  named (`annotate`), and how obs and var are written (`write_obs_index`,
+  `write_var`);
+* export: which matrix to write (`plan_matrix_source`) and each feature's id,
+  name and type, worked out from var (`export_features`).
+
+The AnnData produced matches what scanpy's `read_10x_h5` and `read_10x_mtx`
+give with `gex_only=False`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from adata.conversion.base import Options
+from adata.core.recast import describe
+from adata.elements import spec
+from adata.elements.read import (
+    dataframe_columns,
+    element_len,
+    read_str_all,
+    resolve_index,
+)
+from adata.elements.strings import string_dtype_for
+from adata.elements.write import (
+    write_categorical,
+    write_dataframe_header,
+    write_dense,
+    write_string_array,
+)
+from adata.storage import create_dataset, is_group, is_zarr_group, open_store
+from adata.util.names import count_duplicates, make_index_unique, unique_names
+
+VAR_NAMES = ("gene_symbols", "gene_ids")
+
+#: Rows of a string column handled per read when streaming one.
+STRING_STEP = 1 << 18
+
+
+# ---------------------------------------------------------------------------
+# import
+
+
+@dataclass
+class Target:
+    """One AnnData to write: which features it keeps, and their annotation."""
+
+    label: Optional[str]
+    keep: Optional[np.ndarray]
+    var_names: List[str]
+    columns: Dict[str, np.ndarray]
+
+
+def type_counts(types: np.ndarray) -> List[Tuple[str, int]]:
+    """Feature types in order of first appearance, with how many of each."""
+    labels, first, counts = np.unique(types, return_index=True, return_counts=True)
+    order = np.argsort(first)
+    return [(str(labels[i]), int(counts[i])) for i in order]
+
+
+def check_import_options(options: Options) -> None:
+    if options.var_names not in VAR_NAMES:
+        raise ValueError(f"--var-names must be one of: {', '.join(VAR_NAMES)}.")
+    if options.feature_type is not None and options.split_feature_types:
+        raise ValueError(
+            "--feature-type keeps one type and --split-feature-types writes "
+            "every type separately; pass one or the other."
+        )
+
+
+def annotate(
+    names: np.ndarray,
+    columns: Dict[str, np.ndarray],
+    keep: Optional[np.ndarray],
+    options: Options,
+    label: Optional[str],
+) -> Target:
+    """var for the features in `keep`: their names, and their columns."""
+
+    def pick(values: np.ndarray) -> np.ndarray:
+        return values if keep is None else values[keep]
+
+    picked = {key: pick(values) for key, values in columns.items()}
+    if options.var_names == "gene_ids":
+        # As scanpy's read_10x_mtx does it: ids become the names, and the
+        # symbols move into a column where the ids were.
+        index = list(picked["gene_ids"])
+        picked = {
+            ("gene_symbols" if key == "gene_ids" else key): (
+                pick(names) if key == "gene_ids" else values
+            )
+            for key, values in picked.items()
+        }
+    else:
+        index = list(pick(names))
+    if options.make_unique:
+        index = make_index_unique(index)
+    return Target(label=label, keep=keep, var_names=index, columns=picked)
+
+
+def plan_targets(
+    output: Path,
+    names: np.ndarray,
+    columns: Dict[str, np.ndarray],
+    types: Optional[np.ndarray],
+    keep: np.ndarray,
+    options: Options,
+    *,
+    noun: str,
+) -> Tuple[List[Path], List[Target], List[str]]:
+    """The outputs to write, the features each keeps, and any warnings.
+
+    One output, unless `--split-feature-types` asks for one per type. `keep`
+    is what survives filters the caller applied first, such as `--genome`;
+    `noun` names the input in messages ("file", "folder").
+    """
+    groups: List[Tuple[Optional[str], np.ndarray]] = []
+    if options.feature_type is not None:
+        available = [t for t, _ in type_counts(types)]
+        if options.feature_type not in available:
+            raise ValueError(
+                f"No features of type {options.feature_type!r}; this {noun} "
+                f"has: {', '.join(available)}."
+            )
+        groups.append((options.feature_type, keep & (types == options.feature_type)))
+    elif options.split_feature_types:
+        for label, _ in type_counts(types[keep]):
+            groups.append((label, keep & (types == label)))
+    else:
+        groups.append((None, keep))
+
+    stems = unique_names([label for label, _ in groups if label is not None])
+    outputs: List[Path] = []
+    targets: List[Target] = []
+    warnings: List[str] = []
+    for label, mask in groups:
+        path = output
+        if options.split_feature_types:
+            path = output.with_name(f"{output.stem}.{stems[label]}{output.suffix}")
+        selection = None if mask.all() else np.flatnonzero(mask)
+        target = annotate(names, columns, selection, options, label)
+        duplicated = count_duplicates(target.var_names)
+        if duplicated:
+            where = f" in {path.name}" if options.split_feature_types else ""
+            warnings.append(
+                f"{duplicated:,} var names{where} repeat an earlier one. "
+                "Pass --make-unique to suffix them as anndata's "
+                "var_names_make_unique does."
+            )
+        outputs.append(path)
+        targets.append(target)
+    return outputs, targets, warnings
+
+
+def describe_import(
+    n_barcodes: int,
+    n_features: int,
+    types: Optional[np.ndarray],
+    targets: Sequence[Target],
+) -> str:
+    """`1,222 barcodes x 33,538 features (Gene Expression 33,538)`, and so on."""
+    described = f"{n_barcodes:,} barcodes x {n_features:,} features"
+    if types is not None:
+        described += " (" + ", ".join(f"{t} {n:,}" for t, n in type_counts(types)) + ")"
+    if len(targets) > 1:
+        described += f", into {len(targets)} outputs by feature type"
+    elif targets[0].keep is not None:
+        described += f", keeping {len(targets[0].keep):,} features"
+    return described
+
+
+def write_obs_index(root: Any, n: int, blocks: Iterable[Sequence[str]]) -> Any:
+    """obs, holding only its index: the barcodes, written a block at a time.
+
+    Returns the group, for the caller to add columns to. A source that gives
+    more or fewer than `n` barcodes is refused.
+    """
+    obs = root.create_group("obs")
+    spec.set_encoding(obs, spec.DATAFRAME)
+    obs.attrs["_index"] = "_index"
+
+    backend = "zarr" if is_zarr_group(root) else "hdf5"
+    index = create_dataset(obs, "_index", shape=(n,), dtype=string_dtype_for(backend))
+    written = 0
+    for block in blocks:
+        if written + len(block) > n:
+            raise ValueError(f"There are more than {n:,} barcodes.")
+        index[written : written + len(block)] = np.asarray(block, dtype=object)
+        written += len(block)
+    if written != n:
+        raise ValueError(f"There are {written:,} barcodes, not {n:,}.")
+    spec.set_encoding(index, spec.STRING_ARRAY)
+    return obs
+
+
+def write_var(root: Any, target: Target) -> None:
+    """var, with string columns encoded as anndata's writer would encode them.
+
+    anndata turns any string column with a repeated value into a categorical
+    when it writes (`strings_to_categoricals`), so an h5ad scanpy wrote from
+    the same file holds `feature_types` and `genome` as categoricals. Doing
+    the same keeps the two interchangeable, and those columns a few bytes
+    instead of a string per feature.
+    """
+    var = write_dataframe_header(root, "var", target.var_names, list(target.columns))
+    for key, values in target.columns.items():
+        if values.dtype.kind == "b":
+            write_dense(var, key, values)
+            continue
+        categories, codes = np.unique(values, return_inverse=True)
+        if len(categories) < len(values):
+            write_categorical(var, key, codes, list(categories))
+        else:
+            write_string_array(var, key, values)
+
+
+# ---------------------------------------------------------------------------
+# export
+
+
+def matrix_path(layer: Optional[str]) -> str:
+    """`--layer` as a path: X, raw/X, a layer's name, or layers/NAME."""
+    if layer is None or layer in ("X", "raw/X") or layer.startswith("layers/"):
+        return layer or "X"
+    return f"layers/{layer}"
+
+
+def resolve(root: Any, path: str) -> Any:
+    node = root
+    for part in path.split("/"):
+        if not is_group(node) or part not in node:
+            raise KeyError(f"{path!r} not found in the store.")
+        node = node[part]
+    return node
+
+
+@dataclass
+class ExportFeatures:
+    ids: List[str]
+    names: List[str]
+    types: List[str]
+    genomes: List[str]
+    tags: Dict[str, List[str]]
+
+
+@dataclass
+class MatrixSource:
+    """The matrix an export writes, and what is known about it before writing."""
+
+    path: str
+    n_obs: int
+    n_var: int
+    dtype: np.dtype
+    features: ExportFeatures
+
+
+def plan_matrix_source(
+    source: Path, options: Options, warnings: List[str]
+) -> MatrixSource:
+    """Check the matrix `--layer` names against obs and var; read var's features.
+
+    Warns when the matrix holds floats, which 10x formats are not expected to.
+    """
+    path = matrix_path(options.layer)
+    with open_store(source, "r", require_anndata=False) as store:
+        root = store.root
+        matrix = describe(resolve(root, path))
+        var_path = "raw/var" if path.startswith("raw/") else "var"
+        var, obs = resolve(root, var_path), resolve(root, "obs")
+        obs_index, _ = resolve_index(obs, "obs")
+        var_index, _ = resolve_index(var, "var")
+        n_obs, n_var = element_len(obs_index), element_len(var_index)
+        if matrix.shape != (n_obs, n_var):
+            raise ValueError(
+                f"{path} is {matrix.shape[0]} x {matrix.shape[1]}, but obs has "
+                f"{n_obs} and {var_path} has {n_var} entries."
+            )
+        features = export_features(root, var, var_index, options, warnings)
+
+    if matrix.dtype.kind == "f":
+        warnings.append(
+            f"{path} holds {matrix.dtype} values. Cell Ranger writes integer "
+            "counts, and tools that read its output may expect them: export "
+            "a counts layer with --layer, or recast to int32 first."
+        )
+    return MatrixSource(
+        path=path, n_obs=n_obs, n_var=n_var, dtype=matrix.dtype, features=features
+    )
+
+
+def export_features(
+    root: Any,
+    var: Any,
+    var_index: Any,
+    options: Options,
+    warnings: List[str],
+) -> ExportFeatures:
+    """Work out each feature's id, name, type and genome from var."""
+    columns = dataframe_columns(var)
+    n = element_len(var_index)
+
+    def column(name: str) -> List[str]:
+        return read_str_all(var[name], parent_group=var)
+
+    def requested(flag: str, name: Optional[str]) -> Optional[str]:
+        if name is not None and name not in columns:
+            raise ValueError(
+                f"{flag} {name}: no such var column. It has: "
+                f"{', '.join(columns) or 'none'}."
+            )
+        return name
+
+    ids_col = requested("--gene-ids-column", options.gene_ids_column)
+    names_col = requested("--gene-names-column", options.gene_names_column)
+    types_col = requested("--feature-types-column", options.feature_types_column)
+    index = read_str_all(var_index)
+
+    missing = []
+    if ids_col is None and names_col is None and "gene_ids" not in columns and "gene_symbols" in columns:
+        # var_names are ids already, as `--var-names gene_ids` leaves them.
+        ids, names = index, column("gene_symbols")
+    else:
+        names = column(names_col) if names_col else index
+        if ids_col is None and "gene_ids" in columns:
+            ids_col = "gene_ids"
+        if ids_col is not None:
+            ids = column(ids_col)
+        else:
+            missing.append("gene ids (a gene_ids column, or --gene-ids-column)")
+            ids = names
+    if types_col is None and "feature_types" in columns:
+        types_col = "feature_types"
+    if types_col is not None:
+        types = column(types_col)
+    else:
+        missing.append("feature types (a feature_types column, or --feature-types-column)")
+        types = ["Gene Expression"] * n
+
+    if missing:
+        if not options.force:
+            raise ValueError(
+                f"var has no {' and no '.join(missing)}, which a 10x matrix "
+                "records for every feature. Pass --force to write placeholders: "
+                "the names as ids, and 'Gene Expression' as the type."
+            )
+        warnings.append(f"Writing placeholders for {' and '.join(missing)}.")
+
+    genomes = column("genome") if "genome" in columns else [""] * n
+    tags: Dict[str, List[str]] = {}
+    for key in recorded_tag_keys(root):
+        if key != "genome" and key in columns:
+            tags[key] = column(key)
+    return ExportFeatures(ids=ids, names=names, types=types, genomes=genomes, tags=tags)
+
+
+def cellranger_meta(root: Any) -> Optional[Any]:
+    """`uns/cellranger`, as an import recorded it, if there is one."""
+    if "uns" not in root or "cellranger" not in root["uns"]:
+        return None
+    meta = root["uns"]["cellranger"]
+    return meta if is_group(meta) else None
+
+
+def recorded_tag_keys(root: Any) -> List[str]:
+    meta = cellranger_meta(root)
+    if meta is None or "feature_tag_keys" not in meta:
+        return []
+    return read_str_all(meta["feature_tag_keys"])
+