# constantamateur/soupx architecture

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

- Interactive diagram: https://gitdiagram.com/constantamateur/soupx
- Repository: https://github.com/constantamateur/soupx

## Overview

##### Project type and purpose
- SoupX is an R/Bioconductor package (an open-source tool) whose core purpose is to estimate and remove ambient “soup” RNA contamination from droplet-based single-cell RNA-seq data.
- It provides a high-level API for loading raw matrices, estimating contamination, adjusting counts, and producing a clean count matrix for downstream analysis.

##### File structure
Top-level directories and files:
- R/            – All R source files: the core functions and class definitions (e.g., SoupChannel class, estimation and adjustment routines).
- data/         – Pre-built example datasets (.RData).
- inst/         –
– extdata/    – Toy 10X matrices and metadata in Matrix Market format.
– doc/        – Rendered vignettes and tutorials.
– CITATION    – Citation info.
- man/          – Automatically generated Rd documentation for every exported function.
- vignettes/    – R Markdown source for longer tutorials.
- DESCRIPTION, NAMESPACE – Package metadata and export directives.
- README.md     – High-level overview, quickstart, FAQs, changelog.

##### README for additional insights
- Describes user-facing workflow: load10X → setClusters (if needed) → autoEstCont → adjustCounts → output corrected matrix.
- Lists dependencies (Seurat, BiocManager, multtest, standard R packages).
- Explains two main modes: automatic (autoEstCont) and manual (setContaminationFraction).

##### Main components
a. Components
1. User Interface Layer
- R console / script / interactive session.
2. Input Data
- Raw count matrices (10X HDF5 or Matrix Market files under inst/extdata).
- Metadata (barcodes, genes).
- Optional cluster labels.
- SoupChannel class (data structure holding raw data, metadata, and results).
- Loading functions: load10X(), SoupChannel().
- Estimation functions: estimateSoup(), estimateNonExpressingCells(), autoEstCont(), calculateContaminationFraction().
- Adjustment functions: adjustCounts().
- Utility & plotting: plotFunctions.R, utils.R, quickMarkers.R, etc.
- Seurat::Read10X, BiocManager::multtest, Matrix package, stats, methods.
5. Output Data
- Corrected count matrix (returned by adjustCounts).
- Diagnostic plots and reports (via plotFunctions and vignettes).

b. Relationships & interactions
- User invokes load10X() / SoupChannel() → constructs SoupChannel S4 object.
- (Optional) setClusters() injects clustering labels into object.
- autoEstCont() or calculateContaminationFraction() reads the SoupChannel slots (raw counts + metadata + clusters) and writes a contamination estimate (ρ) back into the object.
- adjustCounts() takes the contamination‐annotated SoupChannel object, applies the correction algorithm, and produces a new corrected count matrix.
- Utility and plot functions read from the SoupChannel object (before or after correction) to generate diagnostic plots.
- Vignette and documentation reference all of these steps.

c. Architectural patterns & design principles
- S4 object‐oriented design (SoupChannel class encapsulates data + methods).
- Modular: each R file implements a logical subset of functionality (I/O, estimation, plotting).
- Data‐flow pipeline: raw data → object creation → contamination estimation → count adjustment → output.
- Separation of concerns: core algorithm separated from I/O and plotting utilities.

d. Key technologies & libraries
- R and Bioconductor ecosystem.
- Matrix Market I/O (matrix.mtx, barcodes.tsv).
- S4 classes (methods package).
- Seurat for 10X loading.
- BiocManager/multtest for statistical routines.
- ggplot2 or base graphics for plotting (via plotFunctions).

##### Detail without over-partitioning
- R file group as a subcomponent (I/O, estimation, adjustment, plotting).
- How documentation (man/, vignettes/) and data (inst/extdata, data/) fit around the core algorithm.

