# csglab/gedi2 architecture

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

- Interactive diagram: https://gitdiagram.com/csglab/gedi2
- Repository: https://github.com/csglab/gedi2

## Overview

GEDI-2 is an R package for fitting an interpretable latent model to multi-sample, multi-condition single-cell expression data. The main user workflow is to provide expression data, fit the model, then use its latent representation for projections and downstream analyses such as differential expression, pathway activity, imputation, and visualization. The README establishes the product scope; sampled C++ excerpts show model training and specialized numerical routines. Most R-facing orchestration and optional integrations were not sampled, so their internal connections are not asserted.

Main entry points: [`src/gedi_core.cpp`](https://github.com/csglab/gedi2/blob/main/src/gedi_core.cpp) (Model optimizer), [`R/gedi_class.R`](https://github.com/csglab/gedi2/blob/main/R/gedi_class.R) (GEDI object)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model fitting"]
  node_gedi_object["GEDI object<br/>[gedi_class.R]"]
  node_model_core["Model optimizer<br/>[gedi_core.cpp]"]
  node_matrix_ops["Matrix operations"]
end

subgraph group_analysis["Model analyses"]
  node_imputation_engine["Imputation routines"]
  node_dimred_engine["Factorized SVD<br/>[gedi_dimred.cpp]"]
  node_projection_engine["Projections"]
  node_differential_engine["Differential analysis"]
  node_feature_engine["Feature projections<br/>[gedi_plots.cpp]"]
  node_dynamics["Dynamics analysis<br/>[gedi_dynamics.R]"]
  node_pathway["Pathway analysis<br/>[gedi_pathway.R]"]
  node_imputation["Imputation API<br/>[gedi_imputation.R]"]
  node_plots["Visualization<br/>[gedi_plots.R]"]
  node_plot_wrappers["Plot wrappers"]
  node_projection_r["Projection API<br/>[gedi_projections.R]"]
  node_dimred_r["Dimension reduction<br/>[gedi_dimred.R]"]
end

subgraph group_io["Data exchange"]
  node_h5_read["HDF5 readers<br/>[h5_readers.R]"]
  node_h5_write["HDF5 writers<br/>[h5_writers.R]"]
  node_seurat["Seurat exchange"]
end

subgraph group_interface["R interface"]
  node_cpp_bindings["Rcpp bindings<br/>[RcppExports.cpp]"]
end

node_user(("Analyst"))

node_user -.->|"provides data"| node_gedi_object
node_model_core -->|"initializes then optimizes"| node_model_core

click node_gedi_object "https://github.com/csglab/gedi2/blob/main/R/gedi_class.R"
click node_model_core "https://github.com/csglab/gedi2/blob/main/src/gedi_core.cpp"
click node_matrix_ops "https://github.com/csglab/gedi2/blob/main/src/matrix_oprations.cpp"
click node_imputation_engine "https://github.com/csglab/gedi2/blob/main/src/gedi_imputation.cpp"
click node_dimred_engine "https://github.com/csglab/gedi2/blob/main/src/gedi_dimred.cpp"
click node_projection_engine "https://github.com/csglab/gedi2/blob/main/src/gedi_projections.cpp"
click node_differential_engine "https://github.com/csglab/gedi2/blob/main/src/gedi_differential.cpp"
click node_feature_engine "https://github.com/csglab/gedi2/blob/main/src/gedi_plots.cpp"
click node_dynamics "https://github.com/csglab/gedi2/blob/main/R/gedi_dynamics.R"
click node_pathway "https://github.com/csglab/gedi2/blob/main/R/gedi_pathway.R"
click node_imputation "https://github.com/csglab/gedi2/blob/main/R/gedi_imputation.R"
click node_plots "https://github.com/csglab/gedi2/blob/main/R/gedi_plots.R"
click node_plot_wrappers "https://github.com/csglab/gedi2/blob/main/R/gedi_plot_wrappers.R"
click node_h5_read "https://github.com/csglab/gedi2/blob/main/R/h5_readers.R"
click node_h5_write "https://github.com/csglab/gedi2/blob/main/R/h5_writers.R"
click node_seurat "https://github.com/csglab/gedi2/blob/main/R/seurat_integration.R"
click node_cpp_bindings "https://github.com/csglab/gedi2/blob/main/src/RcppExports.cpp"
click node_projection_r "https://github.com/csglab/gedi2/blob/main/R/gedi_projections.R"
click node_dimred_r "https://github.com/csglab/gedi2/blob/main/R/gedi_dimred.R"

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_gedi_object,node_model_core,node_matrix_ops toneBlue
class node_imputation_engine,node_dimred_engine,node_projection_engine,node_differential_engine,node_feature_engine,node_dynamics,node_pathway,node_imputation,node_plots,node_plot_wrappers,node_projection_r,node_dimred_r toneAmber
class node_h5_read,node_h5_write,node_seurat toneMint
class node_cpp_bindings toneRose
class node_user toneIndigo
```

## Components

### Model fitting

- [GEDI object](https://github.com/csglab/gedi2/blob/main/R/gedi_class.R): `R/gedi_class.R`
- [Model optimizer](https://github.com/csglab/gedi2/blob/main/src/gedi_core.cpp): `src/gedi_core.cpp`
- [Matrix operations](https://github.com/csglab/gedi2/blob/main/src/matrix_oprations.cpp): `src/matrix_oprations.cpp`

### Model analyses

- [Imputation routines](https://github.com/csglab/gedi2/blob/main/src/gedi_imputation.cpp): `src/gedi_imputation.cpp`
- [Factorized SVD](https://github.com/csglab/gedi2/blob/main/src/gedi_dimred.cpp): `src/gedi_dimred.cpp`
- [Projections](https://github.com/csglab/gedi2/blob/main/src/gedi_projections.cpp): `src/gedi_projections.cpp`
- [Differential analysis](https://github.com/csglab/gedi2/blob/main/src/gedi_differential.cpp): `src/gedi_differential.cpp`
- [Feature projections](https://github.com/csglab/gedi2/blob/main/src/gedi_plots.cpp): `src/gedi_plots.cpp`
- [Dynamics analysis](https://github.com/csglab/gedi2/blob/main/R/gedi_dynamics.R): `R/gedi_dynamics.R`
- [Pathway analysis](https://github.com/csglab/gedi2/blob/main/R/gedi_pathway.R): `R/gedi_pathway.R`
- [Imputation API](https://github.com/csglab/gedi2/blob/main/R/gedi_imputation.R): `R/gedi_imputation.R`
- [Visualization](https://github.com/csglab/gedi2/blob/main/R/gedi_plots.R): `R/gedi_plots.R`
- [Plot wrappers](https://github.com/csglab/gedi2/blob/main/R/gedi_plot_wrappers.R): `R/gedi_plot_wrappers.R`
- [Projection API](https://github.com/csglab/gedi2/blob/main/R/gedi_projections.R): `R/gedi_projections.R`
- [Dimension reduction](https://github.com/csglab/gedi2/blob/main/R/gedi_dimred.R): `R/gedi_dimred.R`

### Data exchange

- [HDF5 readers](https://github.com/csglab/gedi2/blob/main/R/h5_readers.R): `R/h5_readers.R`
- [HDF5 writers](https://github.com/csglab/gedi2/blob/main/R/h5_writers.R): `R/h5_writers.R`
- [Seurat exchange](https://github.com/csglab/gedi2/blob/main/R/seurat_integration.R): `R/seurat_integration.R`

### R interface

- [Rcpp bindings](https://github.com/csglab/gedi2/blob/main/src/RcppExports.cpp): `src/RcppExports.cpp`

### Other components

- **Analyst**

## Connections

- Analyst → GEDI object: provides data (evidence: `README.md`)
- Model optimizer → Model optimizer: initializes then optimizes (evidence: `src/gedi_core.cpp`)
