Utilities for testing tatami libraries. More...

Classes
class	ForcedOracleWrapper
	Force oracular extraction. More...

class	ReversedIndicesWrapper
	Reverse indices for sparse extraction. More...

struct	SimulateCompressedSparseOptions
	Options for `simulate_compressed_sparse()`. More...

struct	SimulateCompressedSparseResult
	Result of `simulate_compressed_sparse()`. More...

struct	SimulateVectorOptions
	Options for `simulate_vector()`. More...

struct	SparseVector
	Sparse vector. More...

struct	TestAccessOptions
	Options for `test_full_access()` and friends. More...

Typedefs
typedef std::tuple< bool, bool, TestAccessOrder, int >	StandardTestAccessOptions

Enumerations
enum class	TestAccessOrder : char { FORWARD , REVERSE , RANDOM }

Functions
template<typename Index_ >
tatami::VectorPtr< Index_ >	create_indexed_subset (Index_ extent, double relative_start, double probability, uint64_t seed)

template<typename Value_ , typename Index_ >
std::vector< Value_ >	fetch (tatami::MyopicDenseExtractor< Value_, Index_ > &ext, Index_ i, size_t number)

template<typename Value_ , typename Index_ >
std::vector< Value_ >	fetch (tatami::OracularDenseExtractor< Value_, Index_ > &ext, size_t number)

template<typename Value_ , typename Index_ >
SparseVector< Value_, Index_ >	fetch (tatami::MyopicSparseExtractor< Value_, Index_ > &ext, Index_ i, size_t number)

template<typename Value_ , typename Index_ >
SparseVector< Value_, Index_ >	fetch (tatami::OracularSparseExtractor< Value_, Index_ > &ext, size_t number)

template<typename Value_ , typename Index_ >
SimulateCompressedSparseResult< Value_, Index_ >	simulate_compressed_sparse (size_t primary, size_t secondary, const SimulateCompressedSparseOptions &options)

template<typename Type_ >
std::vector< Type_ >	simulate_vector (size_t length, const SimulateVectorOptions &options)

TestAccessOptions	convert_test_access_options (const StandardTestAccessOptions &x)

auto	standard_test_access_options_combinations ()

template<typename Value_ , typename Index_ >
void	test_full_access (const tatami::Matrix< Value_, Index_ > &matrix, const tatami::Matrix< Value_, Index_ > &reference, const TestAccessOptions &options)

template<typename Value_ , typename Index_ >
void	test_block_access (const tatami::Matrix< Value_, Index_ > &matrix, const tatami::Matrix< Value_, Index_ > &reference, double relative_start, double relative_length, const TestAccessOptions &options)

template<typename Value_ , typename Index_ >
void	test_indexed_access (const tatami::Matrix< Value_, Index_ > &matrix, const tatami::Matrix< Value_, Index_ > &reference, double relative_start, double probability, const TestAccessOptions &options)

template<typename Value_ , typename Index_ >
void	test_simple_column_access (const tatami::Matrix< Value_, Index_ > &matrix, const tatami::Matrix< Value_, Index_ > &reference)

template<typename Value_ , typename Index_ >
void	test_simple_row_access (const tatami::Matrix< Value_, Index_ > &matrix, const tatami::Matrix< Value_, Index_ > &reference)

template<typename Value_ , typename Index_ >
void	test_unsorted_full_access (const tatami::Matrix< Value_, Index_ > &matrix, const TestAccessOptions &options)

template<typename Value_ , typename Index_ >
void	test_unsorted_block_access (const tatami::Matrix< Value_, Index_ > &matrix, double relative_start, double relative_length, const TestAccessOptions &options)

template<typename Value_ , typename Index_ >
void	test_unsorted_indexed_access (const tatami::Matrix< Value_, Index_ > &matrix, double relative_start, double probability, const TestAccessOptions &options)

template<class Function_ >
void	throws_error (Function_ fun, const std::string &msg)

Detailed Description

Utilities for testing tatami libraries.

Typedef Documentation

◆ StandardTestAccessOptions

typedef std::tuple<bool, bool, TestAccessOrder, int> tatami_test::StandardTestAccessOptions

Contents of TestAccessOptions as a tuple. This is required for GoogleTest's parametrized generators, see standard_test_access_options_combinations().

