How jigonzal/lineseeker works
Project Type and Purpose
• This is a Python‐based command-line data analysis pipeline (an open-source tool) for detecting emission‐line candidates in ALMA radio astronomy data cubes.
• It consists of three main user-invoked scripts (SearchLine.py, SimulateCubeSearch.py, GetLineCandidates.py) plus a shared function library (LineSeekerFunctions.py).
• The pipeline ingests a FITS data cube, applies a line-search algorithm, optionally runs Monte Carlo simulations, then computes candidate lists with false-alarm probabilities.
File Structure Analysis
• Top-level scripts:
• SearchLine.py – scans a cube for peaks over multiple spectral convolutions
• SimulateCubeSearch.py – runs the same search on simulated Gaussian noise cubes
• GetLineCandidates.py – combines results from SearchLine (and SimulateCubeSearch if used) to estimate line reliability
• Shared code: LineSeekerFunctions.py contains reusable routines (I/O, convolution, fitting, plotting).
• README.md describes usage, parameters, workflow.
• No dedicated “src” or “tests” directories; all code lives at root.
Key Components
a. Data Inputs
• FITS data cube (user-specified via –Cube flag)
• (Optional) Continuum image (mask generation)
• Configuration parameters (MinSN, MaxSigmas, LimitN, UserEPS, EPS)
b. Processing Modules
1. SearchLine Module
• Reads cube, applies Gaussian kernels of various widths
• Detects positive and negative line candidates
• Writes per-kernel detection files into an output folder
2. Simulation Module (SimulateCubeSearch)
• Generates N simulated cubes with Gaussian noise
• Applies same SearchLine routines
• Stores simulated detection statistics
3. Candidate Extraction Module (GetLineCandidates)
• Ingests SearchLine output (and simulation output if present)
• Fits negative-count distributions per kernel
• Computes probabilities and error estimates
• Produces summary tables and diagnostic plots (PDFs)
c. Outputs
• Text/CSV lists of line candidates with S/N, probabilities
• Diagnostic PDF plots (NumberPositiveNegative_x.pdf)
• Log messages on the console
d. External Dependencies
• astropy.io.fits (FITS I/O)
• numpy, scipy (kernels, statistics, fitting)
• matplotlib (plots)
• Python 3.x standard libraries (argparse, os, subprocess)
Relationships and Data Flow
• Start: User invokes SearchLine.py
→ Input: FITS cube, parameters
→ Process: convolution & detection loops
→ Output: folder “OutputLineSearch” containing per-kernel detection files
• Optional branch: User invokes SimulateCubeSearch.py
→ Reads same parameters, loops over simulated cubes
→ Output: folder “OutputSimulations” or similar
• Final stage: User invokes GetLineCandidates.py
→ Reads both previous outputs
→ Fits negative counts, computes candidate statistics
→ Outputs combined candidate list + plots
Architectural Patterns and Design Principles
• Modular CLI architecture: each script is a self-contained module that can be run independently but shares a common function library.
• Data-driven pipeline: outputs of one step form the inputs of the next; uses filesystem as message bus.
• Separation of concerns:
• SearchLine focuses purely on feature detection
• SimulateCubeSearch generates statistical baseline
• GetLineCandidates performs statistical inference and reporting
• Parameterization via command-line flags allows flexibility and reproducibility.
Essential Elements to Capture
• Clear component names matching file names.
• Distinction between real‐data branch and simulation branch.