# hanlife02/social-science-quantitative-methods architecture

> Architecture diagram of the GitHub repository hanlife02/social-science-quantitative-methods, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hanlife02/social-science-quantitative-methods
- Repository: https://github.com/hanlife02/social-science-quantitative-methods

## Overview

##### Project Type and Purpose
- This is a Python-based data-analysis pipeline for a social-science research project. It ingests raw CSV data, processes it, computes descriptive statistics, fits statistical models, interprets results, and produces visualizations and markdown reports. There is no frontend or web layer.

##### File-Structure Analysis
- Top level:
- main.py – orchestration entrypoint
- config.py – global parameters (paths, model settings)
- requirements.txt – external Python libraries (pandas, numpy, statsmodels, matplotlib, seaborn, etc.)
- data/ethnic_conflict_data.csv – raw data
- output/ – directory to hold figures and results in subfolders
- src/ – Python modules by functionality:
- data_processing.py
- descriptive_stats.py
- modeling.py
- interpretation.py
- visualization.py

##### Key Components
a. Data Input Layer
- Raw CSV (data/ethnic_conflict_data.csv)
- Configuration (config.py)
b. Processing & Analysis Modules
- Data Processing Module (src/data_processing.py)
- Descriptive Statistics Module (src/descriptive_stats.py)
- Modeling Module (src/modeling.py)
- Interpretation Module (src/interpretation.py)
- Visualization Module (src/visualization.py)
c. Orchestration
- main.py ties together modules in sequence, reading config values
d. Output Layer
- Figures (output/figures/*)
- Text Results and Markdown Reports (output/results/*.md)
e. External Dependencies
- Python runtime
- Libraries (pandas, numpy, statsmodels, matplotlib, seaborn, etc.)

##### Relationships & Data Flow
- main.py → reads config.py → loads raw CSV
- raw data → data_processing → cleaned/augmented DataFrame
- processed data → descriptive_stats → summary tables
- processed data → modeling → fitted models & coefficients
- models & stats → interpretation → narrative insights (markdown)
- processed data + model outputs → visualization → plots saved under output/figures
- All outputs collected under output/ directory
- Dependencies: each module imports pandas/numpy/statsmodels, config.py

##### Architectural Patterns & Principles
- Pipeline pattern: sequential stages, single responsibility per module
- Layered grouping: Input → Processing → Analysis → Presentation → Storage
- Modular design: each src/*.py encapsulates one stage, enabling testing and reuse
- Config-driven: behavior controlled by a single config.py

##### Technologies & Frameworks
- Python 3.x
- pandas for data ingestion & manipulation
- numpy for numeric operations
- statsmodels (or scikit-learn) for regression modeling
- matplotlib / seaborn for plotting
- markdown for narrative output

##### Essential Elements
- Clear textual labels for each node (module names, file paths)
- Data stores
- Code modules
- Outputs
- External libraries
- Optional: annotate module inputs/outputs (e.g., “DataFrame with X variables”)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration
    main["main.py"]:::module
    config["config.py"]:::module
    raw["Raw CSV\ndata/ethnic_conflict_data.csv"]:::datastore

    %% Processing & Analysis Modules
    subgraph "Processing & Analysis"
        direction TB
        dp["Data Processing\nsrc/data_processing.py"]:::module
        ds["Descriptive Statistics\nsrc/descriptive_stats.py"]:::module
        mdl["Modeling\nsrc/modeling.py"]:::module
        interp["Interpretation\nsrc/interpretation.py"]:::module
        viz["Visualization\nsrc/visualization.py"]:::module
    end

    %% Output Layer
    fig["Figures\noutput/figures/"]:::output
    mdr["Markdown Reports\noutput/results/"]:::output

    %% External Dependencies
    ext["External Libraries\nrequirements.txt"]:::external

    %% Connections
    main -->|"reads config"| config
    main -->|"loads raw data"| raw
    main -->|"calls processing"| dp
    config -->|"provides parameters"| dp
    raw -->|"input data"| dp

    dp -->|"cleaned data"| ds
    dp -->|"cleaned data"| mdl

    ds -->|"summary tables"| interp
    mdl -->|"model outputs"| interp

    dp -->|"cleaned data"| viz
    mdl -->|"model outputs"| viz

    viz -->|"saves plots"| fig
    interp -->|"writes markdown"| mdr

    %% Dependencies
    ext -.-> dp
    ext -.-> ds
    ext -.-> mdl
    ext -.-> interp
    ext -.-> viz
    ext -.-> main

    %% Click Events
    click main "https://github.com/hanlife02/social-science-quantitative-methods/blob/main/main.py"
    click config "https://github.com/hanlife02/social-science-quantitative-methods/blob/main/config.py"
    click raw "https://github.com/hanlife02/social-science-quantitative-methods/blob/main/data/ethnic_conflict_data.csv"
    click dp "https://github.com/hanlife02/social-science-quantitative-methods/blob/main/src/data_processing.py"
    click ds "https://github.com/hanlife02/social-science-quantitative-methods/blob/main/src/descriptive_stats.py"
    click mdl "https://github.com/hanlife02/social-science-quantitative-methods/blob/main/src/modeling.py"
    click interp "https://github.com/hanlife02/social-science-quantitative-methods/blob/main/src/interpretation.py"
    click viz "https://github.com/hanlife02/social-science-quantitative-methods/blob/main/src/visualization.py"
    click fig "https://github.com/hanlife02/social-science-quantitative-methods/tree/main/output/figures/"
    click mdr "https://github.com/hanlife02/social-science-quantitative-methods/tree/main/output/results/"
    click ext "https://github.com/hanlife02/social-science-quantitative-methods/blob/main/requirements.txt"

    %% Styles
    classDef datastore fill:#1f77b4,stroke:#000,color:#fff
    classDef module fill:#2ca02c,stroke:#000,color:#000
    classDef output fill:#ffbb78,stroke:#000,color:#000
    classDef external stroke-dasharray: 5 5,fill:#d3d3d3,stroke:#000,color:#000
```