Enumeration Type Documentation

◆ TestAccessOrder

enum class tatami_test::TestAccessOrder : char

strong

Order for accessing rows/columns during tatami::Matrix access tests.

FORWARD: rows/columns are accessed in strictly increasing order.
REVERSE: rows/columns are accessed in strictly decreasing order.
RANDOM: rows/columns are accessed in random order.

Function Documentation

◆ convert_test_access_options()

TestAccessOptions tatami_test::convert_test_access_options ( const StandardTestAccessOptions & x )

inline

Convert from tuple-like options into a TestAccessOptions object. This allows TEST_P bodies to easily convert the GetParam()-supplied tuple into options for test_full_access() and friends.

Parameters

x	Options as a tuple.

Returns: The same options as a TestAccessOptions object.

◆ create_indexed_subset()

template<typename Index_ >

tatami::VectorPtr< Index_ > tatami_test::create_indexed_subset	(	Index_	extent,
		double	relative_start,
		double	probability,
		uint64_t	seed
	)

Create a random subset of sorted and unique indices, typically corresponding to elements of the non-target dimension.

Template Parameters

Index_ Integer type for the dimension elements.

Parameters

extent	Extent of the non-target dimension.
relative_start	Start of the indexed subset, as a proportion of the extent of the non-target dimension. The (floored) product of this value and `extent` is used as the index of the first element in the indexed subset. This should lie in `[0, 1)`.
probability	Probability of sampling elements into the indexed subset. This should lie in `[0, 1]`. Only elements after the first index (as defined by `relative_start`) are considered.
seed	Seed for the PRNG.

Returns: Pointer to a vector of indices of sampled elements. The vector will be empty if extent = 0, otherwise it is guaranteed to contain at least one element corresponding to relative_start.

◆ fetch() [1/4]

template<typename Value_ , typename Index_ >

std::vector< Value_ > tatami_test::fetch	(	tatami::MyopicDenseExtractor< Value_, Index_ > &	ext,
		Index_	i,
		size_t	number
	)

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

ext	An extractor object.
i	Row/column index to extract.
number	Number of elements to extract along the non-target dimension.

Returns: Vector of length number, containing the extracted values from row/column i.

◆ fetch() [2/4]

template<typename Value_ , typename Index_ >

SparseVector< Value_, Index_ > tatami_test::fetch	(	tatami::MyopicSparseExtractor< Value_, Index_ > &	ext,
		Index_	i,
		size_t	number
	)

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

ext	An extractor object.
i	Row/column index to extract.
number	Number of elements to extract along the non-target dimension.

Returns: Sparse vector containing up to number extracted values from row/column i.

◆ fetch() [3/4]

template<typename Value_ , typename Index_ >

std::vector< Value_ > tatami_test::fetch	(	tatami::OracularDenseExtractor< Value_, Index_ > &	ext,
		size_t	number
	)

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

ext	An extractor object.
number	Number of elements to extract along the non-target dimension.

Returns: Vector of length number, containing the extracted values from the next row/column.

◆ fetch() [4/4]

template<typename Value_ , typename Index_ >

SparseVector< Value_, Index_ > tatami_test::fetch	(	tatami::OracularSparseExtractor< Value_, Index_ > &	ext,
		size_t	number
	)

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

ext	An extractor object.
number	Number of elements to extract along the non-target dimension.

Returns: Sparse vector containing up to number extracted values from the next row/column.

◆ simulate_compressed_sparse()

template<typename Value_ , typename Index_ >

SimulateCompressedSparseResult< Value_, Index_ > tatami_test::simulate_compressed_sparse	(	size_t	primary,
		size_t	secondary,
		const SimulateCompressedSparseOptions &	options
	)

Simulate values in a compressed sparse matrix.

Template Parameters

Value_	Type of simulated value.
Index_	Integer type for the index.

Parameters

primary	Extent of the primary dimension, i.e., the dimension used to compress non-zero elements.
secondary	Extent of the secondary dimension.
options	Simulation options.

Returns: Simulated values that can be used to construct a compressed sparse matrix.

◆ simulate_vector()

template<typename Type_ >

std::vector< Type_ > tatami_test::simulate_vector	(	size_t	length,
		const SimulateVectorOptions &	options
	)

