# ppalacios92/earthquakesignal architecture

> Architecture diagram of the GitHub repository ppalacios92/earthquakesignal, 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/ppalacios92/earthquakesignal
- Repository: https://github.com/ppalacios92/earthquakesignal

## Overview

##### Project Type and Purpose
- EarthquakeSignal is a Python library and CLI-style toolkit for processing, analyzing, and visualizing earthquake ground‐motion signals.
- It provides a modular API to load raw signal files (AT2, IG, RUP/BL formats), wrap them in a model object, compute engineering metrics (Arias Intensity, Fourier spectra, Newmark spectrum, ROTD), and produce summary tables or plots.

- Data Source (External filesystem or user-provided folders of .AT2/.txt files)
- Config Module
– settings.py holds global defaults (sampling rate, output paths, plot styles)
- Core Processing
– signal_loader.py reads raw files → EarthquakeSignal model
– core analyzers (arias_intensity, fourier_analyzer, newmark_spectrum_analyzer, rotd_analyzer, base_line, signal_components) compute metrics
- Model
– earthquake_signal.py defines EarthquakeSignal class (attributes: time series, metadata, computed results)
- Tools
– plotters (earthquake_plotter, fourier_plotter, newmark_plotter, arias_plotter, rotd_plotter) generate visualizations
– earthquake_summary and earthquake_comparison_plotter for aggregations and PDF/PNG exports
- Batch Processor
– earthquake_batch_processor.py orchestrates bulk workflows: read many inputs, apply core analyzers, route results to tools
- Examples
– Jupyter notebooks demonstrate end-to-end usage; include embedded data sets

1. Data Source → signal_loader
2. signal_loader → Model (EarthquakeSignal instances)
3. EarthquakeSignal → Core Analyzers → results stored back on the model
4. Model + Config → Tools (plotters / summary) → Output files (charts, tables)
5. Batch Processor calls steps 1–4 in sequence for multiple signals

##### Architectural Patterns & Design Principles
- Modular package structure: each concern in its own subpackage (core, models, tools, batch, config)
- Single Responsibility: loaders, analyzers, and plotters do one job each
- Inversion of Control via Config: centralized settings allow extending default behavior without code changes
- Extensibility: new analyzer or plotter plug-ins can be added by dropping a module into core or tools

##### Step-by-Step Construction
c. Inside core block, arrange loader at top feeding into analyzer cluster
f. At the bottom, overlay “Batch Processor” which invokes loader→analyzers→tools in a loop
h. Optionally, include “Examples / Notebooks” below as a consumer of the library

