# mcallaghan/regional-impacts-map architecture

> Architecture diagram of the GitHub repository mcallaghan/regional-impacts-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mcallaghan/regional-impacts-map
- Repository: https://github.com/mcallaghan/regional-impacts-map

## Overview

##### Main Components
- Data Ingestion & Preprocessing:
- Literature Identification: “literature_identification” contains scripts and notebooks to gather, filter, and process bibliographic and study metadata.
- Supplementary Data: “supplementary_data” and “tables” hold raw/aggregated data that feed into the analysis.
- Analysis & Machine Learning Module:
- Analysis Directory: “analysis” is the core where numerous Jupyter notebooks and Python scripts orchestrate clustering, cross-validation, model selection, and prediction. In particular, the “2-cluster-ml-scripts” folder contains scripts to run prediction pipelines (including SVM and BERT models) and perform extensive model evaluations.
- Detection and Attribution: “detection_and_attribution” contains notebooks and scripts dedicated to attributing climate trends (temperature and precipitation) to underlying patterns.
- Visualization & Output Generation:
- Figures/Plots: “figures”, “plots”, and “presentation” directories store the final outputs – PDFs, images, and LaTeX files – that represent the scientific results (including interactive map links referenced in the README).
- Manuscript Generation: “manuscript” holds the LaTeX source and PDFs for the scientific paper and supplementary materials.

##### Relationships & Interactions
- Data & Input Flow:
- Raw data (from literature and supplementary data) are processed using scripts in “literature_identification” and “analysis”.
- Modeling & Analysis Flow:
- Preprocessed inputs feed into the ML pipelines in “analysis” (cluster-ml-scripts) and into the “detection_and_attribution” module.
- The outputs (predictions, cross-validation results, error logs) are then aggregated.
- Visualization & Reporting Flow:
- The aggregated results drive the generation of figures (in “figures” and “plots”), which in turn support the manuscript and presentation documents.
- The interactive map mentioned in the README is an additional presentation layer accessible via a web link.

##### Architectural Patterns
- Modular Pipeline:
- Each directory represents a distinct stage of the research pipeline: data collection (literature_identification), ML analysis (analysis and detection_and_attribution), and results presentation (figures, plots, manuscript, presentation).
- Separation of Concerns:
- Different modules are strictly separated, allowing independent development or rerunning of model selection, cross-validation, and visualization scripts.
- Data Flow Orientation:
- The system is architected as a sequential flow: starting from data ingestion, through complex computation in ML pipelines, to ultimately producing publication-quality outputs.
- Use of Notebooks and Scripts:

##### Relevant Technologies/Frameworks
- Python is the primary language, with extensive Jupyter notebook usage.
- Machine learning techniques using classification models (SVM, BERT) are central.
- Data visualization tools (likely matplotlib, LaTeX for PDF generation) are used in producing figures and the manuscript.
- Version control (Git) is in place, as indicated by .gitignore and LICENSE.txt.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing Layer
    subgraph "Data Ingestion & Preprocessing"
        LitID["Literature Identification"]:::dataClass
        SuppData["Supplementary Data"]:::dataClass
        Tables["Tables"]:::dataClass
    end

    %% Analysis & Machine Learning Layer
    subgraph "Analysis & Machine Learning Module"
        Analysis["Core Analysis & Model Evaluation"]:::mlClass
        ClusterML["Model Selection & Prediction Engine (2-cluster-ml-scripts)"]:::mlClass
        DetAttrib["Climate Attribution Module"]:::mlClass
    end

    %% Visualization & Output Generation Layer
    subgraph "Visualization & Output Generation"
        Figures["Figures"]:::visClass
        Plots["Plots"]:::visClass
        Presentation["Presentation Materials"]:::visClass
        Manuscript["Manuscript Generation"]:::visClass
        ExtMap["Interactive Map Portal"]:::external
    end

    %% Data Flow Connections
    LitID -->|"feeds"| Analysis
    SuppData -->|"feeds"| Analysis
    Tables -->|"feeds"| Analysis

    Analysis -->|"triggers"| ClusterML
    Analysis -->|"triggers"| DetAttrib

    ClusterML -->|"outputs"| Figures
    ClusterML -->|"outputs"| Plots
    ClusterML -->|"outputs"| Manuscript
    ClusterML -->|"outputs"| Presentation

    DetAttrib -->|"outputs"| Figures
    DetAttrib -->|"outputs"| Plots
    DetAttrib -->|"outputs"| Manuscript
    DetAttrib -->|"outputs"| Presentation

    Presentation -->|"links to"| ExtMap

    %% Click Events
    click LitID "https://github.com/mcallaghan/regional-impacts-map/tree/master/literature_identification/"
    click SuppData "https://github.com/mcallaghan/regional-impacts-map/tree/master/supplementary_data/"
    click Tables "https://github.com/mcallaghan/regional-impacts-map/tree/master/tables/"
    click Analysis "https://github.com/mcallaghan/regional-impacts-map/tree/master/analysis/"
    click ClusterML "https://github.com/mcallaghan/regional-impacts-map/tree/master/analysis/2-cluster-ml-scripts/"
    click DetAttrib "https://github.com/mcallaghan/regional-impacts-map/tree/master/detection_and_attribution/"
    click Figures "https://github.com/mcallaghan/regional-impacts-map/tree/master/figures/"
    click Plots "https://github.com/mcallaghan/regional-impacts-map/tree/master/plots/"
    click Presentation "https://github.com/mcallaghan/regional-impacts-map/tree/master/presentation/"
    click Manuscript "https://github.com/mcallaghan/regional-impacts-map/tree/master/manuscript/"

    %% Styles
    classDef dataClass fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef mlClass fill:#D0F7BE,stroke:#333,stroke-width:2px;
    classDef visClass fill:#F7D6AE,stroke:#333,stroke-width:2px;
    classDef external fill:#FFEEAA,stroke:#333,stroke-width:2px;
```
