Package {cudacellr}

Construct a nearest-neighbour representation

Description

Construct a nearest-neighbour representation

Usage

cuda_cell_neighbors(
  embedding,
  k = 15L,
  metric = c("euclidean", "cosine"),
  device = c("auto", "cuda", "cpu"),
  batch_size = 256L
)

Arguments

Value

A cuda_knn object retaining cell names from the embedding.

Examples

cuda_cell_neighbors(
  matrix(rnorm(60), 20, 3),
  k = 5,
  batch_size = 4,
  device = "cpu"
)

Run PCA on highly variable single-cell features

Description

Run PCA on highly variable single-cell features

Usage

cuda_cell_pca(
  counts,
  n_components = 30L,
  n_hvg = 2000L,
  scale. = TRUE,
  device = c("auto", "cuda", "cpu"),
  scale_factor = 10000,
  log1p = TRUE,
  min_mean = 0
)

Arguments

Value

A cuda_pca object with an additional features element. Cell names label PCA score rows and selected feature names label loadings.

Examples

set.seed(2)
counts <- matrix(rpois(30 * 20, lambda = 2), 30, 20)
cuda_cell_pca(counts, n_components = 3, n_hvg = 10, device = "cpu")

Select highly variable features

Description

Select highly variable features

Usage

cuda_hvg(counts, n_top = 2000L, min_mean = 0)

Arguments

Value

A data frame ordered by dispersion with feature statistics and a selected indicator. The index column retains the original feature position even when feature names are duplicated.

Examples

set.seed(1)
counts <- Matrix::rsparsematrix(20, 10, density = 0.3)
counts@x <- abs(round(counts@x * 5))
cuda_hvg(counts, n_top = 5)

Normalize a single-cell count matrix

Description

Counts are expected with features in rows and cells in columns.

Usage

cuda_normalize_counts(counts, scale_factor = 10000, log1p = TRUE)

Arguments

Value

A sparse Matrix::dgCMatrix with the input feature and cell names.

Examples

counts <- Matrix::Matrix(matrix(c(1, 0, 3, 2, 4, 1), 3), sparse = TRUE)
cuda_normalize_counts(counts)

Inspect provenance stored on native single-cell containers

Description

These methods expose the shared cudaverse::cuda_provenance() contract for SingleCellExperiment and Seurat objects produced by cudacellr.

Usage

## S3 method for class 'SingleCellExperiment'
cuda_provenance(x)

## S3 method for class 'Seurat'
cuda_provenance(x)

Arguments

Value

A cuda_provenance data frame.

Run a cudacell workflow on a SingleCellExperiment

Description

cudacell_sce() reads one assay, runs cudacell_workflow(), and returns a modified copy of the input object. Existing assays, row and column metadata, reduced dimensions, alternative experiments, pairings, and top-level metadata are retained. New results are stored in native SingleCellExperiment locations:

Usage

cudacell_sce(
  x,
  assay = "counts",
  n_hvg = 2000L,
  n_components = 30L,
  k = 15L,
  device = c("auto", "cuda", "cpu"),
  batch_size = 256L,
  scale_factor = 10000,
  log1p = TRUE,
  min_mean = 0,
  scale. = TRUE,
  normalized_assay = NULL,
  reduced_dim = "CUDACELL_PCA",
  col_pair = "CUDACELL_KNN",
  row_data_prefix = "cudacell",
  set_size_factors = FALSE,
  overwrite = FALSE,
  realize = FALSE
)

Arguments

Details

• normalized expression in an assay;

• PCA scores in a reduced dimension;

• highly variable feature statistics in rowData;

• directed nearest-neighbour relationships in a colPair;

• parameters and compute provenance in metadata(x)$cudacellr.

The selected assay must currently be a base matrix or Matrix object. Delayed assays are never realized silently. Set realize = TRUE only after confirming that the selected assay fits in memory.

Value

A valid SingleCellExperiment of the same class as x.

Examples

