Comment on the choice of Output_, behavior of skip_nan_=false.

tatami-inc · Mar 27, 2024 · 4f9b9f3 · 4f9b9f3
1 parent 22dbdb8
commit 4f9b9f3
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 2 deletions.
diff --git 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<Value_, Index_>* 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<Output_> row_nan_counts(const tatami::Matrix<Value_, Index_>* 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<Value_, Index_>* 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<Output_> column_nan_counts(const tatami::Matrix<Value_, Index_>* 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<Value_, Index_>* 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<Output_> row_zero_counts(const tatami::Matrix<Value_, Index_>* 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<Value_, Index_>* 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
@@ -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<Value_, Index_>* 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<Value_, Index_>* 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<Output_> column_medians(const tatami::Matrix<Value_, Index_>* 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<Value_, Index_>* 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
@@ -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<Value_, Index_>* 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<Value_, Index_>* 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<Output_> column_sums(const tatami::Matrix<Value_, Index_>* 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<Value_, Index_>* 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
@@ -65,6 +65,7 @@ std::pair<Output_, Output_> 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<Output_, Output_> 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<Output_, Output_> 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<Value_, Index_>* 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<Value_, Index_>* 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<Output_> column_variances(const tatami::Matrix<Value_, Index_>* 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<Value_, Index_>* 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.