tinydenseR <a href="artwork/tinydenseR_hex_piano_behind.png"><img src="artwork/tinydenseR_hex_piano_behind.png" align="right" height="138" /></a>

<!-- badges: start -->

<!-- badges: end -->

Table of Contents

• Overview
• Key Features
• Installation
• Quick Start
• Background
• How it Works
• Detailed Example
• Getting Help
• Contributing
• Citation
• License
• Note

Overview

tinydenseR is a landmark‑based R package for single-cell data analysis that goes beyond traditional clustering approaches. Instead of treating each cell as an independent biological replicate, tinydenseR considers samples as the true biological units, enabling more accurate statistical modeling and interpretation.

Why use tinydenseR? Traditional single-cell analysis methods rely heavily on clustering, which can be oversimplified and subjective. tinydenseR provides a clustering-independent framework that preserves biological complexity while maintaining statistical rigor.

Key Features

• 🎯 Sample-centric analysis: Treats samples, not cells, as biological replicates for proper statistical modeling
• 🚀 Memory efficient: Handles atlas-scale datasets with minimal memory footprint
• 🔬 Multi-technology support: Works with scRNA-seq, flow cytometry, mass cytometry (multi-modal data support coming soon)
• 📊 Rich visualizations: Built-in plotting functions for exploring results
• 🔗 Clinical integration: Links cell-level variation to clinical and experimental outcomes
• ⚡ Fast processing: Efficient algorithms for large-scale data analysis

Installation

System Requirements

• R version 4.1 or higher

You can install tinydenseR from GitHub using devtools:

# Install devtools if you haven't already
if (!require("devtools")) install.packages("devtools")

# Install `tinydenseR`
devtools::install_github("Novartis/tinydenseR")

Dependencies

tinydenseR requires R (>= 4.1) and several Bioconductor and CRAN packages. Most dependencies will be installed automatically, but you may need to install Bioconductor and its dependencies first:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}

# Download DESCRIPTION from GitHub
data_url <-
  "https://raw.githubusercontent.com/Novartis/tinydenseR/main/DESCRIPTION"
temp_file <-
  tempfile()
utils::download.file(
  url = data_url, 
  destfile = temp_file, 
  mode = "wb",
  quiet = TRUE)

# Parse Imports
desc <-
  read.dcf(file = temp_file)
imports <-
  strsplit(x = desc[, "Imports"],
           split = "\\s*,\\s*")[[1]]
imports <-
  gsub(pattern = "\\s*\\(.*?\\)", 
       replacement = "", 
       x = imports)  # remove version constraints

# Install only missing Bioconductor packages
avail.bioc.pkgs <-
  BiocManager::repositories() |>
  (\(x)
  available.packages(repos = x)
  )() |>
  rownames() 

bioc_pkgs <-
  imports[imports %in%
            avail.bioc.pkgs[!avail.bioc.pkgs %in% 
                              (installed.packages() |>
                                 rownames())]]
if (length(bioc_pkgs) > 0) {
  BiocManager::install(pkgs = bioc_pkgs)
}

unlink(temp_file)

Example Data

Examples in this README use simulated trajectory data that is automatically fetched from the miloR package repository. This data is sourced from:

Dann, E., Henderson, N.C., Teichmann, S.A. et al. Differential abundance testing on single-cell data using k-nearest neighbor graphs. Nat Biotechnol (2021). https://doi.org/10.1038/s41587-021-01033-z

Quick Start

Here’s a minimal example to get you started:

# Note: This example downloads data from miloR (GPL v3 licensed)
# for demonstration purposes only

library(tinydenseR)

# Try to fetch trajectory data from miloR repository
# If no internet connection, use miloR package directly
if (curl::has_internet()) {
    # Fetch example data from miloR repository
    sim_trajectory <- fetch_trajectory_data()
    
} else {
    # Fall back to using miloR package directly
    message("No internet connection detected. Using miloR package data directly.")
    library(miloR)
    data(sim_trajectory)
    SummarizedExperiment::colData(x = sim_trajectory$SCE) <-
        S4Vectors::DataFrame(as.list(x = sim_trajectory$meta))
    colnames(x = sim_trajectory$SCE) <- 
        sim_trajectory$meta$cell_id
}

