# mauricioayllon/nasa-gamma architecture

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

- Interactive diagram: https://gitdiagram.com/mauricioayllon/nasa-gamma
- Repository: https://github.com/mauricioayllon/nasa-gamma

## Overview

##### Project Type and Purpose
- From the README and file tree, the project is clearly a scientific application focused on gamma spectroscopy. It provides functionalities such as spectrum smoothing, rebinning, peak searching/fitting, energy/efficiency calibration, and data visualization.
- It is a full-featured application that includes a fully functional Qt-based GUI and several command/script examples. The project supports both interactive data exploration (via the GUI) and scripted analyses (via example scripts and Jupyter notebooks).

##### File Structure
- Top-Level Files: Files like .gitignore, LICENSE, README.md, setup.py, and pyproject.toml indicate packaging and development configuration.
- Examples Directory: Contains numerous example Jupyter notebooks and .py scripts that demonstrate various functionalities (e.g., spectrum analysis, calibration, diagnostics). Also includes a data subfolder with raw spectral data in various formats.
- nasagamma Directory: This is the core module containing numerous Python scripts (e.g., peaksearch.py, peakfit.py, energy_calibration.py) that implement the analysis algorithms and spectroscopy operations. It also includes various UI description files (e.g., *.ui) that are used in the GUI.
- GUI Components: The “gammaGUI-qt” file along with various *.ui files (win_info_main.ui, qt_gui.ui, etc.) indicate that a Qt-based interface is used for visualization and user interaction.
- Additional Support Scripts: Scripts like mplwidget.py provide integrated plotting support (presumably with matplotlib).

##### Core Components
a. GUI Layer:
- Component: Qt-based Graphical User Interface (gammaGUI-qt and associated *.ui files)
- Dependencies: Likely uses PyQt and matplotlib (mplwidget.py).

b. Core Processing Module:
- Component: The "nasagamma" package
- Sub-components:
- Spectrum Processing: Files such as spectrum.py, peaksearch.py, peakfit.py, smoothing functions, and decomposition routines.
- Calibration: energy_calibration.py and efficiency.py manage energy and efficiency calibration.
- Data Handling: file_reader.py, read_cnf.py, read_parquet_api.py for importing various data formats.
- Diagnostic and Advanced Fit: diagnostics.py and advanced_fit.py support extended analysis and model fitting.
- Role: Implements the algorithms and functionality for gamma spectroscopy analysis.

c. Data Storage and I/O:
- Component: File structures and example data (contained within the examples/data directory)
- Purpose: Acts as the data repository for testing and demonstrating the tools’ capabilities.
- Interaction: The GUI and core module depend on these files for analysis runs.

d. Examples and User Scripts:
- Component: The “examples” directory with notebooks and scripts illustrating usage.
- Purpose: Demonstrates how each functionality can be utilized independently or integrated through the GUI.
- Role: Serves as documentation and test cases to validate system behavior.

##### Relationships and Architectural Patterns
- Data Flow: Illustrate how data originates from user-selected files (examples/data) and flows into the GUI or directly to core functions.
- Interaction: The GUI component sends commands to the core processing module (for tasks like peak search or calibration), and the results are rendered through plots and UI windows. Similarly, the example scripts can bypass the GUI to interact directly with the core library.
- Layering: Show a separation between the presentation layer (GUI) and the business logic (nasagamma modules), with clear data I/O modules to support file reading.
- Design Pattern: Although not explicitly an MVC framework, conceptually the separation of UI (View/Controller) and core algorithms (Model) is beneficial for understanding the system.

