orbit-gui 0.1.0__tar.gz

orbit_gui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NeuralCoDy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orbit_gui-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include src/orbit/_native/orbit_native.cpp

orbit_gui-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: orbit-gui
+Version: 0.1.0
+Summary: Assessment-forward analysis pipeline and GUI for functional neural optical imaging
+Author: Adam Charles
+License: MIT
+Project-URL: Homepage, https://github.com/NeuralCoDy/orbit-gui
+Project-URL: Repository, https://github.com/NeuralCoDy/orbit-gui
+Project-URL: Issues, https://github.com/NeuralCoDy/orbit-gui/issues
+Keywords: calcium-imaging,neuroscience,microscopy,source-extraction,roi,image-processing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-image>=0.21
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: opencv-python-headless>=4.8
+Requires-Dist: PyWavelets>=1.4
+Requires-Dist: threadpoolctl>=3.1
+Requires-Dist: pygraft-gui>=0.3.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: gui
+Requires-Dist: PySide6>=6.5; extra == "gui"
+Requires-Dist: pyqtgraph>=0.13; extra == "gui"
+Requires-Dist: tifffile>=2023.7; extra == "gui"
+Requires-Dist: h5py>=3.9; extra == "gui"
+Requires-Dist: roiapp>=0.1.0; extra == "gui"
+Requires-Dist: matplotlib>=3.7; extra == "gui"
+Requires-Dist: astropy>=5.3; extra == "gui"
+Requires-Dist: psutil>=5.9; extra == "gui"
+Dynamic: license-file
+
+# orbit-gui
+
+An assessment-forward GUI for the analysis of functional neural optical imaging data:
+validation metrics are computed and surfaced at every pipeline stage (motion correction,
+source identification, demixing, ...), not bolted on at the end.
+
+## Layout
+
+- `src/orbit/` -- pure-Python algorithm and validation-metric core, no Qt. Every stage
+  and every metric is a standalone function (e.g. `orbit.projections.mean_projection`),
+  independently unit-tested, and called by the GUI rather than implemented inside it.
+- `src/orbitapp/` -- the PySide6 GUI shell. One tab per pipeline stage; tabs only call
+  `orbit` functions and display results. Mirrors the architecture of the sibling
+  [pyGraFT](https://github.com/adamshch/GraFT-analysis) project (`AppState` +
+  per-stage tabs), and reuses the `MovieSliderWidget` bundled with the
+  [roiapp](https://pypi.org/project/roiapp/) distribution for movie playback.
+
+## Install
+
+```bash
+pip install orbit-gui[gui]
+```
+
+or, for a development checkout:
+
+```bash
+pip install -e ".[test,gui]"
+```
+
+`orbit`'s native (C++) accelerator for the slower per-pixel/per-trace operations
+(local correlation and mode projections, OASIS deconvolution, the per-pixel
+Ljung-Box test) builds automatically whenever a C++ compiler is available (via
+`setup.py`'s `ext_modules` -- see PyPI's published wheels, which ship it
+prebuilt) -- falls back to pure numpy/Python if no compiler is found, so this
+never blocks `pip install`. To rebuild it in place after editing the `.cpp`
+source, without reinstalling:
+
+```bash
+src/orbit/_native/build_native.sh
+```
+
+Real-SEUDO's own per-cell FISTA solve has a separate optional accelerator (also
+falls back to pure Python if skipped) -- needs FFTW3 in addition to a C++14
+compiler and pybind11 (Debian/Ubuntu: `apt-get install libfftw3-dev`). It builds
+automatically alongside the accelerator above wherever FFTW3 is found (including
+in PyPI's published wheels, on the platforms where FFTW3 could be provisioned in
+CI). To rebuild it in place after editing the `.cpp` source, without reinstalling:
+
+```bash
+src/orbit/seudo/_native/build_native.sh
+```
+
+## Run
+
+```bash
+python3 -m orbitapp
+```
+
+## Develop
+
+```bash
+pytest
+```
+
+## Status
+
+- **Load**: a movie (TIFF/folder-of-TIFFs/NPY/H5/MAT), previewed via an embedded,
+  scrubbable movie player.
+- **Data Projections**: mean/median/mode/variance/Fano-factor/local-correlation
+  projections, computed lazily and cached.
+- **Motion Correction**: rigid, piecewise-rigid, or PatchWarp-style piecewise-affine
+  registration, with quality metrics (mMD/mCM/ECC, singular-value-spectrum tightening,
+  spatial PC maps) shown alongside the before/after images. Runs in the background;
+  results are explicit candidates previewed in the tab until committed to the active
+  dataset, which is then recorded in the header's pipeline breadcrumb.
+
+Later phases add source identification and demixing/contamination assessment -- see
+project memory for the full roadmap.
+

