arrayview 0.31.2__py3-none-any.whl → 0.32.0__py3-none-any.whl

arrayview/__init__.py

@@ -7,14 +7,12 @@ __all__ = [
     "arrayview",
     "view",
     "view_batch",
-    "view_dir",
-    "view_dir_patterns",
     "zarr_chunk_preset",
 ]
 
 
 def __getattr__(name: str):
-    if name in {"arrayview", "view", "view_dir", "view_dir_patterns", "ViewHandle"}:
+    if name in {"arrayview", "view", "ViewHandle"}:
         from arrayview import _launcher
 
         return getattr(_launcher, name)

arrayview/_io.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import fnmatch
+import gzip
 import glob
 import os
 import re
@@ -18,6 +19,19 @@ import numpy as np
 _nib_mod = None
 
 
+class MissingOverlayCasesError(ValueError):
+    """A required collection overlay has no file for some image cases."""
+
+    def __init__(self, overlay_name, missing_cases, total_cases):
+        self.overlay_name = str(overlay_name)
+        self.missing_cases = tuple(str(case) for case in missing_cases)
+        self.total_cases = int(total_cases)
+        missing = ", ".join(repr(case) for case in self.missing_cases)
+        super().__init__(
+            f"Overlay {self.overlay_name!r} is missing case(s): {missing}."
+        )
+
+
 def _nib():
     """Lazy nibabel import."""
     global _nib_mod
@@ -170,6 +184,194 @@ def _nifti_display_array(proxy):
     return np.asarray(proxy, dtype=display_dtype)
 
 
