# mrcieu/twosamplemr architecture

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

- Interactive diagram: https://gitdiagram.com/mrcieu/twosamplemr
- Repository: https://github.com/mrcieu/twosamplemr

## Overview

##### Project type and purpose
- This is an R package (“TwoSampleMR”) for performing Mendelian randomization analyses on GWAS summary data.
- It exposes a set of R functions to the end-user and connects to the IEU OpenGWAS database to fetch input data.
- It also includes vignettes, example datasets, automated tests, and CI/CD workflows for package checking, documentation building, and coverage reporting.

a. Core R Library (R/ directory)
– All exported functions (mr(), harmonise(), clump_data(), forest_plot(), etc.)
– Internal utilities and pipelines (utils-pipe.R, globals.R)
b. Example Data & Vignettes (inst/ directory)
– inst/extdata: example CSV, TXT, RData files used in examples/tests
– inst/reports & inst/sandpit: reproducible R Markdown reports and scripts
c. Documentation Site (pkgdown)
– pkgdown config (_pkgdown.yml, pkgdown/extra.css)
– index.md, vignettes/*.Rmd
d. Testing Suite (tests/)
– testthat scripts that invoke core functions against sample data
e. Metadata & Build Files
– DESCRIPTION, NAMESPACE, CITATION, LICENSE, NEWS.md
– R-project file (TwoSampleMR.Rproj), .Rbuildignore, .lintr
f. CI/CD Pipelines (.github/workflows)
– check-full.yaml: run R-CMD-check on multiple platforms
– test-coverage.yaml: generate coverage report
– pkgdown.yaml: build and deploy website
g. External Services
– IEU OpenGWAS API (data source)
– Zenodo (DOI badge)
– GitHub (source repo, Actions)
– R-Universe (package distribution)

##### Relationships & data flows
- User calls exported functions in Core R Library → Library fetches data via OpenGWAS API → transforms & harmonises data → runs MR methods → returns results or plots.
- Core Library functions read example inst/extdata for internal cross-checks or vignettes.
- Testing Suite invokes Core Library functions using inst/extdata; reports pass/fail to CI.
- Vignettes and inst/reports use Core Library to generate HTML/PDF outputs; served via pkgdown site.
- GitHub Actions orchestrate:
– R-CMD check → fails/passes status back to GitHub PR
– Test coverage tool → updates Codecov badge
– pkgdown build → publishes HTML site to GitHub Pages or R-Universe

##### Architectural patterns & design principles
- Modular functional design: each analytical step is a separate function (e.g., mr_ivw, mr_egger).
- Directory‐by‐concern: R/, man/, tests/, vignettes/, inst/, pkgdown/
- CI/CD as first‐class citizens: every push triggers checks, coverage, docs.
- Reproducibility via vignettes and inst/sandpit examples.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Local Development
    subgraph "Local Development"
        direction TB
        User["User (R Session)"]:::external
        CoreRL["Core R Library"]:::code
        ExampleData["Inst/Extdata"]:::data
        Reports["Reproducible Reports & Sandpit"]:::data
        Vignettes["Vignettes"]:::data
        DocsConfig["Documentation Site Config"]:::docs
        Testing["Testing Suite"]:::test
        Metadata["Metadata & Build Files"]:::code
    end

    %% CI/CD Infrastructure
    subgraph "CI/CD Infrastructure"
        direction TB
        Actions["GitHub Actions"]:::ci
        Coverage["Codecov"]:::ci
        PkgdownSite["Pkgdown Site (Deployed)"]:::docs
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenGWAS["IEU OpenGWAS API"]:::external
        Zenodo["Zenodo (DOI)"]:::external
        GitHub["GitHub (Repo & Actions)"]:::external
        RUniverse["R-Universe"]:::external
    end

    %% Data Flows and Relationships
    User -->|"calls functions"| CoreRL
    CoreRL -->|"HTTP GET /gwas/{id}.json"| OpenGWAS
    OpenGWAS -->|"returns JSON/TSV"| CoreRL
    CoreRL -->|"reads RData/CSV"| ExampleData
    CoreRL -->|"invoked by"| Testing
    Testing -->|"R-CMD-check & testthat"| Actions
    CoreRL -->|"used in reports"| Reports
    Reports -->|"R Markdown"| PkgdownSite
    CoreRL -->|"used in vignettes"| Vignettes
    Vignettes -->|"R Markdown"| PkgdownSite
    Actions -->|"build & deploy site"| PkgdownSite
    Actions -->|"updates badge"| Coverage
    Coverage -->|"badge on README"| GitHub
    Actions -->|"CI status"| GitHub
    Actions -->|"release package"| RUniverse
    Zenodo -->|"DOI badge"| DocsConfig

    %% Click Events
    click CoreRL "https://github.com/mrcieu/twosamplemr/tree/master/R/"
    click CoreRL "https://github.com/mrcieu/twosamplemr/blob/master/R/mr.R"
    click CoreRL "https://github.com/mrcieu/twosamplemr/blob/master/R/harmonise.R"
    click CoreRL "https://github.com/mrcieu/twosamplemr/blob/master/R/clump_data.R"
    click CoreRL "https://github.com/mrcieu/twosamplemr/blob/master/R/forest_plot.R"
    click CoreRL "https://github.com/mrcieu/twosamplemr/blob/master/R/utils-pipe.R"
    click CoreRL "https://github.com/mrcieu/twosamplemr/blob/master/R/globals.R"
    click ExampleData "https://github.com/mrcieu/twosamplemr/tree/master/inst/extdata/"
    click Reports "https://github.com/mrcieu/twosamplemr/blob/master/inst/reports/mr_report.Rmd"
    click Reports "https://github.com/mrcieu/twosamplemr/tree/master/inst/sandpit/"
    click Vignettes "https://github.com/mrcieu/twosamplemr/tree/master/vignettes/"
    click DocsConfig "https://github.com/mrcieu/twosamplemr/blob/master/_pkgdown.yml"
    click DocsConfig "https://github.com/mrcieu/twosamplemr/blob/master/pkgdown/extra.css"
    click DocsConfig "https://github.com/mrcieu/twosamplemr/blob/master/index.md"
    click Testing "https://github.com/mrcieu/twosamplemr/tree/master/tests/"
    click Testing "https://github.com/mrcieu/twosamplemr/blob/master/tests/testthat/test_mr.R"
    click Testing "https://github.com/mrcieu/twosamplemr/blob/master/tests/testthat/helper-twosamplemr.R"
    click Metadata "https://github.com/mrcieu/twosamplemr/tree/master/DESCRIPTION"
    click Metadata "https://github.com/mrcieu/twosamplemr/tree/master/NAMESPACE"
    click Metadata "https://github.com/mrcieu/twosamplemr/blob/master/CITATION.cff"
    click Metadata "https://github.com/mrcieu/twosamplemr/tree/master/LICENSE"
    click Metadata "https://github.com/mrcieu/twosamplemr/blob/master/NEWS.md"
    click Metadata "https://github.com/mrcieu/twosamplemr/blob/master/.Rbuildignore"
    click Metadata "https://github.com/mrcieu/twosamplemr/blob/master/.lintr"
    click Metadata "https://github.com/mrcieu/twosamplemr/blob/master/TwoSampleMR.Rproj"
    click Actions "https://github.com/mrcieu/twosamplemr/blob/master/.github/workflows/check-full.yaml"
    click Actions "https://github.com/mrcieu/twosamplemr/blob/master/.github/workflows/test-coverage.yaml"
    click Actions "https://github.com/mrcieu/twosamplemr/blob/master/.github/workflows/pkgdown.yaml"
    click Coverage "https://github.com/mrcieu/twosamplemr/blob/master/codecov.yml"

    %% Styles
    classDef code fill:#D0E1F9,stroke:#0B3D91,color:#0B3D91
    classDef data fill:#D4EDDA,stroke:#155724,color:#155724
    classDef test fill:#FFF3CD,stroke:#856404,color:#856404
    classDef docs fill:#E2D9F3,stroke:#5F259F,color:#5F259F
    classDef ci fill:#FFE5D4,stroke:#D35400,color:#D35400
    classDef external fill:#ECECEC,stroke:#7F8C8D,color:#7F8C8D
    class User,OpenGWAS,Zenodo,GitHub,RUniverse external
    class CoreRL,Metadata code
    class ExampleData,Reports,Vignettes data
    class Testing test
    class DocsConfig,PkgdownSite docs
    class Actions,Coverage ci
```
