Scaling normalization of single-cell data. More...

Classes
struct	CenterSizeFactorsBlockedOptions
	Options for `center_size_factors_blocked()`. More...

struct	CenterSizeFactorsOptions
	Options for `center_size_factors()`. More...

struct	CenterSpikeInFactorsBlockedOptions
	Options for `center_spike_in_factors_blocked()`. More...

struct	CenterSpikeInFactorsOptions
	Options for `center_spike_in_factors()`. More...

struct	ChoosePseudoCountOptions
	Options for `choose_pseudo_count()`. More...

struct	ComputeMeanSizeFactorOptions
	Options for `compute_mean_size_factor()` and `compute_mean_size_factor_blocked()`. More...

class	DelayedLogNormalizeHelper
	Helper for delayed log-normalization. More...

struct	NormalizeCountsOptions
	Options for `normalize_counts()`. More...

struct	SanitizeSizeFactorsOptions
	Options for `sanitize_size_factors()`. More...

struct	SizeFactorDiagnostics
	Diagnostics for the size factors. More...

Enumerations
enum class	CenterBlockMode : char { PER_BLOCK , LOWEST , CUSTOM }

enum class	SanitizeAction : char { IGNORE , ERROR , SANITIZE }

Functions
template<typename SizeFactor_ >
SizeFactor_	compute_mean_size_factor (const std::size_t num, const SizeFactor_ *const size_factors, const ComputeMeanSizeFactorOptions &options)

template<typename SizeFactor_ , typename Block_ >
std::vector< SizeFactor_ >	compute_mean_size_factor_blocked (const std::size_t num, const SizeFactor_ const size_factors, const Block_ const block, const ComputeMeanSizeFactorOptions &options)

template<typename SizeFactor_ >
SizeFactor_	center_size_factors (const std::size_t num, SizeFactor_ *const size_factors, const CenterSizeFactorsOptions &options)

template<typename SizeFactor_ , typename Block_ >
std::vector< SizeFactor_ >	center_size_factors_blocked (const std::size_t num, SizeFactor_ const size_factors, const Block_ const block, const CenterSizeFactorsBlockedOptions &options)

template<typename SizeFactor_ >
void	center_spike_in_factors (const std::size_t num, SizeFactor_ const endogenous, const std::vector< SizeFactor_ > &spike_ins, const CenterSpikeInFactorsOptions &options)

template<typename SizeFactor_ , typename Block_ >
std::vector< SizeFactor_ >	center_spike_in_factors_blocked (const std::size_t num, SizeFactor_ const endogenous, const std::vector< SizeFactor_ > &spike_ins, const Block_ *const block, const CenterSpikeInFactorsBlockedOptions &options)

template<typename Float_ >
Float_	choose_pseudo_count_raw (std::size_t num, Float_ *const size_factors, const ChoosePseudoCountOptions &options)

template<typename Float_ >
Float_	choose_pseudo_count (const std::size_t num, const Float_ *const size_factors, const ChoosePseudoCountOptions &options)

template<typename OutputValue_ = double, typename InputValue_ , typename Index_ , class SizeFactors_ >
std::shared_ptr< tatami::Matrix< OutputValue_, Index_ > >	normalize_counts (std::shared_ptr< const tatami::Matrix< InputValue_, Index_ > > counts, SizeFactors_ size_factors, const NormalizeCountsOptions &options)

template<typename SizeFactor_ >
SizeFactorDiagnostics	check_size_factor_sanity (const std::size_t num, const SizeFactor_ *const size_factors)

template<typename SizeFactor_ >
void	sanitize_size_factors (const std::size_t num, SizeFactor_ *const size_factors, const SizeFactorDiagnostics &status, const SanitizeSizeFactorsOptions &options)

template<typename SizeFactor_ >
SizeFactorDiagnostics	sanitize_size_factors (const std::size_t num, SizeFactor_ *const size_factors, const SanitizeSizeFactorsOptions &options)

