How chris-mcginnis-ucsf/doubletfinder works
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.