orbit_gui-0.1.0/README.md

@@ -0,0 +1,79 @@
+# orbit-gui
+
+An assessment-forward GUI for the analysis of functional neural optical imaging data:
+validation metrics are computed and surfaced at every pipeline stage (motion correction,
+source identification, demixing, ...), not bolted on at the end.
+
+## Layout
+
+- `src/orbit/` -- pure-Python algorithm and validation-metric core, no Qt. Every stage
+  and every metric is a standalone function (e.g. `orbit.projections.mean_projection`),
+  independently unit-tested, and called by the GUI rather than implemented inside it.
+- `src/orbitapp/` -- the PySide6 GUI shell. One tab per pipeline stage; tabs only call
+  `orbit` functions and display results. Mirrors the architecture of the sibling
+  [pyGraFT](https://github.com/adamshch/GraFT-analysis) project (`AppState` +
+  per-stage tabs), and reuses the `MovieSliderWidget` bundled with the
+  [roiapp](https://pypi.org/project/roiapp/) distribution for movie playback.
+
+## Install
+
+```bash
+pip install orbit-gui[gui]
+```
+
+or, for a development checkout:
+
+```bash
+pip install -e ".[test,gui]"
+```
+
+`orbit`'s native (C++) accelerator for the slower per-pixel/per-trace operations
+(local correlation and mode projections, OASIS deconvolution, the per-pixel
+Ljung-Box test) builds automatically whenever a C++ compiler is available (via
+`setup.py`'s `ext_modules` -- see PyPI's published wheels, which ship it
+prebuilt) -- falls back to pure numpy/Python if no compiler is found, so this
+never blocks `pip install`. To rebuild it in place after editing the `.cpp`
+source, without reinstalling:
+
+```bash
+src/orbit/_native/build_native.sh
+```
+
+Real-SEUDO's own per-cell FISTA solve has a separate optional accelerator (also
+falls back to pure Python if skipped) -- needs FFTW3 in addition to a C++14
+compiler and pybind11 (Debian/Ubuntu: `apt-get install libfftw3-dev`). It builds
+automatically alongside the accelerator above wherever FFTW3 is found (including
+in PyPI's published wheels, on the platforms where FFTW3 could be provisioned in
+CI). To rebuild it in place after editing the `.cpp` source, without reinstalling:
+
+```bash
+src/orbit/seudo/_native/build_native.sh
+```
+
+## Run
+
+```bash
+python3 -m orbitapp
+```
+
+## Develop
+
+```bash
+pytest
+```
+
+## Status
+
+- **Load**: a movie (TIFF/folder-of-TIFFs/NPY/H5/MAT), previewed via an embedded,
+  scrubbable movie player.
+- **Data Projections**: mean/median/mode/variance/Fano-factor/local-correlation
+  projections, computed lazily and cached.
+- **Motion Correction**: rigid, piecewise-rigid, or PatchWarp-style piecewise-affine
+  registration, with quality metrics (mMD/mCM/ECC, singular-value-spectrum tightening,
+  spatial PC maps) shown alongside the before/after images. Runs in the background;
+  results are explicit candidates previewed in the tab until committed to the active
+  dataset, which is then recorded in the header's pipeline breadcrumb.
+
+Later phases add source identification and demixing/contamination assessment -- see
+project memory for the full roadmap.
+

