# uobwatergroup/towerpy architecture

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

- Interactive diagram: https://gitdiagram.com/uobwatergroup/towerpy
- Repository: https://github.com/uobwatergroup/towerpy

## Overview

##### Project Type and Purpose
- Towerpy is an open-source Python toolbox (library + CLI scripts + notebooks) for reading, processing, analyzing and visualizing polarimetric weather radar data.
- It is not a web or mobile app but a domain-specific scientific library with command-line entry points and extensive Sphinx-based documentation and example notebooks.

##### High-level Architecture Components
a. CLI & Notebooks (Entry Points)
- scripts/ directory: Python scripts (e.g., radchain_ukmo.py) that invoke library functions.
- Jupyter notebooks under docs and .virtual_documents provide worked examples and tutorial flows.
b. Core Library Package (`towerpy/`)
- IO Layer
– towerpy/io: readers for various radar formats (ukmo, ncas, empty)
- Data Processing & Calibration
– towerpy/calib: functions for phase, ZDR calibration
– towerpy/eclass: classification algorithms and calibration factors for different bands
– towerpy/ml: machine-learning models (e.g., mlyr)
– towerpy/qpe: quantitative precipitation estimation algorithms
– towerpy/profs: radial profile computations
- Geospatial & Coordinate Services
– towerpy/georad: coordinate transformations, georeferencing functions
- Visualization
– towerpy/datavis: static and interactive plotting utilities, colormap definitions
- Utilities
– towerpy/base, towerpy/utils: shared base classes, unit conversions, general helpers
c. External Dependencies
- NumPy, SciPy, Matplotlib, Cartopy, netCDF4
- Sphinx (docs), Jupyter (notebooks)

##### Data Flow and Interactions
1. User calls a CLI script or imports towerpy in a notebook.
2. IO module loads raw radar data into NumPy arrays or xarray structures.
3. Calibration (towerpy/calib) and classification (towerpy/eclass, towerpy/ml) process the raw fields.
4. QPE algorithms compute precipitation estimates (towerpy/qpe).
5. Georeferencing maps data to geographical coordinates (towerpy/georad).
6. Visualization module (towerpy/datavis) renders plots or interactive figures.
7. Output can be saved, further analyzed in notebooks, or used downstream.

##### Architectural Patterns & Principles
- Modular layering: clear separation of concerns (I/O → Processing → Visualization).
- Plugin-like extensibility: new formats (in io/), new calibration tables (in eclass/), new algorithms (in ml/, qpe/).
- Data-centric design: all processing functions operate on in-memory arrays, enabling chaining.
- Documentation pipeline: Sphinx source under docs/source generates HTML, example notebooks are auto-executed via jupyter_execute.