- the user-driven workflow,
- the central SoupChannel data structure,
- the modular functions operating on it, and
- the inputs, outputs, and external dependencies that define the SoupX architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    User["User (R Console / Script)"]:::user

    %% Input Data
    subgraph "Input Data" 
        direction TB
        RawMatrices["Raw Count Matrices\n(10X HDF5 / Matrix Market)"]:::data
        Metadata["Metadata\n(barcodes.tsv, genes.tsv)"]:::data
        ClusterLabels["Optional Cluster Labels"]:::data
    end

    %% Core Pipeline
    subgraph "Core Pipeline" 
        direction TB

        subgraph "Loading Module" 
            direction TB
            Load10X["load10X()"]:::module
            SoupCtor["SoupChannel S4 Class Definition\n& Constructor"]:::module
        end

        SoupChannelObj["SoupChannel S4 Object"]:::object

        subgraph "Estimation Module"
            direction TB
            EstimateSoup["estimateSoup()"]:::module
            EstimateNonExpress["estimateNonExpressingCells()"]:::module
            AutoEstCont["autoEstCont()"]:::module
            ManualEstCont["calculateContaminationFraction()"]:::module
        end

        subgraph "Adjustment Module"
            direction TB
            AdjustCounts["adjustCounts()"]:::module
        end

        subgraph "Utilities & Plotting"
            direction TB
            PlotFuncs["plotFunctions.R"]:::module
            QuickMarkers["quickMarkers.R"]:::module
            Utils["utils.R / data.R"]:::module
        end

        %% Pipeline arrows
        RawMatrices --> Load10X
        Metadata --> Load10X
        Load10X --> SoupCtor
        SoupCtor --> SoupChannelObj

        SoupChannelObj --> EstimateSoup
        SoupChannelObj --> EstimateNonExpress
        EstimateSoup --> AutoEstCont
        EstimateNonExpress --> AutoEstCont
        AutoEstCont --> SoupChannelObj
        SoupChannelObj --> ManualEstCont
        ManualEstCont --> SoupChannelObj

        SoupChannelObj --> AdjustCounts
        AdjustCounts --> CorrectedMatrix

        SoupChannelObj --> PlotFuncs
        SoupChannelObj --> QuickMarkers
        SoupChannelObj --> Utils
    end

    %% Outputs
    subgraph "Output Data"
        direction TB
        CorrectedMatrix["Corrected Count Matrix"]:::data
        DiagnosticPlots["Diagnostic Plots & Reports"]:::data
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        Seurat["Seurat::Read10X"]:::external
        BiocMulti["BiocManager::multtest"]:::external
        MatrixPkg["Matrix package"]:::external
        Stats["stats package"]:::external
        Methods["methods package"]:::external
        ggplot2["ggplot2 / base graphics"]:::external
    end

    %% Data & Documentation
    subgraph "Data & Documentation"
        direction TB
        ExampleData["Example Datasets (.RData)"]:::data
        MatrixMarket["10X Matrix Market Files"]:::data
        VignetteSrc["vignettes/pbmcTutorial.Rmd"]:::doc
        VignetteDoc["inst/doc/pbmcTutorial.html"]:::doc
        ManPages["man/*.Rd"]:::doc
        Description["DESCRIPTION & NAMESPACE"]:::doc
        Readme["README.md"]:::doc
    end

    %% Doc/Data arrows
    ExampleData --> SoupChannelObj
    MatrixMarket --> Load10X
    VignetteSrc --> User
    VignetteDoc --> User
    ManPages --> User
    Description --> SoupChannelObj
    Readme --> User

    %% Dependencies arrows
    Load10X --> Seurat
    EstimateSoup --> BiocMulti
    EstimateSoup --> Stats
    EstimateSoup --> MatrixPkg
    EstimateSoup --> Methods
    PlotFuncs --> ggplot2

    %% Click Events
    click Load10X "https://github.com/constantamateur/soupx/blob/master/R/load10X.R"
    click SoupCtor "https://github.com/constantamateur/soupx/blob/master/R/classFunctions.R"
    click SoupCtor "https://github.com/constantamateur/soupx/blob/master/R/setProperties.R"
    click EstimateSoup "https://github.com/constantamateur/soupx/blob/master/R/estimateSoup.R"
    click EstimateNonExpress "https://github.com/constantamateur/soupx/blob/master/R/estimateNonExpressingCells.R"
    click AutoEstCont "https://github.com/constantamateur/soupx/blob/master/R/autoEstCont.R"
    click ManualEstCont "https://github.com/constantamateur/soupx/blob/master/R/calculateContaminationFraction.R"
    click AdjustCounts "https://github.com/constantamateur/soupx/blob/master/R/adjustCounts.R"
    click PlotFuncs "https://github.com/constantamateur/soupx/blob/master/R/plotFunctions.R"
    click QuickMarkers "https://github.com/constantamateur/soupx/blob/master/R/quickMarkers.R"
    click Utils "https://github.com/constantamateur/soupx/blob/master/R/utils.R"
    click Utils "https://github.com/constantamateur/soupx/blob/master/R/data.R"
    click ExampleData "https://github.com/constantamateur/soupx/blob/master/data/PBMC_metaData.RData"
    click ExampleData "https://github.com/constantamateur/soupx/blob/master/data/PBMC_sc.RData"
    click ExampleData "https://github.com/constantamateur/soupx/blob/master/data/scToy.RData"
    click MatrixMarket "https://github.com/constantamateur/soupx/tree/master/inst/extdata/toyData/filtered_gene_bc_matrices/GRCh38/"
    click MatrixMarket "https://github.com/constantamateur/soupx/tree/master/inst/extdata/toyData/raw_gene_bc_matrices/GRCh38/"
    click VignetteSrc "https://github.com/constantamateur/soupx/blob/master/vignettes/pbmcTutorial.Rmd"
    click VignetteDoc "https://github.com/constantamateur/soupx/blob/master/inst/doc/pbmcTutorial.html"
    click ManPages "https://github.com/constantamateur/soupx/blob/master/man/SoupChannel.Rd"
    click ManPages "https://github.com/constantamateur/soupx/blob/master/man/autoEstCont.Rd"
    click ManPages "https://github.com/constantamateur/soupx/blob/master/man/adjustCounts.Rd"
    click Description "https://github.com/constantamateur/soupx/tree/master/DESCRIPTION"
    click Description "https://github.com/constantamateur/soupx/tree/master/NAMESPACE"

    %% Styles
    classDef user fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#7BEAFF,stroke:#333,stroke-width:1px
    classDef module fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef object fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef doc fill:#98FB98,stroke:#333,stroke-width:1px
```