# Extract components 
sim_trajectory.meta <- 
    sim_trajectory$meta
sim_trajectory <-
    sim_trajectory$SCE

# Create .min.meta for 2-sample example  
.min.meta <-
    tinydenseR::get.meta(.obj = sim_trajectory,
                         .sample.var = "Sample",
                         .verbose = FALSE)[c("A_R1", "B_R1"),]

# Create .cells object using SCE method
.min.cells <-
    tinydenseR::get.cells(.exprs = sim_trajectory,
                          .meta = .min.meta,
                          .sample.var = "Sample")[rownames(x = .min.meta)]

# Set up the landmark object
lm.cells <-
    tinydenseR::setup.lm.obj(
        .cells = .min.cells,
        .meta = .min.meta, 
        .assay.type = "RNA",
        .prop.landmarks = 0.05
    ) |>
    tinydenseR::get.landmarks(.nHVG = 500,
                              .nPC = 3) |>
    tinydenseR::get.graph(.k = 5) |>
    tinydenseR::get.map()

# Visualize results
tinydenseR::plotPCA(.lm.obj = lm.cells,
                    .point.size = 1,
                    .panel.size = 1.5)

Background

Single-cell technologies have revolutionized our understanding of cellular biology, but current analysis methods face significant challenges:

The Problem with Current Methods

Clustering limitations: Most single-cell analysis tools rely heavily on clustering algorithms, which can be:

• Oversimplistic for complex biological systems

• Sensitive to parameter choices and method selection

• Poor at capturing cell states at cluster boundaries

• Subjective and labor-intensive to optimize

Statistical modeling issues: Traditional approaches treat each cell as an independent biological replicate, which:

• Ignores the hierarchical structure of biological systems (cells within samples)

• Exaggerates differences between cell populations

• Can lead to misleading statistical conclusions

The tinydenseR Solution

tinydenseR addresses these challenges by:

1. Using samples as biological replicates: This respects the true experimental design and enables proper statistical inference
2. Providing clustering-independent analysis: Reduces subjectivity and captures biological complexity more accurately
3. Linking cellular variation to outcomes: Connects cell-level changes to clinical, experimental, or treatment variables
4. Scaling to large datasets: Efficient algorithms handle atlas-scale data with minimal memory requirements

This approach enables researchers to answer the key question: “How does cellular variation relate to sample-level outcomes?”

How it Works

tinydenseR uses a straightforward three-step process to analyze single-cell data:

<a href="man/figures/README1.png"><img src="man/figures/README1.png" align="center" height="600" /></a>

Step 1: Identify Landmarks 🗺️

• Select representative cells that capture the diversity of your entire dataset
• These “landmark” cells serve as reference points for all subsequent analysis

Step 2: Map Cells to Landmarks 📍

For each sample:

• Map: Determine how similar each cell is to each landmark

• Calculate probabilities: Estimate the likelihood that each cell belongs to each landmark’s neighborhood

• Sum probabilities: Add up all the probabilities for each landmark (this gives you the “density” estimate)

Higher density = many cells are similar to that landmark

Step 3: Link to Outcomes 🔗

• Use the density estimates as features in statistical models

• Connect cellular variation patterns to your experimental variables, treatments, or clinical outcomes

• Generate insights about which cell states are associated with your conditions of interest

<a href="man/figures/README2.png"><img src="man/figures/README2.png" align="center" height="600" /></a>

• Use cell states associated with outcomes to identify key genes or markers

• tinydenseR automatically generates pseudo-bulks of cells mapped to landmarks of interest

<a href="man/figures/README3.png"><img src="man/figures/README3.png" align="center" height="250" /></a>

This approach captures the complexity of cell-to-cell variation while maintaining statistical rigor by treating samples (not individual cells) as the unit of biological replication.

Detailed Example

This example demonstrates a complete tinydenseR analysis workflow using simulated trajectory data with two conditions (A and B) across three replicates each.

Load Libraries and Data

# Note: This example downloads data from miloR (GPL v3 licensed)
# for demonstration purposes only

library(tinydenseR)
library(tidyverse)
#> ── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
#> ✔ dplyr     1.1.4     ✔