# rajdeepofgithub/criteo-uplift architecture

> Architecture diagram of the GitHub repository rajdeepofgithub/criteo-uplift, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajdeepofgithub/criteo-uplift
- Repository: https://github.com/rajdeepofgithub/criteo-uplift

## Overview

This repository is a reproducible causal-analysis pipeline for the CRITEO-UPLIFT advertising benchmark. The user-facing workflow acquires and verifies data, ingests it, freezes a stratified split, audits the data, estimates the intention-to-treat effect, trains and compares fixed-budget targeting policies on validation, freezes the selected analysis, and opens a sealed test once. The graph retains leakage control, preprocessing, policy evaluation, and bootstrap uncertainty as internal layers. Several later-stage implementations are unsampled; their presence and purpose are based on the README, and those links cite it.

Main entry points: [`scripts/run_stage45_validation.py`](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage45_validation.py) (Validation modeling), [`scripts/run_stage2_split_audit_eda.py`](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage2_split_audit_eda.py) (Split audit EDA), [`scripts/run_stage3_ate.py`](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage3_ate.py) (Assignment effect), [`src/uplift_project/leakage.py`](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/leakage.py) (Feature whitelist)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_stage1["Acquire stage<br/>[run_stage1.py]"]
  node_acquire["Verified download<br/>[acquire.py]"]
  node_ingest["Parquet ingestion<br/>[ingest.py]"]
  node_parquet["Processed data"]
end

subgraph group_analysis["Study analysis"]
  node_stage2["Split audit EDA"]
  node_split["Deterministic split<br/>[split.py]"]
  node_splitmanifest["Split manifest"]
  node_leakage["Feature whitelist<br/>[leakage.py]"]
  node_stage3["Assignment effect<br/>[run_stage3_ate.py]"]
  node_ate["ITT estimator<br/>[ate.py]"]
  node_ateresult["Effect report<br/>[ate.json]"]
end

subgraph group_models["Policy modeling"]
  node_stage45["Validation modeling"]
  node_preprocess["Logistic preprocessing<br/>[preprocess.py]"]
  node_policy["Budgeted targeting<br/>[policy.py]"]
  node_stage5b["LightGBM selection"]
end

subgraph group_evaluation["Evaluation and release"]
  node_bootstrap["Paired bootstrap<br/>[bootstrap.py]"]
  node_freeze["Freeze stage"]
  node_sealedtest["Sealed test"]
  node_testresult["Test report<br/>[test.json]"]
end

node_analyst(("Researcher"))
node_dataset["Criteo benchmark"]

node_analyst -->|"runs pipeline"| node_stage1
node_stage1 -->|"uses"| node_acquire
node_stage1 -->|"uses"| node_ingest
node_acquire -->|"downloads"| node_dataset
node_ingest -->|"writes"| node_parquet
node_stage2 -->|"assigns split"| node_split
node_stage2 -->|"writes"| node_splitmanifest
node_stage2 -->|"uses"| node_leakage
node_stage2 -->|"reads"| node_parquet
node_stage2 -->|"produces audit outputs"| node_ateresult
node_stage3 -->|"estimates effect"| node_ate
node_stage3 -->|"uses"| node_leakage
node_stage3 -->|"writes"| node_ateresult
node_stage45 -->|"uses"| node_preprocess
node_stage45 -->|"guards features"| node_leakage
node_stage45 -->|"ranks policies"| node_policy
node_stage45 -->|"estimates uncertainty"| node_bootstrap
node_stage45 -->|"loads split data"| node_parquet
node_stage5b -->|"guards features"| node_leakage
node_stage5b -->|"selects policies"| node_policy
node_stage5b -->|"compares policies"| node_bootstrap
node_stage45 -->|"informs selection"| node_freeze
node_freeze -->|"freezes before"| node_sealedtest
node_sealedtest -->|"writes"| node_testresult
node_stage3 -->|"analyzes"| node_parquet