Detailed Description

Scaling normalization of single-cell data.

Enumeration Type Documentation

◆ CenterBlockMode

enum class scran_norm::CenterBlockMode : char

strong

Strategy for handling blocks when centering size factors, see CenterSizeFactorsOptions::block_mode for details.

◆ SanitizeAction

enum class scran_norm::SanitizeAction : char

strong

How invalid size factors should be handled:

IGNORE: ignore invalid size factors with no error or change.
ERROR: throw an error.
SANITIZE: fix each invalid size factor.

Function Documentation

◆ compute_mean_size_factor()

template<typename SizeFactor_ >

SizeFactor_ scran_norm::compute_mean_size_factor	(	const std::size_t	num,
		const SizeFactor_ *const	size_factors,
		const ComputeMeanSizeFactorOptions &	options )

Compute the mean size factor.

Template Parameters

SizeFactor_ Floating-point type of the size factors.

Parameters

	num	Number of cells.
[in]	size_factors	Pointer to an array of length `num`, containing the size factor for each cell.
	options	Further options.

Returns: The mean size factor.

◆ compute_mean_size_factor_blocked()

template<typename SizeFactor_ , typename Block_ >

std::vector< SizeFactor_ > scran_norm::compute_mean_size_factor_blocked	(	const std::size_t	num,
		const SizeFactor_ *const	size_factors,
		const Block_ *const	block,
		const ComputeMeanSizeFactorOptions &	options )

Compute the mean size factor for each block.

Template Parameters

SizeFactor_	Floating-point type of the size factors.
Block_	Integer type of the block assignments.

Parameters

	num	Number of cells.
[in]	size_factors	Pointer to an array of length `num`, containing the size factor for each cell.
[in]	block	Pointer to an array of length `num`, containing the block assignment for each cell. Each assignment should be an integer in \([0, N)\) where \(N\) is the total number of blocks.
	options	Further options.

Returns: Vector of length \(N\) containing the mean size factor for each block.

◆ center_size_factors()

template<typename SizeFactor_ >

SizeFactor_ scran_norm::center_size_factors	(	const std::size_t	num,
		SizeFactor_ *const	size_factors,
		const CenterSizeFactorsOptions &	options )

Centering the size factors involves scaling all size factors so that the mean across cells is equal to 1 (i.e., CenterSizeFactorsOptions::center). The aim is to ensure that the normalized expression values are on roughly the same scale as the original counts. This simplifies interpretation and ensures that any pseudo-count added prior to log-transformation has a predictable shrinkage effect. In general, size factors should be centered before calling normalize_counts().

Template Parameters

SizeFactor_ Floating-point type of the size factors.

Parameters

	num	Number of cells.
[in,out]	size_factors	Pointer to an array of length `num`, containing the size factor for each cell. On output, this contains the centered size factors, scaled such that their mean is equal to `CenterSizeFactorsOptions::center`. If the mean of the input size factors is zero, no scaling is performed.
	options	Further options.

Returns: The mean of the input size factors (if CenterSizeFactorsOptions::report_final = false) or the mean of the size factors after centering (otherwise).

◆ center_size_factors_blocked()

template<typename SizeFactor_ , typename Block_ >

std::vector< SizeFactor_ > scran_norm::center_size_factors_blocked	(	const std::size_t	num,
		SizeFactor_ *const	size_factors,
		const Block_ *const	block,
		const CenterSizeFactorsBlockedOptions &	options )

Center size factors within each block to obtain interpretable values after normalization. The rationale is the same as discussed in center_size_factors() but some additional work is required to account for experimental blocking, e.g., to accommodate systematic differences in sequencing depth between runs. The exact strategy for adjusting size factors between blocks is controlled by CenterSizeFactorsOptions::block_mode.

Template Parameters

SizeFactor_	Floating-point type of the size factors.
Block_	Integer type of the block assignments.

