scran_blocks Namespace Reference

Blocking utilities for libscran. More...

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

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

Functions
template<typename Stat_ , typename Output_ >
void	average_vectors (size_t n, std::vector< Stat_ * > in, Output_ *out, bool skip_nan)
template<typename Output_ = double, typename Stat_ >
std::vector< Output_ >	average_vectors (size_t n, std::vector< Stat_ * > in, bool skip_nan)
template<typename Stat_ , typename Weight_ , typename Output_ >
void	average_vectors_weighted (size_t n, std::vector< Stat_ * > in, const Weight_ *w, Output_ *out, bool skip_nan)
template<typename Output_ = double, typename Stat_ , typename Weight_ >
std::vector< Output_ >	average_vectors_weighted (size_t n, std::vector< Stat_ * > in, const Weight_ *w, bool skip_nan)
double	compute_variable_weight (double s, const VariableWeightParameters &params)
template<typename Size_ , typename Weight_ >
void	compute_weights (size_t num_blocks, const Size_ *sizes, WeightPolicy policy, const VariableWeightParameters &variable, Weight_ *weights)
template<typename Weight_ = double, typename Size_ >
std::vector< Weight_ >	compute_weights (const std::vector< Size_ > &sizes, WeightPolicy policy, const VariableWeightParameters &variable)

Detailed Description

Blocking utilities for libscran.

Enumeration Type Documentation

WeightPolicy

enum class scran_blocks::WeightPolicy : char

strong

Policy to use for weighting blocks based on their size, i.e., the number of cells in each block. This controls the calculation of weighted averages across blocks.

• NONE: no weighting is performed. Larger blocks will contribute more to the weighted average.
• EQUAL: each block receives equal weight, regardless of its size. Equivalent to averaging across 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.

Function Documentation

average_vectors() [1/2]

template<typename Output_ = double, typename Stat_ >

std::vector< Output_ > scran_blocks::average_vectors	(	size_t	n,
		std::vector< Stat_ * >	in,
		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.

average_vectors() [2/2]

template<typename Stat_ , typename Output_ >

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

Average parallel elements across multiple arrays.

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, each element of out is set to the average of the corresponding elements 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	(	size_t	n,
		std::vector< Stat_ * >	in,
		const Weight_ *	w,
		bool	skip_nan
	)

Overload of compute_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	(	size_t	n,
		std::vector< Stat_ * >	in,
		const Weight_ *	w,
		Output_ *	out,
		bool	skip_nan
	)

Compute a weighted average of parallel elements across multiple arrays.

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, each element of out is set to the weighted average of the corresponding elements 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 ( 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" 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 Weight_ = double, typename Size_ >

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

A convenience overload that accepts and returns vectors.

Template Parameters

Size_	Numeric type for the block size.
Weight_	Floating-point type for 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.

compute_weights() [2/2]

template<typename Size_ , typename Weight_ >

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

Compute block 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.

Template Parameters

Size_	Numeric type for the block size.
Weight_	Floating-point type for 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.