# hmz-03/daspy architecture

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

- Interactive diagram: https://gitdiagram.com/hmz-03/daspy
- Repository: https://github.com/hmz-03/daspy

## Overview

##### Project type and purpose
- DASPy is an open-source Python toolbox (library) for Distributed Acoustic Sensing (DAS) data processing.
- It provides core I/O, basic seismic processing routines, visualization, and advanced DAS-specific algorithms.

##### File structure
- Top-level packaging and metadata:
- setup.py, LICENSE, README.md, .github/workflows (CI)
- Core package directory “daspy/” with three main subpackages:
- core: data I/O (`read.py`, `write.py`), fundamental data structures (`collection.py`, `section.py`), datetime handling
- basic_tools: generic seismic processing (filtering, frequency attributes, preprocessing, visualization)
- advanced_tools: DAS-specific algorithms (denoising, channel analysis, waveform decomposition, strain→velocity)
- Documentation & examples:
- document/ (MAT file example, Jupyter notebook)
- website/ (logo, tutorial assets)
- Contribution files (CONTRIBUTING.md, CONTRIBUTORS.txt) and CI workflow.

##### README for additional insights
- Confirms the Python-only toolbox orientation.
- Lists core functionality: preprocessing, filter, spectrum analysis, visualization, denoising, decomposition, channel attributes, strain-velocity conversion.
- Points to tutorials and dependencies (numpy, scipy, matplotlib, geographiclib, pyproj, h5py, segyio, nptdms, tqdm).

##### Main components & their relationships
a. Core I/O & data model
- read(), write(), Section/Collection classes encapsulate waveform data and metadata
b. Basic Tools
- Consume Section/Collection objects to provide filtering, spectral analysis, visualization
c. Advanced Tools
- Build on core data structures and basic tools to deliver specialized DAS algorithms
d. External dependencies
- Underlying libraries (numpy, scipy, etc.)
e. User interface
- Python API, Jupyter notebook examples, CLI entry point (if any), package distribution via PyPI/Conda
f. Documentation site & CI
- Hosted assets, automated tests/builds via GitHub Actions

##### Architectural patterns and design principles
- Modular package design: clear separation of core, basic, and advanced toolsets
- Data-centric API: central Section/Collection classes flow through modules
- Extensibility: users can add new processing modules under basic_tools/ or advanced_tools/

