xenium-splitter 0.2.1__py3-none-any.whl

xenium_splitter/__init__.py

@@ -0,0 +1,6 @@
+"""xenium-splitter package."""
+
+from importlib.metadata import version
+
+__all__ = ["__version__"]
+__version__ = version("xenium-splitter")

xenium_splitter/cli.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+import shutil
+import tempfile
+
+import typer
+
+from xenium_splitter.estimator import estimate_ram
+from xenium_splitter.models import SplitConfig
+from xenium_splitter.show_regions import create_regions_preview
+from xenium_splitter.splitter import run_split
+
+app = typer.Typer(help="Split Xenium outputs by LASSO regions.")
+
+
+def _configure_app_logging(verbose: bool) -> None:
+    """Configure logging for xenium_splitter only.
+
+    Avoid configuring the root logger so dependency loggers like zarr do not
+    emit through this CLI unless the caller configures them separately.
+    """
+    package_logger = logging.getLogger("xenium_splitter")
+    package_logger.handlers.clear()
+    package_logger.setLevel(logging.DEBUG if verbose else logging.WARNING)
+    package_logger.propagate = False
+
+    handler = logging.StreamHandler()
+    handler.setLevel(logging.DEBUG if verbose else logging.WARNING)
+    handler.setFormatter(logging.Formatter("%(name)s - %(levelname)s - %(message)s"))
+    package_logger.addHandler(handler)
+
+
+@app.command("clean-temp")
+def clean_temp_command() -> None:
+    """Delete xenium-splitter temporary working files."""
+    temp_root = Path(tempfile.gettempdir()) / "xenium_splitter"
+    if not temp_root.exists():
+        typer.echo(f"No temp directory found at: {temp_root}")
+        return
+
+    shutil.rmtree(temp_root)
+    typer.echo(f"Deleted temp directory: {temp_root}")
+
+
+@app.command("show-regions")
+def show_regions_command(
+    input_dir: Path = typer.Option(..., exists=True, file_okay=False, dir_okay=True),
+    lasso_file: Path = typer.Option(..., exists=True, file_okay=True, dir_okay=False),
+    output_image: Path = typer.Option(..., file_okay=True, dir_okay=False),
+    he_image: Path | None = typer.Option(None, exists=True, file_okay=True, dir_okay=False),
+    max_dimension_px: int = typer.Option(
+        2000,
+        min=1,
+        max=2000,
+        help="Maximum width or height of the generated preview image.",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "-v",
+        "--verbose",
+        help="Enable debug logging to see detailed processing info.",
+    ),
+) -> None:
+    """Create a low-resolution preview of LASSO regions over H&E or morphology.
+
+    H&E is preferred; morphology is used as a fallback when no H&E-like image
+    can be found in the input directory.
+    """
+    _configure_app_logging(verbose)
+    result = create_regions_preview(
+        input_dir=input_dir,
+        lasso_file=lasso_file,
+        output_image=output_image,
+        he_image=he_image,
+        max_dimension_px=max_dimension_px,
+    )
+    typer.echo("show_regions complete.")
+    typer.echo(f"Source image type: {result['source_kind']}")
+    typer.echo(f"Source image: {result['source_path']}")
+    typer.echo(f"Regions drawn: {result['region_count']}")
+    typer.echo(f"Output image: {result['output_path']}")
+
+
+@app.command("estimate-ram")
+def estimate_ram_command(
+    input_dir: Path = typer.Option(..., exists=True, file_okay=False, dir_okay=True),
+    lasso_file: Path = typer.Option(..., exists=True, file_okay=True, dir_okay=False),
+    output_dir: Path = typer.Option(..., file_okay=False, dir_okay=True),
+    he_image: Path | None = typer.Option(None, exists=True, file_okay=True, dir_okay=False),
+    convert_svs_to_ome: bool = typer.Option(
+        False, help="If --he-image is .svs, also emit OME-TIFF outputs.",
+    ),
+    squash_layers: bool = typer.Option(
+        True, "--squash-layers/--no-squash-layers",
+        help="Flatten multi-layer image stacks when possible.",
+    ),
+    include_glob: list[str] = typer.Option(
+        None, help="Optional glob patterns (repeatable) to limit files from input-dir.",
+    ),
+    skip_images: bool = typer.Option(
+        False, "--skip-images/--process-images", help="Skip image extraction.",
+    ),
+    overlays: bool = typer.Option(
+        False, "--overlays/--no-overlays", help="Write morphology grid overlays.",
+    ),
+    recalculate_diffexp: bool = typer.Option(
+        True, "--recalculate-diffexp/--skip-diffexp-recalc",
+        help="Recompute analysis/diffexp outputs.",
+    ),
+    write_cell_feature_matrix_zarr: bool = typer.Option(
+        True, "--write-cell-feature-matrix-zarr/--skip-cell-feature-matrix-zarr",
+        help="Write cell_feature_matrix.zarr.zip outputs.",
+    ),
+    copy_transcripts: bool = typer.Option(
+        False, "--copy-transcripts", help="Copy transcript files without filtering or rebasing.",
+    ),
+    images_only: bool = typer.Option(
+        False, "--images-only", help="Process only images; conflicts with --skip-images.",
+    ),
+    verbose: bool = typer.Option(
+        False, "-v", "--verbose", help="Enable debug logging.",
+    ),
+) -> None:
+    """Estimate peak RAM without splitting files or creating output directories."""
+    _configure_app_logging(verbose)
+    if images_only and skip_images:
+        raise typer.BadParameter(
+            "--images-only and --skip-images are mutually exclusive: "
+            "--images-only processes only images while --skip-images skips all images."
+        )
+    try:
+        peak_ram_gb = estimate_ram(input_dir)
+    except (FileNotFoundError, OSError) as exc:
+        raise typer.BadParameter(str(exc), param_hint="--input-dir") from exc
+
+    typer.echo(f"Estimated peak RAM: {peak_ram_gb:.2f} GB")
+    typer.echo("Archive sizes use decimal MB (1 MB = 1,000,000 bytes).")
+    typer.echo("Only archive sizes affect this equation; split options are not modeled.")
+    typer.echo("No files were written.")
+    typer.echo("This is a rough peak estimate, not a guaranteed RAM limit.")
+
+
+@app.command("split")
+def split_command(
+    input_dir: Path = typer.Option(..., exists=True, file_okay=False, dir_okay=True),
+    lasso_file: Path = typer.Option(..., exists=True, file_okay=True, dir_okay=False),
+    output_dir: Path = typer.Option(..., file_okay=False, dir_okay=True),
+    he_image: Path | None = typer.Option(None, exists=True, file_okay=True, dir_okay=False),
+    convert_svs_to_ome: bool = typer.Option(
+        False,
+        help="If --he-image is .svs, also emit OME-TIFF outputs.",
+    ),
+    squash_layers: bool = typer.Option(
+        True,
+        "--squash-layers/--no-squash-layers",
+        help="Flatten multi-layer image stacks when possible.",
+    ),
+    include_glob: list[str] = typer.Option(
+        None,
+        help="Optional glob patterns (repeatable) to limit files from input-dir.",
+    ),
+    skip_images: bool = typer.Option(
+        False,
+        "--skip-images/--process-images",
+        help="Skip image extraction to reduce memory usage.",
+    ),
+    overlays: bool = typer.Option(
+        False,
+        "--overlays/--no-overlays",
+        help="Write region grid overlay images when a morphology_mip.ome.tif output is available.",
+    ),
+    recalculate_diffexp: bool = typer.Option(
+        True,
+        "--recalculate-diffexp/--skip-diffexp-recalc",
+        help="Recompute analysis/diffexp files from region-filtered matrix and clustering outputs.",
+    ),
+    write_cell_feature_matrix_zarr: bool = typer.Option(
+        True,
+        "--write-cell-feature-matrix-zarr/--skip-cell-feature-matrix-zarr",
+        help="Write cell_feature_matrix.zarr.zip outputs (disable to benchmark runtime impact).",
+    ),
+    copy_transcripts: bool = typer.Option(
+        False,
+        "--copy-transcripts",
+        help="Copy transcript files verbatim to each region output with no filtering or rebasing.",
+    ),
+    images_only: bool = typer.Option(
+        False,
+        "--images-only",
+        help=(
+            "Process only image files (morphology, H&E); skip all tabular data, zarr, CFM, and "
+            "diffexp stages. Useful for image-only re-runs after a data-only pass, or when RAM "
+            "must be reserved entirely for image processing. Mutually exclusive with --skip-images."
+        ),
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "-v",
+        "--verbose",
+        help="Enable debug logging to see detailed processing info.",
+    ),
+) -> None:
+    """Split Xenium files and optional H&E image into per-region outputs."""
+    _configure_app_logging(verbose)
+    if images_only and skip_images:
+        raise typer.BadParameter(
+            "--images-only and --skip-images are mutually exclusive: "
+            "--images-only processes only images while --skip-images skips all images."
+        )
+    config = SplitConfig(
+        input_dir=input_dir,
+        lasso_file=lasso_file,
+        output_dir=output_dir,
+        he_image=he_image,
+        convert_svs_to_ome=convert_svs_to_ome,
+        squash_layers=squash_layers,
+        include_globs=include_glob or [],
+        skip_images=skip_images,
+        overlays=overlays,
+        recalculate_diffexp=recalculate_diffexp,
+        write_cell_feature_matrix_zarr=write_cell_feature_matrix_zarr,
+        copy_transcripts=copy_transcripts,
+        images_only=images_only,
+    )
+    metrics, metadata_path = run_split(config)
+    typer.echo("Split complete.")
+    typer.echo(f"Regions: {metrics.region_count}")
+    typer.echo(f"Files processed: {metrics.files_processed}")
+    typer.echo(f"Files skipped: {metrics.files_skipped}")
+    typer.echo(f"Files failed: {metrics.files_failed}")
+    typer.echo(f"Metadata: {metadata_path}")
+
+
+if __name__ == "__main__":
+    app()

xenium_splitter/estimator.py

@@ -0,0 +1,20 @@
+"""Estimate peak RAM from the encoded Xenium Zarr archive sizes."""
+from pathlib import Path
+
+
+def estimate_ram(input_dir: Path) -> float:
+    """Return estimated peak RAM in GB using archive sizes in decimal MB.
+
+    Peak RAM = 2.5 + 0.010 * transcript MB + 0.007 * cell MB.
+    Both archives must exist directly inside the Xenium output directory.
+    No archive contents are read or extracted.
+    """
+    transcript_path = input_dir / "transcripts.zarr.zip"
+    cell_path = input_dir / "cells.zarr.zip"
+    for archive_path in (transcript_path, cell_path):
+        if not archive_path.is_file():
+            raise FileNotFoundError(f"Required Zarr archive not found: {archive_path}")
+
+    transcript_mb = transcript_path.stat().st_size / 1_000_000
+    cell_mb = cell_path.stat().st_size / 1_000_000
+    return 2.5 + 0.010 * transcript_mb + 0.007 * cell_mb