Parameters

	num	Number of cells.
[in,out]	size_factors	Pointer to an array of length `num`, containing the size factor for each cell. On output, this contains size factors that are centered according to `CenterSizeFactorsOptions::block_mode`.
[in]	block	Pointer to an array of length `num`, containing the block assignment for each cell. Each assignment should be an integer in \([0, N)\) where \(N\) is the total number of blocks.
	options	Further options.

Returns: Vector of length \(N\) containing the mean size factor for each block, used to scale size_factors on output.

◆ center_spike_in_factors()

template<typename SizeFactor_ >

void scran_norm::center_spike_in_factors	(	const std::size_t	num,
		SizeFactor_ *const	endogenous,
		const std::vector< SizeFactor_ * > &	spike_ins,
		const CenterSpikeInFactorsOptions &	options )

Center size factors for both endogenous genes and spike-in transcripts, as described in center_size_factors(). In addition to preserving the original scale of the counts, we ensure that the average normalized abundances of genes and spike-ins are comparable in downstream analyses. Typically, we would use spike-in transcripts to infer some properties of endogenous genes of similar molarity, e.g., estimating technical noise as a function of the abundance.

In practice, this function is no different to calling center_size_factors() separately for endogenous and each of spike_ins. This function is provided for convenience and for consistency with center_spike_in_factors_blocked().

Template Parameters

SizeFactor_ Floating-point type of the size factors.

Parameters

	num	Number of cells.
[in]	endogenous	Pointer to an array of length `num`, containing the size factor for endogenous genes for each cell. On output, this contains size factors that are centered at 1.
[in]	spike_ins	Vector of length equal to the number of spike-in sets (e.g., ERCCs, SIRV). Each entry should be a pointer to an array of length `num`, containing the size factor for its corresponding spike-in set for each cell. On output, this contains size factors that are centered at 1.
	options	Further options.

◆ center_spike_in_factors_blocked()

template<typename SizeFactor_ , typename Block_ >

std::vector< SizeFactor_ > scran_norm::center_spike_in_factors_blocked	(	const std::size_t	num,
		SizeFactor_ *const	endogenous,
		const std::vector< SizeFactor_ * > &	spike_ins,
		const Block_ *const	block,
		const CenterSpikeInFactorsBlockedOptions &	options )

Center size factors for both endogenous genes and spike-in transcripts as described in center_spike_in_factors(), accounting for the experiment's block structure. Specifically, the size factors of each block are scaled so that the mean size factor for each spike-in set is the same as the mean for the endogenous genes. This ensures that the average normalized abundances of genes and spike-ins are comparable within each block.

Template Parameters

SizeFactor_	Floating-point type of the size factors.
Block_	Integer type for the block assignments.

Parameters

	num	Number of cells.
[in,out]	endogenous	Pointer to an array of length `num`, containing the size factor for endogenous genes for each cell. On output, this contains size factors that are centered according to `CenterSpikeInFactorsBlockedOptions::block_mode`.
[in,out]	spike_ins	Vector of length equal to the number of spike-in sets (e.g., ERCCs, SIRV). Each entry should be a pointer to an array of length `num`, containing the size factor for its corresponding spike-in set for each cell. On output, the mean size factor within each block for each spike-in set is equal to the mean of the corresponding entries of `endogenous`.
[in]	block	Pointer to an array of length `num`, containing the block assignment for each cell. Each assignment should be an integer in \([0, N)\) where \(N\) is the total number of blocks.
	options	Further options.

Returns: Vector of length equal to the number of blocks. Each entry contains the mean of the output size factors (endogenous or spike-in) in each block.

◆ choose_pseudo_count_raw()

template<typename Float_ >

Float_ scran_norm::choose_pseudo_count_raw	(	std::size_t	num,
		Float_ *const	size_factors,
		const ChoosePseudoCountOptions &	options )

