# chris-mcginnis-ucsf/doubletfinder architecture

> Architecture diagram of the GitHub repository chris-mcginnis-ucsf/doubletfinder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chris-mcginnis-ucsf/doubletfinder
- Repository: https://github.com/chris-mcginnis-ucsf/doubletfinder

## Overview

##### Project Overview & Main Purpose
- This package is designed to take a fully-processed Seurat object as input and, via several well-defined steps, predict which cells are doublets.
- Its architecture revolves around generating artificial doublets, preprocessing the merged data, running PCA and computing a pANN metric, and finally thresholding this metric to classify cells.
- The README provides a step-by-step workflow (four major steps) and includes several functions (e.g., doubletFinder, paramSweep, summarizeSweep, find.pK, modelHomotypic) that are the building blocks of this process.

##### Main Components
a. Input/Preprocessing Layer:
- “Data Preprocessing” module: This is where quality filtering and standard workflows occur. You may also indicate the “data” folder holding example datasets (e.g., pbmc_small.rda).

b. Artificial Doublet Generation:
- “Artificial Doublet Generation” component representing functions (e.g., within doubletFinder and related helper functions) generating simulated doublets based on real cells.

c. Parameter Sweep and pK Optimization:
- “ParamSweep Module”: Contains functions paramSweep and summarizeSweep, which explore a range of parameters.
- “Optimal pK Selection” module: Includes find.pK that calculates the mean-variance normalized bimodality coefficient (BCmvn) to choose the appropriate pK value.

d. Dimensionality Reduction & pANN Calculation:
- “PCA / Dimensionality Reduction” module: Emphasize that PCA is applied to both real and artificial doublets.
- “pANN Calculation” component: Uses the PCA distance matrix to compute the proportion of Artificial k-nearest neighbors.

e. Classification & Thresholding Engine:
- “Doublet Classification” module: This incorporates the ranking and thresholding logic based on the expected number of doublets (nExp), with adjustment using the “modelHomotypic” function that models homotypic doublets.

f. Output/Integration:
- “Seurat Object Update” component: Indicates that the original Seurat object is updated with doublet annotations.

g. Supporting Components:
- “Documentation” and “Testing Framework”:
- A “Documentation/Man Pages” component to show how Rd files (in the man folder) provide user support.
- A “Test Suite” module: Represented by the tests directory and test scripts ensuring package integrity.

##### Relationships & Interactions
– Flow from Preprocessing to “Artificial Doublet Generation.”
– Next, from pANN Calculation to “Doublet Classification,” which also receives guidance from “Optimal pK Selection” and “Homotypic Adjustment.”
- Optionally, highlight how the documentation is available parallelly to guide the use of each module.

##### Architectural Patterns and Design Principles
- Modular design: Each component (e.g., preprocessing, simulation, parameter optimization) is clearly separated.
- Integration with a well-known external framework (Seurat) and the plug-and-play nature of its functional utilities.

##### Final Elements
- Each component must have a clear, concise label.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Preprocessing Layer
    subgraph "Input & Preprocessing Layer"
        A["Seurat Input"]:::input
        B["Data Preprocessing"]:::process
    end
    A --> B

    %% Doublet Generation & pANN Calculation
    subgraph "Doublet Generation & pANN Calculation"
        C["Artificial Doublet Generation"]:::process
        D["Dimensionality Reduction & pANN Calculation"]:::process
    end
    B --> C
    C --> D

    %% Parameter Sweep & pK Optimization
    subgraph "Parameter Sweep & pK Optimization"
        E1["ParamSweep"]:::module
        E2["SummarizeSweep"]:::module
        F["Optimal pK Selection"]:::module
    end
    B --> E1
    E1 --> E2
    E2 --> F

    %% Doublet Classification Engine
    subgraph "Doublet Classification Engine"
        G["Doublet Classification (with Homotypic Adjustment)"]:::process
        H["Seurat Object Update"]:::process
    end
    D --> G
    F --> G
    G --> H

    %% Result Output
    subgraph "Result Output"
        I["Result Visualization & Diagnostics"]:::process
    end
    H --> I

    %% Supporting Components
    subgraph "Supporting Components"
        subgraph "Utilities & Helper Functions"
            J1["Bimodality Coefficient"]:::support
            J2["Kurtosis"]:::support
            J3["Skewness"]:::support
            J4["Parallel ParamSweep"]:::support
        end
        K["Documentation/Man Pages"]:::support
        L["Testing Framework"]:::support
        M["External Dependencies"]:::external
    end

    %% Dotted links from Testing Framework to major modules
    L -.-> B
    L -.-> C
    L -.-> D
    L -.-> F
    L -.-> G

    %% Legend
    subgraph "Legend"
        L1["Input: Blue"]:::input
        L2["Process: Green"]:::process
        L3["Module: Gold"]:::module
        L4["Support: Pink"]:::support
        L5["External: Plum"]:::external
    end

    %% Click Events
    click A "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/data/pbmc_small.rda"
    click B "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/data.R"
    click C "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/doubletFinder.R"
    click D "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/doubletFinder.R"
    click E1 "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/paramSweep.R"
    click E2 "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/summarizeSweep.R"
    click F "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/find.pK.R"
    click G "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/modelHomotypic.R"
    click J1 "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/bimodality_coefficient.R"
    click J2 "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/kurtosis.R"
    click J3 "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/skewness.R"
    click J4 "https://github.com/chris-mcginnis-ucsf/doubletfinder/blob/master/R/parallel_paramSweep.R"
    click K "https://github.com/chris-mcginnis-ucsf/doubletfinder/tree/master/man/"
    click L "https://github.com/chris-mcginnis-ucsf/doubletfinder/tree/master/tests/"

    %% Styles
    classDef input fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef process fill:#98FB98,stroke:#000,stroke-width:2px;
    classDef module fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef support fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef external fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