Simulate a vector of values from a uniform distribution.

Template Parameters

Type_ Type of value to be simulated.

Parameters

length	Length of the array of values to simulate.
options	Simulation options.

Returns: Vector of simulated values.

◆ standard_test_access_options_combinations()

auto tatami_test::standard_test_access_options_combinations ( )

inline

Returns: A parametrized GoogleTest generator for all TestAccessOptions combinations. This should be used inside a INSTANTIATE_TEST_SUITE_P macro, which ensures that GetParam() in the TEST_P body returns a StandardTestAccessOptions instance.

◆ test_block_access()

template<typename Value_ , typename Index_ >

void tatami_test::test_block_access	(	const tatami::Matrix< Value_, Index_ > &	matrix,
		const tatami::Matrix< Value_, Index_ > &	reference,
		double	relative_start,
		double	relative_length,
		const TestAccessOptions &	options
	)

Test access to a contiguous block of a row/column. Any discrepancies between matrix and reference will raise a GoogleTest error.

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

matrix	Matrix for which to test access.
reference	Reference matrix containing the same values as `matrix`. This typically uses a "known-good" representation like a `tatami::DenseRowMatrix`.
relative_start	Start of the block, as a proportion of the extent of the non-target dimension. The (floored) product of this value and the non-target extent is used as the index of the first row/column of the block. This should lie in `[0, 1)`.
relative_length	Length of the block, as a proportion of the extent of the non-target dimension. This should lie in `[0, 1)`, and the sum of `relative_start` and `relative_length` should be no greater than 1. The (floored) product of this value and the non-target extent is used as the number of rows/columns in the block.
options	Further options for testing.

◆ test_full_access()

template<typename Value_ , typename Index_ >

void tatami_test::test_full_access	(	const tatami::Matrix< Value_, Index_ > &	matrix,
		const tatami::Matrix< Value_, Index_ > &	reference,
		const TestAccessOptions &	options
	)

Test access to the full extent of a row/column. Any discrepancies between matrix and reference will raise a GoogleTest error.

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

matrix	Matrix for which to test access.
reference	Reference matrix containing the same values as `matrix`. This typically uses a "known-good" representation like a `tatami::DenseRowMatrix`.
options	Further options for testing.

◆ test_indexed_access()

template<typename Value_ , typename Index_ >

void tatami_test::test_indexed_access	(	const tatami::Matrix< Value_, Index_ > &	matrix,
		const tatami::Matrix< Value_, Index_ > &	reference,
		double	relative_start,
		double	probability,
		const TestAccessOptions &	options
	)

Test access to an indexed subset of a row/column. Any discrepancies between matrix and reference will raise a GoogleTest error.

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

matrix	Matrix for which to test access.
reference	Reference matrix containing the same values as `matrix`. This typically uses a "known-good" representation like a `tatami::DenseRowMatrix`.
relative_start	Start of the indexed subset, as a proportion of the extent of the non-target dimension. The (floored) product of this value and the non-target extent is used as the index of the first row/column in the indexed subset. This should lie in `[0, 1)`.
probability	Probability of sampling rows/columns when simulating the indexed subset. This should lie in `[0, 1]`. Only rows/columns after the first index (as defined by `relative_start`) are considered.
options	Further options for testing.

◆ test_simple_column_access()

template<typename Value_ , typename Index_ >

void tatami_test::test_simple_column_access	(	const tatami::Matrix< Value_, Index_ > &	matrix,
		const tatami::Matrix< Value_, Index_ > &	reference
	)

Equivalent to test_full_access() with TestAccessOptions::use_row = false. All other options are set to their defaults. This is intended for quick testing of matrix access when a full parametrized test suite is not required.

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

matrix	Matrix for which to test access.
reference	Reference matrix containing the same values as `matrix`. This typically uses a "known-good" representation like a `tatami::DenseRowMatrix`.

◆ test_simple_row_access()

template<typename Value_ , typename Index_ >

void tatami_test::test_simple_row_access	(	const tatami::Matrix< Value_, Index_ > &	matrix,
		const tatami::Matrix< Value_, Index_ > &	reference
	)

Equivalent to test_full_access() with TestAccessOptions::use_row = true. All other options are set to their defaults. This is intended for quick testing of matrix access when a full parametrized test suite is not required.

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

