# ellenbet/survana architecture

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

- Interactive diagram: https://gitdiagram.com/ellenbet/survana
- Repository: https://github.com/ellenbet/survana

## Overview

##### Project type and purpose
- This is a Python-based survival analysis and biomarker‐discovery toolkit. It provides functionality for:
- Artificial data generation
- Data ingestion, merging, and preprocessing
- Model definition and fitting (e.g., Cox proportional hazards)
- Hyperparameter tuning (Optuna objectives)
- Example notebooks and result visualization
- It ships as a library (`src/survana`), a CLI entrypoint (`main.py`), and supporting docs, tests, and Docker/CI config.

##### File structure
- Top-level:
- Dockerfile, .dockerignore – containerization
- .pre-commit-config.yaml – code style enforcement
- mkdocs.yml and `docs/` – documentation site configuration
- `examples/` – Jupyter notebooks illustrating usage
- `src/survana/` – core library packages
- `tests/` + `test_data/` – automated tests
- `main.py` – likely CLI start point
- Core library submodules under `src/survana/`:
- `artificial_data_generation/` – synthetic dataset creation
- `data_processing/` – data models, loaders, merger utilities
- `models/` – statistical/ML models (e.g., `coxph.py`)
- `tuning/` – tuning entrypoints for Optuna
- Supporting files: `pyproject.toml` for packaging, `uv.lock` for dependency locking.

##### README
- Confirms survival analysis focus and dependency on pre-commit, mypy, isort, black, flake8.
- Mentions “uv sync”—likely referencing a task runner CLI.

a. CLI / entrypoint
– main.py invokes library functions (data gen → processing → modeling → tuning)
b. Library packages
– Artificial Data Generation
– Data Processing
– Models
– Tuning
c. External systems / services
– Optuna (for hyperparameter search)
– MLflow (if used—docs mention mlflow)
– Docker (for containerized runs)
d. Data stores
– Input CSVs (e.g., `test_matrix.csv`, user data)
– Generated synthetic data
– Output figures (`result_figs/`)
e. Tests & CI
– pytest runs tests in `tests/` against `test_data/`

##### Relationships and interactions
- CLI → calls Artificial Data Generation → outputs dataset
- CLI → calls Data Processing → ingests real or synthetic CSVs → normalized data models
- Processed data → passed to Models → fit and evaluate survival models
- Model fitting → optionally triggers Tuning → uses Optuna engine → iterates model fits
- Tuning results → logged to MLflow or local artifact store → final metrics and output figures
- All modules share common data models and type definitions (in `data_models.py`)

##### Architectural patterns and design principles
- Modular layering: each functional area (generation, processing, modeling, tuning) lives in its own package
- Single-responsibility: modules do one job, enabling testability
- Dependency injection via function arguments (e.g., pass DataFrame to model/trainer)
- Extensibility: adding new models or tuning objectives involves dropping in new modules under `models` or `tuning`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Orchestrator
    subgraph "CLI / Orchestrator"
        CLI["CLI / Orchestrator\n(main.py)"]:::lib
    end

    %% Library Modules
    subgraph "Library Modules"
        ADG["Artificial Data Generation\n(generation.py, methods.py)"]:::lib
        DP["Data Processing\n(data_models.py, dataloaders.py, datamergers.py)"]:::lib
        MDL["Modeling\n(coxph.py)"]:::lib
        TUNE["Tuning Engine\n(optuna_objectives.py)"]:::lib
    end

    %% Data Stores
    subgraph "Data Stores"
        RAW["Raw Input CSV\n(test_matrix.csv, user data)"]:::data
        SYN["Synthetic Data Store"]:::data
        OUT["Output Artifacts\n(result_figs/)"]:::data
    end

    %% External Services
    subgraph "External Services"
        OPTUNA["Optuna"]:::external
        MLFLOW["MLflow"]:::external
        DOCKER["Docker"]:::external
    end

    %% CI and Documentation
    subgraph "CI / Documentation"
        DOCS["MkDocs\n(mkdocs.yml, docs/)"]:::external
        TESTS["Test Suite\n(tests/, test_data/)"]:::external
        PRECOMMIT["Pre-commit Hooks"]:::external
    end

    %% Flow of Data and Control
    CLI -->|"generate synthetic data"| ADG
    ADG -->|"save synthetic CSV"| SYN
    CLI -->|"ingest data"| DP
    DP -->|"read raw CSV"| RAW
    SYN -->|"ingest data"| DP
    DP -->|"normalized data frame"| MDL
    MDL -->|"fit model"| TUNE
    TUNE -.->|"invoke Optuna"| OPTUNA
    TUNE -.->|"log results"| MLFLOW
    TUNE -->|"generate figures"| OUT

    %% Docker integration
    DOCKER -.-> CLI
    DOCKER -.-> ADG
    DOCKER -.-> DP
    DOCKER -.-> MDL
    DOCKER -.-> TUNE

    %% CI and Docs integration
    DOCS -->|"build docs"| PRECOMMIT
    TESTS -->|"run tests"| PRECOMMIT

    %% Click Events
    click CLI "https://github.com/ellenbet/survana/blob/main/main.py"
    click ADG "https://github.com/ellenbet/survana/blob/main/src/survana/artificial_data_generation/generation.py"
    click ADG "https://github.com/ellenbet/survana/blob/main/src/survana/artificial_data_generation/methods.py"
    click DP "https://github.com/ellenbet/survana/blob/main/src/survana/data_processing/data_models.py"
    click DP "https://github.com/ellenbet/survana/blob/main/src/survana/data_processing/dataloaders.py"
    click DP "https://github.com/ellenbet/survana/blob/main/src/survana/data_processing/datamergers.py"
    click MDL "https://github.com/ellenbet/survana/blob/main/src/survana/models/coxph.py"
    click TUNE "https://github.com/ellenbet/survana/blob/main/src/survana/tuning/optuna_objectives.py"
    click DOCKER "https://github.com/ellenbet/survana/tree/main/Dockerfile"
    click DOCKER "https://github.com/ellenbet/survana/blob/main/.dockerignore"
    click DOCS "https://github.com/ellenbet/survana/blob/main/mkdocs.yml"
    click DOCS "https://github.com/ellenbet/survana/tree/main/docs/"
    click TESTS "https://github.com/ellenbet/survana/tree/main/tests/"
    click TESTS "https://github.com/ellenbet/survana/blob/main/test_data/test_matrix.csv"
    click OUT "https://github.com/ellenbet/survana/tree/main/result_figs/"

    %% Styles
    classDef lib fill:#cce5ff,stroke:#004085;
    classDef external fill:#d4edda,stroke:#155724;
    classDef data fill:#fff3cd,stroke:#856404;
```
