# pmsims-package/pmsims architecture

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

- Interactive diagram: https://gitdiagram.com/pmsims-package/pmsims
- Repository: https://github.com/pmsims-package/pmsims

## Overview

##### Main components
- Core R package (the “pmsims engine”)
- Data generators module (R/data_generators.R)
- Model generators module (R/model_generators.R)
- Metric generators module (R/metric_generators.R & calculate_metrics_perf.R)
- Surrogate models & tuning modules (R/surrogate_models.R, R/*_tuning.R)
- Simulation wrappers & orchestrator (R/simulate_*.R, pmsims_objective_function.R)
- Plotting & reporting (R/plotting.R, R/summary.R)
- Input validation & printing (R/input_validation.R, R/print.R)
- External R ecosystem
- Base R & CRAN dependencies (stats, graphics, etc.)
- User‐supplied functions or models
- Documentation site (pkgdown)
- Docs content (docs/*, pkgdown.yml)
- Vignettes (vignettes/*.Rmd)
- Testing suite
- Unit tests (tests/testthat/*.R)
- Test runner (tests/testthat.R)
- CI/CD pipelines (GitHub Actions)
- R-CMD-check, formatting, coverage, pkgdown deploy
- Docker environment
- docker/Dockerfile for reproducible builds

##### Relationships and data flow
- “User script or R session” → calls “pmsims engine” APIs → internal flow:
Data generators → Model generators → Metric generators → Tuning loops → Summaries/Plots → Returned R objects/plots
- CI/CD: push to GitHub → triggers workflows → runs tests against the engine → builds pkgdown site → optional Docker build
- Documentation: pkgdown pipeline reads R source & man/ Rd files → outputs HTML under docs/ → served on GitHub Pages
- Docker: encapsulates R environment + pmsims code → used for CI or local reproducibility

##### Architectural patterns & design principles
- Modular code organization: each R script implements a single concern (e.g., data gen, tuning)
- Dependency injection: user can plug in custom data‐ or model‐generators
- Separation of concerns:
- Core simulation logic vs. metrics vs. plotting
- Testing and docs outside core package
- CI as code: GitHub Actions workflows centrally orchestrate checks, builds, and deployment

##### Technologies & frameworks
- R (language & runtime)
- testthat (unit testing)
- pkgdown (documentation site generator)
- GitHub Actions (CI/CD)
- Docker (reproducible environment)
- remotes (GitHub install)

##### Elements
- Tests & CI (another)
- Docs & website (another)
- Docker environment (another)
- Notes on the side for technologies (e.g., “testthat,” “pkgdown,” “Dockerfile”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User entry point
    User["User Script / R Session"]:::external
    
    %% Simulation Engine
    subgraph "Simulation Engine" 
        direction TB
        DataGen["Data Generators Module"]:::core
        ModelGen["Model Generators Module"]:::core
        MetricGen1["Metric Generators Module"]:::core
        MetricGen2["Calculate Metrics Perf"]:::core
        Surrogate["Surrogate Models"]:::core
        BinaryT["Binary Tuning"]:::core
        ContT["Continuous Tuning"]:::core
        SurvT["Survival Tuning"]:::core
        SimWrap["Simulation Wrappers"]:::core
        SimCustom["Custom Simulation"]:::core
        ObjFunc["Objective Function"]:::core
        PlotRep["Plotting & Reporting"]:::core
        Summary["Summary Reporting"]:::core
        InputVal["Input Validation"]:::core
        PrintMod["Printing Module"]:::core
    end

    %% Outputs
    Outputs["Returned R Objects / Plots"]:::external

    %% External R Ecosystem
    subgraph "External R Ecosystem" 
        direction TB
        CRAN["CRAN & Base R"]:::external
        UserFunc["User-supplied Functions / Models"]:::external
        Desc["DESCRIPTION (CRAN deps)"]:::external
    end

    %% CI/CD Pipelines
    subgraph "CI/CD (GitHub Actions)"
        direction TB
        GHRepo["GitHub Repository"]:::external
        Actions["GitHub Actions"]:::ci
        Check["R-CMD-check Workflow"]:::ci
        Format["Format & Suggest Workflow"]:::ci
        Coverage["Test Coverage Workflow"]:::ci
        PKGDeploy["pkgdown Deploy Workflow"]:::ci
    end

    %% Documentation Site
    subgraph "Documentation (pkgdown)"
        direction TB
        PkgCfg["_pkgdown.yml"]:::doc
        Vignettes["Vignettes / pmsims.Rmd"]:::doc
        Docs["docs/ HTML Site"]:::doc
    end

    %% Docker Environment
    subgraph "Docker Environment"
        direction TB
        Dockerfile["docker/Dockerfile"]:::docker
        DockerReadme["docker/README.md"]:::docker
        ReproBuild["Reproducible Build"]:::docker
    end

    %% Data Flow
    User -->|"calls"| DataGen
    DataGen --> ModelGen
    ModelGen --> MetricGen1
    MetricGen1 --> MetricGen2
    MetricGen2 --> Surrogate
    Surrogate --> BinaryT
    Surrogate --> ContT
    Surrogate --> SurvT
    BinaryT --> SimWrap
    ContT --> SimWrap
    SurvT --> SimWrap
    SimWrap --> SimCustom
    SimCustom --> ObjFunc
    ObjFunc --> PlotRep
    PlotRep --> Summary
    Summary --> InputVal
    InputVal --> PrintMod
    PrintMod --> Outputs

    %% External ecosystem connections
    DataGen --> CRAN
    ModelGen --> CRAN
    MetricGen1 --> CRAN
    Surrogate --> CRAN
    UserFunc -.-> DataGen
    UserFunc -.-> ModelGen

    %% CI/CD flow
    GHRepo --> Actions
    Actions --> Check
    Actions --> Format
    Actions --> Coverage
    Actions --> PKGDeploy

    %% Docs flow
    PKGDeploy --> PkgCfg
    PKGDeploy --> Vignettes
    PkgCfg --> Docs
    Vignettes --> Docs

    %% Docker flow
    Dockerfile --> ReproBuild
    DockerReadme --> ReproBuild
    ReproBuild --> Actions
    ReproBuild --> Outputs

    %% Click Events
    click DataGen "https://github.com/pmsims-package/pmsims/blob/main/R/data_generators.R"
    click ModelGen "https://github.com/pmsims-package/pmsims/blob/main/R/model_generators.R"
    click MetricGen1 "https://github.com/pmsims-package/pmsims/blob/main/R/metric_generators.R"
    click MetricGen2 "https://github.com/pmsims-package/pmsims/blob/main/R/calculate_metrics_perf.R"
    click Surrogate "https://github.com/pmsims-package/pmsims/blob/main/R/surrogate_models.R"
    click BinaryT "https://github.com/pmsims-package/pmsims/blob/main/R/binary_tuning.R"
    click ContT "https://github.com/pmsims-package/pmsims/blob/main/R/continuous_tuning.R"
    click SurvT "https://github.com/pmsims-package/pmsims/blob/main/R/survival_tuning.R"
    click SimWrap "https://github.com/pmsims-package/pmsims/blob/main/R/simulate_wrappers.R"
    click SimCustom "https://github.com/pmsims-package/pmsims/blob/main/R/simulate_custom.R"
    click ObjFunc "https://github.com/pmsims-package/pmsims/blob/main/R/pmsims_objective_function.R"
    click PlotRep "https://github.com/pmsims-package/pmsims/blob/main/R/plotting.R"
    click Summary "https://github.com/pmsims-package/pmsims/blob/main/R/summary.R"
    click InputVal "https://github.com/pmsims-package/pmsims/blob/main/R/input_validation.R"
    click PrintMod "https://github.com/pmsims-package/pmsims/blob/main/R/print.R"
    click Desc "https://github.com/pmsims-package/pmsims/tree/main/DESCRIPTION"
    click PkgCfg "https://github.com/pmsims-package/pmsims/blob/main/_pkgdown.yml"
    click Docs "https://github.com/pmsims-package/pmsims/tree/main/docs/"
    click Vignettes "https://github.com/pmsims-package/pmsims/blob/main/vignettes/pmsims.Rmd"
    click Check "https://github.com/pmsims-package/pmsims/blob/main/.github/workflows/R-CMD-check.yaml"
    click Format "https://github.com/pmsims-package/pmsims/blob/main/.github/workflows/format-suggest.yaml"
    click Coverage "https://github.com/pmsims-package/pmsims/blob/main/.github/workflows/test-coverage.yaml"
    click PKGDeploy "https://github.com/pmsims-package/pmsims/blob/main/.github/workflows/pkgdown.yaml"
    click Dockerfile "https://github.com/pmsims-package/pmsims/tree/main/docker/Dockerfile"
    click DockerReadme "https://github.com/pmsims-package/pmsims/blob/main/docker/README.md"

    %% Styles
    classDef core fill:#a0c4ff,stroke:#0366d6,color:#000;
    classDef ci fill:#caffbf,stroke:#198754,color:#000;
    classDef doc fill:#ffadad,stroke:#d6336c,color:#000;
    classDef docker fill:#fdffb6,stroke:#fcc419,color:#000;
    classDef external fill:#e0e0e0,stroke:#6c757d,color:#000;
```
