Blocking utilities for libscran. More...

Classes
struct	VariableWeightParameters
	Parameters for `compute_variable_weight()`. More...

Enumerations
enum class	WeightPolicy : char { NONE , SIZE , VARIABLE , EQUAL }

Functions
template<typename Stat_ , typename Output_ >
void	average_vectors (const std::size_t n, std::vector< Stat_ * > in, Output_ *const out, const bool skip_nan)

template<typename Output_ = double, typename Stat_ >
std::vector< Output_ >	average_vectors (const std::size_t n, std::vector< Stat_ * > in, const bool skip_nan)

template<typename Stat_ , typename Weight_ , typename Output_ >
void	average_vectors_weighted (const std::size_t n, std::vector< Stat_ * > in, const Weight_ const w, Output_ const out, const bool skip_nan)

template<typename Output_ = double, typename Stat_ , typename Weight_ >
std::vector< Output_ >	average_vectors_weighted (const std::size_t n, std::vector< Stat_ * > in, const Weight_ *const w, const bool skip_nan)

double	compute_variable_weight (const double s, const VariableWeightParameters &params)

template<typename Size_ , typename Weight_ >
void	compute_weights (const std::size_t num_blocks, const Size_ const sizes, const WeightPolicy policy, const VariableWeightParameters &variable, Weight_ const weights)

template<typename Weight_ = double, typename Size_ >
std::vector< Weight_ >	compute_weights (const std::vector< Size_ > &sizes, const WeightPolicy policy, const VariableWeightParameters &variable)

template<typename Input_ >
std::remove_cv_t< std::remove_reference_t< Input_ > >	I (Input_ x)

Detailed Description

Blocking utilities for libscran.

Enumeration Type Documentation

◆ WeightPolicy

enum class scran_blocks::WeightPolicy : char

strong

Policy for weighting blocks based on their size, i.e., the number of cells in each block. This determines the nature of the weight calculations in compute_weights().

SIZE: blocks are weighted in proportion to their size. Larger blocks will contribute more to the weighted average.
EQUAL: each non-empty block is assigned equal weight, regardless of its size. Equivalent to averaging across non-empty blocks without weights.
VARIABLE: each batch is weighted using the logic in compute_variable_weight(). This penalizes small blocks with unreliable statistics while equally weighting all large blocks.
NONE: a deprecated alias for SIZE.

Function Documentation

◆ average_vectors() [1/2]

template<typename Output_ = double, typename Stat_ >

std::vector< Output_ > scran_blocks::average_vectors	(	const std::size_t	n,
		std::vector< Stat_ * >	in,
		const bool	skip_nan )

Overload of compute() that allocates an output vector of averaged values.

Template Parameters

Output	Floating-point output type.
Stat	Type of the input statistic, typically floating point.

Parameters

	n	Length of each array.
[in]	in	Vector of pointers to input arrays of length `n`.
	skip_nan	Whether to check for NaNs.

Returns: A vector of length n is returned, containing the average of all arrays in in. Specifically, the i-th entry is set to the average of the i-th entry across all in arrays.

◆ average_vectors() [2/2]

template<typename Stat_ , typename Output_ >

void scran_blocks::average_vectors	(	const std::size_t	n,
		std::vector< Stat_ * >	in,
		Output_ *const	out,
		const bool	skip_nan )

Average parallel elements across multiple arrays. This is equivalent to calling average_weighted_vectors() with equal weights for each array.

Template Parameters

Stat_	Type of the input statistic, typically floating point.
Output_	Floating-point output type.

Parameters

	n	Length of each array.
[in]	in	Vector of pointers to input arrays of length `n`.
[out]	out	Pointer to an output array of length `n`. On completion, `out` is filled with the average of all arrays in `in`. Specifically, the `i`-th entry of `out` is set to the average of the `i`-th entry across all `in` arrays.
	skip_nan	Whether to check for NaNs. If `true`, NaNs are ignored in the average calculations for each element, at the cost of some efficiency.

◆ average_vectors_weighted() [1/2]

template<typename Output_ = double, typename Stat_ , typename Weight_ >

std::vector< Output_ > scran_blocks::average_vectors_weighted	(	const std::size_t	n,
		std::vector< Stat_ * >	in,
		const Weight_ *const	w,
		const bool	skip_nan )

Overload of average_vectors_weighted() that allocates an output vector of averaged values.

Template Parameters

Output_	Floating-point output type.
Weight_	Type of the weight, typically floating point.
Stat_	Type of the input statistic, typically floating point.

