# jreyesv063/plotter architecture

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

- Interactive diagram: https://gitdiagram.com/jreyesv063/plotter
- Repository: https://github.com/jreyesv063/plotter

## Overview

##### Project Type and Purpose
- This is a domain-specific, Python-based data-analysis and plotting tool (called “Plotter”) geared toward high-energy physics studies.
- It provides a reusable core library (`src/Plotter.py` plus many `utils_*.py` modules), configuration files (`jsons/*.json`), and driver notebooks (`*.ipynb`) that orchestrate data ingestion, efficiency calculations, systematic-variation studies, and final plotting.

##### Top-Level Architecture
- Driver Layer (Jupyter Notebooks):
- `Z_mumu.ipynb`, `eff_btag.ipynb`, `eff_studies.ipynb`, etc.
- Core Library Layer (`src/`):
- Plotting engine (`Plotter.py`, `plotter_eff.py`)
- Domain logic (e.g., `intervals.py`)
- Utilities for data I/O, weighting, efficiencies, errors, metadata, systematics (`utils_*.py`)
- Configuration Layer (`jsons/`):
- Cross-section lookups (`DAS_xsec.json`)
- Luminosity settings (`luminosity.json`)
- External Data Layer (not explicitly in tree, but implied):
- ROOT files or other physics datasets loaded by `utils_pkl.py` or similar.

##### Interactions and Data Flows
- Notebooks → invoke Plotter API →
- Plotter core functions call relevant utility modules →
- Utility modules read/parse JSON configs and external data files →
- Processed data flows back up through Plotter →
- Final plots are rendered in the notebook or saved to disk.

##### Key Architectural Patterns
- Modular design with separation of concerns: plotting logic, domain computations, I/O/config, and driver scripts.
- Single-entry API (`Plotter.py`) that orchestrates sub-modules.
- Configuration-as-code via JSON files decouples parameters from logic.

- “Notebooks / Driver Scripts”
- “Plotter Core”
- “Domain Logic & Utilities” (group `utils_*.py` + `intervals.py`)
- “Configuration Files” (JSONs)
- “External Data Sources” (ROOT, CSV, or other physics data files)
- “Output” (PNG, PDF, or in-notebook plots)
c. Highlighted Patterns:
- “single-entry” façade of `Plotter.py` orchestrating everything.
- Similar modules (all `utils_*.py`) into one “Utilities” cluster.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Driver Layer
    subgraph "Driver Layer"
        direction TB
        ZM["Z_mumu.ipynb"]:::driver
        EB["eff_btag.ipynb"]:::driver
        ES["eff_studies.ipynb"]:::driver
        SI["signal.ipynb"]:::driver
        TT["tt_bgr.ipynb"]:::driver
        WJ["wj_bgr.ipynb"]:::driver
    end

    %% Core Library Layer
    subgraph "Core Library"
        direction TB
        PC1["Plotter.py"]:::core
        PC2["plotter_eff.py"]:::core
    end

    %% Domain Logic & Utilities Layer
    subgraph "Domain Logic & Utilities"
        direction TB
        IL["intervals.py"]:::util
        U["utils.py"]:::util
        U2["utils_2D_weights.py"]:::util
        UE["utils_efficiency.py"]:::util
        UER["utils_errors.py"]:::util
        UM["utils_metadata.py"]:::util
        UP["utils_pkl.py"]:::util
        UP2["utils_plot.py"]:::util
        UP22["utils_plot_2D.py"]:::util
        UQ["utils_qcd.py"]:::util
        USV["utils_systematic_variations.py"]:::util
    end

    %% Configuration Layer
    subgraph "Configuration Files"
        direction TB
        CX["DAS_xsec.json"]:::config
        CL["luminosity.json"]:::config
    end

    %% External Data Layer
    ED["External Data Sources"]:::data

    %% Output Layer
    OP["Output (PNG, PDF, In-Notebook)"]:::output

    %% Connections
    ZM -->|invokes| PC1
    EB -->|invokes| PC1
    ES -->|invokes| PC1
    SI -->|invokes| PC1
    TT -->|invokes| PC1
    WJ -->|invokes| PC1

    PC1 -->|"calls domain & utils"| IL
    PC1 -->|"calls domain & utils"| U
    PC1 -->|"calls domain & utils"| U2
    PC1 -->|"calls domain & utils"| UE
    PC1 -->|"calls domain & utils"| UER
    PC1 -->|"calls domain & utils"| UM
    PC1 -->|"calls domain & utils"| UP
    PC1 -->|"calls domain & utils"| UP2
    PC1 -->|"calls domain & utils"| UP22
    PC1 -->|"calls domain & utils"| UQ
    PC1 -->|"calls domain & utils"| USV

    %% Utilities to Config & Data
    U -->|reads| CX
    U -->|reads| CL
    UP -->|loads| ED
    USV -->|loads| ED

    %% Plotter to Output
    PC1 -->|renders/saves| OP
    PC2 -->|renders/saves| OP

    %% Click Events
    click ZM "https://github.com/jreyesv063/plotter/blob/main/Z_mumu.ipynb"
    click EB "https://github.com/jreyesv063/plotter/blob/main/eff_btag.ipynb"
    click ES "https://github.com/jreyesv063/plotter/blob/main/eff_studies.ipynb"
    click SI "https://github.com/jreyesv063/plotter/blob/main/signal.ipynb"
    click TT "https://github.com/jreyesv063/plotter/blob/main/tt_bgr.ipynb"
    click WJ "https://github.com/jreyesv063/plotter/blob/main/wj_bgr.ipynb"
    click PC1 "https://github.com/jreyesv063/plotter/blob/main/src/Plotter.py"
    click PC2 "https://github.com/jreyesv063/plotter/blob/main/src/plotter_eff.py"
    click IL "https://github.com/jreyesv063/plotter/blob/main/src/intervals.py"
    click U "https://github.com/jreyesv063/plotter/blob/main/src/utils.py"
    click U2 "https://github.com/jreyesv063/plotter/blob/main/src/utils_2D_weights.py"
    click UE "https://github.com/jreyesv063/plotter/blob/main/src/utils_efficiency.py"
    click UER "https://github.com/jreyesv063/plotter/blob/main/src/utils_errors.py"
    click UM "https://github.com/jreyesv063/plotter/blob/main/src/utils_metadata.py"
    click UP "https://github.com/jreyesv063/plotter/blob/main/src/utils_pkl.py"
    click UP2 "https://github.com/jreyesv063/plotter/blob/main/src/utils_plot.py"
    click UP22 "https://github.com/jreyesv063/plotter/blob/main/src/utils_plot_2D.py"
    click UQ "https://github.com/jreyesv063/plotter/blob/main/src/utils_qcd.py"
    click USV "https://github.com/jreyesv063/plotter/blob/main/src/utils_systematic_variations.py"
    click CX "https://github.com/jreyesv063/plotter/blob/main/jsons/DAS_xsec.json"
    click CL "https://github.com/jreyesv063/plotter/blob/main/jsons/luminosity.json"

    %% Styles
    classDef driver fill:#D0E6F6,stroke:#333,stroke-width:1px
    classDef core fill:#D6F5D6,stroke:#333,stroke-width:1px
    classDef util fill:#E8F8E8,stroke:#333,stroke-width:1px
    classDef config fill:#FFF5CC,stroke:#333,stroke-width:1px
    classDef data fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef output fill:#FFE0B2,stroke:#333,stroke-width:1px
```
