firepype 0.0.1__py3-none-any.whl

firepype/utils.py

@@ -0,0 +1,344 @@
+# firepype/utils.py
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable, Tuple
+
+import numpy as np
+from scipy.ndimage import gaussian_filter1d
+
+
+def ensure_dir(p: str | Path):
+    """
+    Purpose:
+        Create a directory (and all missing parents) if it does not already exist
+    Inputs:
+        p: Path-like string or Path to the directory to create
+    Returns:
+        None
+    """
+
+    Path(p).mkdir(parents=True, exist_ok=True)
+
+
+def sg_window_len(n_points: int, preferred: int, min_odd: int = 5) -> int:
+    """
+    Purpose:
+        Compute odd window length for filtering/smoothing that:
+        - Does not exceed n_points
+        - Is at least min_odd
+        - Is as close as possible to preferred
+        - Is odd (decremented by 1 if even)
+    Inputs:
+        n_points: Total number of points available (upper bound for window)
+        preferred: Preferred window length
+        min_odd: Minimum allowed odd window length (default 5)
+    Returns:
+        int:
+            An odd window length satisfying the constraints (>=3 if possible)
+    """
+
+    if n_points <= 0:
+        return 0
+
+    w = min(preferred, n_points)
+
+    if w % 2 == 0:
+        w -= 1
+
+    w = max(w, min_odd)
+
+    if w > n_points:
+        w = n_points if (n_points % 2 == 1) else (n_points - 1)
+
+    return max(w, 3)
+
+
+def cheb_design_matrix(x: np.ndarray, deg: int) -> np.ndarray:
+    """
+    Purpose:
+        Build Chebyshev T_k(x) design matrix up to degree for inputs x in [-1, 1]
+    Inputs:
+        x: 1D array of input values (ideally scaled to [-1, 1])
+        deg: Non-negative integer degree of polynomial basis
+    Returns:
+        np.ndarray:
+            Matrix of shape (len(x), deg+1) with columns [T0(x), T1(x), ..., T_deg(x)]
+    """
+
+    x = np.asarray(x, float)
+    X = np.ones((x.size, deg + 1), float)
+
+    if deg >= 1:
+        X[:, 1] = x
+
+    for k in range(2, deg + 1):
+        X[:, k] = 2.0 * x * X[:, k - 1] - X[:, k - 2]
+
+    return X
+
+
+def robust_weights(residuals: np.ndarray, c: float = 4.685) -> np.ndarray:
+    """
+    Purpose:
+        Compute Tukey's biweight (squared) robust regression weights from residuals.
+        Points with |u| >= 1 (u = r/(c*s)) receive zero weight
+    Inputs:
+        residuals: 1D array of residual values
+        c: Tuning constant controlling downweighting (default 4.685)
+    Returns:
+        np.ndarray:
+            Weights in [0, 1], same shape as residuals
+    """
+
+    r = np.asarray(residuals, float)
+    s = np.nanmedian(np.abs(r - np.nanmedian(r))) * 1.4826 + 1e-12
+    u = r / (c * s)
+    w = (1 - u**2)
+    w[(np.abs(u) >= 1) | ~np.isfinite(w)] = 0.0
+
+    return w**2
+
+
+def orient_to_increasing(wl: np.ndarray, fx: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Purpose:
+        Ensure wavelength array increases with index. If decreasing, reverse both
+        wavelength and flux arrays to maintain alignment
+    Inputs:
+        wl: 1D array of wavelengths
+        fx: 1D array of flux values aligned with wl
+    Returns:
+        tuple:
+            - wl_out (np.ndarray): Wavelengths in increasing order
+            - fx_out (np.ndarray): Flux values reoriented to match wl_out
+    """
+
+    wl = np.asarray(wl, float)
+    fx = np.asarray(fx, float)
+
+    if wl.size >= 2 and wl[0] > wl[-1]:
+        return wl[::-1], fx[::-1]
+
+    return wl, fx
+
+
+def assert_monotonic_and_align(
+    wl: np.ndarray,
+    fx: np.ndarray,
+    name: str = "",
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Purpose:
+        Clean and align wavelength and flux arrays by:
+        - Dropping non-finite entries
+        - Sorting by wavelength
+        - Enforcing strictly increasing wavelengths (removing non-increasing steps)
+        Raises if monotonicity cannot be achieved
+    Inputs:
+        wl: 1D array of wavelengths
+        fx: 1D array of flux values aligned with wl
+        name: Optional label used in error messages
+    Returns:
+        tuple:
+            - wl_out (np.ndarray): Strictly increasing wavelengths
+            - fx_out (np.ndarray): Flux aligned to wl_out
+    Raises:
+        RuntimeError: If wavelengths are not strictly increasing after alignment
+    """
+
+    wl = np.asarray(wl, float)
+    fx = np.asarray(fx, float)
+    m = np.isfinite(wl) & np.isfinite(fx)
+    wl = wl[m]
+    fx = fx[m]
+
+    if wl.size == 0:
+        return wl, fx
+
+    idx = np.argsort(wl)
+    wl = wl[idx]
+    fx = fx[idx]
+
+    if wl.size >= 2:
+        good = np.concatenate(([True], np.diff(wl) > 0))
+        wl = wl[good]
+        fx = fx[good]
+
+    if wl.size >= 2 and not np.all(np.diff(wl) > 0):
+        raise RuntimeError(f"{name}: wl not strictly increasing after alignment")
+
+    return wl, fx
+
+
+# -------------------- Interpolation and mask helpers --------------------
+def mask_interp_edge_artifacts(
+    grid_wl: np.ndarray,
+    wl_native: np.ndarray,
+    f_native: np.ndarray | None,
+    err_native: np.ndarray | None,
+    *,
+    min_span_px: int = 10,
+    pad_bins: int = 8,
+    min_keep_bins: int = 24,
+) -> np.ndarray:
+    """
+    Purpose:
+        Build a boolean mask (True=keep) on the coadd grid that retains only bins
+        well-supported by native data
+        Rules:
+          1) Keep bins strictly inside native wavelength span
+          2) Trim pad_bins bins from both ends of each inside segment
+          3) Drop any inside segment shorter than min_keep_bins
+          4) If native span < min_span_px, keep nothing
+    Inputs:
+        grid_wl: 1D coadd wavelength grid
+        wl_native: 1D native wavelengths where data exist.
+        f_native: Native flux (unused; present for API symmetry)
+        err_native: Native errors (unused; present for API symmetry)
+        min_span_px: Minimum contiguous native length (pixels) to consider (default 10)
+        pad_bins: Padding to exclude at both ends of each inside segment (default 8)
+        min_keep_bins: Minimum interior length to keep after padding (default 24)
+    Returns:
+        np.ndarray:
+            Boolean mask on grid_wl where True indicates bins to keep
+    """
+    grid_wl = np.asarray(grid_wl, float)
+    wl_native = np.asarray(wl_native, float)
+    if wl_native.size < max(3, min_span_px) or not np.any(np.isfinite(wl_native)):
+        return np.zeros_like(grid_wl, dtype=bool)
+    wmin = np.nanmin(wl_native)
+    wmax = np.nanmax(wl_native)
+    inside = np.isfinite(grid_wl) & (grid_wl > wmin) & (grid_wl < wmax)
+
+    keep = np.zeros_like(inside, dtype=bool)
+    n = inside.size
+    i = 0
+    while i < n:
+        if not inside[i]:
+            i += 1
+            continue
+        j = i
+        while j < n and inside[j]:
+            j += 1
+        ii = i + pad_bins
+        jj = j - pad_bins
+        if jj - ii >= min_keep_bins:
+            keep[ii:jj] = True
+        i = j
+    return keep
+
+
+def clean_bool_runs(mask: np.ndarray, min_run: int = 24) -> np.ndarray:
+    """
+    Purpose:
+        Remove short True segments from a boolean mask. Any contiguous run of True
+        values shorter than min_run is set to False
+    Inputs:
+        mask: Boolean array
+        min_run: Minimum run-length of True values to retain (default 24)
+    Returns:
+        np.ndarray:
+            Cleaned boolean mask
+    """
+    m = np.asarray(mask, bool).copy()
+    n = m.size
+    i = 0
+    while i < n:
+        if not m[i]:
+            i += 1
+            continue
+        j = i
+        while j < n and m[j]:
+            j += 1
+        if (j - i) < min_run:
+            m[i:j] = False
+        i = j
+    return m
+
+
+# -------------------- Sky-line helper --------------------
+def skyline_mask_from_1d(y: np.ndarray, sigma_hi: float = 3.0, win: int = 51) -> np.ndarray:
+    """
+    Purpose:
+        Identify strong skyline-like deviations in a 1D vector using high-pass
+        filtering and a robust MAD-based threshold
+    Inputs:
+        y: 1D array of values
+        sigma_hi: Threshold in Gaussian sigmas for detection (default 3.0)
+        win: Window parameter guiding the smoothing scale (default 51)
+    Returns:
+        np.ndarray:
+            Boolean mask of same length as y where True indicates a skyline-like outlier
+    """
+    y = np.asarray(y, float)
+    if y.size < 20:
+        return np.zeros_like(y, dtype=bool)
+    base = gaussian_filter1d(y, max(5, win // 4), mode="nearest")
+    hp = y - base
+    mad = np.nanmedian(np.abs(hp - np.nanmedian(hp))) + 1e-12
+    thr = sigma_hi * 1.4826 * mad
+    return np.abs(hp) > thr
+
+
+# -------------------- Line list loader --------------------
+def load_line_list_to_microns(path: str | Path) -> np.ndarray:
+    """
+    Purpose:
+        Load a line list file of wavelengths with optional units and convert to microns.
+        Supported units: um/µm/micron(s), nm, A/Angstrom(s). Bare numbers are
+        heuristically interpreted based on magnitude
+    Inputs:
+        path: Path to the text file containing wavelengths, one or more tokens per line
+              Lines starting with '#' are ignored; commas are allowed
+    Returns:
+        np.ndarray:
+            Sorted 1D float array of wavelengths in microns
+    """
+    waves: list[float] = []
+    with open(path, "r") as f:
+        for raw in f:
+            s = raw.strip()
+            if not s or s.startswith("#"):
+                continue
+            parts = s.replace(",", " ").split()
+            val = None
+            unit = None
+            for tok in parts:
+                t = tok.strip()
+                tl = t.lower()
+                try:
+                    if tl.endswith(("um", "µm", "micron", "microns")):
+                        unit = "um"
+                        num = "".join(ch for ch in t if (ch.isdigit() or ch in ".-+eE"))
+                        val = float(num)
+                        break
+                    if tl.endswith("nm"):
+                        unit = "nm"
+                        val = float(t[:-2])
+                        break
+                    if tl.endswith(("a", "ang", "angs", "angstrom", "angstroms")):
+                        unit = "A"
+                        num = "".join(ch for ch in t if (ch.isdigit() or ch in ".-+eE"))
+                        val = float(num)
+                        break
+                    # bare number
+                    val = float(t)
+                    unit = None
+                    break
+                except Exception:
+                    continue
+            if val is None:
+                continue
+            if unit is None:
+                # heuristic unit inference
+                if val > 1000:
+                    unit = "A"
+                elif 400 <= val <= 5000:
+                    unit = "nm"
+                else:
+                    unit = "um"
+            waves.append(val if unit == "um" else val / 1000.0 if unit == "nm" else val / 1e4)
+    arr = np.array(waves, dtype=float)
+    arr = arr[np.isfinite(arr)]
+    return np.sort(arr)

firepype-0.0.1.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: firepype
+Version: 0.0.1
+Summary: FIRE AB-pair NIR reduction pipeline
+Author: Gemma Cheng
+License: MIT
+Project-URL: Homepage, https://github.com/gemma-cheng/firepype
+Project-URL: Repository, https://github.com/gemma-cheng/firepype.git
+Project-URL: Issues, https://github.com/gemma-cheng/firepype/issues
+Keywords: astronomy,spectroscopy,FIRE,infrared,data-reduction
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.9
+Requires-Dist: astropy>=5.2
+Requires-Dist: matplotlib>=3.6
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# firepype
+
+Python pipeline for Magellan/FIRE Prism-mode data. Experimental; validated on a limited dataset. Verify outputs against established pipelines (e.g. [FireHose_v2](https://github.com/jgagneastro/FireHose_v2/)).
+
+## Features
+
+- Slit edge and object detection with robust heuristics
+- Arc 1D extraction and line matching
+- Robust Chebyshev dispersion solution with optional anchors
+- Parity-aware A–B/B–A differencing and robust negative-beam scaling
+- Footprint median extraction with error estimates
+- Interpolation-edge masking and inverse-variance coaddition
+- Telluric correction:
+  - POS-only standard extraction
+  - Band-wise scaling with deep-gap masking
+  - Vega model broadened to the instrument resolution
+  - Transmission (T) smoothing only inside dense contiguous regions
+- Optional QA plots: arc overlays, labeled arc 1D, final coadd, telluric T(λ), corrected spectra
+
+## Installation
+
+Installation (PyPi):
+
+```python -m venv .venv
+. .venv/bin/activate  # Windows: .venv\Scripts\activate
+python -m pip install -U pip
+pip install firepype
+```
+
+Alternatively, install from source:
+
+```python -m venv .venv
+. .venv/bin/activate
+python -m pip install -U pip
+git clone https://github.com/gemma-cheng/firepype
+cd firepype
+pip install -e .[dev]
+```
+
+Requirements:
+- Python 3.10–3.12
+- numpy ≥ 1.22, scipy ≥ 1.9, astropy ≥ 5.2, matplotlib ≥ 3.6
+
+
+## Quickstart
+
+Minimal end-to-end reduction:
+
+```
+firepype \
+  --raw-dir /path/to/raw \
+  --out-dir ./out \
+  --arc /path/to/raw/fire_0123.fits \
+  --ref-list /path/to/ref/line_list.lst \
+  --spec "1-4, 10-7"
+```
+
+Telluric/response only:
+```
+firepype-telluric \
+  --standard ./out/standard_extracted.fits \
+  --out-dir ./out/telluric \
+  --stype A0V --plot
+```
+
+Outputs
+- ./output/qa/ … if QA enabled
+- Coadded spectrum FITS: wavelength_um, flux
+- Telluric and response FITS in out/telluric/
+
+
+## Basic Tutorials
+
+Basic usage tutorials can be found in the [`tutorials`](./tutorials/) directory
+
+
+## Notes on telluric method
+
+- Standard extraction: POS-only column, tuned aperture/background; alternative beam used if POS median is non-positive
+- Wavecal: average across a small footprint around the chosen standard column, using ARC + line list
+- Vega model: broadened to instrument resolution (R ~ 6000 by default) in log-λ space
+- Continuum: robust Chebyshev fit to the standard/model ratio within each band (J/H/K), excluding deep telluric gaps and known A0V intrinsic lines; fit is used to normalize before deriving T
+- Transmission T(λ): computed and lightly smoothed only within dense contiguous support (prevents spreading across gaps)
+- Application: science flux and errors are divided by T within overlap where T_min ≤ T ≤ T_max; elsewhere, values are left as NaN to avoid artifacts
+
+
+## Limitations and validation
+
+- Tested on a limited set of FIRE Prism-mode observations; results are not guaranteed.
+- Validate outputs against established pipelines (e.g. [FireHose_v2](https://github.com/jgagneastro/FireHose_v2/)):
+  - Wavelength RMS per region
+  - Sky residuals around OH lines
+  - Merged-order continuity
+  - S/N consistency
+
+
+## License
+
+MIT (see [`LICENSE`](./LICENSE)).
+
+
+## File Structure
+
+- `firepype/`
+  - `__init__.py` — package API (exposes `run_ab_pairs`, `apply_telluric_correction`)
+  - `config.py` — dataclasses for configuration
+  - `io.py` — FITS I/O, path builders, ID pairing
+  - `utils.py` — math helpers, masks, line-list loader
+  - `calibration.py` — peak detection, line matching, dispersion solver
+  - `detection.py` — slit/object detection, parity, negative scaling
+  - `extraction.py` — 1D extraction routines
+  - `coadd.py` — coaddition accumulator
+  - `plotting.py` — optional QA plotting
+  - `pipeline.py` — high-level AB-pair orchestration
+  - `telluric.py` — telluric correction API
+  - `cli.py` — command-line interface (pipeline + telluric subcommand if enabled)
+- `tests/` — minimal tests for core functionality
+- `pyproject.toml` — packaging configuration
+- `README.md` — this file
+- `LICENSE`

firepype-0.0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+firepype/__init__.py,sha256=xLNpzFiR9836YIZRlyRDazMzAvs26EfsKyCk2FOulNo,530
+firepype/calibration.py,sha256=fnqjlQ5gX0gc_UfS0NreppdE4Fpo0FOfH9bzUdid80E,17745
+firepype/cli.py,sha256=GR-Q6HwQ92ERiUQGtbAEiOEV8vXlcFoltBaofgpjOyw,8833
+firepype/coadd.py,sha256=GkXAYSp7ta_XuJ2RKjKxICKDa3a-_PT9-Vk-dD48YBA,3572
+firepype/config.py,sha256=5LZ1jWKFKLtty6kFjTE8-KfzMkyo9ZloaQBp7ByRmtY,1507
+firepype/detection.py,sha256=mjWL88YcxzOEE1apT6WGm_C5PYwfIyiUQ-iuI5xqCoE,17643
+firepype/extraction.py,sha256=szuWuVy41NeKMTTJkP1qb9OWBYQPItW-vDvcda59fGM,6731
+firepype/io.py,sha256=1PcAsonkyiyNj6Z6y9e0i_QM5qehCr83nuuzOhgoIf0,8016
+firepype/pipeline.py,sha256=y6Fxo8WtkA_xrtAonrMwkbtQowkPAMtBim5yX_BNA3U,11838
+firepype/plotting.py,sha256=QA5zMSn1K4FsaDSyKtGOTqFKJXlsu8Xzc7JU5ZmYk7k,7809
+firepype/telluric.py,sha256=2BZbM2D0kpOaSnK5iWeakvFMIvezryl0GkSlOhZCRgo,45641
+firepype/utils.py,sha256=zaKRnjiX4u34F18ARjOC0BH6b5U446jQqRjFqt6cRQM,10815
+firepype-0.0.1.dist-info/licenses/LICENSE,sha256=x48N5ZHPdntCIe7-ar6ihNwS14EP6Qrh3lomJszfqOg,1068
+firepype-0.0.1.dist-info/METADATA,sha256=7mazulby_bozdt0nEDOr2qMMfqH7mPOlLvfctu5u-LI,5247
+firepype-0.0.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+firepype-0.0.1.dist-info/entry_points.txt,sha256=kDNIahVdISpH9Sp9XOigY5L0CgIc_jbUVV0Qh3_cPmY,94
+firepype-0.0.1.dist-info/top_level.txt,sha256=zoxsw_Fp0xGN4gIuhxSMwaVVkYvhliujeehZ4TnK_Lo,9
+firepype-0.0.1.dist-info/RECORD,,

firepype-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

firepype-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+firepype = firepype.cli:main
+firepype-telluric = firepype.cli:main_telluric

firepype-0.0.1.dist-info/licenses/LICENSE

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

firepype-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+firepype