# dmesonanalysers/dmesonanalysis architecture

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

- Interactive diagram: https://gitdiagram.com/dmesonanalysers/dmesonanalysis
- Repository: https://github.com/dmesonanalysers/dmesonanalysis

## Overview

##### Project type and purpose
- DmesonAnalysis is an open‐source, physics data analysis pipeline (not a web app), built to process the outputs of AliPhysics ROOT‐based tasks and produce pₜ‐differential yields, cross sections, and systematic studies for various charm hadrons.
- It consists of C++ “analysis tasks” run inside the AliROOT/AliPhysics framework and Python orchestration scripts that drive filtering, ML model training/application, physics observables computation, systematics, and final comparisons/plots.

##### High‐level architecture and main components
A. Data Sources & Ingestion
- AliPhysics processing tasks (C++):
– AliAnalysisTaskSEDs, SEDplus, SENonPromptLc, SEDmesonTree → produce ROOT trees or sparse output.
- runanalysistask/ and run3/tool/ modules orchestrate task submission & pre‐processing.
B. Data Preparation & Filtering
- filterdata/ (Python/C++ filters + YAML configs) – skim trees and sparses.
- cutobjects/ (C++ cut definitions) & configfiles/cutsets – apply selection criteria.
C. ML Model Pipeline
- ML/ folder:
– Training: config_Training_*.yml → MLClassification.py → trained_models/*.pickle
– Application: MLApplication.py (applies BDT/XGBoost)
– Model conversion & validation: ConvertModel.py, CheckFeatureDistr…
D. Physics Observable Computation
- Compute* scripts at root:
– ComputeDataDrivenFraction, ComputeDataDrivenCrossSection, ComputeRawYields, ComputeEfficiency…
– charmhadronflow/, femto/, resonances/ – specialized subsystems for flow (v₂), femtoscopy, resonance analysis
E. Systematics & Uncertainties
- systematics/ (multiple subfolders for checks, fraction, rawyields, seleff, tracking, genptshape…)
- run3/flow/systematics for Run3‐specific systematics
F. Merging, Combining & Comparisons
- merge/ (MergeTrainOutputs.py + YAML)
- comparisons/ (CompareCrossSecToFONLL.py, CompareRaa.py, etc.)
G. Models & Theory Predictions
- models/ (FONLL, MC@, PHSD, TAMU… files and scripts)
H. Orchestration & Utilities
- RunFullAnalysis.sh – top‐level driver
- utils/ (common Python helpers)
- requirements.txt, .pylintrc

##### Relationships & data flow
- ROOT files → filterdata → selected trees/sparses.
- Selected data → ML training (if training run) → train models → stored in ML/trained_models.
- Selected data + trained models → ML application → produce ML‐tagged output.
- Tagged data → Compute* modules & resonances/femto/charmhadronflow → produce physics observables.
- Observables → systematics sub‐pipelines → generate uncertainty envelopes.
- Results → merge & comparisons → final plots, tables.

##### Key architectural patterns & principles
- Modular pipeline: each analysis step (filter, train, apply, compute, systematics, compare) is decoupled and configurable via YAML.
- Config‐driven: all selection cuts, training, systematics, merging are parameterized in configfiles/ and ML/*.yml.
- C++ for ROOT tasks, Python for orchestration and high‐level computation.
- Reuse of utilities (utils/) and standard ML package (hipe4ml, xgboost).

##### Detailed capture of essential elements
- Do not omit the systematics subfolders—they represent distinct computation nodes.
- That RunFullAnalysis.sh calls multiple stages in sequence or parallel.
- That merge/ and comparisons/ consume outputs from all Compute* and systematics modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration & Utilities
    subgraph "Orchestration & Utilities"
        OF["RunFullAnalysis.sh"]:::python
        UT["utils/"]:::python
        RI["requirements.txt"]:::config
        PYRC[".pylintrc"]:::config
    end

    %% Data Sources & Ingestion
    subgraph "1. Data Sources & Ingestion"
        D1["RunAnalysisDplusDsLcTask.cc"]:::cpp
        D2["RunAnalysisTreeCreator.cc"]:::cpp
        D3["RunAnalysisCheckHFProd.cc"]:::cpp
        D4["ValidateTreeCreator.py"]:::python
        DS_DIR["runanalysistask/"]:::python
        R3TOOL["run3/tool/"]:::python
    end

    %% Data Preparation & Filtering
    subgraph "2. Data Preparation & Filtering"
        FD["filterdata/"]:::python
        CO["cutobjects/"]:::cpp
        CF["configfiles/cutsets/"]:::config
    end

    %% ML Model Pipeline
    subgraph "3. ML Model Pipeline"
        MLCLF["MLClassification.py"]:::python
        MLAPP["MLApplication.py"]:::python
        CONV["ConvertModel.py"]:::python
        MLCONF["config_Training_*.yml & config_Application_*.yml"]:::config
        TMOD["ML/trained_models/"]:::config
    end

    %% Physics Observable Computation
    subgraph "4. Physics Observable Computation"
        ROOTSCR["Compute*.py/.C"]:::python
        FLOW["charmhadronflow/"]:::python
        FEMTO["femto/"]:::python
        RESO["resonances/"]:::python
    end

    %% Systematics & Uncertainties
    subgraph "5. Systematics & Uncertainties"
        SYS["systematics/"]:::python
        R3SYS["run3/flow/systematics/"]:::python
    end

    %% Merging & Comparisons
    subgraph "6. Merging, Combining & Comparisons"
        MRG["merge/"]:::python
        CMP["comparisons/"]:::python
    end

    %% Models & Theory Predictions
    subgraph "7. Models & Theory Predictions"
        MOD["models/"]:::python
    end

    %% External Dependencies
    subgraph "External"
        EX1["AliPhysics Framework"]:::external
        EX2["hipe4ml, xgboost, pyaml"]:::external
    end

    %% Data Flow
    OF -->|"initiates"| D1
    OF --> D2
    OF --> D3
    OF --> D4
    D1 & D2 & D3 -->|"ROOT trees/sparses"| FD
    D4 --> FD
    FD -->|"skimmed data"| MLCLF
    FD --> MLAPP
    MLCLF -->|"training configs"| TMOD
    MLCONF --> MLCLF
    TMOD --> MLAPP
    MLAPP -->|"ML-tagged data"| ROOTSCR
    ROOTSCR --> FLOW
    ROOTSCR --> FEMTO
    ROOTSCR --> RESO
    FLOW & FEMTO & RESO --> SYS
    SYS --> R3SYS
    R3SYS --> MRG
    MRG --> CMP
    CMP -->|"final plots & tables"| OF
    EX1 --> D1
    EX1 --> D2
    EX1 --> D3
    EX2 --> MLCLF
    EX2 --> MLAPP

    %% Click Events
    click D1 "https://github.com/dmesonanalysers/dmesonanalysis/blob/master/runanalysistask/RunAnalysisDplusDsLcTask.cc"
    click D2 "https://github.com/dmesonanalysers/dmesonanalysis/blob/master/runanalysistask/RunAnalysisTreeCreator.cc"
    click D3 "https://github.com/dmesonanalysers/dmesonanalysis/blob/master/runanalysistask/RunAnalysisCheckHFProd.cc"
    click D4 "https://github.com/dmesonanalysers/dmesonanalysis/blob/master/runanalysistask/ValidateTreeCreator.py"
    click DS_DIR "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/runanalysistask/"
    click R3TOOL "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/run3/tool/"
    click FD "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/filterdata/"
    click CO "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/cutobjects/"
    click CF "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/configfiles/cutsets/"
    click MLCLF "https://github.com/dmesonanalysers/dmesonanalysis/blob/master/ML/MLClassification.py"
    click MLAPP "https://github.com/dmesonanalysers/dmesonanalysis/blob/master/ML/MLApplication.py"
    click CONV "https://github.com/dmesonanalysers/dmesonanalysis/blob/master/ML/ConvertModel.py"
    click MLCONF "https://github.com/dmesonanalysers/dmesonanalysis/blob/master/ML/config_Training_*.yml"
    click TMOD "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/ML/trained_models/"
    click FLOW "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/charmhadronflow/"
    click FEMTO "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/femto/"
    click RESO "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/resonances/"
    click SYS "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/systematics/"
    click R3SYS "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/run3/flow/systematics/"
    click MRG "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/merge/"
    click CMP "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/comparisons/"
    click MOD "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/models/"
    click OF "https://github.com/dmesonanalysers/dmesonanalysis/blob/master/RunFullAnalysis.sh"
    click UT "https://github.com/dmesonanalysers/dmesonanalysis/tree/master/utils/"

    %% Styles
    classDef cpp fill:#add8e6,stroke:#333,stroke-width:1px
    classDef python fill:#90ee90,stroke:#333,stroke-width:1px
    classDef config fill:#ffa500,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
```
