# usra-sti/gamma-ray-targeted-search architecture

> Architecture diagram of the GitHub repository usra-sti/gamma-ray-targeted-search, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/usra-sti/gamma-ray-targeted-search
- Repository: https://github.com/usra-sti/gamma-ray-targeted-search

## Overview

##### Project type and purpose
- From the file tree and README, this is an open-source Python library/CLI tool (“GTS”) for performing mission-agnostic gamma-ray targeted searches.
- It provides:
- A core Python package (gts.py plus support modules: likelihood.py, skymap.py, results.py, plots.py, utils.py)
- A command-line entry point (gbm_targeted_search.py)
- Example notebooks (GBM Example.ipynb, GW170817 Example.ipynb)
- Tests under tests/

##### File structure
- Top-level modules:
- gts.py (core API)
- likelihood.py, skymap.py, results.py, plots.py, utils.py (domain logic)
- gbm_targeted_search.py (CLI wrapper around core API)
- Notebooks demonstrate usage, not part of the runtime flow
- requirements.txt declares dependencies (e.g. gdt, numpy, scipy, astropy)
- tests/ contains unit tests for the core functionality
- No “frontend/backend” split; this is a library + CLI tool.

##### README for additional insights
- Integration with external Gamma-ray Data Tools (gdt), particularly Fermi-GBM mission modules (TriggerFtp, GbmTte, Trigdat, etc.)
- Data flow: fetch TTE and position history → prepare input arrays → load detector response → run search → produce skymap and statistics → optionally plot and save results

##### Main components
a. External Data Sources & Dependencies
– HEASARC/FERMI FTP (TriggerFtp, ContinuousFtp modules from gdt)
– Local filesystem (raw FITS, templates directory)
– Python dependencies: gdt, numpy, scipy, astropy, healpy, matplotlib, etc.
b. Data Acquisition Layer
– gdt mission modules for downloading/reading GBM data (in utils or via direct imports in scripts)
c. Data Preparation Layer
– gts.preparePha2Data (bins TTE data)
– gts.loadResponse (loads pre-computed detector response templates)
d. Core Search Engine
– likelihood.py: constructs Poisson or background models
– skymap.py: computes sky posterior over HEALPix grid
– results.py: aggregates log-likelihood ratios, TS maps, detection statistics
e. Presentation Layer
– plots.py: plots skymaps, spectra, diagnostics
– gbm_targeted_search.py (CLI): exposes --time, --format, --output options
– Example notebooks: drive the same core API interactively
f. Test Suite
– tests/test_gbm_targeted_search.py: validates integration of CLI and core library

##### Relationships and interactions
- The CLI (gbm_targeted_search.py) and notebooks import the gts module + submodules
- Data requests (TTE, trigdat) flow from the CLI or notebook through gdt mission modules into memory
- gts.preparePha2Data and gts.loadResponse produce arrays/objects that feed into the likelihood engine
- The likelihood engine calls skymap routines, writes result objects; results.py serializes or returns Python structures
- plots.py consumes result objects to generate visualizations
- Tests invoke the CLI or core API, checking outputs against known values

##### Architectural patterns / design principles
- Layered architecture (Data acquisition → Preparation → Computation → Presentation)
- Single responsibility per module: each file focuses on one domain concept
- Clear separation between core API (gts.py + submodules) and user interfaces (CLI + notebooks)
- Extensibility via the gdt abstraction for different missions – code is “mission-agnostic”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    subgraph "External Data Sources & Dependencies"
        direction TB
        ext_gdt["gdt Modules (TriggerFtp, GbmTte, Trigdat)"]:::external
        ext_ftp["HEASARC/FERMI FTP"]:::external
        ext_fs["Local Filesystem (FITS, templates)"]:::external
        ext_deps["Python Dependencies"]:::external
    end

    %% Data Acquisition Layer
    subgraph "Data Acquisition Layer"
        direction TB
        utils["Utility Functions & Data Acquisition Helpers"]:::core
    end

    %% Data Preparation Layer
    subgraph "Data Preparation Layer"
        direction TB
        gts_api["Core API Module (gts.py)"]:::core
        prep["gts.preparePha2Data"]:::core
        loadresp["gts.loadResponse"]:::core
    end

    %% Core Search Engine
    subgraph "Core Search Engine"
        direction TB
        likelihood["Likelihood Engine (likelihood.py)"]:::core
        skymap["Sky Map Computation (skymap.py)"]:::core
        results["Results Aggregation (results.py)"]:::core
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        plots["Plotting & Presentation (plots.py)"]:::ui
        cli["CLI Entry Point (gbm_targeted_search.py)"]:::ui
        nb1["Notebook: GBM Example.ipynb"]:::ui
        nb2["Notebook: GW170817 Example.ipynb"]:::ui
    end

    %% Test Suite
    subgraph "Test Suite"
        direction TB
        tests["tests/test_gbm_targeted_search.py"]:::test
    end

    %% Documentation & Config
    subgraph "Docs & Config"
        direction TB
        reqs["requirements.txt"]:::docs
        readme["README.md"]:::docs
        license["license.txt"]:::docs
    end

    %% Data Flow
    ext_gdt -->|"download TTE & trigdat"| utils
    ext_ftp -->|"raw data"| utils
    ext_fs -->|"templates"| loadresp
    ext_deps -->|"libraries"| gts_api

    utils -->|"TTE array"| prep
    utils -->|"detector history"| gts_api
    prep -->|"binned data"| gts_api
    loadresp -->|"response templates"| gts_api

    gts_api -->|"prepared arrays"| likelihood
    likelihood -->|"likelihood maps"| skymap
    skymap -->|"HEALPix posterior"| results
    results -->|"result objects"| plots
    results -->|"result objects"| cli
    results -->|"result objects"| nb1
    results -->|"result objects"| nb2

    cli -->|"console output, files"| ext_fs
    plots -->|"figures"| ext_fs

    %% Tests and Docs interactions
    tests -->|"validate API & CLI"| gts_api
    tests -->|"validate CLI"| cli

    readme -.->|"documentation"| gts_api
    reqs -.->|"declares deps"| ext_deps
    license -.->|"license info"| gts_api

    %% Click Events
    click gts_api "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/gts.py"
    click likelihood "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/likelihood.py"
    click skymap "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/skymap.py"
    click results "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/results.py"
    click plots "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/plots.py"
    click utils "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/utils.py"
    click cli "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/gbm_targeted_search.py"
    click nb1 "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/GBM Example.ipynb"
    click nb2 "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/GW170817 Example.ipynb"
    click tests "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/tests/test_gbm_targeted_search.py"
    click reqs "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/requirements.txt"
    click readme "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/README.md"
    click license "https://github.com/usra-sti/gamma-ray-targeted-search/blob/main/license.txt"

    %% Styles
    classDef external fill:#cccccc,stroke:#888,stroke-dasharray: 5 5;
    classDef core fill:#add8e6,stroke:#000;
    classDef ui fill:#90ee90,stroke:#000;
    classDef test fill:#dda0dd,stroke:#000,stroke-dasharray: 2 2;
    classDef docs fill:#f4a460,stroke:#000;
```