+class _ProgressiveLoadCancelled(Exception):
+    """Internal signal used when newer navigation supersedes a cold load."""
+
+
+def _read_exact(stream, size):
+    """Read exactly *size* bytes, or raise when a gzip stream ends early."""
+    chunks = []
+    remaining = size
+    while remaining:
+        chunk = stream.read(remaining)
+        if not chunk:
+            raise EOFError(f"NIfTI voxel data ended {remaining} bytes early.")
+        chunks.append(chunk)
+        remaining -= len(chunk)
+    return b"".join(chunks)
+
+
+def _progressive_nifti_spec(filepath):
+    """Describe a gzip volume that can be decoded one canonical Z plane at a time."""
+    if not filepath.endswith(".nii.gz"):
+        return None
+
+    nib = _nib()
+    img = nib.load(filepath)
+    proxy = img.dataobj
+    if len(img.shape) != 3 or getattr(proxy, "order", None) != "F":
+        return None
+
+    source_ornt = nib.orientations.io_orientation(img.affine)
+    canonical_ornt = nib.orientations.axcodes2ornt(("R", "A", "S"))
+    transform = nib.orientations.ornt_transform(source_ornt, canonical_ornt)
+    # A source Z plane must remain a canonical Z plane. X/Y may be swapped or
+    # flipped inside the plane without requiring any later voxel data.
+    if int(transform[2, 0]) != 2:
+        return None
+
+    raw_dtype = np.dtype(proxy.dtype)
+    if raw_dtype.kind not in "biufc" or raw_dtype.itemsize <= 0:
+        return None
+    display_dtype = (
+        np.dtype(np.float32)
+        if np.issubdtype(raw_dtype, np.floating) and raw_dtype.itemsize > 4
+        else raw_dtype
+    )
+    canonical_shape = tuple(int(img.shape[int(axis)]) for axis in transform[:, 0])
+    return {
+        "source_shape": tuple(int(size) for size in img.shape),
+        "canonical_shape": canonical_shape,
+        "transform": transform,
+        "raw_dtype": raw_dtype,
+        "display_dtype": display_dtype,
+        "offset": int(proxy.offset),
+        "slope": proxy.slope,
+        "inter": proxy.inter,
+    }
+
+
+class _ProgressiveNiftiJob:
+    """Decode one gzip stream once, releasing requested planes as they arrive."""
+
+    def __init__(self, filepath, spec, on_complete, on_finished):
+        self.filepath = filepath
+        self.spec = spec
+        self._on_complete = on_complete
+        self._on_finished = on_finished
+        self._condition = threading.Condition()
+        self._decoded = np.zeros(spec["canonical_shape"][2], dtype=bool)
+        # Allocate the large destination only once a worker actually starts.
+        # Superseded jobs can otherwise reserve hundreds of MiB while queued.
+        self._volume = None
+        self._done = False
+        self._cancelled = False
+        self._error = None
+        self.future = None
+
+    def cancel(self):
+        with self._condition:
+            self._cancelled = True
+            self._condition.notify_all()
+        if self.future is not None and self.future.cancel():
+            self._finish(cancelled=True)
+
+    def plane(self, z_index):
+        with self._condition:
+            while not self._decoded[z_index] and not self._done:
+                self._condition.wait()
+            if self._decoded[z_index]:
+                return self._volume[:, :, z_index]
+            if self._cancelled:
+                raise _ProgressiveLoadCancelled()
+            if self._error is not None:
+                raise self._error
+            raise RuntimeError("Progressive NIfTI loading stopped before the requested plane.")
+
+    def volume(self):
+        with self._condition:
+            while not self._done:
+                self._condition.wait()
+            if self._cancelled:
+                raise _ProgressiveLoadCancelled()
+            if self._error is not None:
+                raise self._error
+            return self._volume
+
+    def _finish(self, *, error=None, cancelled=False):
+        should_notify = False
+        with self._condition:
+            if self._done:
+                return
+            self._error = error
+            self._cancelled = self._cancelled or cancelled
+            self._done = True
+            self._condition.notify_all()
+            should_notify = True
+        if should_notify:
+            self._on_finished(self)
+
+    def run(self):
+        spec = self.spec
+        source_shape = spec["source_shape"]
+        plane_bytes = source_shape[0] * source_shape[1] * spec["raw_dtype"].itemsize
+        z_reversed = int(spec["transform"][2, 1]) < 0
+        try:
+            from nibabel.volumeutils import apply_read_scaling
+
+            self._volume = np.empty(
+                spec["canonical_shape"], dtype=spec["display_dtype"]
+            )
+            with gzip.open(self.filepath, "rb") as stream:
+                stream.seek(spec["offset"])
+                for source_z in range(source_shape[2]):
+                    raw = _read_exact(stream, plane_bytes)
+                    plane = np.ndarray(
+                        source_shape[:2],
+                        dtype=spec["raw_dtype"],
+                        buffer=raw,
+                        order="F",
+                    )
+                    plane = apply_read_scaling(plane, spec["slope"], spec["inter"])
+                    plane = np.asarray(plane, dtype=spec["display_dtype"])
+                    plane = _nib().orientations.apply_orientation(
+                        plane[:, :, None], spec["transform"]
+                    )[:, :, 0]
+                    canonical_z = source_shape[2] - 1 - source_z if z_reversed else source_z
+                    with self._condition:
+                        self._volume[:, :, canonical_z] = plane
+                        self._decoded[canonical_z] = True
+                        self._condition.notify_all()
+                        cancelled = self._cancelled
+                    if cancelled:
+                        self._finish(cancelled=True)
+                        return
+            with self._condition:
+                cancelled = self._cancelled
+            if cancelled:
+                self._finish(cancelled=True)
+                return
+            self._on_complete(self._volume)
+            self._finish()
+        except Exception as exc:
+            self._finish(error=exc)
+
+
+_PROGRESSIVE_NIFTI_POOL = None
+_PROGRESSIVE_NIFTI_OVERLAY_POOL = None
+_PROGRESSIVE_NIFTI_POOL_LOCK = threading.Lock()
+
+
+def _get_progressive_nifti_pool(*, overlay_prefetch=False):
+    """Return a bounded gzip pool without mixing base and overlay prefetch."""
+    global _PROGRESSIVE_NIFTI_POOL, _PROGRESSIVE_NIFTI_OVERLAY_POOL
+    with _PROGRESSIVE_NIFTI_POOL_LOCK:
+        if overlay_prefetch:
+            if (
+                _PROGRESSIVE_NIFTI_OVERLAY_POOL is None
+                or _PROGRESSIVE_NIFTI_OVERLAY_POOL._shutdown
+            ):
+                _PROGRESSIVE_NIFTI_OVERLAY_POOL = ThreadPoolExecutor(
+                    max_workers=2, thread_name_prefix="arrayview-nifti-overlay"
+                )
+            return _PROGRESSIVE_NIFTI_OVERLAY_POOL
+        if _PROGRESSIVE_NIFTI_POOL is None or _PROGRESSIVE_NIFTI_POOL._shutdown:
+            _PROGRESSIVE_NIFTI_POOL = ThreadPoolExecutor(
+                max_workers=2, thread_name_prefix="arrayview-nifti"
+            )
+        return _PROGRESSIVE_NIFTI_POOL
+
+
 def _load_nifti_with_meta(filepath):
     """Load a NIfTI file, canonical-reorient, return (array, meta).
 
@@ -198,7 +400,74 @@ def _load_nifti_with_meta(filepath):
 # ---------------------------------------------------------------------------
 
 
-class _NiftiSeries:
+class _ProgressiveNiftiSeriesMixin:
+    """Progressive gzip support shared by dense and ragged NIfTI stacks."""
+
+    def _init_progressive_loading(self):
+        self._progressive_jobs = {}
+        self._progressive_lock = threading.RLock()
+
+    def _cache_volume(self, cache_key, vol):
+        with self._cache_lock:
+            old = self._vol_cache.get(cache_key)
+            if old is not None:
+                self._vol_cache_bytes -= int(getattr(old, "nbytes", 0))
+            self._vol_cache[cache_key] = vol
+            self._vol_cache.move_to_end(cache_key)
+            self._vol_cache_bytes += int(getattr(vol, "nbytes", 0))
+            while self._vol_cache_bytes > self._vol_cache_max_bytes and len(self._vol_cache) > 1:
+                _key, evicted = self._vol_cache.popitem(last=False)
+                self._vol_cache_bytes -= int(getattr(evicted, "nbytes", 0))
+
+    def _get_progressive_plane(self, p_idx, m_idx, z_index):
+        cache_key = (p_idx, m_idx)
+        with self._cache_lock:
+            if cache_key in self._vol_cache:
+                self._vol_cache.move_to_end(cache_key)
+                return self._vol_cache[cache_key][:, :, z_index]
+
+        filepath = self._file_matrix[p_idx][m_idx]
+        if filepath is None:
+            return None
+        with self._progressive_lock:
+            job = self._progressive_jobs.get(cache_key)
+            if job is None:
+                spec = _progressive_nifti_spec(filepath)
+                if spec is None:
+                    return None
+                # Keep the visible patient and one neighbor requested by the
+                # existing collection prefetch. A third cold request cancels
+                # the oldest unfinished decode instead of growing a queue.
+                while len(self._progressive_jobs) >= 2:
+                    old_key, old_job = next(iter(self._progressive_jobs.items()))
+                    old_job.cancel()
+                    self._progressive_jobs.pop(old_key, None)
+
+                def _complete(volume):
+                    self._cache_volume(cache_key, volume)
+
+                def _finished(finished_job):
+                    with self._progressive_lock:
+                        if self._progressive_jobs.get(cache_key) is finished_job:
+                            self._progressive_jobs.pop(cache_key, None)
+
+                job = _ProgressiveNiftiJob(filepath, spec, _complete, _finished)
+                self._progressive_jobs[cache_key] = job
+                overlay_prefetch = threading.current_thread().name.startswith(
+                    "arrayview-overlay-prefetch"
+                )
+                job.future = _get_progressive_nifti_pool(
+                    overlay_prefetch=overlay_prefetch
+                ).submit(job.run)
+        try:
+            return job.plane(z_index)
+        except _ProgressiveLoadCancelled:
+            raise
+        except Exception:
+            return None
+
+
+class _NiftiSeries(_ProgressiveNiftiSeriesMixin):
     """Lazy 4D/5D view over a directory of same-shape NIfTI files.
 
     ``file_matrix`` is a P x M list-of-lists of filepaths (P patients,
@@ -232,6 +501,7 @@ class _NiftiSeries:
         )
         self._cache_lock = threading.Lock()
         self._load_locks = {}
