firepype 0.0.1__py3-none-any.whl

firepype/cli.py

@@ -0,0 +1,296 @@
+# firepype/cli.py
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from .config import PipelineConfig, RunSpec
+from .pipeline import run_ab_pairs
+
+
+def main():
+    """
+    Purpose:
+        Command-line entry point for the FIRE AB-pair NIR reduction pipeline.
+        Parses CLI arguments, constructs PipelineConfig (applying optional
+        overrides), and executes AB-pair processing to produce co-added
+        spectrum and QA outputs
+    Inputs:
+        None (arguments are read from sys.argv via argparse)
+    Returns:
+        None
+            Runs the pipeline and writes outputs to disk. Exits with argparse
+            error messages on invalid usage
+    CLI options:
+        --raw-dir         Directory with raw FITS files (required)
+        --out-dir         Output directory for products and QA (required)
+        --arc             Path to ARC frame FITS (required)
+        --ref-list        Path to reference line list file (required)
+        --spec            Frame spec string for AB pairing (required)
+        --no-qa           Disable QA plots (optional flag)
+        --ap-radius       Extraction aperture half-width in pixels (optional)
+        --bg-in           Inner background offset in pixels (optional)
+        --bg-out          Outer background offset in pixels (optional)
+        --footprint-half  Half-size (columns) for footprint median combine (optional)
+        --wl-min          Wavelength range minimum in microns (optional)
+        --wl-max          Wavelength range maximum in microns (optional)
+        --grid-step       Wavelength grid step for coadd in microns (optional)
+        --verbose         Enable verbose diagnostic prints (optional)
+    """
+
+    p = argparse.ArgumentParser(
+        prog="firepype",
+        description="FIRE AB-pair NIR reduction pipeline",
+    )
+
+    p.add_argument(
+        "--raw-dir",
+        required=True,
+        help="Directory containing raw FITS files (e.g., /data/raw)",
+    )
+
+    p.add_argument(
+        "--out-dir",
+        required=True,
+        help="Output directory for products and QA (e.g., ./out)",
+    )
+
+    p.add_argument(
+        "--arc",
+        required=True,
+        help="Path to the ARC frame FITS (e.g., /data/raw/fire_XXXX.fits)",
+    )
+
+    p.add_argument(
+        "--ref-list",
+        required=True,
+        help="Path to the line list file (e.g., /data/ref/line_list.lst)",
+    )
+
+    p.add_argument(
+        "--spec",
+        required=True,
+        help='Frame spec string for AB pairing, e.g. "XXXX-XXXX" or "XX-XX,XX-XX"',
+    )
+
+    p.add_argument(
+        "--no-qa",
+        action="store_true",
+        help="Disable QA plots",
+    )
+
+    # Optional default overrides
+    p.add_argument(
+        "--ap-radius", type=int, default=None, help="Extraction aperture half-width (px)"
+    )
+
+    p.add_argument(
+        "--bg-in", type=int, default=None, help="Inner background offset (px)"
+    )
+
+    p.add_argument(
+        "--bg-out", type=int, default=None, help="Outer background offset (px)"
+    )
+
+    p.add_argument(
+        "--footprint-half",
+        type=int,
+        default=None,
+        help="Half-size (in columns) for footprint median combine",
+    )
+
+    p.add_argument(
+        "--wl-min", type=float, default=None, help="Wavelength range min (micron)"
+    )
+    p.add_argument(
+        "--wl-max", type=float, default=None, help="Wavelength range max (micron)"
+    )
+    p.add_argument(
+        "--grid-step", type=float, default=None, help="Grid step for coadd (micron)"
+    )
+    p.add_argument(
+        "--verbose", action="store_true", help="Verbose detection/diagnostic prints"
+    )
+
+    args = p.parse_args()
+
+    # Build config with defaults, then override if provided
+    cfg = PipelineConfig(
+        run=RunSpec(
+            raw_dir=Path(args.raw_dir),
+            out_dir=Path(args.out_dir),
+            arc_path=Path(args.arc),
+            ref_list_path=Path(args.ref_list),
+            user_spec=args.spec,
+        )
+    )
+
+    cfg.qa.save_figs = not args.no_qa
+    cfg.qa.verbose = bool(args.verbose)
+    cfg.qa.out_dir = Path(args.out_dir)
+    cfg.qa.qa_dir = Path(args.out_dir) / "qa"
+
+    if args.ap_radius is not None:
+        cfg.extraction.ap_radius = int(args.ap_radius)
+
+    if args.bg_in is not None:
+        cfg.extraction.bg_in = int(args.bg_in)
+
+    if args.bg_out is not None:
+        cfg.extraction.bg_out = int(args.bg_out)
+
+    if args.footprint_half is not None:
+        cfg.extraction.footprint_half = int(args.footprint_half)
+
+    if args.wl_min is not None or args.wl_max is not None:
+        wl_lo = args.wl_min if args.wl_min is not None else cfg.wavecal.wl_range[0]
+        wl_hi = args.wl_max if args.wl_max is not None else cfg.wavecal.wl_range[1]
+        cfg.wavecal.wl_range = (float(wl_lo), float(wl_hi))
+
+    if args.grid_step is not None:
+        cfg.wavecal.grid_step = float(args.grid_step)
+
+    run_ab_pairs(cfg)
+
+def main_telluric() -> None:
+    """
+    Telluric/response CLI.
+
+    Minimal workflow:
+      - Read a standard-star exposure (or coadd) FITS.
+      - Optionally read a reference spectrum (A0V) to derive response.
+      - Fit/derive telluric transmission and instrument response.
+      - Write out telluric.fits and response.fits (or as configured).
+    """
+    import argparse
+    import sys
+    from pathlib import Path
+
+    parser = argparse.ArgumentParser(
+        prog="firepype-telluric",
+        description="Telluric + instrument response from a standard star",
+    )
+    
+    parser.add_argument(
+        "--standard",
+        required=True,
+        help="Path to standard star FITS (2D or extracted 1D).",
+    )
+    
+    parser.add_argument(
+        "--out-dir",
+        required=True,
+        help="Output directory for telluric/response products.",
+    )
+    
+    parser.add_argument(
+        "--ref-spectrum",
+        default=None,
+        help="Optional path to reference spectrum for the standard "
+             "(e.g., A0V template). If omitted, use built-in or empirical.",
+    )
+    
+    parser.add_argument(
+        "--stype",
+        default="A0V",
+        help='Standard star spectral type (default: "A0V").',
+    )
+    
+    parser.add_argument(
+        "--airmass",
+        type=float,
+        default=None,
+        help="Airmass to use for telluric modeling (override header if given).",
+    )
+    
+    parser.add_argument(
+        "--wl-min",
+        type=float,
+        default=None,
+        help="Minimum wavelength (micron) to include.",
+    )
+    
+    parser.add_argument(
+        "--wl-max",
+        type=float,
+        default=None,
+        help="Maximum wavelength (micron) to include.",
+    )
+    
+    parser.add_argument(
+        "--plot",
+        action="store_true",
+        help="Save diagnostic plots to out-dir.",
+    )
+    
+    parser.add_argument(
+        "--overwrite",
+        action="store_true",
+        help="Overwrite existing outputs.",
+    )
+
+    args = parser.parse_args()
+
+    std_path = Path(args.standard).expanduser().resolve()
+    out_dir = Path(args.out_dir).expanduser().resolve()
+    ref_path = (
+        None
+        if args.ref_spectrum is None
+        else Path(args.ref_spectrum).expanduser().resolve()
+    )
+
+    # Basic validations
+    if not std_path.exists():
+        print(f"error: standard file not found: {std_path}", file=sys.stderr)
+        sys.exit(2)
+    
+    if ref_path is not None and not ref_path.exists():
+        print(f"error: reference spectrum not found: {ref_path}", file=sys.stderr)
+        sys.exit(2)
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # Default output filenames
+    telluric_out = out_dir / "telluric.fits"
+    response_out = out_dir / "response.fits"
+    qa_dir = out_dir / "qa"
+
+    if not args.overwrite:
+        for p in (telluric_out, response_out):
+            if p.exists():
+                print(f"error: output exists (use --overwrite): {p}", file=sys.stderr)
+                sys.exit(2)
+
+    # Import and run the actual logic
+    try:
+        from .telluric import run_telluric
+    except Exception as e:
+        print(f"error: could not import telluric runner: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        run_telluric(
+            standard_fits=std_path,
+            stype=args.stype,
+            out_telluric=telluric_out,
+            out_response=response_out,
+            ref_spectrum=ref_path,
+            airmass=args.airmass,
+            wl_min=args.wl_min,
+            wl_max=args.wl_max,
+            save_plots=args.plot,
+            qa_dir=qa_dir,
+            overwrite=args.overwrite,
+        )
+    
+    except Exception as e:
+        print(f"error: telluric processing failed: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"wrote: {telluric_out}")
+    print(f"wrote: {response_out}")
+    if args.plot:
+        print(f"qa:    {qa_dir}")
+
+if __name__ == "__main__":
+    main()

firepype/coadd.py

@@ -0,0 +1,105 @@
+# firepype/coadd.py
+from __future__ import annotations
+
+import numpy as np
+
+
+class CoaddAccumulator:
+    """
+    Purpose:
+        Maintain inverse-variance coaddition accumulator on a fixed wavelength
+        grid. Add multiple spectra (already interpolated to this grid) along
+        with their per-bin uncertainties and an optional validity mask; to
+        accumulate weighted sums and producecco-added spectrum and errors
+    Inputs:
+        grid_wl (at init): 1D array of target wavelength grid in microns (or
+            arbitrary units) onto which all spectra are interpolated
+    Returns:
+        CoaddAccumulator instance
+    """
+
+    def __init__(self, grid_wl: np.ndarray):
+        """
+        Purpose:
+            Initialise coaddition accumulator for a specified wavelength grid
+        Inputs:
+            grid_wl: 1D array of wavelengths defining the coadd grid
+        Returns:
+            None
+        """
+
+        self.grid = np.asarray(grid_wl, float)
+        self.flux_sum = np.zeros_like(self.grid, dtype=float)
+        self.weight_sum = np.zeros_like(self.grid, dtype=float)
+
+    def add_spectrum(
+        self,
+        flux: np.ndarray,
+        err: np.ndarray,
+        mask: np.ndarray | None = None,
+    ) -> None:
+        """
+        Purpose:
+            Add single spectrum to accumulator. Spectrum should already be
+            interpolated onto the accumulator's grid (self.grid). Accumulation is
+            performed using inverse-variance weights
+        Inputs:
+            flux: 1D array of flux values on self.grid (same shape as grid)
+            err: 1D array of 1-sigma uncertainties on self.grid (same shape)
+            mask: Optional boolean mask (same shape) where True indicates a bin
+                  should be used. If provided, it is combined with finite/positive
+                  error masking
+        Returns:
+            None
+        Raises:
+            ValueError: If flux/err (or mask, when provided) shapes do not match
+                        the grid shape
+        """
+
+        f = np.asarray(flux, float)
+        e = np.asarray(err, float)
+
+        if f.shape != self.grid.shape or e.shape != self.grid.shape:
+            raise ValueError("flux/err must match grid shape")
+
+        m = np.isfinite(f) & np.isfinite(e) & (e > 0)
+
+        if mask is not None:
+            mask = np.asarray(mask, bool)
+
+            if mask.shape != self.grid.shape:
+                raise ValueError("mask must match grid shape")
+
+            m &= mask
+
+        if not np.any(m):
+            return
+
+        w = 1.0 / np.maximum(e[m] ** 2, 1e-20)
+        self.flux_sum[m] += w * f[m]
+        self.weight_sum[m] += w
+
+
+    def finalize(self) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Purpose:
+            Compute final coadded flux and error arrays from accumulated
+            weighted sums
+        Inputs:
+            None
+        Returns:
+            tuple:
+                - flux (np.ndarray): Weighted-mean flux on self.grid; NaN where no
+                  samples contributed (weight == 0)
+                - err (np.ndarray): 1-sigma uncertainty as sqrt(1/weight); NaN where
+                  weight == 0
+                - used (np.ndarray): Boolean mask where weight > 0 (bins used)
+        """
+
+        used = self.weight_sum > 0
+        flux = np.full_like(self.grid, np.nan, dtype=float)
+        err = np.full_like(self.grid, np.nan, dtype=float)
+        flux[used] = self.flux_sum[used] / self.weight_sum[used]
+        err[used] = np.sqrt(1.0 / self.weight_sum[used])
+
+        return flux, err, used

firepype/config.py

@@ -0,0 +1,55 @@
+# firepype/config.py
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Sequence, Tuple, Optional, List
+
+@dataclass
+class QASettings:
+    save_figs: bool = True
+    verbose: bool = True
+    out_dir: Path = Path("./output")
+    qa_dir: Path = field(default_factory=lambda: Path("./output/qa"))
+
+@dataclass
+class WavecalSettings:
+    wl_range: Tuple[float, float] = (0.83, 2.45)
+    grid_step: float = 0.0008
+    band_anchors_global: Sequence[Tuple[int, float]] = (
+        (100, 0.83),
+        (1000, 1.15),
+        (1600, 1.79),
+        (1950, 2.43),
+    )
+    max_sep: float = 0.012
+    deg: int = 3
+    force_global_orient: str = "fwd"
+
+@dataclass
+class ExtractionSettings:
+    ap_radius: int = 5
+    bg_in: int = 8
+    bg_out: int = 18
+    footprint_half: int = 1
+    row_fraction: Tuple[float, float] = (0.35, 0.85)
+
+@dataclass
+class SlitDetectionSettings:
+    slit_x_hint: Tuple[int, int] = (900, 1300)
+    slit_hint_expand: int = 150
+    row_fraction: Tuple[float, float] = (0.35, 0.85)
+
+@dataclass
+class RunSpec:
+    raw_dir: Path
+    out_dir: Path
+    arc_path: Path
+    ref_list_path: Path
+    user_spec: str  # e.g., "XXXX-XXXX"
+
+@dataclass
+class PipelineConfig:
+    run: RunSpec
+    qa: QASettings = field(default_factory=QASettings)
+    wavecal: WavecalSettings = field(default_factory=WavecalSettings)
+    extraction: ExtractionSettings = field(default_factory=ExtractionSettings)
+    slit: SlitDetectionSettings = field(default_factory=SlitDetectionSettings)