pyadata-cli 0.5.0__py3-none-any.whl

adata/commands/__init__.py

@@ -0,0 +1,8 @@
+from adata.commands.info import show_info
+from adata.commands.subset import subset_h5ad
+from adata.commands.export import export_table, export_image, export_json, export_mtx, export_npy
+from adata.commands.import_data import import_object
+from adata.commands.ls import list_store
+from adata.commands.create import create_store
+from adata.commands.split import split_store
+from adata.commands.concat import MERGE_STRATEGIES, concat_stores

adata/commands/concat.py

@@ -0,0 +1,21 @@
+"""Command wrapper for `concat`."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Sequence
+
+from rich.console import Console
+
+from adata.core.concat import MERGE_STRATEGIES, concat_on_disk
+
+__all__ = ["MERGE_STRATEGIES", "concat_stores"]
+
+
+def concat_stores(
+    files: Sequence[Path],
+    output: Path,
+    console: Console,
+    **kwargs: object,
+) -> None:
+    concat_on_disk(files, output, console, **kwargs)  # type: ignore[arg-type]

adata/commands/create.py

@@ -0,0 +1,93 @@
+"""`create` -- write a new, empty AnnData store.
+
+Gives `import` something to write into. The result is a complete AnnData
+object in its own right: root attributes, obs and var dataframes with real
+indices, and the optional mapping groups, so anndata can open it before a
+single matrix has been attached.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console
+
+from adata.elements.write import ensure_anndata_skeleton, write_dataframe_header
+from adata.storage import open_store
+
+
+def _read_names(path: Path) -> List[str]:
+    """Read a newline-delimited name list, ignoring blank lines."""
+    names = [
+        line.strip()
+        for line in path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]
+    if not names:
+        raise ValueError(f"'{path}' contains no names.")
+    if len(set(names)) != len(names):
+        raise ValueError(f"'{path}' contains duplicate names.")
+    return names
+
+
+def _resolve_axis(
+    axis: str, n: Optional[int], names_file: Optional[Path]
+) -> List[str]:
+    """Determine an axis's index, from an explicit list or a generated range."""
+    if names_file is not None:
+        names = _read_names(names_file)
+        if n is not None and n != len(names):
+            raise ValueError(
+                f"--n-{axis} is {n} but '{names_file}' has {len(names)} names."
+            )
+        return names
+
+    if n is None:
+        raise ValueError(f"Provide either --n-{axis} or --{axis}-names.")
+    if n < 0:
+        raise ValueError(f"--n-{axis} must not be negative.")
+
+    width = len(str(max(n - 1, 0)))
+    prefix = "cell" if axis == "obs" else "gene"
+    return [f"{prefix}_{i:0{width}d}" for i in range(n)]
+
+
+def create_store(
+    output: Path,
+    console: Console,
+    n_obs: Optional[int] = None,
+    n_var: Optional[int] = None,
+    obs_names: Optional[Path] = None,
+    var_names: Optional[Path] = None,
+    zarr_format: Optional[int] = None,
+    force: bool = False,
+) -> None:
+    """Create an empty AnnData store at `output`.
+
+    Names come from `obs_names`/`var_names` when given, otherwise they are
+    generated as `cell_0000`-style labels wide enough for the axis length.
+    """
+    if output.exists() and not force:
+        raise FileExistsError(
+            f"'{output}' already exists. Pass --force to overwrite it."
+        )
+
+    obs_index = _resolve_axis("obs", n_obs, obs_names)
+    var_index = _resolve_axis("var", n_var, var_names)
+
+    if output.exists() and force:
+        import shutil
+
+        shutil.rmtree(output) if output.is_dir() else output.unlink()
+
+    with open_store(output, "w", zarr_format=zarr_format) as store:
+        root = store.root
+        write_dataframe_header(root, "obs", obs_index, [])
+        write_dataframe_header(root, "var", var_index, [])
+        ensure_anndata_skeleton(root)
+
+    console.print(
+        f"[green]Created[/] {output} "
+        f"({len(obs_index)} obs x {len(var_index)} var, empty)"
+    )