+        self._init_progressive_loading()
 
     @property
     def dtype(self):
@@ -249,6 +519,13 @@ class _NiftiSeries:
                 if cache_key in self._vol_cache:
                     self._vol_cache.move_to_end(cache_key)
                     return self._vol_cache[cache_key]
+            with self._progressive_lock:
+                job = self._progressive_jobs.get(cache_key)
+            if job is not None:
+                try:
+                    return job.volume()
+                except Exception:
+                    pass
             filepath = self._file_matrix[p_idx][m_idx]
             if filepath is None:
                 return np.zeros(self._vol_shape, dtype=self._dtype)
@@ -259,13 +536,7 @@ class _NiftiSeries:
             # only the requested slice. Gzip files must be decompressed once and
             # are therefore materialized into the byte-bounded cache.
             vol = canon.dataobj if filepath.endswith(".nii") else _nifti_display_array(canon.dataobj)
-            with self._cache_lock:
-                self._vol_cache[cache_key] = vol
-                self._vol_cache.move_to_end(cache_key)
-                self._vol_cache_bytes += int(getattr(vol, "nbytes", 0))
-                while self._vol_cache_bytes > self._vol_cache_max_bytes and len(self._vol_cache) > 1:
-                    _key, evicted = self._vol_cache.popitem(last=False)
-                    self._vol_cache_bytes -= int(getattr(evicted, "nbytes", 0))
+            self._cache_volume(cache_key, vol)
             return vol
 
     def __getitem__(self, key):
