feat(cli): add iohub compute-pyramid command

Wraps `Position.compute_pyramid` so users can build multiscale
pyramid levels in place from the command line, mirroring the
ergonomics of `iohub set-scale` (per-position glob, plate
expansion, mode="r+").

  iohub compute-pyramid -i input.zarr/*/*/* --levels 4
  iohub compute-pyramid -i input.zarr/*/*/* -l 3 -m median --dims y,x

Tests cover:
- happy path with explicit levels and method
- plate-glob expansion (passing the plate root)
- partial-axis downsampling via --dims y,x (Z preserved)
- --help and invalid --dims rejection

Author: edyoshikun

src/iohub/cli/cli.py

@@ -1,3 +1,4 @@
+import logging
 import pathlib
 
 import click
@@ -8,6 +9,8 @@
 from iohub.reader import print_info
 from iohub.rename_wells import rename_wells
 
+_logger = logging.getLogger(__name__)
+
 VERSION = __version__
 
 _DATASET_PATH = click.Path(exists=True, file_okay=False, resolve_path=True, path_type=pathlib.Path)
@@ -163,6 +166,65 @@ def set_scale(
                 dataset.set_scale(image, name, value)
 
 
+_PYRAMID_METHODS = ["mean", "median", "mode", "min", "max", "stride"]
+_PYRAMID_DIM_CHOICES = ["t", "z", "y", "x"]
+
+
+def _parse_dims(ctx, param, value):
+    if value is None:
+        return None
+    tokens = [t.strip().lower() for t in value.split(",") if t.strip()]
+    if not tokens:
+        return None
+    invalid = [t for t in tokens if t not in _PYRAMID_DIM_CHOICES]
+    if invalid:
+        raise click.BadParameter(f"Unknown dim(s) {invalid}. Valid choices: {_PYRAMID_DIM_CHOICES}.")
+    return set(tokens)
+
+
+@cli.command(name="compute-pyramid")
+@click.help_option("-h", "--help")
+@input_position_dirpaths()
+@click.option(
+    "--levels",
+    "-l",
+    required=True,
+    type=click.IntRange(min=2),
+    help="Total number of pyramid levels including level 0 (e.g. 4 = level 0 + 3 extra).",
+)
+@click.option(
+    "--method",
+    "-m",
+    required=False,
+    default="mean",
+    show_default=True,
+    type=click.Choice(_PYRAMID_METHODS),
+    help="Downsampling method.",
+)
+@click.option(
+    "--dims",
+    "-d",
+    required=False,
+    default=None,
+    callback=_parse_dims,
+    help=("Comma-separated axes to downsample (e.g. 'y,x' for YX-only). Defaults to 'z,y,x' inside iohub."),
+)
+def compute_pyramid(input_position_dirpaths, levels, method, dims):
+    """Compute multiscale pyramid levels in place for OME-Zarr positions.
+
+    The level-0 array is preserved; new downsampled levels are appended.
+
+    ```
+    iohub compute-pyramid -i input.zarr/*/*/* --levels 4
+    iohub compute-pyramid -i input.zarr/*/*/* -l 3 -m median --dims y,x
+    ```
+    """
+    for input_position_dirpath in input_position_dirpaths:
+        _logger.info(f"Computing pyramid for {input_position_dirpath}")
+        with open_ome_zarr(input_position_dirpath, layout="fov", mode="r+") as dataset:
+            dataset.compute_pyramid(levels=levels, method=method, dims=dims)
+
+
 @cli.command(name="rename-wells")
 @click.help_option("-h", "--help")
 @click.option(

tests/cli/test_cli.py

@@ -3,6 +3,7 @@
 from pathlib import Path
 from unittest.mock import patch
 
+import numpy as np
 import pytest
 from click.testing import CliRunner
 
@@ -217,3 +218,127 @@ def test_cli_rename_wells(csv_data_file_1):
 
         assert result.exit_code == 0
         assert "Renaming" in result.output
+
+
+def _make_pyramid_test_plate(store_path: Path) -> tuple[tuple[int, ...], list[str]]:
+    """Create a tiny plate with a single position and a level-0 array.
+
+    Returns the level-0 shape and the position key (row, col, fov).
+    """
+    shape = (1, 2, 8, 64, 64)
+    rng = np.random.default_rng(0)
+    data = rng.integers(0, 255, size=shape, dtype=np.uint16)
+    position_key = ("A", "1", "0")
+    with open_ome_zarr(
+        store_path,
+        layout="hcs",
+        mode="w",
+        channel_names=["ch1", "ch2"],
+    ) as plate:
+        position = plate.create_position(*position_key)
+        position.create_image("0", data)
+    return shape, list(position_key)
+
+
+def test_cli_compute_pyramid(tmp_path, caplog):
+    store_path = tmp_path / "compute_pyramid.zarr"
+    shape, position_key = _make_pyramid_test_plate(store_path)
+    position_path = store_path.joinpath(*position_key)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        [
+            "compute-pyramid",
+            "-i",
+            str(position_path),
+            "--levels",
+            "3",
+            "--method",
+            "mean",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    assert any("Computing pyramid" in record.message for record in caplog.records)
+
+    with open_ome_zarr(position_path, layout="fov", mode="r") as pos:
+        dataset_paths = pos.metadata.multiscales[0].get_dataset_paths()
+        assert dataset_paths == ["0", "1", "2"]
+        assert pos["0"].shape == shape
+        # Cascade YX/Z downsampling halves spatial axes per level.
+        assert pos["1"].shape[-2:] == (shape[-2] // 2, shape[-1] // 2)
+        assert pos["2"].shape[-2:] == (shape[-2] // 4, shape[-1] // 4)
+
+
+def test_cli_compute_pyramid_plate_glob(tmp_path):
+    store_path = tmp_path / "compute_pyramid_plate.zarr"
+    _, position_key = _make_pyramid_test_plate(store_path)
+    position_path = store_path.joinpath(*position_key)
+
+    runner = CliRunner()
+    # Pass the plate root: `_validate_and_process_paths` expands it into positions.
+    result = runner.invoke(
+        cli,
+        ["compute-pyramid", "-i", str(store_path), "-l", "2"],
+    )
+    assert result.exit_code == 0, result.output
+
+    with open_ome_zarr(position_path, layout="fov", mode="r") as pos:
+        dataset_paths = pos.metadata.multiscales[0].get_dataset_paths()
+        assert dataset_paths == ["0", "1"]
+
+
+def test_cli_compute_pyramid_dims(tmp_path):
+    store_path = tmp_path / "compute_pyramid_dims.zarr"
+    shape, position_key = _make_pyramid_test_plate(store_path)
+    position_path = store_path.joinpath(*position_key)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        [
+            "compute-pyramid",
+            "-i",
+            str(position_path),
+            "-l",
+            "2",
+            "--dims",
+            "y,x",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+
+    with open_ome_zarr(position_path, layout="fov", mode="r") as pos:
+        # Z is preserved; YX halved.
+        assert pos["1"].shape[-3] == shape[-3]
+        assert pos["1"].shape[-2:] == (shape[-2] // 2, shape[-1] // 2)
+
+
+def test_cli_compute_pyramid_help():
+    runner = CliRunner()
+    for option in ("-h", "--help"):
+        result = runner.invoke(cli, ["compute-pyramid", option])
+        assert result.exit_code == 0
+        assert "compute-pyramid" in result.output or "Compute multiscale" in result.output
+
+
+def test_cli_compute_pyramid_invalid_dims(tmp_path):
+    store_path = tmp_path / "compute_pyramid_bad_dims.zarr"
+    _, position_key = _make_pyramid_test_plate(store_path)
+    position_path = store_path.joinpath(*position_key)
+
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        [
+            "compute-pyramid",
+            "-i",
+            str(position_path),
+            "-l",
+            "2",
+            "--dims",
+            "y,bogus",
+        ],
+    )
+    assert result.exit_code != 0
+    assert "bogus" in result.output