Renamed methods for checking sparsity to is_sparse, is_sparse_proport…

…ion.

This avoids potential confusion with the new sparse() extractor method;
we painted ourselves into a corner naming-wise when we shortened
dense_row() to dense(), because sparse_row() becomes sparse(). Oh well.

README.md

@@ -158,7 +158,7 @@ auto iext = mat->sparse_row(std::vector<int>{ 1, 3, 5, 7 });
 In performance-critical sections, it may be desirable to customize the extraction based on properties of the matrix.
 This is supported with the following methods:
 
-- `tatami::Matrix::sparse()` indicates whether a matrix is sparse.
+- `tatami::Matrix::is_sparse()` indicates whether a matrix is sparse.
 - `tatami::Matrix::prefer_rows()` indicates whether a matrix is more efficiently accessed along its rows (e.g., row-major dense matrices).
 
 Users can then write dedicated code paths to take advantage of these properties.
@@ -168,7 +168,7 @@ we could iterate on the columns and attempt to compute the statistic in a "runni
 In the most complex cases, this leads to code like:
 
 ```cpp
-if (mat->sparse()) {
+if (mat->is_sparse()) {
     if (mat->prefer_rows()) {
         auto sext = mat->sparse_row();
         // Do compute along sparse rows.

gallery/src/colsums.cpp

@@ -59,7 +59,7 @@ std::vector<double> colsums_sparse(std::shared_ptr<tatami::NumericMatrix> p) {
     std::vector<double> output(NC);
     std::vector<double> buffer(NR);
 
-    if (p->sparse()) {
+    if (p->is_sparse()) {
         /* When performing sparse extractions, we usually need an additional
          * buffer for the indices of the non-zero elements. However, if we don't
          * care about the indices, we can skip their extraction for efficiency.
@@ -108,7 +108,7 @@ std::vector<double> colsums_preferred(std::shared_ptr<tatami::NumericMatrix> p)
     // Deciding whether or not to perform row-wise extraction.
     if (p->prefer_rows()) {
         std::vector<double> buffer(NC);
-        if (p->sparse()) {
+        if (p->is_sparse()) {
             // This time, we actually do need the sparse indices.
             auto wrk = p->sparse_row();
             std::vector<int> ibuffer(NC);
@@ -131,7 +131,7 @@ std::vector<double> colsums_preferred(std::shared_ptr<tatami::NumericMatrix> p)
     } else {
         // Copied from colsums_sparse.
         std::vector<double> buffer(NR);
-        if (p->sparse()) {
+        if (p->is_sparse()) {
             std::vector<int> ibuffer(NR);
             tatami::Options opt;
             opt.sparse_extract_index = false;

include/tatami/base/Matrix.hpp

@@ -96,17 +96,17 @@ class Matrix {
      *
      * This can be used to choose between dense and sparse outputs.
      */
-    virtual bool sparse() const = 0;
+    virtual bool is_sparse() const = 0;
 
     /**
      * @return Approximate proportion of the matrix that is sparse.
      *
      * This is defined as the proportion of matrix elements that lie within sparse submatrices.
      * It is intended for use in `Matrix` representations that consist of combinations of multiple submatrices (e.g., `DelayedBind`),
-     * allowing them to derive a suitable value for `sparse()` based on whether most of its submatrices are sparse.
+     * allowing them to derive a suitable value for `is_sparse()` based on whether most of its submatrices are sparse.
      * (A more granular approach would be to report the density of structural non-zero elements, but this may not be known by all representations at construction time.)
      */
-    virtual double sparse_proportion() const = 0;
+    virtual double is_sparse_proportion() const = 0;
 
     /**
      * @return The preferred dimension for extracting values.

include/tatami/dense/DenseMatrix.hpp

@@ -200,9 +200,9 @@ class DenseMatrix : public Matrix<Value_, Index_> {
 
     bool uses_oracle(bool) const { return false; }
 
-    bool sparse() const { return false; }
+    bool is_sparse() const { return false; }
 
-    double sparse_proportion() const { return 0; }
+    double is_sparse_proportion() const { return 0; }
 
     double prefer_rows_proportion() const { return static_cast<double>(row_major); }
 

include/tatami/dense/convert_to_dense.hpp

@@ -58,7 +58,7 @@ void convert_to_dense(const Matrix<InputValue_, InputIndex_>* incoming, bool row
             }
         }, primary, threads);
 
-    } else if (incoming->sparse()) {
+    } else if (incoming->is_sparse()) {
         std::fill_n(store, primary * secondary, 0); // already cast to size_t to avoid overflow.
 
         // We iterate over the input matrix's preferred dimension but split

include/tatami/isometric/binary/DelayedBinaryIsometricOp.hpp

@@ -492,10 +492,10 @@ class DelayedBinaryIsometricOp : public Matrix<Value_, Index_> {
 
         if constexpr(is_advanced) {
             if (operation.is_sparse()) {
-                is_sparse_internal = left->sparse() && right->sparse();
+                is_sparse_internal = left->is_sparse() && right->is_sparse();
 
                 // Well, better than nothing, I guess.
-                sparse_proportion_internal = (left->sparse_proportion() + right->sparse_proportion())/2;
+                is_sparse_proportion_internal = (left->is_sparse_proportion() + right->is_sparse_proportion())/2;
             }
         }
     }
@@ -504,7 +504,7 @@ class DelayedBinaryIsometricOp : public Matrix<Value_, Index_> {
     std::shared_ptr<const Matrix<Value_, Index_> > left, right;
     Operation_ operation;
     double prefer_rows_proportion_internal;
-    double sparse_proportion_internal = 0;
+    double is_sparse_proportion_internal = 0;
     bool is_sparse_internal = false;
 
     static constexpr bool is_advanced = (!Operation_::zero_depends_on_row || !Operation_::zero_depends_on_column);
@@ -518,12 +518,12 @@ class DelayedBinaryIsometricOp : public Matrix<Value_, Index_> {
         return left->ncol();
     }
 
-    bool sparse() const {
+    bool is_sparse() const {
         return is_sparse_internal;
     }
 
-    double sparse_proportion() const {
-        return sparse_proportion_internal;
+    double is_sparse_proportion() const {
+        return is_sparse_proportion_internal;
     }
 
     bool prefer_rows() const { 
@@ -631,7 +631,7 @@ class DelayedBinaryIsometricOp : public Matrix<Value_, Index_> {
     template<bool oracle_, typename ... Args_>
     std::unique_ptr<DenseExtractor<oracle_, Value_, Index_> > dense_internal(bool row, Args_&& ... args) const {
         if constexpr(is_advanced) {
-            if (left->sparse() && right->sparse()) {
+            if (left->is_sparse() && right->is_sparse()) {
                 // If we don't depend on the rows, then we don't need row indices when 'row = false'.
                 // Similarly, if we don't depend on columns, then we don't column row indices when 'row = true'.
                 if ((!Operation_::zero_depends_on_row && !row) || (!Operation_::zero_depends_on_column && row)) {

include/tatami/isometric/unary/DelayedUnaryIsometricOp.hpp

@@ -485,13 +485,13 @@ struct SparseNeedsIndices : public SparseExtractor<oracle_, Value_, Index_> {
         report_index = opt.sparse_extract_index;
 
         // The index is not required if we don't even want the values,
-        // in which case Operation_::sparse() isn't even called.
+        // in which case Operation_::is_sparse() isn't even called.
         if (report_value) {
             opt.sparse_extract_index = true;
 
             // We only need an internal ibuffer if the user wants the
             // values but didn't provide enough space to store the indices
-            // (which we need to pass to Operation_::sparse()).
+            // (which we need to pass to Operation_::is_sparse()).
             if (!report_index) {
                 internal_ibuffer.resize(extent);
             }
@@ -567,19 +567,19 @@ class DelayedUnaryIsometricOp : public Matrix<Value_, Index_> {
         return mat->ncol();
     }
 
-    bool sparse() const {
+    bool is_sparse() const {
         if constexpr(is_advanced) {
             if (operation.is_sparse()) {
-                return mat->sparse();
+                return mat->is_sparse();
             }
         }
         return false;
     }
 
-    double sparse_proportion() const {
+    double is_sparse_proportion() const {
         if constexpr(is_advanced) {
             if (operation.is_sparse()) {
-                return mat->sparse_proportion();
+                return mat->is_sparse_proportion();
             }
         }
         return 0;
@@ -642,7 +642,7 @@ class DelayedUnaryIsometricOp : public Matrix<Value_, Index_> {
     template<bool oracle_, typename ... Args_>
     std::unique_ptr<DenseExtractor<oracle_, Value_, Index_> > dense_internal(bool row, Args_&& ... args) const {
         if constexpr(is_advanced) {
-            if (mat->sparse()) {
+            if (mat->is_sparse()) {
                 // If we don't depend on the rows, then we don't need row indices when 'row = false'.
                 // Similarly, if we don't depend on columns, then we don't column row indices when 'row = true'.
                 if ((!Operation_::zero_depends_on_row && !row) || (!Operation_::zero_depends_on_column && row)) {
@@ -702,7 +702,7 @@ class DelayedUnaryIsometricOp : public Matrix<Value_, Index_> {
     template<bool oracle_, typename ... Args_>
     std::unique_ptr<SparseExtractor<oracle_, Value_, Index_> > sparse_internal(bool row, MaybeOracle<oracle_, Index_> oracle, Args_&& ... args) const {
         if constexpr(is_advanced) {
-            if (operation.is_sparse() && mat->sparse()) { 
+            if (operation.is_sparse() && mat->is_sparse()) { 
                 if ((!Operation_::non_zero_depends_on_row && !row) || (!Operation_::non_zero_depends_on_column && row)) {
                     // If we don't depend on the rows, then we don't need row indices when 'row = false'.
                     // Similarly, if we don't depend on columns, then we don't column row indices when 'row = true'.

include/tatami/other/DelayedBind.hpp

@@ -606,7 +606,7 @@ class DelayedBind : public Matrix<Value_, Index_> {
         for (const auto& x : mats) {
             double total = static_cast<double>(x->nrow()) * static_cast<double>(x->ncol());
             denom += total;
-            sparse_prop += total * x->sparse_proportion();
+            sparse_prop += total * x->is_sparse_proportion();
             row_prop += total * x->prefer_rows_proportion();
         }
         if (denom) {
@@ -662,11 +662,11 @@ class DelayedBind : public Matrix<Value_, Index_> {
         }
     }
 
-    bool sparse() const {
+    bool is_sparse() const {
         return sparse_prop > 0.5;
     }
 
-    double sparse_proportion() const {
+    double is_sparse_proportion() const {
         return sparse_prop;
     }
 

include/tatami/other/DelayedCast.hpp

@@ -210,12 +210,12 @@ class DelayedCast : public Matrix<ValueOut_, IndexOut_> {
         return ptr->ncol();
     }
 
-    bool sparse() const {
-        return ptr->sparse();
+    bool is_sparse() const {
+        return ptr->is_sparse();
     }
 
-    double sparse_proportion() const {
-        return ptr->sparse_proportion();
+    double is_sparse_proportion() const {
+        return ptr->is_sparse_proportion();
     }
 
     bool prefer_rows() const { 

include/tatami/other/DelayedTranspose.hpp

@@ -43,12 +43,12 @@ class DelayedTranspose : public Matrix<Value_, Index_> {
         return mat->nrow();
     }
 
-    bool sparse() const {
-        return mat->sparse();
+    bool is_sparse() const {
+        return mat->is_sparse();
     }
 
-    double sparse_proportion() const {
-        return mat->sparse_proportion();
+    double is_sparse_proportion() const {
+        return mat->is_sparse_proportion();
     }
 
     bool prefer_rows() const {

include/tatami/sparse/CompressedSparseMatrix.hpp

@@ -487,9 +487,9 @@ class CompressedSparseMatrix : public Matrix<Value_, Index_> {
 
     Index_ ncol() const { return ncols; }
 
-    bool sparse() const { return true; }
+    bool is_sparse() const { return true; }
 
-    double sparse_proportion() const { return 1; }
+    double is_sparse_proportion() const { return 1; }
 
     bool prefer_rows() const { return csr; }
 

include/tatami/sparse/FragmentedSparseMatrix.hpp

@@ -473,9 +473,9 @@ class FragmentedSparseMatrix : public Matrix<Value_, Index_> {
 
     Index_ ncol() const { return ncols; }
 
-    bool sparse() const { return true; }
+    bool is_sparse() const { return true; }
 
-    double sparse_proportion() const { return 1; }
+    double is_sparse_proportion() const { return 1; }
 
     bool prefer_rows() const { return row_based; }
 

include/tatami/sparse/convert_to_compressed_sparse.hpp

@@ -92,7 +92,7 @@ CompressedSparseContents<StoredValue_, StoredIndex_> retrieve_compressed_sparse_
         // First pass to figure out how many non-zeros there are.
         output_p.resize(static_cast<size_t>(primary) + 1);
 
-        if (incoming->sparse()) {
+        if (incoming->is_sparse()) {
             Options opt;
             opt.sparse_extract_value = false;
             opt.sparse_extract_index = false;
@@ -128,7 +128,7 @@ CompressedSparseContents<StoredValue_, StoredIndex_> retrieve_compressed_sparse_
         output_i.resize(output_p.back());
 
         // Second pass to actually fill our vectors.
-        if (incoming->sparse()) {
+        if (incoming->is_sparse()) {
             Options opt;
             opt.sparse_ordered_index = false;
 
@@ -176,7 +176,7 @@ CompressedSparseContents<StoredValue_, StoredIndex_> retrieve_compressed_sparse_
             x.resize(static_cast<size_t>(primary) + 1);
         }
 
-        if (incoming->sparse()) {
+        if (incoming->is_sparse()) {
             Options opt;
             opt.sparse_extract_value = false;
             opt.sparse_ordered_index = false;
@@ -228,7 +228,7 @@ CompressedSparseContents<StoredValue_, StoredIndex_> retrieve_compressed_sparse_
         output_i.resize(output_p.back());
 
         // Second pass to actually fill our vectors.
-        if (incoming->sparse()) {
+        if (incoming->is_sparse()) {
             Options opt;
             opt.sparse_ordered_index = false;
 

include/tatami/sparse/convert_to_fragmented_sparse.hpp

@@ -74,7 +74,7 @@ FragmentedSparseContents<StoredValue_, StoredIndex_> retrieve_fragmented_sparse_
     auto& store_i = output.index;
 
     if (row == incoming->prefer_rows()) {
-        if (incoming->sparse()) {
+        if (incoming->is_sparse()) {
             parallelize([&](size_t, InputIndex_ start, InputIndex_ length) -> void {
                 std::vector<InputValue_> buffer_v(secondary);
                 std::vector<InputIndex_> buffer_i(secondary);
@@ -124,7 +124,7 @@ FragmentedSparseContents<StoredValue_, StoredIndex_> retrieve_fragmented_sparse_
         // non-preferred dim; it is thus cheaper to do cache-unfriendly inserts
         // into the output buffers. 
 
-        if (incoming->sparse()) {
+        if (incoming->is_sparse()) {
             parallelize([&](size_t, InputIndex_ start, InputIndex_ length) -> void {
                 std::vector<InputValue_> buffer_v(primary);
                 std::vector<InputIndex_> buffer_i(primary);

include/tatami/subset/DelayedSubset.hpp

@@ -411,12 +411,12 @@ class DelayedSubset : public Matrix<Value_, Index_> {
         }
     }
 
-    bool sparse() const {
-        return mat->sparse();
+    bool is_sparse() const {
+        return mat->is_sparse();
     }
 
-    double sparse_proportion() const {
-        return mat->sparse_proportion();
+    double is_sparse_proportion() const {
+        return mat->is_sparse_proportion();
     }
 
     bool prefer_rows() const {

include/tatami/subset/DelayedSubsetBlock.hpp

@@ -195,12 +195,12 @@ class DelayedSubsetBlock : public Matrix<Value_, Index_> {
         }
     }
 
-    bool sparse() const {
-        return mat->sparse();
+    bool is_sparse() const {
+        return mat->is_sparse();
     }
 
-    double sparse_proportion() const {
-        return mat->sparse_proportion();
+    double is_sparse_proportion() const {
+        return mat->is_sparse_proportion();
     }
 
     bool prefer_rows() const {

include/tatami/subset/DelayedSubsetSorted.hpp

@@ -375,12 +375,12 @@ class DelayedSubsetSorted : public Matrix<Value_, Index_> {
         }
     }
 
-    bool sparse() const {
-        return mat->sparse();
+    bool is_sparse() const {
+        return mat->is_sparse();
     }
 
-    double sparse_proportion() const {
-        return mat->sparse_proportion();
+    double is_sparse_proportion() const {
+        return mat->is_sparse_proportion();
     }
 
     bool prefer_rows() const {

include/tatami/subset/DelayedSubsetSortedUnique.hpp

@@ -167,12 +167,12 @@ class DelayedSubsetSortedUnique : public Matrix<Value_, Index_> {
         }
     }
 
-    bool sparse() const {
-        return mat->sparse();
+    bool is_sparse() const {
+        return mat->is_sparse();
     }
 
-    double sparse_proportion() const {
-        return mat->sparse_proportion();
+    double is_sparse_proportion() const {
+        return mat->is_sparse_proportion();
     }
 
     bool prefer_rows() const {