How constantamateur/soupx works
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.