pyccapt 0.2.2__tar.gz → 0.2.3__tar.gz

{pyccapt-0.2.2/pyccapt.egg-info → pyccapt-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyccapt
-Version: 0.2.2
+Version: 0.2.3
 Summary: A Python package for atom probe control and data calibration.
 Home-page: https://github.com/mmonajem/pyccapt
 Author: Mehrpad Monajem
@@ -26,6 +26,7 @@ Requires-Dist: pandas
 Requires-Dist: requests
 Requires-Dist: scipy
 Requires-Dist: tables
+Requires-Dist: tomli; python_version < "3.11"
 Requires-Dist: wget
 Provides-Extra: calibration
 Requires-Dist: adjustText; extra == "calibration"
@@ -44,6 +45,7 @@ Requires-Dist: pymatgen; extra == "calibration"
 Requires-Dist: pyvista; extra == "calibration"
 Requires-Dist: scikit-learn; extra == "calibration"
 Requires-Dist: tqdm; extra == "calibration"
+Requires-Dist: uproot; extra == "calibration"
 Requires-Dist: vispy; extra == "calibration"
 Provides-Extra: control
 Requires-Dist: mcculw; platform_system == "Windows" and extra == "control"
@@ -73,6 +75,7 @@ Requires-Dist: pymatgen; extra == "full"
 Requires-Dist: pyvista; extra == "full"
 Requires-Dist: scikit-learn; extra == "full"
 Requires-Dist: tqdm; extra == "full"
+Requires-Dist: uproot; extra == "full"
 Requires-Dist: vispy; extra == "full"
 Requires-Dist: mcculw; platform_system == "Windows" and extra == "full"
 Requires-Dist: networkx; extra == "full"
@@ -101,6 +104,7 @@ Requires-Dist: pymatgen; extra == "all"
 Requires-Dist: pyvista; extra == "all"
 Requires-Dist: scikit-learn; extra == "all"
 Requires-Dist: tqdm; extra == "all"
+Requires-Dist: uproot; extra == "all"
 Requires-Dist: vispy; extra == "all"
 Requires-Dist: mcculw; platform_system == "Windows" and extra == "all"
 Requires-Dist: networkx; extra == "all"
@@ -212,6 +216,32 @@ pip install -e ".[control]"
 pip install -e ".[calibration]"
 ```
 
+### Faster local installs
+
+The editable (`-e`) step is fast; most of the time goes into resolving and
+downloading dependencies. A few scientific dependencies are heavy: `numba`
+pulls in `llvmlite` (and backtracks or builds from source if no wheel matches
+your Python), and `tables`/`h5py` build against the HDF5 C library when no
+wheel is available. The dependencies are also unpinned, so pip downloads
+metadata for many candidate versions to satisfy the `numpy` ranges that
+`numba`, `tables`, and `h5py` require.
+
+To speed it up:
+
+```bash
+# Resolve/download in parallel with uv
+uv pip install -e ".[full]"
+
+# Or let conda provide the heavy binaries, then skip re-resolving them
+conda install -c conda-forge numpy scipy pandas h5py pytables numba matplotlib
+pip install -e . --no-deps
+
+# During iterative development, when deps are already installed
+pip install -e . --no-deps
+```
+
+See [docs/installation](https://pyccapt.readthedocs.io/en/latest/installation.html) for details.
+
 ## Running PyCCAPT
 
 Start the control application:
@@ -272,6 +302,16 @@ Vacuum logs are written under `pyccapt/files/logs/vacuum`, and baking logs are w
 
 PyCCAPT calibration workflows cover detector hit maps, FDM views, mass-spectrum calibration, bowl and voltage correction, reconstruction, and downstream visualization.
 
+Mass calibration runs as a pipeline: initial `t0`/flight-path estimate →
+voltage correction → bowl correction → optional per-ion-index time-drift
+correction → adaptive per-peak residual fit. A **Config preset** dropdown
+in the data-processing notebook selects between adaptive residual (default),
+adaptive residual with time-drift correction (for long runs with measurable
+drift), and the legacy adaptive residual. A separate NIST reference fit
+rescales the calibrated `m/c` onto reference masses without re-fitting the
+voltage, bowl, or drift terms. See
+[docs/CALIBRATION.md](docs/CALIBRATION.md) for the stages and presets.
+
 ![Mass spectrum](pyccapt/files/readme_images/hist.png)
 
 <p align="center">
@@ -305,9 +345,17 @@ matching dld event are preserved untouched. See
 [docs/Calibration_DATA_STRUCTURE.md](docs/Calibration_DATA_STRUCTURE.md) for
 the on-disk schema.
 
+The Surface Concept raw-data workflow can recover physically valid hits from
+pulses that fired only some delay-line channels: each delay-line axis is paired
+and cross-matched by time-of-flight, and recovered rows are tagged with a `dlts`
+count and a `dlts_quality` label. See
+[docs/CALIBRATION.md](docs/CALIBRATION.md#partial-hit-recovery-surface-concept).
+
 The visualization helpers also include optional precipitate clustering with both
 Min-Max and Maximum-Separation algorithms, plus iso-surface and proxigram
-workflows for interface analysis.
+workflows for interface analysis. Scatter sub-sampling in the reconstruction and
+visualization plots is seeded, so re-running a plot on the same dataset produces
+the same figure.
 
 For control part of the package you can follow the steps
 on [documentation](https://pyccapt.readthedocs.io/).
@@ -373,6 +421,38 @@ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for developmen
 - Issues and bug reports: [GitHub Issues](https://github.com/mmonajem/pyccapt/issues)
 - Contact: Mehrpad Monajem (`mehrpad.monajem@fau.de`)
 
+## Third-party hardware SDKs and libraries
+
+PyCCAPT integrates with several pieces of third-party hardware and uses
+the corresponding vendor SDKs / Python wrappers. These remain the
+intellectual property of their respective owners; the files under the
+listed paths are either thin wrappers around vendor APIs or are
+adapted from vendor-provided example code, and are used here under the
+licence terms shipped with each SDK. Where a wrapper is largely
+vendor-provided code, the source file carries an attribution header.
+
+| Component                                          | Vendor / project                         | Used by                                                                                                        |
+|----------------------------------------------------|------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| Origami XPS laser CLI                              | NKT Photonics                            | `pyccapt/control/nkt_photonics/origamiClassCLI.py`, `nktpbus_activate.py`                                      |
+| NKTPDLL (NKTPBus protocol DLL + Python wrapper)    | NKT Photonics                            | `pyccapt/control/nkt_photonics/nktpbus_switch.py` (loads the vendor's `NKTPDLL.dll` and bundled `NKTP_DLL.py`) |
+| MCS2 stage controller SDK (`smaract.ctl`)          | SmarAct GmbH                             | `pyccapt/control/smaract_mcs2/`                                                                                |
+| Surface Concept TDC SDK (`scTDC`)                  | Surface Concept GmbH                     | `pyccapt/control/tdc_surface_concept/`                                                                         |
+| RoentDek TDC8HP wrapper                            | RoentDek Handels GmbH                    | `pyccapt/control/tdc_roentdek/`                                                                                |
+| DRS digitizer library                              | Paul Scherrer Institute (PSI)            | `pyccapt/control/drs/`                                                                                         |
+| Thorlabs APT motor SDK                             | Thorlabs Inc.                            | `pyccapt/control/thorlabs_apt/`                                                                                |
+| Pfeiffer TPG362 vacuum-gauge protocol              | Pfeiffer Vacuum                          | `pyccapt/control/devices/pfeiffer_gauges.py`                                                                   |
+| Edwards TIC AGC vacuum-controller protocol         | Edwards Vacuum                           | `pyccapt/control/devices/edwards_tic.py`                                                                       |
+| CryoVac TIC 500 temperature-controller protocol    | CryoVac GmbH                             | `pyccapt/control/devices/initialize_devices.py` (`command_cryovac` and friends)                                |
+| MCC Universal Library (`mcculw`) for thermocouples | Measurement Computing                    | `pyccapt/control/core/baking_loging.py`                                                                        |
+| `simple_pid` PID controller                        | Martin Lundberg (MIT licence)            | `pyccapt/control/apt/apt_exp_control.py`                                                                       |
+| PyQt6                                              | Riverbank Computing (GPLv3 / commercial) | All GUI windows under `pyccapt/control/gui/`                                                                   |
+
+To use a given component, install the vendor's SDK or Python package per
+their documentation (see `requirements.txt` / `pyproject.toml` for pip
+packages, and the vendor's installer for the proprietary SDKs that ship
+DLLs). A missing SDK only disables the corresponding device — the rest
+of PyCCAPT continues to work.
+
 ## License
 
 PyCCAPT is licensed under the GNU General Public License v3.0. See [LICENSE](LICENSE).

{pyccapt-0.2.2 → pyccapt-0.2.3}/README.md

@@ -79,6 +79,32 @@ pip install -e ".[control]"
 pip install -e ".[calibration]"
 ```
 
+### Faster local installs
+
+The editable (`-e`) step is fast; most of the time goes into resolving and
+downloading dependencies. A few scientific dependencies are heavy: `numba`
+pulls in `llvmlite` (and backtracks or builds from source if no wheel matches
+your Python), and `tables`/`h5py` build against the HDF5 C library when no
+wheel is available. The dependencies are also unpinned, so pip downloads
+metadata for many candidate versions to satisfy the `numpy` ranges that
+`numba`, `tables`, and `h5py` require.
+
+To speed it up:
+
+```bash
+# Resolve/download in parallel with uv
+uv pip install -e ".[full]"
+
+# Or let conda provide the heavy binaries, then skip re-resolving them
+conda install -c conda-forge numpy scipy pandas h5py pytables numba matplotlib
+pip install -e . --no-deps
+
+# During iterative development, when deps are already installed
+pip install -e . --no-deps
+```
+
+See [docs/installation](https://pyccapt.readthedocs.io/en/latest/installation.html) for details.
+
 ## Running PyCCAPT
 
 Start the control application:
@@ -139,6 +165,16 @@ Vacuum logs are written under `pyccapt/files/logs/vacuum`, and baking logs are w
 
 PyCCAPT calibration workflows cover detector hit maps, FDM views, mass-spectrum calibration, bowl and voltage correction, reconstruction, and downstream visualization.
 
+Mass calibration runs as a pipeline: initial `t0`/flight-path estimate →
+voltage correction → bowl correction → optional per-ion-index time-drift
+correction → adaptive per-peak residual fit. A **Config preset** dropdown
+in the data-processing notebook selects between adaptive residual (default),
+adaptive residual with time-drift correction (for long runs with measurable
+drift), and the legacy adaptive residual. A separate NIST reference fit
+rescales the calibrated `m/c` onto reference masses without re-fitting the
+voltage, bowl, or drift terms. See
+[docs/CALIBRATION.md](docs/CALIBRATION.md) for the stages and presets.
+
 ![Mass spectrum](pyccapt/files/readme_images/hist.png)
 
 <p align="center">
@@ -172,9 +208,17 @@ matching dld event are preserved untouched. See
 [docs/Calibration_DATA_STRUCTURE.md](docs/Calibration_DATA_STRUCTURE.md) for
 the on-disk schema.
 
+The Surface Concept raw-data workflow can recover physically valid hits from
+pulses that fired only some delay-line channels: each delay-line axis is paired
+and cross-matched by time-of-flight, and recovered rows are tagged with a `dlts`
+count and a `dlts_quality` label. See
+[docs/CALIBRATION.md](docs/CALIBRATION.md#partial-hit-recovery-surface-concept).
+
 The visualization helpers also include optional precipitate clustering with both
 Min-Max and Maximum-Separation algorithms, plus iso-surface and proxigram
-workflows for interface analysis.
+workflows for interface analysis. Scatter sub-sampling in the reconstruction and
+visualization plots is seeded, so re-running a plot on the same dataset produces
+the same figure.
 
 For control part of the package you can follow the steps
 on [documentation](https://pyccapt.readthedocs.io/).
@@ -240,6 +284,38 @@ Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for developmen
 - Issues and bug reports: [GitHub Issues](https://github.com/mmonajem/pyccapt/issues)
 - Contact: Mehrpad Monajem (`mehrpad.monajem@fau.de`)
 
+## Third-party hardware SDKs and libraries
+
+PyCCAPT integrates with several pieces of third-party hardware and uses
+the corresponding vendor SDKs / Python wrappers. These remain the
+intellectual property of their respective owners; the files under the
+listed paths are either thin wrappers around vendor APIs or are
+adapted from vendor-provided example code, and are used here under the
+licence terms shipped with each SDK. Where a wrapper is largely
+vendor-provided code, the source file carries an attribution header.
+
+| Component                                          | Vendor / project                         | Used by                                                                                                        |
+|----------------------------------------------------|------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| Origami XPS laser CLI                              | NKT Photonics                            | `pyccapt/control/nkt_photonics/origamiClassCLI.py`, `nktpbus_activate.py`                                      |
+| NKTPDLL (NKTPBus protocol DLL + Python wrapper)    | NKT Photonics                            | `pyccapt/control/nkt_photonics/nktpbus_switch.py` (loads the vendor's `NKTPDLL.dll` and bundled `NKTP_DLL.py`) |
+| MCS2 stage controller SDK (`smaract.ctl`)          | SmarAct GmbH                             | `pyccapt/control/smaract_mcs2/`                                                                                |
+| Surface Concept TDC SDK (`scTDC`)                  | Surface Concept GmbH                     | `pyccapt/control/tdc_surface_concept/`                                                                         |
+| RoentDek TDC8HP wrapper                            | RoentDek Handels GmbH                    | `pyccapt/control/tdc_roentdek/`                                                                                |
+| DRS digitizer library                              | Paul Scherrer Institute (PSI)            | `pyccapt/control/drs/`                                                                                         |
+| Thorlabs APT motor SDK                             | Thorlabs Inc.                            | `pyccapt/control/thorlabs_apt/`                                                                                |
+| Pfeiffer TPG362 vacuum-gauge protocol              | Pfeiffer Vacuum                          | `pyccapt/control/devices/pfeiffer_gauges.py`                                                                   |
+| Edwards TIC AGC vacuum-controller protocol         | Edwards Vacuum                           | `pyccapt/control/devices/edwards_tic.py`                                                                       |
+| CryoVac TIC 500 temperature-controller protocol    | CryoVac GmbH                             | `pyccapt/control/devices/initialize_devices.py` (`command_cryovac` and friends)                                |
+| MCC Universal Library (`mcculw`) for thermocouples | Measurement Computing                    | `pyccapt/control/core/baking_loging.py`                                                                        |
+| `simple_pid` PID controller                        | Martin Lundberg (MIT licence)            | `pyccapt/control/apt/apt_exp_control.py`                                                                       |
+| PyQt6                                              | Riverbank Computing (GPLv3 / commercial) | All GUI windows under `pyccapt/control/gui/`                                                                   |
+
+To use a given component, install the vendor's SDK or Python package per
+their documentation (see `requirements.txt` / `pyproject.toml` for pip
+packages, and the vendor's installer for the proprietary SDKs that ship
+DLLs). A missing SDK only disables the corresponding device — the rest
+of PyCCAPT continues to work.
+
 ## License
 
 PyCCAPT is licensed under the GNU General Public License v3.0. See [LICENSE](LICENSE).

pyccapt-0.2.3/pyccapt/__init__.py

@@ -0,0 +1,16 @@
+"""Top-level package for PyCCAPT."""
+
+import warnings
+
+# SciPy ships a runtime guard that complains when it's loaded against a
+# newer NumPy than the one it was built for. Our lab environment runs
+# NumPy 1.26 against an older SciPy build, and the bound is advisory
+# (the SciPy routines we use work fine). Filter the specific message
+# here, before any submodule pulls in scipy, so startup logs stay clean.
+warnings.filterwarnings(
+    "ignore",
+    message=r"A NumPy version >=.* and <.* is required for this version of SciPy.*",
+    category=UserWarning,
+)
+
+__version__ = "0.2.3"

{pyccapt-0.2.2 → pyccapt-0.2.3}/pyccapt/calibration/DATA_STRUCTURE.md

@@ -3,6 +3,12 @@
 This document summarizes the data layout used by the calibration module and its
 range files.
 
+The canonical machine-readable schema for the raw acquisition groups
+(`/dld`, `/tdc`, `/hsd`) — column names, order, dtypes, and the group
+aliases accepted across pyccapt versions — is defined in
+`pyccapt.calibration.data_tools.hdf5_schema`. The control-side writer
+and the calibration-side reader both follow that module.
+
 ## Notation
 
 - `(n,)`: one-dimensional array with length `n`
@@ -26,7 +32,19 @@ Typical calibrated dataset fields:
 - `y_det (cm)`: `(n,)` `(cm, float64)` detector y hit position
 - `delta_p`: `(n,)` `(N/A, uint32)` pulses since previous detected event
 - `multi`: `(n,)` `(N/A, uint32)` multiplicity per pulse
-- `start_counter`: `(n,)` `(N/A, float64)` TDC counter value
+- `start_counter`: `(n,)` `(N/A, float64)` TDC counter value (wraps; not unique)
+- `event_group_id` *(optional)*: `(n,)` `(N/A, int64)` shared id linking each
+  dld row to the matching raw `/tdc` rows; present when the dataset was loaded
+  with `load_tdc_raw=True` and preserved through every cropping step.
+
+When partial-hit recovery (`data_tools.partial_recovery`) runs, the DLD
+dataframe gains two columns: `dlts` `(N/A, int8)` — `4` for a native or
+fully-recovered two-axis hit, `2` for a single-axis partial — and
+`dlts_quality` `(N/A, string)` provenance label (`native` for original rows;
+`recovered_xy` / `recovered_x` / `recovered_y` for recovered rows; and
+`recovered_xy_3of4` for a full (x, y) hit rebuilt from a 3-channel pulse via
+the delay-line time-sum constraint). Single-axis recovered rows hold `NaN` on
+the unrecovered detector axis.
 
 ## Range Dataset (HDF5 or Imported `.rrng` / `.rng`)
 

{pyccapt-0.2.2 → pyccapt-0.2.3}/pyccapt/calibration/clustering/clustering.py

@@ -96,6 +96,17 @@ def normalize_clustering_method(method: str) -> str:
 
 
 def _resolve_xyz(variables) -> np.ndarray:
+    """Return the (N, 3) reconstruction coordinates.
+
+    Partial-recovered rows have NaN x/y/z because their detector position
+    was incomplete. ``np.column_stack`` happily carries the NaN through,
+    but downstream clustering (DBSCAN / HDBSCAN / MinMax) raises on NaN
+    inputs. The mask is preserved at full length here so downstream
+    consumers like the colour / mc array stay aligned; callers that
+    actually pass the array into clustering must drop NaN rows with
+    ``np.isnan(coords).any(axis=1)``. We surface a clear notice the first
+    time so the omission is obvious.
+    """
     x = np.asarray(getattr(variables, "x", np.zeros(0)))
     y = np.asarray(getattr(variables, "y", np.zeros(0)))
     z = np.asarray(getattr(variables, "z", np.zeros(0)))
@@ -103,7 +114,16 @@ def _resolve_xyz(variables) -> np.ndarray:
         raise ValueError("Reconstruction coordinates are empty. Run the reconstruction first.")
     if not (len(x) == len(y) == len(z)):
         raise ValueError("Reconstruction coordinates must have the same length.")
-    return np.column_stack((x, y, z))
+    coords = np.column_stack((x, y, z))
+    n_nan = int(np.isnan(coords).any(axis=1).sum())
+    if n_nan > 0:
+        print(
+            f'[clustering._resolve_xyz] Note: {n_nan} rows have NaN (x, y, z) '
+            '(partial-recovered ions with undefined detector position). '
+            'Downstream clustering should mask them out with '
+            '``~np.isnan(coords).any(axis=1)``.'
+        )
+    return coords
 
 
 def _resolve_mc(variables) -> np.ndarray:
@@ -216,34 +236,60 @@ def _drop_small_clusters(labels: np.ndarray, *, n_min: int) -> np.ndarray:
     return np.array([remap[int(label)] if label >= 0 else -1 for label in labels], dtype=int)
 
 
-def min_max_clustering(points: np.ndarray, n_clusters: int = 2, max_iter: int = 50) -> tuple[np.ndarray, np.ndarray]:
-    """Segment points with a deterministic Min-Max initialization plus centroid refinement."""
+def min_max_clustering(
+    points: np.ndarray,
+    n_clusters: int = 2,
+    max_iter: int = 50,
+    n_min: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Segment points with a deterministic Min-Max initialization plus centroid refinement.
+
+    Parameters
+    ----------
+    n_min : optional int
+        When provided, clusters with fewer than ``n_min`` members are
+        relabelled as noise (-1) and the surviving labels compacted --
+        consistent with the HDBSCAN / DBSCAN / maximum-separation
+        algorithms in this module, which all drop tiny clusters. The
+        default (None) preserves the legacy behaviour of returning
+        exactly ``n_clusters`` partitions.
+
+    Notes
+    -----
+    NaN-coordinate rows (partial-recovered ions) are dropped before
+    clustering and re-inserted afterwards with label -1; previously the
+    NaN values flowed through ``np.linalg.norm`` / ``argmin`` and
+    silently produced garbage labels.
+    """
     points = np.asarray(points, dtype=float)
     if points.ndim != 2 or points.shape[1] != 3:
         raise ValueError("points must be a (N, 3) array")
     if n_clusters < 2:
         raise ValueError("n_clusters must be at least 2")
-    if len(points) < n_clusters:
-        raise ValueError("Not enough points for the requested number of clusters")
 
-    centroid = points.mean(axis=0)
-    first_index = int(np.argmax(np.linalg.norm(points - centroid, axis=1)))
-    centers = [points[first_index]]
+    nan_row_mask = np.isnan(points).any(axis=1)
+    finite_points = points[~nan_row_mask]
+    if len(finite_points) < n_clusters:
+        raise ValueError("Not enough (finite) points for the requested number of clusters")
+
+    centroid = finite_points.mean(axis=0)
+    first_index = int(np.argmax(np.linalg.norm(finite_points - centroid, axis=1)))
+    centers = [finite_points[first_index]]
 
     while len(centers) < n_clusters:
-        distances = np.stack([np.linalg.norm(points - center, axis=1) for center in centers], axis=1)
+        distances = np.stack([np.linalg.norm(finite_points - center, axis=1) for center in centers], axis=1)
         candidate_index = int(np.argmax(np.min(distances, axis=1)))
-        centers.append(points[candidate_index])
+        centers.append(finite_points[candidate_index])
 
     centers = np.asarray(centers, dtype=float)
-    labels = np.zeros(len(points), dtype=int)
+    labels = np.zeros(len(finite_points), dtype=int)
 
     for _ in range(max_iter):
-        distances = np.stack([np.linalg.norm(points - center, axis=1) for center in centers], axis=1)
+        distances = np.stack([np.linalg.norm(finite_points - center, axis=1) for center in centers], axis=1)
         new_labels = np.argmin(distances, axis=1)
         new_centers = centers.copy()
         for idx in range(n_clusters):
-            cluster_points = points[new_labels == idx]
+            cluster_points = finite_points[new_labels == idx]
             if len(cluster_points) > 0:
                 new_centers[idx] = cluster_points.mean(axis=0)
         if np.array_equal(new_labels, labels) and np.allclose(new_centers, centers):
@@ -257,6 +303,18 @@ def min_max_clustering(points: np.ndarray, n_clusters: int = 2, max_iter: int =
     remap = {int(old): int(new) for new, old in enumerate(order)}
     labels = np.array([remap[int(label)] for label in labels], dtype=int)
     centers = centers[order]
+
+    if n_min is not None:
+        labels = _drop_small_clusters(labels, n_min=int(n_min))
+        centers = _centers_from_labeled_points(finite_points, labels)
+
+    if nan_row_mask.any():
+        # Re-expand to the original input length so callers that index by
+        # selection mask stay aligned; NaN rows are noise (-1).
+        full = np.full(len(points), -1, dtype=int)
+        full[~nan_row_mask] = labels
+        labels = full
+
     return labels, centers
 
 
@@ -289,6 +347,19 @@ def estimate_maximum_separation_distance(
     return d_max
 
 
+def _expand_maxsep_labels(filtered_labels: np.ndarray, finite_idx: np.ndarray, input_len: int) -> np.ndarray:
+    """Re-expand labels computed on the NaN-filtered subset to full length.
+
+    Dropped (NaN-coordinate) rows become -1 (noise) so callers that index
+    by the original selection mask stay aligned.
+    """
+    if len(filtered_labels) == input_len:
+        return filtered_labels
+    full = np.full(input_len, -1, dtype=int)
+    full[finite_idx] = filtered_labels
+    return full
+
+
 def maximum_separation_clustering(
     points: np.ndarray,
     *,
@@ -308,10 +379,24 @@ def maximum_separation_clustering(
     if n_min < 2:
         raise ValueError("n_min must be at least 2")
 
+    # NaN-coordinate rows (partial-recovered ions) would break cKDTree;
+    # drop them up front and re-expand labels to the original length with
+    # -1 (noise) afterwards, consistent with hdbscan_clustering and
+    # min_max_clustering. ``input_len`` / ``finite_idx`` carry the mapping.
+    input_len = len(points)
+    nan_row_mask = np.isnan(points).any(axis=1)
+    finite_idx = np.flatnonzero(~nan_row_mask)
+    if nan_row_mask.any():
+        print(
+            f'[maximum_separation_clustering] Dropping {int(nan_row_mask.sum())} '
+            'rows with NaN (x, y, z) (partial-recovered ions) before clustering.'
+        )
+    points = points[finite_idx]
+
     n_points = len(points)
     labels = np.full(n_points, -1, dtype=int)
     if n_points < n_min:
-        return labels, np.empty((0, 3), dtype=float)
+        return _expand_maxsep_labels(labels, finite_idx, input_len), np.empty((0, 3), dtype=float)
 
     tree = cKDTree(points)
     try:
@@ -320,7 +405,7 @@ def maximum_separation_clustering(
         pairs = np.asarray(sorted(tree.query_pairs(d_max)), dtype=int)
 
     if pairs.size == 0:
-        return labels, np.empty((0, 3), dtype=float)
+        return _expand_maxsep_labels(labels, finite_idx, input_len), np.empty((0, 3), dtype=float)
 
     parent = np.arange(n_points, dtype=int)
     size = np.ones(n_points, dtype=int)
@@ -346,9 +431,13 @@ def maximum_separation_clustering(
 
     roots = np.fromiter((find(index) for index in range(n_points)), count=n_points, dtype=int)
     unique_roots, inverse, counts = np.unique(roots, return_inverse=True, return_counts=True)
+    # numpy 2.0 briefly returned ``inverse`` with the input's shape
+    # (i.e. (n, 1) here); ravel so the ``enumerate(inverse)`` loop below
+    # always yields scalar local_root_id values.
+    inverse = np.ravel(inverse)
     valid_mask = counts >= n_min
     if not np.any(valid_mask):
-        return labels, np.empty((0, 3), dtype=float)
+        return _expand_maxsep_labels(labels, finite_idx, input_len), np.empty((0, 3), dtype=float)
 
     centers = []
     cluster_sizes = []
@@ -366,12 +455,19 @@ def maximum_separation_clustering(
 
     remap = {int(old_idx): int(new_idx) for new_idx, old_idx in enumerate(order)}
     for point_index, local_root_id in enumerate(inverse):
+        local_root_id = int(local_root_id)
         if not valid_mask[local_root_id]:
             continue
-        labels[point_index] = remap[old_to_new[int(local_root_id)]]
+        # Defensive .get: old_to_new only holds valid roots, and the
+        # valid_mask guard above already gates entry, but a guard here
+        # makes the relabel robust to any future index-space drift.
+        center_idx = old_to_new.get(local_root_id)
+        if center_idx is None:
+            continue
+        labels[point_index] = remap[center_idx]
 
     centers = centers[order]
-    return labels, centers
+    return _expand_maxsep_labels(labels, finite_idx, input_len), centers
 
 
 def hdbscan_clustering(
@@ -390,6 +486,26 @@ def hdbscan_clustering(
     if len(points) == 0:
         raise ValueError("points cannot be empty")
 
+    # Both HDBSCAN and sklearn DBSCAN raise on NaN coordinates. Drop
+    # partial-recovered rows with undefined (x, y, z) before clustering
+    # rather than letting the backend explode. ``labels`` is returned at
+    # FULL input length: NaN rows get label -1 (noise) so the caller's
+    # ``full_labels[selected_indices] = labels`` assignment continues to
+    # line up with ``selected_indices``. Previously the returned labels
+    # had the filtered length and broadcasting to a longer index slice
+    # crashed with ValueError (or silently misaligned in pre-numpy 1.20
+    # behaviour, putting every label after the first NaN row on the
+    # wrong ion).
+    nan_row_mask = np.isnan(points).any(axis=1)
+    finite_points = points[~nan_row_mask]
+    if nan_row_mask.any():
+        print(
+            f'[hdbscan_clustering] Dropping {int(nan_row_mask.sum())} rows with NaN '
+            '(x, y, z) (partial-recovered ions) before clustering.'
+        )
+        if len(finite_points) == 0:
+            raise ValueError("points has no finite rows after dropping NaN coordinates")
+
     n_min = max(2, int(n_min))
     min_samples = max(1, int(min_samples))
     parameters: dict[str, float | int | bool] = {
@@ -397,13 +513,22 @@ def hdbscan_clustering(
         "min_samples": int(min_samples),
     }
 
+    def _expand_labels(filtered_labels: np.ndarray) -> np.ndarray:
+        """Expand labels back to full input length; NaN rows get -1 (noise)."""
+        full = np.full(len(points), -1, dtype=int)
+        full[~nan_row_mask] = filtered_labels
+        return full
+
     try:
         import hdbscan as _hdbscan
 
         clusterer = _hdbscan.HDBSCAN(min_cluster_size=n_min, min_samples=min_samples)
-        labels = np.asarray(clusterer.fit_predict(points), dtype=int)
-        labels = _drop_small_clusters(labels, n_min=n_min)
-        centers = _centers_from_labeled_points(points, labels)
+        filtered_labels = np.asarray(clusterer.fit_predict(finite_points), dtype=int)
+        filtered_labels = _drop_small_clusters(filtered_labels, n_min=n_min)
+        # Compute centers from the filtered (NaN-free) points so the
+        # centroid calculation isn't poisoned by undefined coords.
+        centers = _centers_from_labeled_points(finite_points, filtered_labels)
+        labels = _expand_labels(filtered_labels)
         parameters["backend"] = True
         return labels, centers, parameters
     except Exception:
@@ -412,16 +537,21 @@ def hdbscan_clustering(
 
         if auto_d_max or d_max is None:
             eps = estimate_maximum_separation_distance(
-                points,
+                finite_points,
                 kth_neighbor=max(1, min_samples),
                 percentile=float(percentile),
             )
         else:
             eps = float(d_max)
-        labels = np.asarray(DBSCAN(eps=eps, min_samples=n_min).fit_predict(points), dtype=int)
-        labels = _drop_small_clusters(labels, n_min=n_min)
-        centers = _centers_from_labeled_points(points, labels)
-        parameters.update({"backend": False, "d_max": float(eps), "auto_d_max": bool(auto_d_max), "percentile": float(percentile)})
+        filtered_labels = np.asarray(
+            DBSCAN(eps=eps, min_samples=n_min).fit_predict(finite_points), dtype=int
+        )
+        filtered_labels = _drop_small_clusters(filtered_labels, n_min=n_min)
+        centers = _centers_from_labeled_points(finite_points, filtered_labels)
+        labels = _expand_labels(filtered_labels)
+        parameters.update(
+            {"backend": False, "d_max": float(eps), "auto_d_max": bool(auto_d_max), "percentile": float(percentile)}
+        )
         return labels, centers, parameters