orbit_gui-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["setuptools>=68", "wheel", "pybind11>=2.11"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# PyPI project/distribution name -- distinct from the importable package
+# name, which stays "orbit" (== `import orbit`), same split as this
+# project's own pygraft-gui dependency (PyPI name) / graft (import name).
+# "orbit" itself is already taken on PyPI by an unrelated package.
+name = "orbit-gui"
+version = "0.1.0"
+description = "Assessment-forward analysis pipeline and GUI for functional neural optical imaging"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Adam Charles" }]
+keywords = [
+    "calcium-imaging",
+    "neuroscience",
+    "microscopy",
+    "source-extraction",
+    "roi",
+    "image-processing",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Image Processing",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "scikit-image>=0.21",
+    "scikit-learn>=1.3",
+    "opencv-python-headless>=4.8",
+    "PyWavelets>=1.4",
+    # scikit-learn's own dependency already, so effectively always present --
+    # listed explicitly since orbit._concurrency.limited_native_threads calls
+    # its API directly, not just benefiting from scikit-learn's internal use.
+    "threadpoolctl>=3.1",
+    # orbit.cnmf's spatial update and orbit.roi_extraction_graft both import
+    # graft (this package's algorithm module, not its GUI) unconditionally --
+    # a base dependency, not gui-only, even though most other GraFT-adjacent
+    # code here is GUI-facing.
+    "pygraft-gui>=0.3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/NeuralCoDy/orbit-gui"
+Repository = "https://github.com/NeuralCoDy/orbit-gui"
+Issues = "https://github.com/NeuralCoDy/orbit-gui/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7.0"]
+gui = [
+    "PySide6>=6.5",
+    "pyqtgraph>=0.13",
+    "tifffile>=2023.7",
+    "h5py>=3.9",
+    "roiapp>=0.1.0",
+    "matplotlib>=3.7",
+    "astropy>=5.3",
+    "psutil>=5.9",
+]
+
+[project.scripts]
+orbitapp = "orbitapp.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

orbit_gui-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

orbit_gui-0.1.0/setup.py

@@ -0,0 +1,115 @@
+"""Builds orbit's two optional C++ extensions. This is additive to
+pyproject.toml's [project] metadata -- setuptools reads both.
+
+Both extensions are marked optional: if a compiler (or, for the second
+one, FFTW3) isn't available, setuptools skips that extension and warns
+instead of aborting `pip install`. Everything that can use them falls
+back to an equivalent pure-Python/numpy implementation transparently
+either way -- see orbit._native's and orbit.seudo._native's own
+docstrings.
+"""
+
+import os
+import sys
+
+from setuptools import Extension, setup
+
+if sys.platform == "win32":
+    # MSVC's flag syntax differs from GCC/Clang's ("/" not "-", /std:c++14
+    # not -std=c++14) -- std::thread needs no extra link flag on Windows
+    # (unlike -pthread on Unix), the runtime provides it directly.
+    EXTRA_COMPILE_ARGS = ["/O2", "/std:c++14"]
+    EXTRA_LINK_ARGS: list[str] = []
+else:
+    EXTRA_COMPILE_ARGS = ["-O3", "-std=c++14", "-pthread"]
+    EXTRA_LINK_ARGS = ["-pthread"]
+
+
+def _native_extension() -> list[Extension]:
+    """orbit._native._orbit_native: local correlation, half-sample mode,
+    OASIS deconvolution, the Ljung-Box Q statistic -- pybind11 + the
+    standard library only (std::thread for parallelism), no system
+    dependency beyond a C++ compiler."""
+    try:
+        import pybind11
+    except ImportError:
+        return []
+
+    return [
+        Extension(
+            "orbit._native._orbit_native",
+            sources=["src/orbit/_native/orbit_native.cpp"],
+            include_dirs=[pybind11.get_include()],
+            language="c++",
+            extra_compile_args=EXTRA_COMPILE_ARGS,
+            extra_link_args=EXTRA_LINK_ARGS,
+            optional=True,
+        )
+    ]
+
+
+# (include_dir, lib_dir) pairs worth trying even with no env override --
+# covers the common package-manager default prefixes. Harmless if a pair
+# doesn't exist: an -I/-L flag pointing at a missing directory is a
+# silent no-op for gcc/clang/MSVC, so listing all of these unconditionally
+# is safe. This matters most on macOS: cibuildwheel cross-compiles an
+# x86_64 wheel from an arm64 (macos-14) runner, and Homebrew installs
+# each architecture's own FFTW3 to a DIFFERENT prefix (/opt/homebrew for
+# native arm64, /usr/local for an x86_64 build under Rosetta) -- a single
+# fixed path can't cover both, but trying both candidates and letting the
+# linker pick whichever actually has the right-architecture library does.
+_FFTW_CANDIDATE_DIRS = [
+    ("/opt/homebrew/include", "/opt/homebrew/lib"),  # Homebrew, Apple Silicon
+    ("/usr/local/include", "/usr/local/lib"),  # Homebrew (Intel/Rosetta) / common Linux local prefix
+    ("/usr/include", "/usr/lib/x86_64-linux-gnu"),  # Debian/Ubuntu system package
+    ("/usr/include", "/usr/lib64"),  # RHEL/AlmaLinux/manylinux system package
+]
+
+
+def _seudo_native_extension() -> list[Extension]:
+    """orbit.seudo._native._fista_native: Real-SEUDO's per-cell FISTA
+    solve, compiled -- needs FFTW3 in addition to a compiler, unlike the
+    extension above. Tries FFTW_INCLUDE_DIR/FFTW_LIB_DIR from the
+    environment first (same override src/orbit/seudo/_native/
+    build_native.sh already supports for a manual build -- set instead
+    by .github/workflows/wheels.yml on Windows, where there's no
+    standard install prefix to guess), then falls back to
+    _FFTW_CANDIDATE_DIRS' common package-manager prefixes."""
+    try:
+        import pybind11
+    except ImportError:
+        return []
+
+    include_dirs = [pybind11.get_include()]
+    library_dirs = []
+
+    fftw_include_dir = os.environ.get("FFTW_INCLUDE_DIR")
+    fftw_lib_dir = os.environ.get("FFTW_LIB_DIR")
+    if fftw_include_dir or fftw_lib_dir:
+        if fftw_include_dir:
+            include_dirs.append(fftw_include_dir)
+        if fftw_lib_dir:
+            library_dirs.append(fftw_lib_dir)
+    else:
+        for inc, lib in _FFTW_CANDIDATE_DIRS:
+            if os.path.isdir(inc):
+                include_dirs.append(inc)
+            if os.path.isdir(lib):
+                library_dirs.append(lib)
+
+    return [
+        Extension(
+            "orbit.seudo._native._fista_native",
+            sources=["src/orbit/seudo/_native/fista_native.cpp"],
+            include_dirs=include_dirs,
+            library_dirs=library_dirs,
+            libraries=["fftw3"],
+            language="c++",
+            extra_compile_args=EXTRA_COMPILE_ARGS,
+            extra_link_args=EXTRA_LINK_ARGS,
+            optional=True,
+        )
+    ]
+
+
+setup(ext_modules=_native_extension() + _seudo_native_extension())

orbit_gui-0.1.0/src/orbit/__init__.py

@@ -0,0 +1,86 @@
+"""orbit: pure-Python algorithm and validation-metric core for the
+assessment-forward functional optical imaging pipeline.
+
+No Qt/GUI dependencies live here (see orbitapp for the PySide6 shell) --
+every stage and every metric is a standalone, independently testable
+function, called by the GUI rather than implemented inside it.
+"""
+
+from .cnmf import CNMFResult, cnmf_source_extraction
+from .cnmf_e import cnmf_e_source_extraction
+from .denoising import (
+    denoise_gaussian,
+    denoise_median,
+    denoise_wavelet_space,
+    denoise_wavelet_time,
+    residual_energy_fraction,
+)
+from .motion_correction import motion_correct, patch_motion_correct, rigid_motion_correct
+from .motion_metrics import (
+    enhanced_correlation_coefficient,
+    mean_correlation_to_reference,
+    mean_max_intensity_difference,
+    spatiotemporal_svd,
+)
+from .neuropil import compute_neuropil_traces, neuropil_ring_mask
+from .normalization import describe_normalization, normalize_movie, pixel_value_histogram, robust_std, summary_stats
+from .patchwarp import patchwarp_motion_correct
+from .projections import (
+    fano_factor_projection,
+    fano_factor_projection_volumetric,
+    local_correlation_projection,
+    mean_projection,
+    mean_projection_volumetric,
+    median_projection,
+    median_projection_volumetric,
+    mode_projection,
+    mode_projection_volumetric,
+    variance_projection,
+    variance_projection_volumetric,
+)
+from .qc_traces import qc_trace_samples
+from .roi_extraction_corr import CorrMaskResult, find_seed_candidates, roi_from_seed
+from .roi_extraction_pca_ica import PCAICAResult, pca_ica_source_extraction
+
+__all__ = [
+    "mean_projection",
+    "median_projection",
+    "variance_projection",
+    "fano_factor_projection",
+    "local_correlation_projection",
+    "mode_projection",
+    "mean_projection_volumetric",
+    "median_projection_volumetric",
+    "variance_projection_volumetric",
+    "fano_factor_projection_volumetric",
+    "mode_projection_volumetric",
+    "rigid_motion_correct",
+    "patch_motion_correct",
+    "patchwarp_motion_correct",
+    "motion_correct",
+    "mean_max_intensity_difference",
+    "enhanced_correlation_coefficient",
+    "mean_correlation_to_reference",
+    "spatiotemporal_svd",
+    "denoise_wavelet_time",
+    "denoise_wavelet_space",
+    "denoise_gaussian",
+    "denoise_median",
+    "qc_trace_samples",
+    "residual_energy_fraction",
+    "normalize_movie",
+    "describe_normalization",
+    "pixel_value_histogram",
+    "robust_std",
+    "summary_stats",
+    "CorrMaskResult",
+    "roi_from_seed",
+    "find_seed_candidates",
+    "compute_neuropil_traces",
+    "neuropil_ring_mask",
+    "PCAICAResult",
+    "pca_ica_source_extraction",
+    "CNMFResult",
+    "cnmf_source_extraction",
+    "cnmf_e_source_extraction",
+]

orbit_gui-0.1.0/src/orbit/_blocks.py

@@ -0,0 +1,124 @@
+"""Tiny helper for streaming a large array through a reduction one slab
+at a time -- so a whole-movie float64 working copy is never held, only
+one block, while the reduction itself still accumulates at full width.
+
+Used by the assessment metrics that are pure reductions over an axis
+(``orbit.denoising.residual_energy_fraction`` over frames-as-rows,
+``orbit.motion_metrics.mean_correlation_to_reference`` over frames) and
+by the depth-projected residual the Denoising tab shows for a volumetric
+movie -- all cases where the input can be a multi-GB (T, L, W, D) volume
+but the result is a scalar or a single 2D-per-frame projection.
+
+``chunked_median``/``chunked_variance`` are the one place ``np.median``
+and ``.var()`` should be called on a potentially movie-sized array
+anywhere in orbit: both build a second, often-larger copy of their whole
+input internally (a partition copy; a promoted-dtype ``arr - mean``
+array). Every such caller routes through here so a memory-bound fix
+lands in one place."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+
+import numpy as np
+
+_DEFAULT_TARGET_BYTES = 64 * 1024 * 1024  # ~64 MiB float64 working slab per block
+_MEDIAN_SLAB_BYTES = 256 * 1024 * 1024  # working-slab budget for chunked_median/chunked_variance
+_BLOCK_PIXELS = 150  # default hard cap on a block's span of the chunked axis (on top of the byte budget)
+
+
+def iter_axis_slices(
+    shape: tuple[int, ...],
+    axis: int,
+    target_bytes: int = _DEFAULT_TARGET_BYTES,
+    itemsize: int = 8,
+    max_block: int | None = None,
+) -> Iterator[slice]:
+    """Yield ``slice`` objects that partition ``axis`` of an array of
+    ``shape`` into consecutive runs, each about ``target_bytes`` once
+    widened to ``itemsize`` bytes per element (default 8 -> float64).
+
+    ``max_block``, if given, further caps the step regardless of what
+    the byte budget alone would allow -- the byte budget still applies
+    underneath it, so a chunk is never larger than either limit allows.
+
+    Index the array as ``arr[s]`` for ``axis == 0`` or, in general,
+    ``arr[(slice(None),) * axis + (s,)]`` / ``arr[..., s]`` for the last
+    axis. A small array yields a single full-extent slice, so callers
+    don't need a separate "small input" path."""
+    axis_len = shape[axis]
+    other_elems = 1
+    for i, n in enumerate(shape):
+        if i != axis:
+            other_elems *= n
+    step = max(1, target_bytes // max(1, other_elems * itemsize))
+    if max_block is not None:
+        step = min(step, max_block)
+    for start in range(0, axis_len, step):
+        yield slice(start, min(start + step, axis_len))
+
+
+def _promoted_dtype(dtype: np.dtype) -> np.dtype:
+    """np.median's/.var()'s own output-dtype promotion rule: int or a
+    float narrower than float64 -> float64; float64 (or wider) stays."""
+    return dtype if np.issubdtype(dtype, np.floating) else np.dtype(np.float64)
+
+
+def _chunked_reduce(
+    arr: np.ndarray,
+    axis: int,
+    reduce_fn: Callable[[np.ndarray], np.ndarray],
+    keepdims: bool = False,
+    out_dtype: np.dtype | None = None,
+    max_block: int | None = _BLOCK_PIXELS,
+) -> np.ndarray:
+    """Shared block-at-a-time driver behind chunked_median/
+    chunked_variance: moves ``axis`` to the front, walks the first
+    remaining axis in blocks (bounded by ``_MEDIAN_SLAB_BYTES`` and
+    ``max_block`` together), and writes ``reduce_fn(block)`` (block's
+    reduction axis at 0) into the matching output slice. Only one block
+    is ever copied to ``out_dtype`` at a time -- ``arr`` is never
+    mutated or fully materialized at that dtype."""
+    moved = np.moveaxis(arr, axis, 0)  # reduction axis -> 0 (a view)
+    if out_dtype is None:
+        out_dtype = _promoted_dtype(moved.dtype)
+    out = np.empty(moved.shape[1:], dtype=out_dtype)
+    itemsize = np.dtype(out_dtype).itemsize
+    for sl in iter_axis_slices(moved.shape, 1, target_bytes=_MEDIAN_SLAB_BYTES, itemsize=itemsize, max_block=max_block):
+        block = np.array(moved[:, sl], dtype=out_dtype)  # own copy -- safe to overwrite
+        out[sl] = reduce_fn(block)
+    return np.expand_dims(out, axis) if keepdims else out
+
+
+def chunked_median(
+    arr: np.ndarray,
+    axis: int | None = None,
+    keepdims: bool = False,
+    out_dtype: np.dtype | None = None,
+    max_block: int | None = _BLOCK_PIXELS,
+) -> np.ndarray:
+    """``np.median(arr, axis=axis, keepdims=keepdims)`` computed one
+    block of the first non-reduction axis at a time -- see this module's
+    docstring. ``axis=None`` (a single global scalar, which genuinely
+    needs every value at once) falls straight through to ``np.median``,
+    so this is a drop-in wherever ``np.median`` was called.
+
+    ``out_dtype`` defaults to np.median's own promotion rule; pass one
+    (e.g. float32) for a caller that wants a narrower working dtype
+    regardless of the input's. Element-wise identical to ``np.median``
+    for any block partitioning -- each block's per-pixel median only
+    needs that pixel's own full time series."""
+    if axis is None:
+        return np.median(arr, keepdims=keepdims)
+    return _chunked_reduce(
+        arr, axis, lambda block: np.median(block, axis=0, overwrite_input=True), keepdims, out_dtype, max_block,
+    )
+
+
+def chunked_variance(arr: np.ndarray, axis: int, max_block: int | None = _BLOCK_PIXELS) -> np.ndarray:
+    """``arr.var(axis=axis)`` (ddof=0) computed one block at a time --
+    ndarray.var() builds a full promoted-dtype ``arr - mean`` array
+    before squaring/summing it, and each block instead only needs its
+    own. Element-wise identical to ``arr.var(axis=axis)``, for the same
+    per-pixel-independence reason as chunked_median."""
+    return _chunked_reduce(arr, axis, lambda block: block.var(axis=0), max_block=max_block)