Choose a pseudo-count for log-transformation (see NormalizeCountsOptions::pseudo_count) that aims to control the transformation-induced bias.

Log-transformation is commonly applied to sequencing count data prior to further analyses (see NormalizeCountsOptions::log). However, this can introduce spurious differences in the expected log-normalized expression between cells with very different size factors (Lun, 2018). This bias is typically modest in datasets where there are stronger sources of variation, but when observed, it manifests as a library size-dependent trend in the log-normalized expression values. It is difficult to regress out without also removing biology that is associated with, e.g., total RNA content.

A simpler solution is to increase the pseudo-count to suppress the bias. This shrinks all log-expression values towards the zero-expression baseline, thus also shrinking log-differences between cells towards zero. The increased shrinkage is strongest at low counts where the data is least informative and the transformation bias is most pronounced. At large counts, the shrinkage has less effect as the log-differences are driven by the data. Our aim is to pick a pseudo-count that is large enough to mitigate the bias while being small enough to avoid shrinking the biological differences.

No centering is performed by this function, so the size factors should be passed through center_size_factors() before calling this function. Invalid size factors (e.g., zero, negative, non-finite) are automatically ignored, so prior sanitization should not be performed - this ensures that we do not include the replacement values in the various quantile calculations.

See also: Lun ATL (2018). Overcoming systematic errors caused by log-transformation of normalized single-cell RNA sequencing data. biorXiv doi:10.1101/404962

Template Parameters

Float_ Floating-point type of the size factors.

Parameters

	num	Number of size factors.
[in]	size_factors	Pointer to an array of size factors of length `num`. Values should be positive, and all non-positive values are ignored. On output, this array is arbitrarily permuted and should not be used.
	options	Further options.

Returns: The suggested pseudo-count to control the log-transformation-induced bias below the specified threshold.

◆ choose_pseudo_count()

template<typename Float_ >

Float_ scran_norm::choose_pseudo_count	(	const std::size_t	num,
		const Float_ *const	size_factors,
		const ChoosePseudoCountOptions &	options )

This function just wraps choose_pseudo_count_raw() with the automatic creation of a writeable buffer for the size factors.

Template Parameters

Float_ Floating-point type of the size factors.

Parameters

	num	Number of size factors.
[in]	size_factors	Pointer to an array of size factors of length `n`. Values should be positive, and all non-positive values are ignored.
	options	Further options.

Returns: The suggested pseudo-count to control the log-transformation-induced bias below the specified threshold.

◆ normalize_counts()

template<typename OutputValue_ = double, typename InputValue_ , typename Index_ , class SizeFactors_ >

std::shared_ptr< tatami::Matrix< OutputValue_, Index_ > > scran_norm::normalize_counts	(	std::shared_ptr< const tatami::Matrix< InputValue_, Index_ > >	counts,
		SizeFactors_	size_factors,
		const NormalizeCountsOptions &	options )

Given a count matrix and a set of size factors, compute log-transformed normalized expression values. All operations are done in a delayed manner using the tatami::DelayedUnaryIsometricOperation class.

For normalization, each cell's counts are divided by the cell's size factor to remove uninteresting scaling differences. The simplest and most common method for defining size factors is to use the centered library sizes (see center_size_factors() for details). This removes scaling biases caused by differences in sequencing depth, capture efficiency etc. between cells. The centering preserves the scale of the counts in the normalized expression values. That said, users can define size factors from any method of their choice (e.g., median-based normalization, TMM) as long as they are positive for all cells.

Normalized values are then typically log-transformed so that differences in log-values represent log-fold changes in expression. This ensures that downstream analyses like t-tests and distance calculations focus on relative fold-changes rather than absolute differences. The log-transformation also provides some measure of variance stabilization so that the downstream analyses are not dominated by sampling noise at large counts. See also DelayedLogNormalizeHelper, which handles the delayed calculation of the log-transformed values.

Template Parameters

