# cristian-pulido/uncertainty-informed-decision-making architecture

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

- Interactive diagram: https://gitdiagram.com/cristian-pulido/uncertainty-informed-decision-making
- Repository: https://github.com/cristian-pulido/uncertainty-informed-decision-making

## Overview

##### Project Context & Overall Components
- Project Type: This repository is an open-source analytical and experimental tool, centering on predictive modeling under uncertainty. It combines both production-grade modules (in the src folder) and research/experimental outputs (in the articulos folder).
- Purpose: To provide code, models, and tools (such as Conformal Prediction) to inform decision-making when dataset limitations or intervention uncertainties exist.

##### Main Components
a. Data Layer & External Data:
- External Data Setup: As noted in the README, large simulation outputs and sensitive real-world datasets exist outside the git repository in “uncertainty-informed-data”. Mark this as an external dependency that feeds into the system.
- Data Sources: Internal CSV files (e.g., in articulos/uncertainty-hotspots/data) and simulated/synthetic data generation (src/data_generation/hotspots.py).

b. Data Generation Module:
- Located under src/data_generation.
- Responsible for generating synthetic or simulation data used in analysis. This feeds into model training and evaluation.

c. Modeling Components:
- Found under src/models and the results folder in articulos. This includes various models such as naive_cell, poisson_cell, poisson models, and dummy models.
- Separate carefully between:
- Model definitions (code in src/models).
- Model outputs and artifacts (stored in articulos/uncertainty-hotspots/results/models).

d. Conformal Prediction & Uncertainty Quantification:
- Under src/conformal, the module (e.g., mapie_per_cell.py) handles the core work of applying Conformal Prediction methods.
- This is key to the project and should be highlighted as a specialized layer that integrates with the model training and evaluation pipeline.

e. Evaluation Suite:
- Located in src/evaluation. This includes scripts for evaluating models (via CP, spatial metrics, and temporal evaluation).
- Demonstrates the metric calculation and testing framework used to assess decision-making under uncertainty.

f. Utility Functions:
- Found under src/utils. Includes support for data partitioning, spatial processing, and visualization.
- These facilitate handling data flows and producing outputs used in reports and notebooks.

g. Experimental / Demonstration Notebooks:
- In articulos/uncertainty-hotspots/notebooks, these provide interactive experiments that guide users through:
- Synthetic data tests.
- Model training and evaluation.
- Visualization and post-processing of model results.
- This layer serves as the research or demonstration interface for the underlying modules.

##### Relationships and Data Flow
- Data Generation outputs are used by the Modeling components.
- Conformal Prediction integrates with the Modeling phase to estimate uncertainty.
- The Evaluation module consumes outputs from the Modeling and Conformal Prediction layers to produce performance metrics.
- Utility modules support data partitioning, spatial transformations, and visualization across many stages.
- The experimental notebooks orchestrate these modules, providing a guided pipeline and visualization of results.

##### Architectural Patterns and Design Details
- Modularity: A clear separation between data ingestion, processing (data generation, modeling, prediction), and evaluation.
- Extensibility: The use of separate directories (e.g., src/models, src/evaluation) suggests that the design should allow plugging in additional models or evaluation criteria.
- Iterative Research Workflow: The presence of notebooks indicates an experimental, iterative approach where results feed back into model improvements.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Handling Layer
    subgraph "Data Handling"
        ED["External Data (uncertainty-informed-data)"]:::data
        DG["Data Generation (src/data_generation/hotspots.py)"]:::data
        UF["Utility Functions (src/utils)"]:::data
    end

    %% Modeling & Prediction Layer
    subgraph "Modeling & Prediction"
        MD["Model Definitions (src/models)"]:::model
        MO["Model Outputs/Artifacts (articulos/uncertainty-hotspots/results/models)"]:::model
        CP["Conformal Prediction (src/conformal/mapie_per_cell.py)"]:::model
        EV["Evaluation Suite (src/evaluation)"]:::model
    end

    %% Experimental/Demo Layer
    subgraph "Experimental/Demo"
        NB["Notebooks (articulos/uncertainty-hotspots/notebooks)"]:::exp
    end

    %% Connections between layers
    ED -->|"feeds"| DG
    DG -->|"generatedData"| MD
    MD -->|"modelArtifacts"| MO
    MD -->|"integrates"| CP
    CP -->|"uncertaintyQuant"| EV
    EV -->|"feedback"| MD
    DG -->|"interactive"| NB
    MO -->|"interactive"| NB
    NB -->|"explores"| MD

    %% Utility functions supporting all layers
    UF ---|"supports"| DG
    UF ---|"supports"| MD
    UF ---|"supports"| CP
    UF ---|"supports"| EV

    %% Click Events
    click DG "https://github.com/cristian-pulido/uncertainty-informed-decision-making/blob/main/src/data_generation/hotspots.py"
    click MD "https://github.com/cristian-pulido/uncertainty-informed-decision-making/tree/main/src/models"
    click MO "https://github.com/cristian-pulido/uncertainty-informed-decision-making/tree/main/articulos/uncertainty-hotspots/results/models"
    click CP "https://github.com/cristian-pulido/uncertainty-informed-decision-making/blob/main/src/conformal/mapie_per_cell.py"
    click EV "https://github.com/cristian-pulido/uncertainty-informed-decision-making/tree/main/src/evaluation"
    click UF "https://github.com/cristian-pulido/uncertainty-informed-decision-making/tree/main/src/utils"
    click NB "https://github.com/cristian-pulido/uncertainty-informed-decision-making/tree/main/articulos/uncertainty-hotspots/notebooks"

    %% Styles
    classDef data fill:#cfe2f3,stroke:#1967b2,stroke-width:2px;
    classDef model fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef exp fill:#fce5cd,stroke:#e69138,stroke-width:2px;
```
