# remingtonsexton/badass3 architecture

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

- Interactive diagram: https://gitdiagram.com/remingtonsexton/badass3
- Repository: https://github.com/remingtonsexton/badass3

## Overview

##### Project Type and Purpose
- BADASS is an open-source Python library and command-line/Jupyter-Notebook tool for spectral analysis and decomposition of astronomical data (especially SDSS and IFU cubes).
- It reads spectral FITS files, applies continuum and line models, performs maximum-likelihood and MCMC fitting, and writes out best-fit spectra, parameter tables, and diagnostic plots.

##### High-Level Architecture Components
a. Data Layer
– Input Spectra (FITS or NumPy arrays) under `example_spectra/` or user-supplied folders.
– Template Libraries under `badass_data/` (stellar libraries, SSP templates, FeII/UV/balmer templates, neural network model).
b. Configuration Layer
– Notebook interface (`example_notebooks/`) and CLI script (`badass.py`).
– Options files (`.py`) or dictionaries in notebooks (`fit_options`, `mcmc_options`, etc.).
c. Core Engine
– `badass.py`: orchestrates data loading, model assembly, fit routines.
– Module packages:
· `badass_utils/`: input checking, IFU cube handling, test suite
· `badass_tools/`: helper routines for spectrum handling
· `badass_data/neural_network`: pre-trained ML models
d. Computational Services
– Optimization service: SciPy basinhopping, least-squares
– MCMC service: emcee sampler with autocorrelation checks
– Parallelization: multiprocessing for batch fits or cube spaxels
e. External Dependencies
– Astropy (FITS I/O, cosmology), NumPy/Pandas, SciPy, Matplotlib, emcee, pPXF, astroquery, spectres, corner, etc.
f. Output Layer
– FITS tables: `par_table.fits`, `best_model_components.fits`, noise and autocorr `.npy`
– Plots: best-fit spectra, chain histograms, interactive HTML (Plotly)
– Log files: text summaries of fit progress and results

##### Relationships and Data Flows
- User launches a Notebook or CLI command → config/options passed to core engine → engine loads input spectrum(s) and templates → engine constructs continuum+line models → optimization service finds ML solution → optionally MCMC service refines with emcee → results fed to output layer → FITS tables, plots, logs are written → user reviews via Notebook or viewers.
- For IFU cubes, engine distributes spaxel fits across CPU cores and aggregates outputs.

##### Architectural Patterns and Principles
- Modular design: separation of concerns between data I/O, fitting logic, utilities, and user interface.
- Plugin-style templates: broad range of spectral components can be turned on/off via config.
- Service-oriented tasks: distinct services for optimization, MCMC sampling, plotting.
- Parallel processing for scalability.
- Data-driven: heavy use of configuration dictionaries and template folders under `badass_data/`.

##### Elements
– Blue for data resources (template folders, input spectra)
– Green for core modules (scripts/packages)
– Orange for services (optimization, MCMC, parallelization)
– Gray for external libraries
– Purple for outputs (FITS, plots, logs)
- Related components (e.g., under “Core Engine” show `badass_utils`, `badass_tools`).