if (requireNamespace("SingleCellExperiment", quietly = TRUE)) {
  counts <- matrix(
    rpois(30 * 12, lambda = 2),
    nrow = 30,
    dimnames = list(paste0("gene_", 1:30), paste0("cell_", 1:12))
  )
  sce <- SingleCellExperiment::SingleCellExperiment(
    assays = list(counts = counts)
  )
  sce <- cudacell_sce(
    sce,
    n_hvg = 10,
    n_components = 3,
    k = 3,
    device = "cpu"
  )
  SingleCellExperiment::reducedDim(sce, "CUDACELL_PCA")
  cuda_provenance(sce)
}

Run a cudacell workflow on a Seurat object

Description

cudacell_seurat() reads one exact assay layer, runs cudacell_workflow(), and returns a modified copy of the input object. The full Seurat package is not required; the object contract uses SeuratObject version 5 or newer.

Usage

cudacell_seurat(
  x,
  assay = NULL,
  layer = "counts",
  n_hvg = 2000L,
  n_components = 30L,
  k = 15L,
  device = c("auto", "cuda", "cpu"),
  batch_size = 256L,
  scale_factor = 10000,
  log1p = TRUE,
  min_mean = 0,
  scale. = TRUE,
  output_assay = "CUDACELL",
  reduction = "cudacell_pca",
  reduction_key = "CUDACELLPC_",
  neighbor = "cudacell_knn",
  metadata_prefix = "cudacell",
  overwrite = FALSE,
  realize = FALSE
)

Arguments

Details

Results are stored in native, namespaced locations:

• normalized expression and feature statistics in a new Assay5;

• PCA embeddings and loadings in a DimReduc;

• exact kNN indices and distances in a Neighbor;

• library-size factors in cell metadata;

• parameters and compute provenance in the cudacell_seurat tool record.

Existing assays and layers, reductions, graphs, neighbours, identities, cell metadata, images, commands, miscellaneous data, and tool records are retained. Every output collision is checked before device selection or computation. overwrite = TRUE replaces only the explicitly named cudacellr outputs.

Feature metadata use the requested prefix. ⁠<prefix>_hvg_rank⁠ is the one-based global dispersion rank across all input features; ⁠<prefix>_hvg⁠ identifies the selected top n_hvg features.

Non-memory-backed layers are never realized silently. Set realize = TRUE only after confirming that the selected layer fits in memory. The selected layer must contain every object cell in the same order.

Value

A valid Seurat object. The input object is not modified.

Examples

if (requireNamespace("SeuratObject", quietly = TRUE)) {
  counts <- Matrix::Matrix(
    matrix(
      rpois(30 * 12, lambda = 2),
      nrow = 30,
      dimnames = list(
        paste0("gene_", 1:30),
        paste0("cell_", 1:12)
      )
    ),
    sparse = TRUE
  )
  object <- SeuratObject::CreateSeuratObject(counts)
  object <- cudacell_seurat(
    object,
    n_hvg = 10,
    n_components = 3,
    k = 3,
    device = "cpu"
  )
  SeuratObject::Embeddings(object[["cudacell_pca"]])
  cuda_provenance(object)
}

Run the initial cudacellr workflow

Description

Run the initial cudacellr workflow

Usage

cudacell_workflow(
  counts,
  n_hvg = 2000L,
  n_components = 30L,
  k = 15L,
  device = c("auto", "cuda", "cpu"),
  batch_size = 256L,
  scale_factor = 10000,
  log1p = TRUE,
  min_mean = 0,
  scale. = TRUE
)

Arguments

Value

A list containing normalized counts, variable features, PCA, and kNN. Feature and cell identifiers are retained throughout all stages.

Examples

set.seed(3)
counts <- matrix(rpois(40 * 25, 2), 40, 25)
cudacell_workflow(
  counts, n_hvg = 15, n_components = 5, k = 5, device = "cpu"
)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

cudaverse

cuda_provenance()