@@ -291,6 +562,24 @@ class _NiftiSeries:
                     m_idx = int(stack_vals[1])
                     if m_idx < 0:
                         m_idx += n_m
+                if (
+                    len(self._vol_shape) == 3
+                    and all(
+                        isinstance(item, slice)
+                        and item.start is None
+                        and item.stop is None
+                        and item.step is None
+                        for item in spatial_key[:2]
+                    )
+                    and isinstance(spatial_key[2], (int, np.integer))
+                ):
+                    z_index = int(spatial_key[2])
+                    if z_index < 0:
+                        z_index += self._vol_shape[2]
+                    if 0 <= z_index < self._vol_shape[2]:
+                        plane = self._get_progressive_plane(p_idx, m_idx, z_index)
+                        if plane is not None:
+                            return plane
                 vol = self._get_volume(p_idx, m_idx)
                 return vol[spatial_key]
         return np.asarray(self)[key]
@@ -400,7 +689,7 @@ class _FileSeries:
         return result
 
 
-class _RaggedFileSeries:
+class _RaggedFileSeries(_ProgressiveNiftiSeriesMixin):
     """Lazy collection view over same-rank, same-dtype files with varying shapes.
 
     The public ``shape`` is a max-spatial-shape facade so existing viewer
@@ -445,6 +734,7 @@ class _RaggedFileSeries:
         )
         self._cache_lock = threading.Lock()
         self._load_locks = {}
+        self._init_progressive_loading()
 
     @property
     def dtype(self):
@@ -497,6 +787,13 @@ class _RaggedFileSeries:
                 if cache_key in self._vol_cache:
                     self._vol_cache.move_to_end(cache_key)
                     return self._vol_cache[cache_key]
+            with self._progressive_lock:
+                job = self._progressive_jobs.get(cache_key)
+            if job is not None:
+                try:
+                    return job.volume()
+                except Exception:
+                    pass
             filepath = self._file_matrix[p_idx][m_idx]
             if filepath is None:
                 return np.zeros(self._spatial_shapes[p_idx][m_idx], dtype=self._dtype)
@@ -507,13 +804,7 @@ class _RaggedFileSeries:
                 vol = proxy if filepath.endswith(".nii") else _nifti_display_array(proxy)
             else:
                 vol = load_data(filepath)
-            with self._cache_lock:
-                self._vol_cache[cache_key] = vol
-                self._vol_cache.move_to_end(cache_key)
-                self._vol_cache_bytes += int(getattr(vol, "nbytes", 0))
-                while self._vol_cache_bytes > self._vol_cache_max_bytes and len(self._vol_cache) > 1:
-                    _key, evicted = self._vol_cache.popitem(last=False)
-                    self._vol_cache_bytes -= int(getattr(evicted, "nbytes", 0))
+            self._cache_volume(cache_key, vol)
             return vol
 
     def __getitem__(self, key):
@@ -540,6 +831,23 @@ class _RaggedFileSeries:
                         spatial_key.append(idx)
                     else:
                         spatial_key.append(val)
+                if (
+                    self._all_nifti
+                    and len(spatial_shape) == 3
+                    and all(
+                        isinstance(item, slice)
+                        and item.start is None
+                        and item.stop is None
+                        and item.step is None
+                        for item in spatial_key[:2]
+                    )
+                    and isinstance(spatial_key[2], (int, np.integer))
+                ):
+                    z_index = int(spatial_key[2])
+                    if 0 <= z_index < spatial_shape[2]:
+                        plane = self._get_progressive_plane(p_idx, m_idx, z_index)
+                        if plane is not None:
+                            return plane
                 return self._get_volume(p_idx, m_idx)[tuple(spatial_key)]
         raise TypeError("Ragged collections require concrete collection indices.")
 
@@ -808,6 +1116,7 @@ def load_dir_collection(
     load="lazy",
     stack="auto",
     scan_progress=None,
+    exclude_cases=None,
 ):
     """Load recursive collection patterns as aligned lazy image/overlay stacks.
 