##### Detailed Capture of Essential Elements
- Notebook interface feeding into `badass.py` with config dictionaries.
- How multiprocessing forks tasks for multiple spectra or IFU spaxels.
- Where log files and FITS outputs are generated and saved.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        DS1["Input Spectra (FITS/NumPy)"]:::data
        DS2["Template Libraries"]:::data
        subgraph "Templates"
            T1["IndoUS"]:::data
            T2["indo_us_library"]:::data
            T3["M09_ssp_templates"]:::data
            T4["MILES_ssp_templates"]:::data
            T5["Vazdekis2010"]:::data
            T6["eMILES"]:::data
            T7["balmer_template"]:::data
            T8["feii_templates"]:::data
            T9["neural_network"]:::data
        end
    end

    %% Configuration Layer
    subgraph "Config Layer"
        C1["Notebook Interface"]:::config
        C2["CLI Script (badass.py)"]:::config
        subgraph "Options Files"
            O1["badass_config_options.py"]:::config
            O2["badass_line_test_options.py"]:::config
            O3["BADASS_options.py"]:::config
        end
    end

    %% Core Engine
    subgraph "Core Engine"
        CE1["badass.py"]:::core
        subgraph "Utils"
            U1["badass_check_input.py"]:::core
            U2["badass_ifu.py"]:::core
            U3["badass_test_suite.py"]:::core
        end
        subgraph "Tools"
            H1["badass_tools.py"]:::core
        end
    end

    %% Services
    subgraph "Computational Services"
        S1["Optimization Service"]:::service
        S2["MCMC Service"]:::service
        S3["Parallelization"]:::service
    end

    %% External Dependencies
    subgraph "External Dependencies"
        E1["Astropy"]:::external
        E2["NumPy/Pandas"]:::external
        E3["SciPy"]:::external
        E4["Matplotlib"]:::external
        E5["emcee"]:::external
        E6["pPXF"]:::external
        E7["astroquery"]:::external
        E8["spectres"]:::external
        E9["corner"]:::external
    end

    %% Output Layer
    subgraph "Output Layer"
        OX1["FITS Tables"]:::output
        OX2["Plots (PNG/HTML)"]:::output
        OX3["Log Files"]:::output
    end

    %% Flows
    DS1 -->|feeds| CE1
    DS2 -->|uses templates| CE1
    C1 -->|launches| CE1
    C2 -->|runs| CE1
    O1 --> CE1
    O2 --> CE1
    O3 --> CE1

    CE1 -->|calls| S1
    CE1 -->|calls| S2
    CE1 -->|spawns| S3
    S1 -->|returns results| CE1
    S2 -->|refines results| CE1
    S3 -->|aggregates tasks| CE1

    CE1 -->|writes| OX1
    CE1 -->|writes| OX2
    CE1 -->|writes| OX3

    E1 --> CE1
    E2 --> CE1
    E3 --> CE1
    E4 --> CE1
    E5 --> CE1
    E6 --> CE1
    E7 --> CE1
    E8 --> CE1
    E9 --> CE1

    E1 --> S1
    E2 --> S1
    E3 --> S1
    E5 --> S2
    E2 --> S2

    %% Click Events for component mapping
    click DS1 "https://github.com/remingtonsexton/badass3/tree/master/example_spectra/"
    click DS2 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/"
    click T1 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/IndoUS/"
    click T2 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/indo_us_library/"
    click T3 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/M09_ssp_templates/"
    click T4 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/MILES_ssp_templates/"
    click T5 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/Vazdekis2010/"
    click T6 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/eMILES/"
    click T7 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/balmer_template/"
    click T8 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/feii_templates/"
    click T9 "https://github.com/remingtonsexton/badass3/tree/master/badass_data/neural_network/"
    click C1 "https://github.com/remingtonsexton/badass3/tree/master/example_notebooks/"
    click C2 "https://github.com/remingtonsexton/badass3/blob/master/badass.py"
    click O1 "https://github.com/remingtonsexton/badass3/blob/master/example_notebooks/badass_config_options.py"
    click O2 "https://github.com/remingtonsexton/badass3/blob/master/example_notebooks/badass_line_test_options.py"
    click O3 "https://github.com/remingtonsexton/badass3/blob/master/example_notebooks/BADASS_options.py"
    click U1 "https://github.com/remingtonsexton/badass3/blob/master/badass_utils/badass_check_input.py"
    click U2 "https://github.com/remingtonsexton/badass3/blob/master/badass_utils/badass_ifu.py"
    click U3 "https://github.com/remingtonsexton/badass3/blob/master/badass_utils/badass_test_suite.py"
    click H1 "https://github.com/remingtonsexton/badass3/blob/master/badass_tools/badass_tools.py"

    %% Styles
    classDef data fill:#cfe2f3,stroke:#1f6feb,color:#1f1f1f
    classDef config fill:#d1e7dd,stroke:#0f5132,color:#0f5132
    classDef core fill:#d1e7dd,stroke:#0d6efd,color:#0d6efd
    classDef service fill:#ffe5b4,stroke:#f0a500,color:#663300
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#212529
    classDef output fill:#e2d6f3,stroke:#6f42c1,color:#4b0082
```