##### Technologies and Tools to Highlight
- Python 3.6+ as the programming language.
- PyQt (indicated by *.ui files and “gammaGUI-qt”).
- Matplotlib (supported by mplwidget.py) for visualization.
- Possibly Pandas or similar libraries for data handling (although not directly referenced, typical in such projects).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Storage and I/O
    subgraph "Data Storage and I/O"
        DATA1("Examples Data"):::data
        DATA2("Core Data Files"):::data
    end

    %% Examples & User Scripts
    subgraph "Examples & Scripts"
        EX("Examples & Scripts"):::examples
    end

    %% Core Processing Module
    subgraph "Core Processing Module"
        %% Spectrum Processing
        subgraph "Spectrum Processing"
            SPEC("spectrum.py"):::core
            PS("peaksearch.py"):::core
            PF("peakfit.py"):::core
            DE("decay_exponential.py"):::core
            RES("resolution.py"):::core
        end
        %% Calibration & Efficiency
        subgraph "Calibration & Efficiency"
            EC("energy_calibration.py"):::core
            EFF("efficiency.py"):::core
            APIcalc("apicalc.py"):::core
        end
        %% Data Handling
        subgraph "Data Handling"
            FR("file_reader.py"):::core
            CNF("read_cnf.py"):::core
            RP("read_parquet_api.py"):::core
            PH("param_handle.py"):::core
            NIST("parse_NIST.py"):::core
            TL("tlist.py"):::core
        end
        %% Diagnostics and Advanced Fit
        subgraph "Diagnostics & Advanced Fit"
            DIAG("diagnostics.py"):::core
            ADVFIT("advanced_fit.py"):::core
        end
        %% Helper Functions
        HELPER("helper_api.py"):::core
    end

    %% GUI Layer
    subgraph "GUI Layer"
        GUI1("gammaGUI-qt"):::gui
        subgraph "UI Files"
            UI1("qt_gui.ui"):::gui
            UI2("win_info_main.ui"):::gui
            UI3("win_peak_find.ui"):::gui
            UI4("win_eff.ui"):::gui
            UI5("win_erg_cal.ui"):::gui
            UI6("win_erg_cal_add_point.ui"):::gui
            UI7("win_erg_cal_eqns.ui"):::gui
            UI8("win_info_add_subt.ui"):::gui
            UI9("win_info_customize.ui"):::gui
            UI10("win_info_ecal.ui"):::gui
            UI11("win_info_eff.ui"):::gui
            UI12("win_info_file.ui"):::gui
            UI13("win_info_isot_id.ui"):::gui
            UI14("win_info_peak_find.ui"):::gui
            UI15("win_info_png.ui"):::gui
            UI16("win_isot_id.ui"):::gui
            UI17("win_add_subtract.ui"):::gui
            UI18("win_adv_fit.ui"):::gui
            UI19("win_api_3D.ui"):::gui
            UI20("win_api_filters.ui"):::gui
            UI21("win_api_mca.ui"):::gui
        end
        MWP("mplwidget.py"):::gui
    end

    %% Relationships and Data Flow
    %% Data Sources flow into Core Processing Module
    DATA1 -->|"input"| SPEC
    DATA2 -->|"input"| SPEC

    %% Examples & Scripts invoking Core Processing functions (via Data Handling)
    EX -->|"scriptCall"| FR

    %% GUI Layer triggers analysis in Core Processing Module (using Spectrum Processing & others)
    GUI1 -->|"process"| PS
    %% Core Processing returns results to the GUI
    PS -->|"result"| GUI1

    %% Class Definitions for colour
    classDef gui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef core fill:#ABEBC6,stroke:#229954,stroke-width:2px;
    classDef data fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef examples fill:#F5CBA7,stroke:#D35400,stroke-width:2px;

    %% Click Events for GUI Layer
    click GUI1 "https://github.com/mauricioayllon/nasa-gamma/tree/master/gammaGUI-qt"
    click UI1 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/qt_gui.ui"
    click UI2 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_info_main.ui"
    click UI3 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_peak_find.ui"
    click UI4 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_eff.ui"
    click UI5 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_erg_cal.ui"
    click UI6 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_erg_cal_add_point.ui"
    click UI7 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_erg_cal_eqns.ui"
    click UI8 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_info_add_subt.ui"
    click UI9 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_info_customize.ui"
    click UI10 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_info_ecal.ui"
    click UI11 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_info_eff.ui"
    click UI12 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_info_file.ui"
    click UI13 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_info_isot_id.ui"
    click UI14 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_info_peak_find.ui"
    click UI15 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_info_png.ui"
    click UI16 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_isot_id.ui"
    click UI17 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_add_subtract.ui"
    click UI18 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_adv_fit.ui"
    click UI19 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_api_3D.ui"
    click UI20 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_api_filters.ui"
    click UI21 "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/win_api_mca.ui"
    click MWP "https://github.com/mauricioayllon/nasa-gamma/blob/master/mplwidget.py"

    %% Click Events for Core Processing Module
    click SPEC "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/spectrum.py"
    click PS "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/peaksearch.py"
    click PF "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/peakfit.py"
    click DE "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/decay_exponential.py"
    click RES "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/resolution.py"
    click EC "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/energy_calibration.py"
    click EFF "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/efficiency.py"
    click APIcalc "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/apicalc.py"
    click FR "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/file_reader.py"
    click CNF "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/read_cnf.py"
    click RP "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/read_parquet_api.py"
    click PH "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/param_handle.py"
    click NIST "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/parse_NIST.py"
    click TL "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/tlist.py"
    click DIAG "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/diagnostics.py"
    click ADVFIT "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/advanced_fit.py"
    click HELPER "https://github.com/mauricioayllon/nasa-gamma/blob/master/nasagamma/helper_api.py"

    %% Click Events for Data Storage and I/O
    click DATA1 "https://github.com/mauricioayllon/nasa-gamma/tree/master/examples/data"
    click DATA2 "https://github.com/mauricioayllon/nasa-gamma/tree/master/nasagamma/data"

    %% Click Event for Examples & Scripts
    click EX "https://github.com/mauricioayllon/nasa-gamma/tree/master/examples"
```
