rangefinder 0.1.0__tar.gz

rangefinder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle McDonald
+
+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.

rangefinder-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: rangefinder
+Version: 0.1.0
+Summary: Automated ranging, species identification, and composition for time-of-flight (APT) mass spectra
+Author: Kyle McDonald
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kylemcdonald/rangefinder
+Project-URL: Repository, https://github.com/kylemcdonald/rangefinder.git
+Project-URL: Issues, https://github.com/kylemcdonald/rangefinder/issues
+Keywords: atom probe tomography,mass spectrometry,ranging,composition
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ase>=3.22
+Requires-Dist: ifes-apt-tc-data-modeling>=0.4
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: matplotlib>=3.6
+Provides-Extra: comparators
+Requires-Dist: pyccapt>=0.2; extra == "comparators"
+Requires-Dist: pyopenms>=3.0; extra == "comparators"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# Rangefinder
+
+[![CI](https://github.com/kylemcdonald/rangefinder/actions/workflows/ci.yml/badge.svg)](https://github.com/kylemcdonald/rangefinder/actions/workflows/ci.yml)
+
+Automated **ranging**, species identification, and composition for time-of-flight
+(atom probe tomography) mass spectra. Rangefinder goes from a raw event list
+(`.pos`/`.epos`, or any array of *m/z* values) to ranged peaks, identified ionic
+species, and isotope-resolved composition — with **no user-supplied ranges, no
+candidate element list, no interactive tuning, and no manual curation**.
+
+It is deterministic (operator variance is exactly zero), pure Python
+(NumPy/SciPy/pandas), and ships its own benchmark harness against the open-source
+APT ecosystem.
+
+## Install
+
+```bash
+python -m pip install rangefinder
+```
+
+For development:
+
+```bash
+git clone https://github.com/kylemcdonald/rangefinder.git
+cd rangefinder
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from pathlib import Path
+
+import rangefinder
+from rangefinder.io.pos_loader import PosSampleData, PosSampleMetadata
+from rangefinder.benchmark.truth import load_pos_arrays
+
+sample_path = Path("your_sample.pos")
+x, y, z, mz = load_pos_arrays(sample_path)
+meta = PosSampleMetadata(path=sample_path, sample_name="s", sample_slug="s",
+                         event_count=len(mz), file_size_bytes=len(mz) * 16,
+                         verified_big_endian_float32=True,
+                         verified_columns=("x_nm", "y_nm", "z_nm", "m_over_z_da"))
+sample = PosSampleData(metadata=meta, x_nm=x, y_nm=y, z_nm=z, m_over_z_da=mz)
+
+config = rangefinder.load_default_config()
+artifacts = rangefinder.run_custom_pipeline(sample, Path("out"), config)
+print(artifacts.elemental_composition)
+```
+
+## Layout
+
+- `src/rangefinder/` — the package.
+  - `analysis/` — the Rangefinder pipeline (`custom_pipeline`) plus the comparator
+    front-ends (naive, PyCCAPT, pyOpenMS) and shared assignment/composition stages.
+  - `benchmark/` — ground-truth registry, metrics, and detection-ablation harness.
+  - `io/`, `references/`, `validation/`, `utils/` — POS loading, isotope tables,
+    the synthetic generator, config/paths helpers.
+  - `bridge.py`, `bridge_runner.py` — run foreign-toolchain comparators
+    (APAV, ms_deisotope, APyT) in a separate environment.
+  - `config/defaults.yaml` — the bundled default pipeline configuration
+    (`rangefinder.default_config_path()`).
+- `scripts/` — the benchmark and paper-table generators.
+- `paper/` — `rangefinder.tex` and its auto-generated `tables/`.
+- `controls/` — public CC-BY reference datasets (fetch large files with
+  `scripts/download_benchmark_controls.sh`; reproducible raw data and generated
+  synthetic controls are git-ignored, while provenance and range files are
+  tracked).
+
+## Reproduce the benchmark and paper
+
+```bash
+scripts/download_benchmark_controls.sh          # fetch public controls
+scripts/bootstrap_env.sh                        # install comparator environments
+python scripts/run_benchmark.py                 # all methods x all datasets
+python scripts/run_detection_ablation.py        # detection-stage ablation
+python scripts/run_ablation.py                  # pipeline-stage ablation
+python scripts/build_paper_tables.py            # regenerate paper/tables/*.tex
+tectonic paper/rangefinder.tex
+```
+
+Every number in the paper regenerates from these commands; table numbers are
+never hand-edited.
+
+## License
+
+The software is released under the [MIT License](LICENSE). The reference data
+and range files under `controls/` remain CC-BY-4.0 as documented in
+[`controls/README.md`](controls/README.md).

rangefinder-0.1.0/README.md

@@ -0,0 +1,91 @@
+# Rangefinder
+
+[![CI](https://github.com/kylemcdonald/rangefinder/actions/workflows/ci.yml/badge.svg)](https://github.com/kylemcdonald/rangefinder/actions/workflows/ci.yml)
+
+Automated **ranging**, species identification, and composition for time-of-flight
+(atom probe tomography) mass spectra. Rangefinder goes from a raw event list
+(`.pos`/`.epos`, or any array of *m/z* values) to ranged peaks, identified ionic
+species, and isotope-resolved composition — with **no user-supplied ranges, no
+candidate element list, no interactive tuning, and no manual curation**.
+
+It is deterministic (operator variance is exactly zero), pure Python
+(NumPy/SciPy/pandas), and ships its own benchmark harness against the open-source
+APT ecosystem.
+
+## Install
+
+```bash
+python -m pip install rangefinder
+```
+
+For development:
+
+```bash
+git clone https://github.com/kylemcdonald/rangefinder.git
+cd rangefinder
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from pathlib import Path
+
+import rangefinder
+from rangefinder.io.pos_loader import PosSampleData, PosSampleMetadata
+from rangefinder.benchmark.truth import load_pos_arrays
+
+sample_path = Path("your_sample.pos")
+x, y, z, mz = load_pos_arrays(sample_path)
+meta = PosSampleMetadata(path=sample_path, sample_name="s", sample_slug="s",
+                         event_count=len(mz), file_size_bytes=len(mz) * 16,
+                         verified_big_endian_float32=True,
+                         verified_columns=("x_nm", "y_nm", "z_nm", "m_over_z_da"))
+sample = PosSampleData(metadata=meta, x_nm=x, y_nm=y, z_nm=z, m_over_z_da=mz)
+
+config = rangefinder.load_default_config()
+artifacts = rangefinder.run_custom_pipeline(sample, Path("out"), config)
+print(artifacts.elemental_composition)
+```
+
+## Layout
+
+- `src/rangefinder/` — the package.
+  - `analysis/` — the Rangefinder pipeline (`custom_pipeline`) plus the comparator
+    front-ends (naive, PyCCAPT, pyOpenMS) and shared assignment/composition stages.
+  - `benchmark/` — ground-truth registry, metrics, and detection-ablation harness.
+  - `io/`, `references/`, `validation/`, `utils/` — POS loading, isotope tables,
+    the synthetic generator, config/paths helpers.
+  - `bridge.py`, `bridge_runner.py` — run foreign-toolchain comparators
+    (APAV, ms_deisotope, APyT) in a separate environment.
+  - `config/defaults.yaml` — the bundled default pipeline configuration
+    (`rangefinder.default_config_path()`).
+- `scripts/` — the benchmark and paper-table generators.
+- `paper/` — `rangefinder.tex` and its auto-generated `tables/`.
+- `controls/` — public CC-BY reference datasets (fetch large files with
+  `scripts/download_benchmark_controls.sh`; reproducible raw data and generated
+  synthetic controls are git-ignored, while provenance and range files are
+  tracked).
+
+## Reproduce the benchmark and paper
+
+```bash
+scripts/download_benchmark_controls.sh          # fetch public controls
+scripts/bootstrap_env.sh                        # install comparator environments
+python scripts/run_benchmark.py                 # all methods x all datasets
+python scripts/run_detection_ablation.py        # detection-stage ablation
+python scripts/run_ablation.py                  # pipeline-stage ablation
+python scripts/build_paper_tables.py            # regenerate paper/tables/*.tex
+tectonic paper/rangefinder.tex
+```
+
+Every number in the paper regenerates from these commands; table numbers are
+never hand-edited.
+
+## License
+
+The software is released under the [MIT License](LICENSE). The reference data
+and range files under `controls/` remain CC-BY-4.0 as documented in
+[`controls/README.md`](controls/README.md).

rangefinder-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rangefinder"
+dynamic = ["version"]
+description = "Automated ranging, species identification, and composition for time-of-flight (APT) mass spectra"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kyle McDonald" }]
+keywords = ["atom probe tomography", "mass spectrometry", "ranging", "composition"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "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",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Chemistry",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+  "ase>=3.22",
+  "ifes-apt-tc-data-modeling>=0.4",
+  "numpy>=1.24",
+  "scipy>=1.10",
+  "pandas>=2.0",
+  "pyyaml>=6.0",
+  "matplotlib>=3.6",
+]
+
+[project.optional-dependencies]
+# Foreign-toolchain comparators used only by the benchmark harness.
+comparators = ["pyccapt>=0.2", "pyopenms>=3.0"]
+test = ["pytest>=8"]
+dev = ["build>=1.2", "pytest>=8", "ruff>=0.9", "twine>=6"]
+
+[project.urls]
+Homepage = "https://github.com/kylemcdonald/rangefinder"
+Repository = "https://github.com/kylemcdonald/rangefinder.git"
+Issues = "https://github.com/kylemcdonald/rangefinder/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "rangefinder.__version__" }
+
+[tool.setuptools.package-data]
+rangefinder = ["config/*.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

rangefinder-0.1.0/setup.cfg

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

rangefinder-0.1.0/src/rangefinder/__init__.py

@@ -0,0 +1,35 @@
+"""Rangefinder: automated ranging, species identification, and composition for
+time-of-flight mass spectra.
+
+Goes from a raw event list (``.pos``/``.epos`` or any array of m/z values) to
+ranged peaks, identified species, and isotope-resolved composition, with no
+user-supplied ranges, element list, or interactive tuning.
+"""
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+from rangefinder.analysis.custom_pipeline import run_custom_pipeline
+from rangefinder.analysis.naive_pipeline import run_naive_pipeline
+from rangefinder.utils.config import load_config
+
+__all__ = [
+    "run_custom_pipeline",
+    "run_naive_pipeline",
+    "default_config_path",
+    "load_default_config",
+]
+
+__version__ = "0.1.0"
+
+
+def default_config_path() -> Path:
+    """Path to the bundled default pipeline configuration."""
+    with resources.as_file(resources.files("rangefinder").joinpath("config/defaults.yaml")) as path:
+        return Path(path)
+
+
+def load_default_config() -> dict:
+    """Load the bundled default pipeline configuration."""
+    return load_config(default_config_path())

rangefinder-0.1.0/src/rangefinder/analysis/__init__.py

@@ -0,0 +1 @@
+"""Analysis pipelines."""

rangefinder-0.1.0/src/rangefinder/analysis/apyt_support.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+from collections import Counter, defaultdict
+import re
+
+import numpy as np
+import pandas as pd
+
+from rangefinder.analysis.assignment import infer_element_support
+from rangefinder.analysis.common import build_species_library, neutral_formula_from_element_counter
+from rangefinder.references.isotopes import isotope_table
+
+
+_FORMULA_RE = re.compile(r"([A-Z][a-z]?)(\d*)")
+
+
+def parse_formula(formula: str) -> dict[str, int]:
+    text = str(formula).strip()
+    if not text:
+        raise ValueError("Formula must be non-empty.")
+    counts: dict[str, int] = {}
+    position = 0
+    for match in _FORMULA_RE.finditer(text):
+        if match.start() != position:
+            raise ValueError(f"Unsupported formula syntax: {formula!r}")
+        symbol = str(match.group(1))
+        count_text = str(match.group(2))
+        count = int(count_text) if count_text else 1
+        counts[symbol] = counts.get(symbol, 0) + count
+        position = match.end()
+    if position != len(text):
+        raise ValueError(f"Unsupported formula syntax: {formula!r}")
+    return counts
+
+
+def formula_category(formula: str) -> str:
+    counts = parse_formula(formula)
+    return "atomic" if len(counts) == 1 and next(iter(counts.values())) == 1 else "molecular"
+
+
+def charged_formula_label(formula: str, charge: int) -> str:
+    return f"{formula}{'+' if int(charge) == 1 else f'{int(charge)}+'}"
+
+
+def select_apyt_species_candidates(peaks: pd.DataFrame, *, config: dict) -> pd.DataFrame:
+    if peaks.empty:
+        return pd.DataFrame(
+            columns=[
+                "formula",
+                "charge",
+                "category",
+                "support_score",
+                "natural_probability",
+                "m_over_z_da",
+            ]
+        )
+    analysis_cfg = config["analysis"]
+    element_support = infer_element_support(
+        peaks,
+        max_charge=int(analysis_cfg["max_charge"]),
+        ppm_tolerance=float(analysis_cfg["ppm_tolerance"]),
+        min_absolute_tolerance_da=float(analysis_cfg["min_absolute_tolerance_da"]),
+        max_absolute_tolerance_da=float(analysis_cfg["max_absolute_tolerance_da"]),
+    )
+    always_include = list(dict.fromkeys(list(analysis_cfg["always_include_elements"])))
+    species_library = build_species_library(
+        isotope_table(),
+        element_support,
+        always_include=always_include,
+        max_candidate_elements=int(
+            analysis_cfg.get("apyt_max_candidate_elements", analysis_cfg["max_candidate_elements"])
+        ),
+        max_charge=int(analysis_cfg.get("apyt_max_charge", analysis_cfg["max_charge"])),
+        max_molecular_charge=int(
+            analysis_cfg.get("apyt_max_molecular_charge", analysis_cfg["max_molecular_charge"])
+        ),
+        max_molecular_atoms=int(
+            analysis_cfg.get("apyt_max_molecular_atoms", analysis_cfg["max_molecular_atoms"])
+        ),
+    )
+    if species_library.empty:
+        return pd.DataFrame()
+    selected = species_library.copy()
+    selected["formula"] = selected["element_counts"].map(
+        lambda counts: neutral_formula_from_element_counter(Counter(dict(counts)))
+    )
+    min_fit_mz = float(
+        analysis_cfg.get(
+            "apyt_min_fit_mz",
+            min(float(analysis_cfg["default_zoom_bin_width_da"]), 0.01),
+        )
+    )
+    selected = selected[
+        (selected["m_over_z_da"] >= min_fit_mz)
+        & (selected["m_over_z_da"] <= float(analysis_cfg["max_mz"]))
+    ].copy()
+    if selected.empty:
+        return pd.DataFrame()
+    atomic = (
+        selected[selected["category"] == "atomic"][
+            ["formula", "charge", "category", "support_score", "natural_probability", "m_over_z_da"]
+        ]
+        .groupby(["formula", "charge", "category"], as_index=False)
+        .max(numeric_only=True)
+    )
+    molecular = selected[selected["category"] == "molecular"].copy()
+    if not molecular.empty:
+        molecular = molecular.sort_values(
+            ["support_score", "natural_probability", "m_over_z_da"],
+            ascending=[False, False, True],
+        )
+        molecular = molecular.drop_duplicates(["formula", "charge"], keep="first")
+        minimum_support = float(analysis_cfg.get("apyt_min_support_score", 0.0))
+        minimum_probability = float(analysis_cfg.get("apyt_min_natural_probability", 0.0))
+        molecular = molecular[
+            (molecular["support_score"] >= minimum_support)
+            & (molecular["natural_probability"] >= minimum_probability)
+        ]
+        molecular = molecular.head(int(analysis_cfg.get("apyt_max_molecular_species", 0)))
+        molecular = molecular[
+            ["formula", "charge", "category", "support_score", "natural_probability", "m_over_z_da"]
+        ]
+    selected = pd.concat([atomic, molecular], ignore_index=True)
+    if selected.empty:
+        return pd.DataFrame()
+    return selected.sort_values(
+        ["category", "support_score", "natural_probability", "formula", "charge"],
+        ascending=[True, False, False, True, True],
+        ignore_index=True,
+    )
+
+
+def build_apyt_species_dictionary(
+    selection: pd.DataFrame,
+    *,
+    atomic_volume_nm3: float,
+) -> dict[str, tuple[tuple[int, ...], float]]:
+    if selection.empty:
+        return {}
+    species: dict[str, tuple[tuple[int, ...], float]] = {}
+    for formula, group in selection.groupby("formula", sort=True):
+        charges = tuple(sorted({int(value) for value in group["charge"].tolist()}))
+        species[str(formula)] = (charges, float(atomic_volume_nm3))
+    return species
+
+
+def apyt_species_tables_from_counts(
+    counts_list: list[dict[str, float | int | str]],
+) -> tuple[pd.DataFrame, pd.DataFrame]:
+    species_rows: list[dict[str, object]] = []
+    element_totals: defaultdict[str, float] = defaultdict(float)
+    for item in counts_list:
+        formula = str(item["element"])
+        charge = int(item["charge"])
+        count = float(item["count"])
+        if not np.isfinite(count) or count <= 0.0:
+            continue
+        category = formula_category(formula)
+        species_rows.append(
+            {
+                "species_label": charged_formula_label(formula, charge),
+                "category": category,
+                "charge": charge,
+                "weighted_counts": count,
+                "robust_counts": count,
+            }
+        )
+        for symbol, atom_count in parse_formula(formula).items():
+            element_totals[symbol] += count * float(atom_count)
+    species = pd.DataFrame(species_rows)
+    if species.empty:
+        return pd.DataFrame(), pd.DataFrame()
+    species = species.groupby(["species_label", "category", "charge"], as_index=False).sum(
+        numeric_only=True
+    )
+    total_species = max(float(species["weighted_counts"].sum()), 1.0)
+    species["atomic_percent_weighted"] = 100.0 * species["weighted_counts"] / total_species
+    species["atomic_percent_robust"] = 100.0 * species["robust_counts"] / total_species
+    elements = pd.DataFrame(
+        [
+            {
+                "element": symbol,
+                "weighted_counts": count,
+                "robust_counts": count,
+            }
+            for symbol, count in sorted(element_totals.items())
+        ]
+    )
+    total_elements = max(float(elements["weighted_counts"].sum()), 1.0)
+    elements["atomic_percent_weighted"] = 100.0 * elements["weighted_counts"] / total_elements
+    elements["atomic_percent_robust"] = 100.0 * elements["robust_counts"] / total_elements
+    return (
+        species.sort_values("atomic_percent_weighted", ascending=False, ignore_index=True),
+        elements.sort_values("atomic_percent_weighted", ascending=False, ignore_index=True),
+    )