How usra-sti/gamma-ray-targeted-search works
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”