By breaking the system into these components, showing their interactions and layering them (I/O layer, processing layer, model layer, presentation layer, orchestration layer), you capture all essential architecture elements without over-engineering.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Input/Output
    DS["Data Source<br/>(.AT2, .txt)"]:::io

    %% Config Module
    subgraph "Config Module"
        Settings["settings.py"]:::config
    end

    %% Core Processing
    subgraph "Core Processing"
        SL["signal_loader"]:::core
        subgraph "Core Analyzers"
            Arias["arias_intensity"]:::core
            Fourier["fourier_analyzer"]:::core
            Newmark["newmark_spectrum_analyzer"]:::core
            ROTD["rotd_analyzer"]:::core
            Baseline["base_line"]:::core
            Components["signal_components"]:::core
        end
    end

    %% Model
    subgraph "Model"
        Model["EarthquakeSignal"]:::core
    end

    %% Tools / Presentation
    subgraph "Tools"
        EQPlotter["earthquake_plotter"]:::tools
        AriasPlot["arias_plotter"]:::tools
        FourierPlot["fourier_plotter"]:::tools
        NewmarkPlot["newmark_plotter"]:::tools
        ROTDPlot["rotd_plotter"]:::tools
        Summary["earthquake_summary"]:::tools
        Comparison["earthquake_comparison_plotter"]:::tools
    end

    Outputs["Output Files<br/>(charts, tables)"]:::io

    %% Batch Processor
    subgraph "Batch Processor"
        Batch["earthquake_batch_processor"]:::batch
    end

    %% Examples
    subgraph "Examples / Notebooks"
        NB["Notebooks (.ipynb)"]:::examples
        DSets["Example Data"]:::examples
    end

    %% Data Flow
    DS -->|".AT2, .txt → time series"| SL
    SL -->|"loads into model"| Model
    Model -->|"provides data to"| Arias
    Model -->|"provides data to"| Fourier
    Model -->|"provides data to"| Newmark
    Model -->|"provides data to"| ROTD
    Model -->|"provides data to"| Baseline
    Model -->|"provides data to"| Components

    Arias -->|"Arias Intensity metric"| Model
    Fourier -->|"Fourier Spectrum metric"| Model
    Newmark -->|"Newmark Spectrum metric"| Model
    ROTD -->|"ROTD metric"| Model
    Baseline -->|"Baseline corrected signal"| Model
    Components -->|"Signal components"| Model

    Model -->|"model + config → plotting"| EQPlotter
    Model -->|"model + config → plotting"| AriasPlot
    Model -->|"model + config → plotting"| FourierPlot
    Model -->|"model + config → plotting"| NewmarkPlot
    Model -->|"model + config → plotting"| ROTDPlot
    Model -->|"model + config → summary"| Summary
    Model -->|"model + config → comparison"| Comparison

    EQPlotter --> Outputs
    AriasPlot --> Outputs
    FourierPlot --> Outputs
    NewmarkPlot --> Outputs
    ROTDPlot --> Outputs
    Summary --> Outputs
    Comparison --> Outputs

    %% Batch orchestration
    Batch --> SL
    Batch --> Arias
    Batch --> Fourier
    Batch --> Newmark
    Batch --> ROTD
    Batch --> Baseline
    Batch --> Components
    Batch --> EQPlotter
    Batch --> Summary

    %% Config dashed dependencies
    SL -.-> Settings
    Arias -.-> Settings
    Fourier -.-> Settings
    Newmark -.-> Settings
    ROTD -.-> Settings
    Baseline -.-> Settings
    Components -.-> Settings
    EQPlotter -.-> Settings
    AriasPlot -.-> Settings
    FourierPlot -.-> Settings
    NewmarkPlot -.-> Settings
    ROTDPlot -.-> Settings
    Summary -.-> Settings
    Comparison -.-> Settings

    %% Examples usage
    NB -.-> SL
    NB -.-> Model
    NB -.-> EQPlotter
    DSets --> DS

    %% Click Events
    click Settings "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/config/settings.py"
    click SL "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/core/signal_loader.py"
    click Arias "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/core/arias_intensity.py"
    click Fourier "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/core/fourier_analyzer.py"
    click Newmark "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/core/newmark_spectrum_analyzer.py"
    click ROTD "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/core/rotd_analyzer.py"
    click Baseline "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/core/base_line.py"
    click Components "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/core/signal_components.py"
    click Model "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/models/earthquake_signal.py"
    click EQPlotter "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/tools/earthquake_plotter.py"
    click AriasPlot "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/tools/arias_plotter.py"
    click FourierPlot "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/tools/fourier_plotter.py"
    click NewmarkPlot "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/tools/newmark_plotter.py"
    click ROTDPlot "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/tools/rotd_plotter.py"
    click Summary "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/tools/earthquake_summary.py"
    click Comparison "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/tools/earthquake_comparison_plotter.py"
    click Batch "https://github.com/ppalacios92/earthquakesignal/blob/main/src/EarthquakeSignal/batch/earthquake_batch_processor.py"
    click NB "https://github.com/ppalacios92/earthquakesignal/tree/main/src/EarthquakeSignal/examples/"
    click DSets "https://github.com/ppalacios92/earthquakesignal/tree/main/src/EarthquakeSignal/examples/data/"

    %% Styles
    classDef io fill:#aed6f1,stroke:#1f618d,color:#1f618d
    classDef config fill:#d5dbdb,stroke:#566573,color:#1b2631
    classDef core fill:#abebc6,stroke:#239b56,color:#1b2631
    classDef tools fill:#fcf3cf,stroke:#b7950b,color:#1b2631
    classDef batch fill:#fcf3cf,stroke:#b7950b,color:#1b2631
    classDef examples fill:#d6dbd6,stroke:#424949,color:#1b2631
```