@@ -816,6 +1125,9 @@ def load_dir_collection(
     sparse overlay whose missing cases should render as empty masks. By
     default, each pattern's sorted matches are paired by position. With
     *case_regex*, files are paired by the regex's named ``case`` group instead.
+    *exclude_cases* removes known case ids before any image or overlay data is
+    opened. It is used by the interactive CLI after the user accepts a partial
+    overlay match.
     """
     if not base_patterns:
         raise ValueError("--stack requires at least one positional image pattern.")
@@ -865,6 +1177,19 @@ def load_dir_collection(
                     for path in base_lists[0]
                 ]
             base_matrix = [list(row) for row in zip(*base_lists)]
+
+    excluded = {str(case) for case in (exclude_cases or ())}
+    if excluded:
+        kept = [
+            (case, row)
+            for case, row in zip(case_ids, base_matrix)
+            if case not in excluded
+        ]
+        if not kept:
+            raise ValueError("No image cases remain after excluding missing overlays.")
+        case_ids = [case for case, _row in kept]
+        base_matrix = [row for _case, row in kept]
+
     data, spatial_meta = _series_from_file_matrix(
         base_matrix,
         load=load,
@@ -884,9 +1209,8 @@ def load_dir_collection(
             by_case = pattern
             missing_cases = [case for case in case_ids if case not in by_case]
             if missing_cases and not allow_missing:
-                raise ValueError(
-                    f"Overlay {name!r} is missing case(s): "
-                    f"{', '.join(repr(c) for c in missing_cases)}."
+                raise MissingOverlayCasesError(
+                    name, missing_cases, total_cases=len(case_ids)
                 )
             matrix = [[by_case.get(case)] for case in case_ids]
             extras = sorted(set(by_case.keys()) - set(case_ids))
@@ -894,9 +1218,8 @@ def load_dir_collection(
             by_case = _collection_pattern_map(pattern, case_regex=case_regex)
             missing_cases = [case for case in case_ids if case not in by_case]
             if missing_cases and not allow_missing:
-                raise ValueError(
-                    f"Overlay {name!r} is missing case(s): "
-                    f"{', '.join(repr(c) for c in missing_cases)}."
+                raise MissingOverlayCasesError(
+                    name, missing_cases, total_cases=len(case_ids)
                 )
             matrix = [[by_case.get(case)] for case in case_ids]
             extras = sorted(set(by_case.keys()) - set(case_ids))
@@ -912,9 +1235,8 @@ def load_dir_collection(
                 )
             missing_cases = [case for case in case_ids if case not in by_case]
             if missing_cases and not allow_missing:
-                raise ValueError(
-                    f"Overlay {name!r} is missing case(s): "
-                    f"{', '.join(repr(c) for c in missing_cases)}."
+                raise MissingOverlayCasesError(
+                    name, missing_cases, total_cases=len(case_ids)
                 )
             matrix = [[by_case.get(case)] for case in case_ids]
             extras = sorted(set(by_case) - set(case_ids))
@@ -968,13 +1290,12 @@ def load_dir_collection(
     return data, spatial_meta, overlay_items, summary
 
 
-def _load_file_series(path, select=None, *, load="lazy", stack="auto"):
+def _load_file_series(path, *, load="lazy", stack="auto"):
     """Build a lazy series from a directory of supported array files.
 
     Walks *path* recursively, groups files of any supported format by
-    immediate parent folder (= patient).  With *select* (a list of fnmatch
-    patterns), picks one file per pattern per patient → 5D ``(*vol, P, M)``.
-    Without *select*, requires exactly one file per patient → 4D ``(*vol, P)``.
+    immediate parent folder (= patient).  Requires exactly one file per
+    patient → 4D ``(*vol, P)``.
 
     If every file is NIfTI (.nii/.nii.gz), delegates to
     ``_load_nifti_series`` for canonical reorientation.  Otherwise builds
@@ -1008,60 +1329,32 @@ def _load_file_series(path, select=None, *, load="lazy", stack="auto"):
 
     # NIfTI-only → preserve canonical reorientation + lazy dataobj slicing
     if all_nifti:
-        return _load_nifti_series(path, select=select, load=load, stack=stack)
+        return _load_nifti_series(path, load=load, stack=stack)
 
     # ── build file matrix ──────────────────────────────────────────
-    select_patterns = select or []
     patient_dirs = sorted(patients.keys())
     file_matrix: list[list[str]] = []
 
-    if select_patterns:
-        for pdir in patient_dirs:
-            selected: list[str] = []
-            for pattern in select_patterns:
-                matches = [
-                    f
-                    for f in patients[pdir]
-                    if fnmatch.fnmatch(os.path.basename(f), pattern)
-                ]
-                if not matches:
-                    raise ValueError(
-                        f"Folder {pdir!r}: no file matches --select "
-                        f"pattern {pattern!r}. Available: "
-                        f"{[os.path.basename(f) for f in patients[pdir]]}"
-                    )
-                if len(matches) > 1:
-                    raise ValueError(
-                        f"Folder {pdir!r}: multiple files match "
-                        f"--select pattern {pattern!r}: "
-                        f"{[os.path.basename(f) for f in matches]}. "
-                        "Make patterns more specific."
-                    )
-                selected.append(matches[0])
-            file_matrix.append(selected)
-    else:
-        for pdir in patient_dirs:
-            files = patients[pdir]
-            if len(files) == 1:
-                file_matrix.append([files[0]])
-            else:
-                raise ValueError(
-                    f"Folder {pdir!r} contains {len(files)} files: "
-                    f"{[os.path.basename(f) for f in files]}. "
-                    "Use --select PATTERN to pick one (or more) per folder. "
-                    "Example: --select '*t1*' --select '*t2*' --select '*flair*'"
-                )
+    for pdir in patient_dirs:
+        files = patients[pdir]
+        if len(files) == 1:
+            file_matrix.append([files[0]])
+        else:
+            raise ValueError(
+                f"Folder {pdir!r} contains {len(files)} files: "
+                f"{[os.path.basename(f) for f in files]}. "
+                "Use --stack with explicit file patterns for multi-file folders."
+            )
 
     return _series_from_file_matrix(file_matrix, load=load, stack=stack)
 
 
-def _load_nifti_series(path, select=None, *, load="lazy", stack="auto"):
+def _load_nifti_series(path, *, load="lazy", stack="auto"):
     """Build a lazy ``_NiftiSeries`` from a directory of NIfTI files.
 
     Walks *path* recursively, groups ``.nii``/``.nii.gz`` by immediate parent
-    folder (= patient).  With *select* (a list of fnmatch patterns), picks one
-    file per pattern per patient → 5D ``(*vol, P, M)``.  Without *select*,
-    requires exactly one NIfTI per patient → 4D ``(*vol, P)``.
+    folder (= patient).  Requires exactly one NIfTI per patient → 4D
+    ``(*vol, P)``.
 
     Returns ``(series, spatial_meta)``.
     """
@@ -1087,51 +1380,24 @@ def _load_nifti_series(path, select=None, *, load="lazy", stack="auto"):
             "first (e.g. `dcm2niix -o <out> <dicom_dir>`)."
         )
 
