rliger (version 1.0.0)

calcAgreement: Calculate agreement metric

Description

This metric quantifies how much the factorization and alignment distorts the geometry of the original datasets. The greater the agreement, the less distortion of geometry there is. This is calculated by performing dimensionality reduction on the original and quantile aligned (or just factorized) datasets, and measuring similarity between the k nearest neighbors for each cell in original and aligned datasets. The Jaccard index is used to quantify similarity, and is the final metric averages across all cells.

Note that for most datasets, the greater the chosen k, the greater the agreement in general. There are several options for dimensionality reduction, with the default being 'NMF' as it is expected to be most similar to iNMF. Although agreement can theoretically approach 1, in practice it is usually no higher than 0.2-0.3 (particularly for non-deterministic approaches like NMF).

Usage

calcAgreement(
  object,
  dr.method = "NMF",
  ndims = 40,
  k = 15,
  use.aligned = TRUE,
  rand.seed = 42,
  by.dataset = FALSE
)

Arguments

object

liger object. Should call quantile_norm before calling.

dr.method

Dimensionality reduction method to use for assessing pre-alignment geometry (either "PCA", "NMF", or "ICA"). (default "NMF")

ndims

Number of dimensions to use in dimensionality reduction (recommended to use the same as number of factors) (default 40).

k

Number of nearest neighbors to use in calculating Jaccard index (default 15).

use.aligned

Whether to use quantile aligned or unaligned cell factor loadings (default TRUE).

rand.seed

Random seed for reproducibility (default 42).

by.dataset

Return agreement calculated for each dataset (default FALSE).

Value

Agreement metric (or vector of agreement per dataset).

Examples

# NOT RUN {
# ligerex (liger object based on in-memory datasets), factorization complete
# generate H.norm by quantile normalizig factor loadings
ligerex <- quantile_norm(ligerex)
agreement <- calcAgreement(ligerex, dr.method = "NMF")
# ligerex (liger object based on datasets in HDF5 format), factorization complete
ligerex <- quantile_norm(ligerex)
ligerex <- readSubset(ligerex, slot.use = "scale.data", max.cells = 5000)
agreement <- calcAgreement(ligerex, dr.method = "NMF")
# }