# jigonzal/lineseeker architecture

> Architecture diagram of the GitHub repository jigonzal/lineseeker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jigonzal/lineseeker
- Repository: https://github.com/jigonzal/lineseeker

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Inputs
    FITS["Input FITS Cube"]:::datastore
    CONFIG["Configuration Parameters\n(MinSN, MaxSigmas,\nLimitN, UserEPS, EPS)"]:::config

    %% LineSeeker CLI Group
    subgraph "LineSeeker CLI"
        SEARCH["SearchLine.py"]:::process
        SIM["SimulateCubeSearch.py"]:::process
        EXTRACT["GetLineCandidates.py"]:::process
        LIB["LineSeekerFunctions.py"]:::library
    end

    %% Data Stores & Outputs
    DETECTIONS["Per-Kernel Detection Files\n(OutputLineSearch/)"]:::datastore
    SIMCUBES["Simulated Cubes (Internal)"]:::datastore
    SIMRESULTS["Simulation Detection Stats\n(OutputSimulations/)"]:::datastore
    CANDLIST["Candidate List CSV/Text"]:::output
    PLOTS["Diagnostic PDF Plots"]:::output
    LOGS["Console Log Messages"]:::output

    %% Documentation
    DOCS["README.md"]:::doc
    GITIGNORE[".gitignore"]:::doc

    %% Pipeline Flow
    FITS -->|"cube + parameters"| SEARCH
    CONFIG --> SEARCH
    SEARCH -->|"detection CSVs"| DETECTIONS

    %% Optional Simulation Branch
    SIMCUBES -.->|"generate N cubes"| SIM
    CONFIG -.-> SIM
    SIM -->|"simulated stats"| SIMRESULTS

    %% Candidate Extraction Stage
    DETECTIONS --> EXTRACT
    SIMRESULTS --> EXTRACT
    CONFIG --> EXTRACT

    EXTRACT -->|"candidate data"| CANDLIST
    EXTRACT -->|"plots PDFs"| PLOTS
    EXTRACT -->|"logs"| LOGS

    %% Shared Library Dependencies
    SEARCH --> LIB
    SIM --> LIB
    EXTRACT --> LIB

    %% Documentation Dependencies
    DOCS -.-> SEARCH
    DOCS -.-> SIM
    DOCS -.-> EXTRACT

    %% Click Events
    click SEARCH "https://github.com/jigonzal/lineseeker/blob/master/SearchLine.py"
    click SIM "https://github.com/jigonzal/lineseeker/blob/master/SimulateCubeSearch.py"
    click EXTRACT "https://github.com/jigonzal/lineseeker/blob/master/GetLineCandidates.py"
    click LIB "https://github.com/jigonzal/lineseeker/blob/master/LineSeekerFunctions.py"
    click DOCS "https://github.com/jigonzal/lineseeker/blob/master/README.md"
    click GITIGNORE "https://github.com/jigonzal/lineseeker/blob/master/.gitignore"

    %% Styles
    classDef process fill:#b2f5b4,stroke:#2f855a,color:#22543d;
    classDef datastore fill:#bee3f8,stroke:#2b6cb0,color:#2a4365,shape:cylinder;
    classDef output fill:#fbd38d,stroke:#dd6b20,color:#7b341e;
    classDef config fill:#e2e8f0,stroke:#4a5568,color:#2d3748,shape:parallelogram;
    classDef library fill:#cbd5e0,stroke:#718096,color:#2d3748;
    classDef doc fill:#f0fff4,stroke:#38a169,color:#22543d,shape:parallelogram;
```