click node_stage1 "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage1.py"
click node_acquire "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/acquire.py"
click node_ingest "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/ingest.py"
click node_stage2 "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage2_split_audit_eda.py"
click node_split "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/split.py"
click node_splitmanifest "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/artifacts/manifests/split_manifest.json"
click node_leakage "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/leakage.py"
click node_stage3 "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage3_ate.py"
click node_ate "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/ate.py"
click node_ateresult "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/reports/ate/ate.json"
click node_stage45 "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage45_validation.py"
click node_preprocess "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/preprocess.py"
click node_policy "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/policy.py"
click node_stage5b "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage5b_lightgbm_v02.py"
click node_bootstrap "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/bootstrap.py"
click node_freeze "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage6_freeze.py"
click node_sealedtest "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage6_sealed_test.py"
click node_testresult "https://github.com/rajdeepofgithub/criteo-uplift/blob/main/reports/test/test.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stage1,node_acquire,node_ingest,node_parquet toneBlue
class node_stage2,node_split,node_splitmanifest,node_leakage,node_stage3,node_ate,node_ateresult toneAmber
class node_stage45,node_preprocess,node_policy,node_stage5b toneMint
class node_bootstrap,node_freeze,node_sealedtest,node_testresult toneRose
class node_analyst,node_dataset toneIndigo
```

## Components

### Data preparation

- [Acquire stage](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage1.py): `scripts/run_stage1.py`
- [Verified download](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/acquire.py): `src/uplift_project/acquire.py`
- [Parquet ingestion](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/ingest.py): `src/uplift_project/ingest.py`
- **Processed data**

### Study analysis

- [Split audit EDA](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage2_split_audit_eda.py): `scripts/run_stage2_split_audit_eda.py`
- [Deterministic split](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/split.py): `src/uplift_project/split.py`
- [Split manifest](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/artifacts/manifests/split_manifest.json): `artifacts/manifests/split_manifest.json`
- [Feature whitelist](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/leakage.py): `src/uplift_project/leakage.py`
- [Assignment effect](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage3_ate.py): `scripts/run_stage3_ate.py`
- [ITT estimator](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/ate.py): `src/uplift_project/ate.py`
- [Effect report](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/reports/ate/ate.json): `reports/ate/ate.json`

### Policy modeling

- [Validation modeling](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage45_validation.py): `scripts/run_stage45_validation.py`
- [Logistic preprocessing](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/preprocess.py): `src/uplift_project/preprocess.py`
- [Budgeted targeting](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/policy.py): `src/uplift_project/policy.py`
- [LightGBM selection](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage5b_lightgbm_v02.py): `scripts/run_stage5b_lightgbm_v02.py`

### Evaluation and release

- [Paired bootstrap](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/src/uplift_project/bootstrap.py): `src/uplift_project/bootstrap.py`
- [Freeze stage](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage6_freeze.py): `scripts/run_stage6_freeze.py`
- [Sealed test](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/scripts/run_stage6_sealed_test.py): `scripts/run_stage6_sealed_test.py`
- [Test report](https://github.com/rajdeepofgithub/criteo-uplift/blob/main/reports/test/test.json): `reports/test/test.json`

### Other components

- **Researcher**
- **Criteo benchmark**

## Connections

- Researcher → Acquire stage: runs pipeline (evidence: `README.md`)
- Acquire stage → Verified download: uses (evidence: `scripts/run_stage1.py`)
- Acquire stage → Parquet ingestion: uses (evidence: `scripts/run_stage1.py`)
- Verified download → Criteo benchmark: downloads (evidence: `README.md`)
- Parquet ingestion → Processed data: writes (evidence: `README.md`)
- Split audit EDA → Deterministic split: assigns split (evidence: `scripts/run_stage2_split_audit_eda.py`)
- Split audit EDA → Split manifest: writes (evidence: `README.md`)
- Split audit EDA → Feature whitelist: uses (evidence: `scripts/run_stage2_split_audit_eda.py`)
- Split audit EDA → Processed data: reads (evidence: `scripts/run_stage2_split_audit_eda.py`)
- Split audit EDA → Effect report: produces audit outputs (evidence: `README.md`)
- Assignment effect → ITT estimator: estimates effect (evidence: `scripts/run_stage3_ate.py`)
- Assignment effect → Feature whitelist: uses (evidence: `scripts/run_stage3_ate.py`)
- Assignment effect → Effect report: writes (evidence: `README.md`)
- Validation modeling → Logistic preprocessing: uses (evidence: `scripts/run_stage45_validation.py`)
- Validation modeling → Feature whitelist: guards features (evidence: `scripts/run_stage45_validation.py`)
- Validation modeling → Budgeted targeting: ranks policies (evidence: `scripts/run_stage45_validation.py`)
- Validation modeling → Paired bootstrap: estimates uncertainty (evidence: `scripts/run_stage45_validation.py`)
- Validation modeling → Processed data: loads split data (evidence: `scripts/run_stage45_validation.py`)
- LightGBM selection → Feature whitelist: guards features (evidence: `scripts/run_stage5b_lightgbm_v02.py`)
- LightGBM selection → Budgeted targeting: selects policies (evidence: `scripts/run_stage5b_lightgbm_v02.py`)
- LightGBM selection → Paired bootstrap: compares policies (evidence: `scripts/run_stage5b_lightgbm_v02.py`)
- Validation modeling → Freeze stage: informs selection (evidence: `README.md`)
- Freeze stage → Sealed test: freezes before (evidence: `README.md`)
- Sealed test → Test report: writes (evidence: `README.md`)
- Assignment effect → Processed data: analyzes (evidence: `README.md`)
