Package 'harmorust'

Rust Native Kernels for Harmony Single-Cell Integration

Description

Rust reimplementation of the Harmony integration loop with the same RunHarmony() signature used by the immunogenomics Harmony R package. A source install compiles the harmorust CLI with Cargo and stores it in the package ‘bin’ directory.

Details

Package:	harmorust
Version:	0.1.0
License:	MIT

Typical workflow: Seurat or seurust produce a PCA embedding, then RunHarmony corrects batch effects.

Author(s)

Nebil Ibrahim [email protected]

See Also

RunHarmony, harmony_options, HarmonyConvergencePlot

---

Advanced Harmony options

Description

Same names as harmony::harmony_options.

Usage

harmony_options(
  alpha = 0.2,
  tau = 0,
  block.size = 0.05,
  max.iter.cluster = 4,
  epsilon.cluster = 1e-3,
  epsilon.harmony = 1e-2,
  batch.prop.cutoff = 1e-5
)

Arguments

alpha	Harmony2 automatic-lambda scale. Default 0.2.
tau	Softens theta for small batches. Default 0.
block.size	Fraction of cells updated per clustering block. (0, 1].
max.iter.cluster	Inner clustering iterations per Harmony round.
epsilon.cluster	Clustering convergence tolerance.
epsilon.harmony	Outer-loop convergence tolerance.
batch.prop.cutoff	Skip a batch in a cluster below this soft membership.

Value

An object of class harmony_options.

Examples

opts <- harmony_options(block.size = 0.1, max.iter.cluster = 5)

---

Plot Harmony objective over clustering steps

Description

Same role as the unexported HarmonyConvergencePlot helper in immunogenomics/harmony: visualise objective_kmeans across outer rounds.

Usage

HarmonyConvergencePlot(
  harmonyObj,
  round_start = 1,
  round_end = Inf,
  do_wrap = FALSE
)

Arguments

harmonyObj	Object from RunHarmony(..., return_object = TRUE).
round_start	First outer Harmony round to include (1-based).
round_end	Last outer Harmony round to include.
do_wrap	Facet by outer round when TRUE.

Value

A ggplot object.

See Also

RunHarmony

Examples

## Not run: 
obj <- RunHarmony(pca_matrix, meta_data, vars_use = "donor",
                  return_object = TRUE)
HarmonyConvergencePlot(obj)

## End(Not run)

---

Run Harmony with the harmorust kernel

Description

Drop-in companion to harmony::RunHarmony(). The default method matches Harmony's matrix API (data_mat, meta_data, vars_use). Seurat and SingleCellExperiment methods match the original package so a seurust-preprocessed object can be integrated without changing the rest of the workflow.

Usage

RunHarmony(...)

## Default S3 method:
RunHarmony(
  data_mat,
  meta_data,
  vars_use,
  theta = NULL,
  sigma = 0.1,
  lambda = NULL,
  nclust = NULL,
  max_iter = 10,
  early_stop = TRUE,
  ncores = 1,
  plot_convergence = FALSE,
  return_object = FALSE,
  verbose = TRUE,
  .options = harmony_options(),
  ...
)

## S3 method for class 'Seurat'
RunHarmony(
  object,
  group.by.vars,
  reduction.use = "pca",
  reduction = NULL,
  dims.use = NULL,
  reduction.save = "harmony",
  reduction.name = NULL,
  project.dim = TRUE,
  ...
)

## S3 method for class 'SingleCellExperiment'
RunHarmony(
  object,
  group.by.vars,
  dims.use = NULL,
  verbose = TRUE,
  reduction.save = "HARMONY",
  ...
)

Arguments

object	PCA matrix, Seurat object, or SingleCellExperiment.
data_mat	Cell embedding matrix (cells $\times$ PCs or PCs $\times$ cells).
meta_data	Data frame of covariates, or a batch vector.
vars_use, group.by.vars	Covariate name(s) Harmony should remove.
theta	Diversity penalty. Default 2 per covariate.
sigma	Soft k-means width. Default 0.1.
lambda	Ridge penalty. NULL enables Harmony2 automatic lambda.
nclust	Number of soft clusters. Default min(round(n/30), 100).
max_iter	Outer Harmony rounds. Default 10.
early_stop	Stop when the objective stalls. Default TRUE.
ncores	Rayon threads for the Rust kernel (RAYON_NUM_THREADS).
plot_convergence	Draw HarmonyConvergencePlot when TRUE.
return_object	Return a Harmony-like object instead of the matrix.
verbose	Print progress messages.
.options	Advanced options from harmony_options.
reduction.use, reduction	Name of the input reduction. Default "pca".
reduction.save, reduction.name	Name of the written reduction.
dims.use	Which PCs to correct.
project.dim	Project Harmony loadings (Seurat). Default TRUE.
...	Must be empty (legacy Harmony args are rejected).

Value

For the default method, a numeric matrix of corrected embeddings, or a Harmony-like object when return_object = TRUE. Seurat and SingleCellExperiment methods return the input object with a Harmony reduction added.

See Also

harmony_options, HarmonyConvergencePlot

Examples

set.seed(1)
pca_matrix <- cbind(rnorm(20), rnorm(20))
batch <- rep(c("A", "B"), each = 10)
## Not run: 
corrected <- RunHarmony(pca_matrix, batch, nclust = 2, max_iter = 2,
                        verbose = FALSE)

## End(Not run)

---