##### Detailed Elements to Capture
- scripts/ → towerpy/io → towerpy/calib/eclass/ml/qpe → towerpy/georad → towerpy/datavis
- Inclusion of docs build: docs/source + jupyter_execute → Sphinx → HTML/PDF
- Sample datasets folder can be shown as optional “Input Data” repository.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Entry Points
  subgraph "Entry Points"
    direction TB
    CLI["CLI Scripts"]:::entry
    NB["Jupyter Notebooks"]:::entry
  end

  %% Core Library
  subgraph "Core Library (towerpy/)"
    direction TB

    subgraph "I/O Layer" 
      direction TB
      IO_empty["empty.py"]:::io
      IO_ncas["ncas.py"]:::io
      IO_ukmo["ukmo.py"]:::io
    end

    subgraph "Processing & Calibration"
      direction TB
      subgraph "Calibration (calib)"
        direction TB
        CAL_PHIDP["calib_phidp.py"]:::proc
        CAL_ZDR["calib_zdr.py"]:::proc
      end
      subgraph "Classification (eclass)"
        direction TB
        E_NME["nme.py"]:::proc
        E_SNR["snr.py"]:::proc
      end
      subgraph "Machine Learning (ml)"
        direction TB
        ML_MLYR["mlyr.py"]:::proc
      end
      subgraph "QPE Algorithms (qpe)"
        direction TB
        QPE_ALG["qpe_algs.py"]:::proc
      end
      subgraph "Radial Profiles (profs)"
        direction TB
        PROFS["polprofs.py"]:::proc
      end
    end

    subgraph "Geo & Coordinates (georad)"
      direction TB
      GEO_CT["coordinate_transformation_tool.py"]:::io
      GEO_GR["georef_rdata.py"]:::io
    end

    subgraph "Visualization (datavis)"
      direction TB
      VIS_DISP["rad_display.py"]:::vis
      VIS_INT["rad_interactive.py"]:::vis
      VIS_CM["tpy_cm.py"]:::vis
      VIS_COL["tpy_colors.py"]:::vis
    end

    subgraph "Utilities & Base"
      direction TB
      UTIL_BASE["base.py"]:::utils
      UTIL_RAD["radutilities.py"]:::utils
      UTIL_UNIT["unit_conversion.py"]:::utils
    end
  end

  %% Documentation Pipeline
  subgraph "Documentation Pipeline"
    direction TB
    DOC_SRC["docs/source/"]:::docs
    DOC_NB["docs/source/notebooks/"]:::docs
    DOC_JE["docs/jupyter_execute/"]:::docs
    DOC_MAKE["docs/Makefile & .readthedocs.yaml"]:::docs
  end

  %% Sample Data
  DATA["Sample Data (datasets/)"]:::data

  %% External Dependencies
  EXTD["External Dependencies (NumPy, SciPy, Matplotlib, Cartopy, netCDF4, Sphinx, Jupyter)"]:::ext

  %% Data Flow
  CLI -->|calls I/O| IO_empty
  CLI --> IO_ncas
  CLI --> IO_ukmo
  NB --> IO_empty
  NB --> IO_ncas
  NB --> IO_ukmo

  IO_empty -->|raw data| CAL_PHIDP
  IO_ncas --> CAL_PHIDP
  IO_ukmo --> CAL_PHIDP

  CAL_PHIDP --> CAL_ZDR
  CAL_ZDR --> E_NME
  E_NME --> E_SNR
  E_SNR --> ML_MLYR
  ML_MLYR --> QPE_ALG
  QPE_ALG --> PROFS

  PROFS --> GEO_CT
  GEO_CT --> GEO_GR
  GEO_GR --> VIS_DISP
  VIS_DISP --> VIS_INT
  VIS_INT --> VIS_CM
  VIS_CM --> VIS_COL

  VIS_COL -->|output| NB
  VIS_COL -->|output| CLI

  DOC_SRC --> DOC_NB
  DOC_NB --> DOC_JE
  DOC_JE --> DOC_MAKE

  DATA --> IO_empty
  DATA --> IO_ncas
  DATA --> IO_ukmo

  EXTD --> IO_empty
  EXTD --> CAL_PHIDP
  EXTD --> VIS_DISP
  EXTD --> DOC_SRC

  %% Click Events
  click CLI "https://github.com/uobwatergroup/towerpy/tree/main/scripts/"
  click NB "https://github.com/uobwatergroup/towerpy/tree/main/.virtual_documents/docs/source/notebooks/"
  click IO_empty "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/io/empty.py"
  click IO_ncas "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/io/ncas.py"
  click IO_ukmo "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/io/ukmo.py"
  click CAL_PHIDP "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/calib/calib_phidp.py"
  click CAL_ZDR "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/calib/calib_zdr.py"
  click E_NME "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/eclass/nme.py"
  click E_SNR "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/eclass/snr.py"
  click ML_MLYR "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/ml/mlyr.py"
  click QPE_ALG "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/qpe/qpe_algs.py"
  click PROFS "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/profs/polprofs.py"
  click GEO_CT "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/georad/coordinate_transformation_tool.py"
  click GEO_GR "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/georad/georef_rdata.py"
  click VIS_DISP "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/datavis/rad_display.py"
  click VIS_INT "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/datavis/rad_interactive.py"
  click VIS_CM "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/datavis/tpy_cm.py"
  click VIS_COL "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/datavis/tpy_colors.py"
  click UTIL_BASE "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/base.py"
  click UTIL_RAD "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/utils/radutilities.py"
  click UTIL_UNIT "https://github.com/uobwatergroup/towerpy/blob/main/towerpy/utils/unit_conversion.py"
  click DOC_SRC "https://github.com/uobwatergroup/towerpy/tree/main/docs/source/"
  click DOC_NB "https://github.com/uobwatergroup/towerpy/tree/main/docs/source/notebooks/"
  click DOC_JE "https://github.com/uobwatergroup/towerpy/tree/main/docs/jupyter_execute/"
  click DOC_MAKE "https://github.com/uobwatergroup/towerpy/tree/main/docs/Makefile"
  click DATA "https://github.com/uobwatergroup/towerpy/tree/main/datasets/ukmo-nimrod/data/"

  %% Styles
  classDef io fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
  classDef proc fill:#c8e6c9,stroke:#43a047,stroke-width:1px
  classDef vis fill:#ffe0b2,stroke:#fb8c00,stroke-width:1px
  classDef utils fill:#e0e0e0,stroke:#9e9e9e,stroke-width:1px
  classDef entry fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
  classDef docs fill:#fff9c4,stroke:#f9a825,stroke-width:1px
  classDef data fill:#dcedc8,stroke:#7cb342,stroke-width:1px
  classDef ext fill:#f5f5f5,stroke:#616161,stroke-width:1px
```