adata/commands/export.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console
+
+from adata.formats.array import export_npy as export_npy_format
+from adata.formats.dataframe import export_dataframe
+from adata.formats.image import export_image as export_image_format
+from adata.formats.json_data import export_json as export_json_format
+from adata.formats.sparse import export_mtx as export_mtx_format
+from adata.storage import open_store
+
+
+def export_table(
+    file: Path,
+    axis: str,
+    columns: Optional[List[str]],
+    out: Optional[Path],
+    chunk_rows: int,
+    head: Optional[int],
+    console: Console,
+) -> None:
+    with open_store(file, "r") as store:
+        export_dataframe(
+            store.root,
+            axis=axis,
+            columns=columns,
+            out=out,
+            chunk_rows=chunk_rows,
+            head=head,
+            console=console,
+        )
+
+
+def export_npy(
+    file: Path,
+    obj: str,
+    out: Optional[Path],
+    chunk_elements: int,
+    console: Console,
+) -> None:
+    with open_store(file, "r") as store:
+        export_npy_format(
+            store.root,
+            obj=obj,
+            out=out,
+            chunk_elements=chunk_elements,
+            console=console,
+        )
+
+
+def export_mtx(
+    file: Path,
+    obj: str,
+    out: Optional[Path],
+    head: Optional[int],
+    chunk_elements: int,
+    in_memory: bool,
+    console: Console,
+) -> None:
+    with open_store(file, "r") as store:
+        export_mtx_format(
+            store.root,
+            obj=obj,
+            out=out,
+            head=head,
+            chunk_elements=chunk_elements,
+            in_memory=in_memory,
+            console=console,
+        )
+
+
+def export_json(
+    file: Path,
+    obj: str,
+    out: Optional[Path],
+    max_elements: int,
+    include_attrs: bool,
+    console: Console,
+) -> None:
+    with open_store(file, "r") as store:
+        export_json_format(
+            store.root,
+            obj=obj,
+            out=out,
+            max_elements=max_elements,
+            include_attrs=include_attrs,
+            console=console,
+        )
+
+
+def export_image(file: Path, obj: str, out: Path, console: Console) -> None:
+    with open_store(file, "r") as store:
+        export_image_format(store.root, obj=obj, out=out, console=console)
+
+
+__all__ = [
+    "export_image",
+    "export_json",
+    "export_mtx",
+    "export_npy",
+    "export_table",
+]

adata/commands/import_data.py