-    select_patterns = select or []
     patient_dirs = sorted(patients.keys())
     file_matrix: list[list[str]] = []
 
-    if select_patterns:
-        for pdir in patient_dirs:
-            selected: list[str] = []
-            for pattern in select_patterns:
-                matches = [
-                    f
-                    for f in patients[pdir]
-                    if fnmatch.fnmatch(os.path.basename(f), pattern)
-                ]
-                if not matches:
-                    raise ValueError(
-                        f"Patient folder {pdir!r}: no file matches --select "
-                        f"pattern {pattern!r}. Available: "
-                        f"{[os.path.basename(f) for f in patients[pdir]]}"
-                    )
-                if len(matches) > 1:
-                    raise ValueError(
-                        f"Patient folder {pdir!r}: multiple files match "
-                        f"--select pattern {pattern!r}: "
-                        f"{[os.path.basename(f) for f in matches]}. "
-                        "Make patterns more specific."
-                    )
-                selected.append(matches[0])
-            file_matrix.append(selected)
-    else:
-        for pdir in patient_dirs:
-            nii_files = patients[pdir]
-            if len(nii_files) == 1:
-                file_matrix.append([nii_files[0]])
-            else:
-                raise ValueError(
-                    f"Patient folder {pdir!r} contains {len(nii_files)} NIfTI "
-                    f"files: {[os.path.basename(f) for f in nii_files]}. "
-                    "Use --select PATTERN to pick one (or more) per patient. "
-                    "Example: --select '*t1*' --select '*t2*' --select '*flair*'"
-                )
+    for pdir in patient_dirs:
+        nii_files = patients[pdir]
+        if len(nii_files) == 1:
+            file_matrix.append([nii_files[0]])
+        else:
+            raise ValueError(
+                f"Patient folder {pdir!r} contains {len(nii_files)} NIfTI "
+                f"files: {[os.path.basename(f) for f in nii_files]}. "
+                "Use --stack with explicit file patterns for multi-file folders."
+            )
 
     return _series_from_file_matrix(file_matrix, load=load, stack=stack)
 
 
-def load_data_with_meta(filepath, key=None, select=None, *, load="lazy", stack="auto"):
+def load_data_with_meta(filepath, key=None, *, load="lazy", stack="auto"):
     """Like load_data but also returns spatial metadata for NIfTI files.
 
     Returns (array, meta_or_None). meta is None for non-NIfTI formats.
@@ -1139,7 +1405,7 @@ def load_data_with_meta(filepath, key=None, select=None, *, load="lazy", stack="
     ``_load_file_series``).
     """
     if os.path.isdir(filepath):
-        return _load_file_series(filepath, select=select, load=load, stack=stack)
+        return _load_file_series(filepath, load=load, stack=stack)
     if filepath.endswith(".nii") or filepath.endswith(".nii.gz"):
         return _load_nifti_with_meta(filepath)
     return load_data(filepath, key=key), None