matrix	Matrix for which to test access.
reference	Reference matrix containing the same values as `matrix`. This typically uses a "known-good" representation like a `tatami::DenseRowMatrix`.

◆ test_unsorted_block_access()

template<typename Value_ , typename Index_ >

void tatami_test::test_unsorted_block_access	(	const tatami::Matrix< Value_, Index_ > &	matrix,
		double	relative_start,
		double	relative_length,
		const TestAccessOptions &	options
	)

Test unsorted sparse access to a contiguous block of a row/column. Any discrepancies between sorted and unsorted accesses on matrix will raise a GoogleTest error. This is intended for tatami::Matrix subclasses where tatami::Options::sparse_ordered_index = false has an effect. Subclasses implementing delayed operations should consider tests with UnorderedWrapper instances to check that unordered access in the seed is handled correctly.

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

matrix	Matrix for which to test access.
relative_start	Start of the block, as a proportion of the extent of the non-target dimension. The (floored) product of this value and the non-target extent is used as the index of the first row/column of the block. This should lie in `[0, 1)`.
relative_length	Length of the block, as a proportion of the extent of the non-target dimension. This should lie in `[0, 1)`, and the sum of `relative_start` and `relative_length` should be no greater than 1. The (floored) product of this value and the non-target extent is used as the number of rows/columns in the block.
options	Further options for testing.

◆ test_unsorted_full_access()

template<typename Value_ , typename Index_ >

void tatami_test::test_unsorted_full_access	(	const tatami::Matrix< Value_, Index_ > &	matrix,
		const TestAccessOptions &	options
	)

Test unsorted sparse access to the full extent of a row/column. Any discrepancies between sorted and unsorted accesses on matrix will raise a GoogleTest error. This is intended for tatami::Matrix subclasses where tatami::Options::sparse_ordered_index = false has an effect. Subclasses implementing delayed operations should consider tests with UnorderedWrapper instances to check that unordered access in the seed is handled correctly.

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

matrix	Matrix for which to test access.
options	Further options for testing.

◆ test_unsorted_indexed_access()

template<typename Value_ , typename Index_ >

void tatami_test::test_unsorted_indexed_access	(	const tatami::Matrix< Value_, Index_ > &	matrix,
		double	relative_start,
		double	probability,
		const TestAccessOptions &	options
	)

Test unsorted sparse access to an indexed subset of a row/column. Any discrepancies between sorted and unsorted accesses on matrix will raise a GoogleTest error. This function is intended for tatami::Matrix subclasses where tatami::Options::sparse_ordered_index = false has an effect. Subclasses implementing delayed operations should consider tests with UnorderedWrapper instances to check that unordered access in the seed is handled correctly.

Template Parameters

Value_	Type of the data.
Index_	Integer type for the row/column index.

Parameters

matrix	Matrix for which to test access.
relative_start	Start of the indexed subset, as a proportion of the extent of the non-target dimension. The (floored) product of this value and the non-target extent is used as the index of the first row/column in the indexed subset. This should lie in `[0, 1)`.
probability	Probability of sampling rows/columns when simulating the indexed subset. This should lie in `[0, 1]`. Only rows/columns after the first index (as defined by `relative_start`) are considered.
options	Further options for testing.

◆ throws_error()

template<class Function_ >

void tatami_test::throws_error	(	Function_	fun,
		const std::string &	msg
	)

Checks that an exception is thrown with the expected message.

Template Parameters

Function_ A function that takes no arguments.

Parameters

fun	A function that may or may not throw an exception.
msg	Any part of the expected error message.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ StandardTestAccessOptions

Enumeration Type Documentation

◆ TestAccessOrder

Function Documentation

◆ convert_test_access_options()

◆ create_indexed_subset()

◆ fetch() [1/4]

◆ fetch() [2/4]

◆ fetch() [3/4]

◆ fetch() [4/4]

◆ simulate_compressed_sparse()

◆ simulate_vector()

◆ standard_test_access_options_combinations()

◆ test_block_access()

◆ test_full_access()

◆ test_indexed_access()

◆ test_simple_column_access()

◆ test_simple_row_access()

◆ test_unsorted_block_access()

◆ test_unsorted_full_access()

◆ test_unsorted_indexed_access()

◆ throws_error()