@@ -0,0 +1,144 @@
+"""Import command helpers for creating/replacing objects in h5ad/zarr stores."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from rich.console import Console
+
+from adata.formats.array import import_npy
+from adata.formats.dataframe import import_dataframe
+from adata.formats.image import import_image
+from adata.formats.json_data import import_json
+from adata.formats.sparse import import_mtx
+from adata.storage import copy_path, copy_store_contents, detect_backend, open_store
+
+
+EXTENSION_FORMAT = {
+    ".csv": "csv",
+    ".npy": "npy",
+    ".mtx": "mtx",
+    ".json": "json",
+}
+
+
+def _prepare_target_path(
+    file: Path,
+    output_file: Optional[Path],
+    inplace: bool,
+    console: Console,
+) -> Path:
+    if inplace:
+        return file
+    if output_file is None:
+        raise ValueError("Output file is required unless --inplace is specified.")
+
+    src_backend = detect_backend(file)
+    dst_backend = detect_backend(output_file)
+
+    if src_backend == dst_backend:
+        copy_path(file, output_file)
+        console.print(f"[dim]Copied {file} → {output_file}[/]")
+        return output_file
+
+    with open_store(file, "r") as src_store, open_store(output_file, "w") as dst_store:
+        copy_store_contents(src_store.root, dst_store.root)
+    console.print(
+        f"[dim]Converted {file} ({src_backend}) → {output_file} ({dst_backend})[/]"
+    )
+    return output_file
+
+
+def import_object(
+    file: Path,
+    obj: str,
+    input_file: Path,
+    output_file: Optional[Path],
+    inplace: bool,
+    index_column: Optional[str],
+    console: Console,
+) -> None:
+    target_file = _prepare_target_path(file, output_file, inplace, console)
+    ext = input_file.suffix.lower()
+
+    if ext not in EXTENSION_FORMAT:
+        raise ValueError(
+            f"Unsupported input file extension '{ext}'. "
+            f"Supported: {', '.join(sorted(EXTENSION_FORMAT.keys()))}"
+        )
+
+    fmt = EXTENSION_FORMAT[ext]
+
+    if index_column and (fmt != "csv" or obj not in ("obs", "var")):
+        raise ValueError("--index-column is only valid for CSV import into 'obs' or 'var'.")
+
+    if fmt == "csv":
+        _import_csv(target_file, obj, input_file, index_column, console)
+    elif fmt == "npy":
+        _import_npy(target_file, obj, input_file, console)
+    elif fmt == "mtx":
+        _import_mtx(target_file, obj, input_file, console)
+    elif fmt == "json":
+        _import_json(target_file, obj, input_file, console)
+
+
+def _import_csv(
+    file: Path,
+    obj: str,
+    input_file: Path,
+    index_column: Optional[str],
+    console: Console,
+    categorical: Optional[list] = None,
+    auto_categorical: bool = True,
+) -> None:
+    with open_store(file, "a") as store:
+        import_dataframe(
+            store.root,
+            obj=obj,
+            input_file=input_file,
+            index_column=index_column,
+            console=console,
+            categorical=categorical,
+            auto_categorical=auto_categorical,
+        )
+
+
+def _import_npy(
+    file: Path,
+    obj: str,
+    input_file: Path,
+    console: Console,
+) -> None:
+    with open_store(file, "a") as store:
+        import_npy(store.root, obj=obj, input_file=input_file, console=console)
+
+
+def _import_mtx(
+    file: Path,
+    obj: str,
+    input_file: Path,
+    console: Console,
+) -> None:
+    with open_store(file, "a") as store:
+        import_mtx(store.root, obj=obj, input_file=input_file, console=console)
+
+
+def _import_image(
+    file: Path,
+    obj: str,
+    input_file: Path,
+    console: Console,
+) -> None:
+    with open_store(file, "a") as store:
+        import_image(store.root, obj=obj, input_file=input_file, console=console)
+
+
+def _import_json(
+    file: Path,
+    obj: str,
+    input_file: Path,
+    console: Console,
+) -> None:
+    with open_store(file, "a") as store:
+        import_json(store.root, obj=obj, input_file=input_file, console=console)

adata/commands/info.py

@@ -0,0 +1,199 @@
+from pathlib import Path
+from typing import Any, Optional
+
+from rich.console import Console
+from rich.tree import Tree
+
+from adata.core.info import axis_len, format_type_info, get_entry_type
+from adata.storage import is_dataset, is_group, open_store
+
+# Preferred display order for top-level keys
+KEY_ORDER = ["X", "obs", "var", "obsm", "varm", "layers", "obsp", "varp", "uns"]
+
+
+def _sort_keys(keys: list) -> list:
+    """Sort keys according to KEY_ORDER, with unknown keys at the end."""
+    order_map = {k: i for i, k in enumerate(KEY_ORDER)}
+    return sorted(keys, key=lambda k: (order_map.get(k, len(KEY_ORDER)), k))
+
+
+def show_info(
+    file: Path,
+    console: Console,
+    show_types: bool = False,
+    depth: Optional[int] = None,
+    entry_path: Optional[str] = None,
+    out_console: Optional[Console] = None,
+) -> None:
+    """
+    Show high-level information about the .h5ad file.
+    Args:
+        file (Path): Path to the .h5ad file
+        console (Console): Rich console for output
+        show_types (bool): Show detailed type information for each entry
+        depth (Optional[int]): Maximum recursion depth for type display (only with show_types=True)
+        entry_path (Optional[str]): Specific entry path to inspect (e.g., 'obsm/X_pca')
+        out_console (Optional[Console]): Where results go. Defaults to stdout so
+            that output pipes cleanly; `console` keeps status and errors.
+    """
+    out = out_console if out_console is not None else Console()
+    with open_store(file, "r") as store:
+        f = store.root
+        # If a specific path is requested, show detailed info for that object
+        if entry_path:
+            _show_object_info(f, entry_path, out)
+            return
+
+        # Get n_obs and n_var
+        n_obs = axis_len(f, "obs")
+        n_var = axis_len(f, "var")
+        out.print(
+            "[bold cyan]An object with n_obs × n_var: "
+            f"{n_obs if n_obs is not None else '?'} × "
+            f"{n_var if n_var is not None else '?'}[/]"
+        )
+
+        if show_types:
+            _show_types_tree(f, out, root_label=str(file), depth=depth)
+        else:
+            # List top-level keys and their sub-keys (original behavior)
+            for key in _sort_keys(list(f.keys())):
+                obj = f[key]
+                # Only process Groups, skip Datasets like X
+                if is_group(obj):
+                    sub_keys = [
+                        k
+                        for k in obj.keys()
+                        if k not in ("_index", "__categories", "obs_names", "var_names")
+                    ]
+                    if sub_keys and key != "X":
+                        out.print(
+                            f"\t[bold yellow]{key}:[/]\t"
+                            + ", ".join(f"[bright_white]{sub}[/]" for sub in sub_keys)
+                        )
+
+
+def _show_types_tree(
+    f: Any, console: Console, root_label: str, depth: Optional[int] = None
+) -> None:
+    """Show a tree view with type information for all entries.
+
+    Recursion depth by group:
+        - obs/var: top level only (no children)
+        - X: top level only
+        - obsm/obsp/varm/varp/layers: 1 level (show matrices)
+        - uns: 2 levels deep
+    """
+    tree = Tree(f"[bold]{root_label}[/]")
+
+    # Define max depth for each top-level group
+    max_depth_map = {
+        "obs": 0,
+        "var": 0,
+        "X": 0,
+        "obsm": 1,
+        "obsp": 1,
+        "varm": 1,
+        "varp": 1,
+        "layers": 1,
+        "uns": 2,
+    }
+
+    def add_node(
+        parent_tree: Tree,
+        name: str,
+        obj: Any,
+        current_depth: int,
+        max_depth: int,
+    ) -> None:
+        info = get_entry_type(obj)
+        type_str = format_type_info(info)
+
+        if is_dataset(obj):
+            shape_str = f"[dim]{obj.shape}[/]" if obj.shape else ""
+            node_text = f"[bright_white]{name}[/] {shape_str} {type_str}"
+            parent_tree.add(node_text)
+        else:
+            # Group
+            node_text = f"[bold yellow]{name}/[/] {type_str}"
+            subtree = parent_tree.add(node_text)
+
+            # Recurse only if within allowed depth
+            if current_depth < max_depth:
+                for child_name in sorted(obj.keys()):
+                    if child_name in ("_index", "__categories"):
+                        continue
+                    child_obj = obj[child_name]
+                    add_node(
+                        subtree, child_name, child_obj, current_depth + 1, max_depth
+                    )
+
+    # Add top-level items in preferred order
+    for key in _sort_keys(list(f.keys())):
+        obj = f[key]
+        # Skip empty groups
+        if is_group(obj):
+            children = [
+                k
+                for k in obj.keys()
+                if k not in ("_index", "__categories", "obs_names", "var_names")
+            ]
+            if not children:
+                continue
+        max_depth = (
+            depth if depth is not None else max_depth_map.get(key, 1)
+        )  # default to 1 level for unknown groups
+        add_node(tree, key, obj, current_depth=0, max_depth=max_depth)
+
+    console.print(tree)
+
+
+def _show_object_info(f: Any, entry_path: str, console: Console) -> None:
+    """Show detailed info for a specific object path."""
+    # Normalize path
+    entry_path = entry_path.strip().lstrip("/")
+
+    if entry_path not in f:
+        console.print(f"[bold red]Error:[/] '{entry_path}' not found in the file.")
+        return
+
+    entry = f[entry_path]
+    info = get_entry_type(entry)
+
+    console.print(f"\n[bold cyan]Path:[/] {entry_path}")
+    console.print(f"[bold cyan]Type:[/] {info['type']}")
+
+    if info["encoding"]:
+        console.print(f"[bold cyan]Encoding:[/] {info['encoding']}")
+
+    if info["shape"]:
+        console.print(f"[bold cyan]Shape:[/] {info['shape']}")
+
+    if info["dtype"]:
+        console.print(f"[bold cyan]Dtype:[/] {info['dtype']}")
+
+    console.print(f"[bold cyan]Details:[/] {info['details']}")
+
+    # Show attributes if any
+    if entry.attrs:
+        console.print(f"\n[bold cyan]Attributes:[/]")
+        for k, v in entry.attrs.items():
+            v_str = v.decode("utf-8") if isinstance(v, bytes) else str(v)
+            if len(v_str) > 80:
+                v_str = v_str[:77] + "..."
+            console.print(f"  [dim]{k}:[/] {v_str}")
+
+    # If it's a group, show children
+    if is_group(entry):
+        children = [
+            k
+            for k in entry.keys()
+            if k not in ("_index", "__categories", "obs_names", "var_names")
+        ]
+        if children:
+            console.print(f"\n[bold cyan]Children:[/]")
+            for child_name in sorted(children):
+                child_entry = entry[child_name]
+                child_info = get_entry_type(child_entry)
+                type_str = format_type_info(child_info)
+                console.print(f"  [bright_white]{child_name}[/] {type_str}")

adata/commands/ls.py

@@ -0,0 +1,114 @@
+"""`ls` -- list the contents of any HDF5 or Zarr store.
+
+Unlike `view`, this makes no AnnData assumptions: there is no n_obs x n_var
+header and no requirement that `obs`/`var` exist, so it works on `.loom` files
+and arbitrary `.h5` stores as well as AnnData ones.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Iterator, Optional, Tuple
+
+from rich.console import Console
+from rich.tree import Tree
+
+from adata.core.info import format_type_info, get_entry_type
+from adata.storage import is_dataset, is_group, open_store
+from adata.util.path import norm_path
+
+
+def walk(obj: Any, prefix: str = "", depth: Optional[int] = None) -> Iterator[Tuple[str, Any]]:
+    """Yield ``(path, element)`` for every member below `obj`, depth-first."""
+    if not is_group(obj):
+        return
+    for key in sorted(obj.keys()):
+        child = obj[key]
+        path = f"{prefix}/{key}" if prefix else key
+        yield path, child
+        if is_group(child) and (depth is None or depth > 1):
+            next_depth = None if depth is None else depth - 1
+            yield from walk(child, path, next_depth)
+
+
+def _describe(obj: Any, long: bool) -> str:
+    """Render the trailing annotation for one entry."""
+    if not long:
+        return ""
+    info = get_entry_type(obj)
+    bits = [format_type_info(info)]
+    shape = getattr(obj, "shape", None)
+    if shape:
+        bits.append(f"[dim]{tuple(shape)}[/]")
+    if is_dataset(obj) and getattr(obj, "dtype", None) is not None:
+        bits.append(f"[dim]{obj.dtype}[/]")
+    if info["encoding"]:
+        bits.append(f"[dim]{info['encoding']}[/]")
+    return " " + " ".join(bits)
+
+
+def list_store(
+    file: Path,
+    console: Console,
+    entry_path: Optional[str] = None,
+    depth: Optional[int] = None,
+    long: bool = False,
+    plain: bool = False,
+) -> None:
+    """Print the structure of a store, as a tree or as bare paths.
+
+    `plain` emits one path per line with no markup, so the output pipes
+    cleanly into grep or xargs.
+    """
+    with open_store(file, "r", require_anndata=False) as store:
+        root = store.root
+        if entry_path:
+            entry_path = norm_path(entry_path)
+            if entry_path not in root:
+                raise KeyError(f"'{entry_path}' not found in the store.")
+            root = root[entry_path]
+
+        if plain:
+            _print_plain(root, entry_path or "", depth)
+            return
+
+        _print_tree(root, console, str(file), entry_path, depth, long)
+
+
+def _print_plain(root: Any, prefix: str, depth: Optional[int]) -> None:
+    if is_dataset(root):
+        sys.stdout.write(f"{prefix}\n")
+        return
+    for path, _ in walk(root, prefix, depth):
+        sys.stdout.write(f"{path}\n")
+
+
+def _print_tree(
+    root: Any,
+    console: Console,
+    label: str,
+    entry_path: Optional[str],
+    depth: Optional[int],
+    long: bool,
+) -> None:
+    root_label = f"{label}:{entry_path}" if entry_path else label
+    tree = Tree(f"[bold]{root_label}[/]")
+
+    if is_dataset(root):
+        tree.add(f"[bright_white]{entry_path or label}[/]{_describe(root, long)}")
+        console.print(tree)
+        return
+
+    nodes = {"": tree}
+    for path, obj in walk(root, "", depth):
+        parent_path, _, name = path.rpartition("/")
+        parent = nodes.get(parent_path, tree)
+        if is_group(obj):
+            nodes[path] = parent.add(
+                f"[bold yellow]{name}/[/]{_describe(obj, long)}"
+            )
+        else:
+            parent.add(f"[bright_white]{name}[/]{_describe(obj, long)}")
+
+    console.print(tree)