- “User Code / Notebook” (entry point)
- Core I/O & Data Model (daspy.core)
- Basic Tools (daspy.basic_tools)
- Advanced Tools (daspy.advanced_tools)
- External Libraries
- Package & CI Infrastructure (setup.py, GitHub Actions, website)
1. User Code → call daspy.read()
2. read() → Core Data Model
3. Core Data Model → Basic Tools → Advanced Tools
4. Tools → Core Data Model updates → write() or plot()
c. Dependencies:
- Daspy modules depend on numpy, scipy, etc.
- CI → runs tests on all modules
- setup.py → bundles modules for distribution
- External dependencies in another
- User interface (notebook/CLI) in a third

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface" 
        UI["User Code / Notebook"]:::ui
    end

    %% Core I/O & Data Model
    subgraph "Core I/O & Data Model" 
        CoreRead["daspy.core.read()"]:::core
        CoreWrite["daspy.core.write()"]:::core
        SectionClass["Section Class"]:::core
        CollectionClass["Collection Class"]:::core
        DateTime["Datetime Handling"]:::core
        ExampleData["Example Data (pickle)"]:::core
    end

    %% Basic Tools
    subgraph "Basic Tools" 
        Filter["Filtering Routines"]:::basic
        FreqAttr["Frequency Attributes"]:::basic
        Preproc["Preprocessing Utilities"]:::basic
        Viz["Visualization Functions"]:::basic
    end

    %% Advanced Tools
    subgraph "Advanced Tools" 
        Channel["Channel Analysis"]:::advanced
        Decomp["Waveform Decomposition"]:::advanced
        Denoise["Denoising Algorithms"]:::advanced
        FDCT["FDCT (Curvelet Transform)"]:::advanced
        Strain2Vel["Strain→Velocity Conversion"]:::advanced
    end

    %% External Dependencies
    subgraph "External Libraries" 
        Numpy["numpy"]:::external
        Scipy["scipy"]:::external
        Matplotlib["matplotlib"]:::external
        GeoLib["geographiclib"]:::external
        Pyproj["pyproj"]:::external
        H5py["h5py"]:::external
        Segyio["segyio"]:::external
        Nptdms["nptdms"]:::external
        Tqdm["tqdm"]:::external
    end

    %% Infrastructure & Docs
    subgraph "Infrastructure & Documentation" 
        Setup["setup.py"]:::infra
        License["LICENSE"]:::infra
        Readme["README.md"]:::infra
        RootContrib["CONTRIBUTORS.txt"]:::infra
        PackageContrib["daspy/CONTRIBUTORS.txt"]:::infra
        ContribGuide["CONTRIBUTING.md"]:::infra
        CI["GitHub Actions Workflow"]:::infra
        DocMAT["MAT Example Data"]:::infra
        NotebookDoc["Jupyter Notebook Tutorial"]:::infra
        Website["Website Assets"]:::infra
    end

    %% Data Flow
    UI -->|"calls read()"| CoreRead
    CoreRead -->|"loads data"| SectionClass
    CoreRead --> SectionClass
    SectionClass --> CollectionClass
    CollectionClass --> Filter
    Filter --> FreqAttr
    FreqAttr --> Preproc
    Preproc --> Viz
    Viz --> CoreWrite
    Viz --> UI
    Viz --> ExampleData
    Filter --> ExampleData
    Preproc --> SectionClass
    SectionClass --> Channel
    Channel --> Decomp
    Decomp --> Denoise
    Denoise --> FDCT
    FDCT --> Strain2Vel
    Strain2Vel --> CoreWrite
    Strain2Vel --> SectionClass

    %% Dependencies
    CoreRead --> Numpy
    CoreRead --> Scipy
    CoreRead --> H5py
    CoreRead --> Segyio
    CoreRead --> Nptdms
    Filter --> Numpy
    FreqAttr --> Scipy
    Viz --> Matplotlib
    Channel --> Scipy
    Decomp --> Scipy
    Denoise --> Numpy
    Strain2Vel --> Pyproj
    Strain2Vel --> GeoLib
    Strain2Vel --> Tqdm

    %% Infrastructure connections
    CI --> CoreRead
    CI --> CoreWrite
    CI --> SectionClass
    CI --> CollectionClass
    CI --> Filter
    CI --> FreqAttr
    CI --> Preproc
    CI --> Viz
    CI --> Channel
    CI --> Decomp
    CI --> Denoise
    CI --> FDCT
    CI --> Strain2Vel
    Setup --> CI
    Setup --> UI
    Readme --> UI
    ContribGuide --> CI
    Website --> UI
    DocMAT --> CoreRead
    NotebookDoc --> UI

    %% Click Events
    click CoreRead "https://github.com/hmz-03/daspy/blob/main/daspy/core/read.py"
    click CoreWrite "https://github.com/hmz-03/daspy/blob/main/daspy/core/write.py"
    click SectionClass "https://github.com/hmz-03/daspy/blob/main/daspy/core/section.py"
    click CollectionClass "https://github.com/hmz-03/daspy/blob/main/daspy/core/collection.py"
    click DateTime "https://github.com/hmz-03/daspy/blob/main/daspy/core/dasdatetime.py"
    click ExampleData "https://github.com/hmz-03/daspy/blob/main/daspy/core/example.pkl"

    click Filter "https://github.com/hmz-03/daspy/blob/main/daspy/basic_tools/filter.py"
    click FreqAttr "https://github.com/hmz-03/daspy/blob/main/daspy/basic_tools/freqattributes.py"
    click Preproc "https://github.com/hmz-03/daspy/blob/main/daspy/basic_tools/preprocessing.py"
    click Viz "https://github.com/hmz-03/daspy/blob/main/daspy/basic_tools/visualization.py"

    click Channel "https://github.com/hmz-03/daspy/blob/main/daspy/advanced_tools/channel.py"
    click Decomp "https://github.com/hmz-03/daspy/blob/main/daspy/advanced_tools/decomposition.py"
    click Denoise "https://github.com/hmz-03/daspy/blob/main/daspy/advanced_tools/denoising.py"
    click FDCT "https://github.com/hmz-03/daspy/blob/main/daspy/advanced_tools/fdct.py"
    click Strain2Vel "https://github.com/hmz-03/daspy/blob/main/daspy/advanced_tools/strain2vel.py"

    click Setup "https://github.com/hmz-03/daspy/blob/main/setup.py"
    click License "https://github.com/hmz-03/daspy/tree/main/LICENSE"
    click Readme "https://github.com/hmz-03/daspy/blob/main/README.md"
    click RootContrib "https://github.com/hmz-03/daspy/blob/main/CONTRIBUTORS.txt"
    click PackageContrib "https://github.com/hmz-03/daspy/blob/main/daspy/CONTRIBUTORS.txt"
    click ContribGuide "https://github.com/hmz-03/daspy/blob/main/CONTRIBUTING.md"
    click CI "https://github.com/hmz-03/daspy/blob/main/.github/workflows/workflow.yml"
    click DocMAT "https://github.com/hmz-03/daspy/blob/main/document/Ridgecrest_traffic_noise.mat"
    click NotebookDoc "https://github.com/hmz-03/daspy/blob/main/document/example.ipynb"
    click Website "https://github.com/hmz-03/daspy/tree/main/website/"

    %% Styling
    classDef core fill:#cce5ff,stroke:#00529B,color:#00529B;
    classDef basic fill:#d4edda,stroke:#2E7D32,color:#2E7D32;
    classDef advanced fill:#ffe5b4,stroke:#E65100,color:#E65100;
    classDef external fill:#f0f0f0,stroke:#707070,color:#707070;
    classDef infra fill:#e1bee7,stroke:#6A1B9A,color:#4A148C;
    classDef ui fill:#f8bbd0,stroke:#AD1457,color:#AD1457;
```
