scran_blocks Namespace Reference

Blocking utilities for libscran. More...

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

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

Functions
double	compute_variable_weight (const double s, const VariableWeightParameters &params)
template<typename GetBlockSize_ , typename SetBlockWeight_ >
void	compute_weights (const std::size_t num_blocks, GetBlockSize_ get_block_size, const WeightPolicy policy, const VariableWeightParameters &variable, SetBlockWeight_ set_block_weight)
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)

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

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 or equal to VariableWeightParameters::lower_bound, it has zero weight.
• If the block size is greater than or equal to 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/3]

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 )

A convenience overload for compute_weights() that accepts an array of block sizes and fills an array of block weights.

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.
	sizes	Vector 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/3]

template<typename GetBlockSize_ , typename SetBlockWeight_ >

void scran_blocks::compute_weights	(	const std::size_t	num_blocks,
		GetBlockSize_	get_block_size,
		const WeightPolicy	policy,
		const VariableWeightParameters &	variable,
		SetBlockWeight_	set_block_weight )

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 to compute a weighted average of statistics across blocks.

Empty blocks (i.e., size zero) will always be assigned a weight of zero. This is guaranteed for all policy and valid parametrizations of variable.

Template Parameters

GetBlockSize_	Function that accepts a size_t and returns a number.
SetBlockWeight_	Function that accepts a size_t and the block weight. The return value is ignored.

Parameters

num_blocks	Number of blocks.
get_block_size	Function that accepts a block index in [0, num_blocks) and returns the size of that block.
policy	Policy for weighting blocks of different sizes.
variable	Parameters for the variable block weights.
set_block_weight	Function that accepts a block index in [0, num_blocks) and the associated block weight. It is expected to store the block weight in some data structure.

compute_weights() [3/3]

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.