Parameters

	n	Length of each array.
[in]	in	Vector of pointers to input arrays of the same length.
[in]	w	Pointer to an array of length equal to `in.size()`, containing the weight to use for each input array. Weights should be non-negative and finite.
	skip_nan	Whether to check for NaNs.

Returns: A vector is returned containing with the average of all arrays in in.

◆ average_vectors_weighted() [2/2]

template<typename Stat_ , typename Weight_ , typename Output_ >

void scran_blocks::average_vectors_weighted	(	const std::size_t	n,
		std::vector< Stat_ * >	in,
		const Weight_ *const	w,
		Output_ *const	out,
		const bool	skip_nan )

Compute a weighted average of parallel elements across multiple arrays. For example, we can average statistics across blocks using weights computed with compute_weights().

Template Parameters

Stat_	Type of the input statistic, typically floating point.
Weight_	Type of the weight, typically floating point.
Output_	Floating-point output type.

Parameters

	n	Length of each array.
[in]	in	Vector of pointers to input arrays of length `n`.
[in]	w	Pointer to an array of length equal to `in.size()`, containing the weight to use for each input array. Weights should be non-negative and finite.
[out]	out	Pointer to an output array of length `n`. On output, `out` is filled with the weighted average of all arrays in `in`. Specifically, the `i`-th entry of `out` is set to the average of the `i`-th entry across all `in` arrays.
	skip_nan	Whether to check for NaNs. If `true`, NaNs are ignored in the average calculations for each element, at the cost of some efficiency.

◆ compute_variable_weight()

double scran_blocks::compute_variable_weight	(	const double	s,
		const VariableWeightParameters &	params )

inline

Assign a variable weight to each block of cells, for use in computing a weighted average across blocks. The weight for each block is calculated from the size of that block.

If the block size is less than VariableWeightParameters::lower_bound, it has zero weight.
If the block size is greater than VariableWeightParameters::upper_bound, it has weight of 1.
Otherwise, the block has weight proportional to its size, increasing linearly from 0 to 1 between the two bounds.

Blocks that are "large enough" (i.e., above the upper bound) are considered to be equally trustworthy and receive the same weight, ensuring that each block contributes equally to the weighted average. By comparison, very small blocks receive lower weight as their statistics are generally less stable.

Parameters

s	Size of the block, in terms of the number of cells in that block.
params	Parameters for the weight calculation, consisting of the lower and upper bounds.

Returns: Weight of the block, to use for computing a weighted average across blocks.

◆ compute_weights() [1/2]

template<typename Size_ , typename Weight_ >

void scran_blocks::compute_weights	(	const std::size_t	num_blocks,
		const Size_ *const	sizes,
		const WeightPolicy	policy,
		const VariableWeightParameters &	variable,
		Weight_ *const	weights )

Compute weights for multiple blocks based on their size and the weighting policy. For variable weights, this function will call compute_variable_weight() for each block.

Weights should be interpreted as relative values within a single compute_weights() call, i.e., weights from different calls may not be comparable. They are typically used in functions like average_weighted_vectors() to compute a weighted average of statistics across blocks.

Template Parameters

Size_	Numeric type of the block size.
Weight_	Floating-point type of the output weights.

Parameters

	num_blocks	Number of blocks.
[in]	sizes	Pointer to an array of length `num_blocks`, containing the size of each block.
	policy	Policy for weighting blocks of different sizes.
	variable	Parameters for the variable block weights.
[out]	weights	Pointer to an array of length `num_blocks`. On output, this is filled with the weight of each block.

◆ compute_weights() [2/2]

template<typename Weight_ = double, typename Size_ >

std::vector< Weight_ > scran_blocks::compute_weights	(	const std::vector< Size_ > &	sizes,
		const WeightPolicy	policy,
		const VariableWeightParameters &	variable )

A convenience overload for compute_weights() that accepts and returns vectors.

Template Parameters

Size_	Numeric type of the block size.
Weight_	Floating-point type of the output weights.

Parameters

sizes	Vector containing the size of each block.
policy	Policy for weighting blocks of different sizes.
variable	Parameters for the variable block weights.

Returns: Vector of block weights.

Classes

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ WeightPolicy

Function Documentation

◆ average_vectors() [1/2]

◆ average_vectors() [2/2]

◆ average_vectors_weighted() [1/2]

◆ average_vectors_weighted() [2/2]

◆ compute_variable_weight()

◆ compute_weights() [1/2]

◆ compute_weights() [2/2]