diff --git a/include/tatami_stats/counts.hpp b/include/tatami_stats/counts.hpp index b312b53..64e3e66 100644 --- a/include/tatami_stats/counts.hpp +++ b/include/tatami_stats/counts.hpp @@ -22,6 +22,7 @@ namespace tatami_stats { * @tparam Value_ Type of the matrix value, should be numeric. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. + * This should be at least large enough to hold the dimensions of `p`. * * @param row Whether to count in each row. * @param p Pointer to a `tatami::Matrix`. @@ -143,6 +144,7 @@ void counts(bool row, const tatami::Matrix* p, Output_* output, * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. + * This should be at least large enough to hold the dimensions of `p`. * * @param p Pointer to a `tatami::Matrix`. * @param[out] output Pointer to an array of length equal to the number of rows. @@ -175,6 +177,7 @@ std::vector row_nan_counts(const tatami::Matrix* p, int * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. + * This should be at least large enough to hold the dimensions of `p`. * * @param p Pointer to a `tatami::Matrix`. * @param[out] output Pointer to an array of length equal to the number of columns. @@ -188,6 +191,7 @@ void column_nan_counts(const tatami::Matrix* p, Output_* output, /** * @tparam Output_ Type of the output value. + * This should be at least large enough to hold the dimensions of `p`. * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. * @@ -207,6 +211,7 @@ std::vector column_nan_counts(const tatami::Matrix* p, * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. + * This should be at least large enough to hold the dimensions of `p`. * * @param p Pointer to a `tatami::Matrix`. * @param[out] output Pointer to an array of length equal to the number of rows. @@ -220,6 +225,7 @@ void row_zero_counts(const tatami::Matrix* p, Output_* output, i /** * @tparam Output_ Type of the output value. + * This should be at least large enough to hold the dimensions of `p`. * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. * @@ -239,6 +245,7 @@ std::vector row_zero_counts(const tatami::Matrix* p, in * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. + * This should be at least large enough to hold the dimensions of `p`. * * @param p Pointer to a `tatami::Matrix`. * @param[out] output Pointer to an array of length equal to the number of columns. @@ -252,6 +259,7 @@ void column_zero_counts(const tatami::Matrix* p, Output_* output /** * @tparam Output_ Type of the output value. + * This should be at least large enough to hold the dimensions of `p`. * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. * diff --git a/include/tatami_stats/medians.hpp b/include/tatami_stats/medians.hpp index af19a4c..9196993 100644 --- a/include/tatami_stats/medians.hpp +++ b/include/tatami_stats/medians.hpp @@ -53,8 +53,9 @@ Index_ translocate_nans(Value_* ptr, Index_& num) { * @param n Length of the array. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output value. - * This should be a floating-point value for possible averaging. + * This should be floating-point to store potential averages. * @tparam Value_ Type of the input values. * * @return The median of values in `[ptr, ptr + n)`. @@ -95,8 +96,9 @@ Output_ compute(Value_* ptr, Index_ num) { * i.e., `num_all - num_nonzero` is the number of zeros. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output value. - * This should be a floating-point value for possible averaging. + * This should be floating-point to store potential averages. * @tparam Value_ Type of the input values. * * @return The median of values in the sparse vector. @@ -159,9 +161,11 @@ Output_ compute(Value_* value, Index_ num_nonzero, Index_ num_all) { * Compute medians for each element of a chosen dimension of a `tatami::Matrix`. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Value_ Type of the matrix value, should be numeric. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. + * This should be floating-point to store potential averages. * * @param row Whether to compute medians for the rows. * @param p Pointer to a `tatami::Matrix`. @@ -205,6 +209,7 @@ void medians(bool row, const tatami::Matrix* p, Output_* output, /** * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Value_ Type of the matrix value. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output. @@ -221,7 +226,9 @@ void column_medians(const tatami::Matrix* p, Output_* output, in /** * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output. + * This should be floating-point to store potential averages. * @tparam Value_ Type of the matrix value. * @tparam Index_ Type of the row/column indices. * @@ -239,9 +246,11 @@ std::vector column_medians(const tatami::Matrix* p, int /** * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Value_ Type of the matrix value. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output. + * This should be floating-point to store potential averages. * * @param p Shared pointer to a `tatami::Matrix`. * @param[out] output Pointer to an array of length equal to the number of rows. @@ -255,7 +264,9 @@ void row_medians(const tatami::Matrix* p, Output_* output, int t /** * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output. + * This should be floating-point to store potential averages. * @tparam Value_ Type of the matrix value. * @tparam Index_ Type of the row/column indices. * diff --git a/include/tatami_stats/sums.hpp b/include/tatami_stats/sums.hpp index d7478ad..7134399 100644 --- a/include/tatami_stats/sums.hpp +++ b/include/tatami_stats/sums.hpp @@ -26,6 +26,7 @@ namespace sum { * This is best used with a sufficiently high-precision `Output_`, hence the default of `double`. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output data. * @tparam Value_ Type of the input data. * @tparam Index_ Type of the row/column index. @@ -64,6 +65,7 @@ Output_ compute(const Value_* ptr, Index_ num) { * Callers should use a sufficiently high-precision `Output_` such as `double` to mitigate round-off errors. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output data. * @tparam Index_ Type of the row/column indices. */ @@ -107,6 +109,7 @@ struct RunningDense { * This is the counterpart to `RunningDense`, but for sparse observed vectors. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output data. * @tparam Index_ Type of the row/column indices. */ @@ -159,6 +162,7 @@ struct RunningSparse { * so it is best to use a sufficiently high-precision `Output_` to mitigate round-off errors. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Value_ Type of the matrix value, should be numeric. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. @@ -238,6 +242,8 @@ void sums(bool row, const tatami::Matrix* p, Output_* output, in } /** + * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. @@ -254,6 +260,8 @@ void column_sums(const tatami::Matrix* p, Output_* output, int t } /** + * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output value. * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. @@ -271,6 +279,8 @@ std::vector column_sums(const tatami::Matrix* p, int th } /** + * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output value. * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. @@ -287,6 +297,8 @@ void row_sums(const tatami::Matrix* p, Output_* output, int thre } /** + * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output value. * @tparam Value_ Type of the matrix value, should be summable. * @tparam Index_ Type of the row/column indices. diff --git a/include/tatami_stats/variances.hpp b/include/tatami_stats/variances.hpp index b41bd88..0ba6934 100644 --- a/include/tatami_stats/variances.hpp +++ b/include/tatami_stats/variances.hpp @@ -65,6 +65,7 @@ std::pair finalize_compute(Output_ mean, Output_ var, Index_ c * thus, it is best used with a sufficiently high-precision `Output_` like `double`. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output data. * @tparam Value_ Type of the input data. * @@ -113,6 +114,7 @@ std::pair compute(const Value_* ptr, Index_ num) { * thus, it is best used with a sufficiently high-precision `Output_` like `double`. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output data. * @tparam Value_ Type of the input data. * @@ -172,6 +174,7 @@ std::pair compute(const Value_* value, Index_ num_nonzero, Ind * and then finally call `finish()` to obtain the mean and variance for each target vector. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output data. * @tparam Index_ Type of the row/column indices. */ @@ -254,6 +257,7 @@ struct RunningDense { * This does the same as its dense overload for sparse observed vectors. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output data. * @tparam Index_ Type of the row/column indices. */ @@ -359,6 +363,7 @@ struct RunningSparse { * depending on the dimension in `row` and the preferred access dimension of `p`. * * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Value_ Type of the matrix value, should be numeric. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. @@ -433,6 +438,7 @@ void variances(bool row, const tatami::Matrix* p, Output_* outpu /** * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Value_ Type of the matrix value, should be numeric. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. @@ -450,6 +456,7 @@ void column_variances(const tatami::Matrix* p, Output_* output, /** * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output value. * @tparam Value_ Type of the matrix value, should be numeric. * @tparam Index_ Type of the row/column indices. @@ -468,6 +475,7 @@ std::vector column_variances(const tatami::Matrix* p, i /** * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Value_ Type of the matrix value, should be numeric. * @tparam Index_ Type of the row/column indices. * @tparam Output_ Type of the output value. @@ -485,6 +493,7 @@ void row_variances(const tatami::Matrix* p, Output_* output, int /** * @tparam skip_nan_ Whether to check for (and skip) NaNs. + * If false, NaNs are assumed to be absent; the behavior of this function in the presence of NaNs is undefined. * @tparam Output_ Type of the output value. * @tparam Value_ Type of the matrix value, should be numeric. * @tparam Index_ Type of the row/column indices.