Normalize a chromatin state counts matrix — NormalizeStateMatrix • chromatic

This function takes a cell-by-chromatin-state counts matrix and produces three normalized versions: fractions (per cell), centered log-ratio (CLR), and z-scored CLR values. Optionally, normalization can be performed relative to a reference cell population defined in the metadata.

Usage

NormalizeStateMatrix(
  state_mat,
  meta,
  pseudocount = 0.5,
  group_by,
  group_name,
  baseline_mu = NULL,
  baseline_sigma = NULL
)

Arguments

state_mat: A numeric matrix of chromatin state counts with cells as rows and chromatin states as columns.
meta: A data frame containing cell metadata. Must have rownames matching rownames(state_mat).
pseudocount: A numeric value added to counts prior to fraction calculation to avoid division by zero. Default is 0.5.
group_by: (Optional) A column name in meta specifying the variable used to define a reference cell group.
group_name: (Optional) The value within group_by that defines the reference group of cells.
baseline_mu: (Optional) A numeric vector of baseline means per chromatin state. If provided, used for reference-based z-scoring.
baseline_sigma: (Optional) A numeric vector of baseline standard deviations per chromatin state. If provided, used for reference-based z-scoring.

Value

A list with three elements:

frac: Matrix of fractions of each chromatin state per cell.
CLR: Matrix of centered log-ratio (CLR) transformed fractions.
zscore: Matrix of z-scored CLR values, either relative to the full dataset or to a specified reference group.

Examples

# Normalize a counts matrix without a reference group
out <- NormalizeStateMatrix(state_mat, meta)
#> Error: object 'state_mat' not found

# Normalize relative to a reference group
out <- NormalizeStateMatrix(state_mat, meta, group_by = "cluster", group_name = "Excitatory")
#> Error: object 'meta' not found