OutputValue_	Floating-point type of the output matrix.
InputValue_	Data type of the input matrix.
InputIndex_	Integer type of the input matrix.
SizeFactors_	Container of floats of the size factors. This should have the `size()`, `begin()`, `end()` and `operator[]` methods.

Parameters

counts	Pointer to a matrix of non-negative counts. Rows should correspond to genes while columns should correspond to cells.
size_factors	Vector of length equal to the number of columns in `counts`, containing the size factor for each cell. All values should be positive, and any invalid values should be replaced with `sanitize_size_factors()`. In most applications, the size factors should also be centered via, e.g., `center_size_factors()`.
options	Further options.

Returns: Pointer to a matrix of normalized expression values. These are log-transformed if NormalizeCountsOptions::log = true.

◆ check_size_factor_sanity()

template<typename SizeFactor_ >

SizeFactorDiagnostics scran_norm::check_size_factor_sanity	(	const std::size_t	num,
		const SizeFactor_ *const	size_factors )

Check whether there are any invalid size factors. Size factors are only valid if they are finite and positive.

Template Parameters

SizeFactor_ Floating-point type of the size factors.

Parameters

	num	Number of size factors.
[in]	size_factors	Pointer to an array of size factors of length `num`.

Returns: Validation results, indicating whether any zero or non-finite size factors exist.

◆ sanitize_size_factors() [1/2]

template<typename SizeFactor_ >

void scran_norm::sanitize_size_factors	(	const std::size_t	num,
		SizeFactor_ *const	size_factors,
		const SizeFactorDiagnostics &	status,
		const SanitizeSizeFactorsOptions &	options )

Replace zero, missing or infinite values in the size factor array so that they can be used to compute well-defined normalized values in normalize_counts(). Such size factors can occasionally arise if, e.g., insufficient quality control was performed upstream. Check out the documentation in SanitizeSizeFactorsOptions to see what placeholder value is used for each type of invalid size factor.

In general, sanitization should occur after calls to center_size_factors(), choose_pseudo_count(), or any function that computes a statistic based on the distribution of size factors. This ensures that the results of those functions are not affected by the placeholder values used to replace the invalid size factors. As a rule of thumb, sanitize_size_factors() should be called just before passing those size factors to normalize_counts().

Template Parameters

SizeFactor_ Floating-point type of the size factors.

Parameters

	num	Number of size factors.
[in,out]	size_factors	Pointer to an array of positive size factors of length `n`. On output, invalid size factors may be replaced depending on the settings in `options`.
	status	A pre-computed object indicating whether invalid size factors are present in `size_factors`. This can be useful if this information is already provided by, e.g., `check_size_factor_sanity()` or `center_size_factors()`.
	options	Further options.

◆ sanitize_size_factors() [2/2]

template<typename SizeFactor_ >

SizeFactorDiagnostics scran_norm::sanitize_size_factors	(	const std::size_t	num,
		SizeFactor_ *const	size_factors,
		const SanitizeSizeFactorsOptions &	options )

Overload of sanitize_size_factors() that calls check_size_factor_sanity() internally.

Template Parameters

SizeFactor_ Floating-point type of the size factors.

Parameters

	num	Number of size factors.
[in,out]	size_factors	Pointer to an array of positive size factors of length `n`. On output, invalid size factors are replaced.
	options	Further options.

Returns: An object indicating whether each type of invalid size factors is present in size_factors.

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ CenterBlockMode

◆ SanitizeAction

Function Documentation

◆ compute_mean_size_factor()

◆ compute_mean_size_factor_blocked()

◆ center_size_factors()

◆ center_size_factors_blocked()

◆ center_spike_in_factors()

◆ center_spike_in_factors_blocked()

◆ choose_pseudo_count_raw()

◆ choose_pseudo_count()

◆ normalize_counts()

◆ check_size_factor_sanity()

◆ sanitize_size_factors() [1/2]

◆ sanitize_size_factors() [2/2]