SparseAccessor
==============

.. cpp:class:: pandas::SparseAccessor

   pandas C++ class.

Example
-------

.. code-block:: cpp

   #include <pandas/pandas.h>
   using namespace pandas;

   // Use SparseAccessor
   SparseAccessor obj;
   // ... operations ...

Constructors
------------

.. list-table::
   :widths: 55 25 20
   :header-rows: 1

   * - Signature
     - Location
     - Example
   * - ``explicit SparseAccessor(const ParentType& parent, double fill_value = 0.0)``
     - pd_sparse_accessor.h:29
     - 

I/O
---

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``to_coo(std::vector<int> row_levels = {0}, std::vector<int> column_levels = {1}, bool sort_labels = false) const``
     - 
     - pd_sparse_accessor.h:141
     - :ref:`View <example-sparseaccessor-to_coo-0>`
   * - ``ParentType to_dense() const``
     - ParentType
     - pd_sparse_accessor.h:123
     - :ref:`View <example-sparseaccessor-to_dense-1>`

Type Checking
-------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``bool is_fill(double val) const``
     - bool
     - pd_sparse_accessor.h:41
     - :ref:`View <example-sparseaccessor-is_fill-2>`
   * - ``bool is_sparse(double threshold = 0.5) const``
     - bool
     - pd_sparse_accessor.h:167
     - :ref:`View <example-sparseaccessor-is_sparse-3>`

Other Methods
-------------

.. list-table::
   :widths: 40 20 15 25
   :header-rows: 1

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``double density() const``
     - double
     - pd_sparse_accessor.h:75
     - :ref:`View <example-sparseaccessor-density-4>`
   * - ``double fill_value() const``
     - double
     - pd_sparse_accessor.h:52
     - :ref:`View <example-sparseaccessor-fill_value-5>`
   * - ``size_t npoints() const``
     - size_t
     - pd_sparse_accessor.h:60
     - :ref:`View <example-sparseaccessor-npoints-6>`
   * - ``const ParentType& parent() const``
     - const ParentType&
     - pd_sparse_accessor.h:32
     - 
   * - ``std::vector<size_t> sp_index() const``
     - std::vector<size_t>
     - pd_sparse_accessor.h:104
     - :ref:`View <example-sparseaccessor-sp_index-7>`
   * - ``numpy::NDArray<double> sp_values() const``
     - numpy::NDArray<double>
     - pd_sparse_accessor.h:84
     - :ref:`View <example-sparseaccessor-sp_values-8>`


Code Examples
-------------

The following examples are extracted from the test suite.

.. _example-sparseaccessor-to_coo-0:

.. dropdown:: to_coo (pd_test_3_all.cpp:21918)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 21908
      :emphasize-lines: 11

              throw std::runtime_error("SparseAccessor.to_dense(): wrong size");
          }
          if (dense[0] != 0.0 || dense[1] != 1.0 || dense[2] != 0.0 || dense[3] != 2.0) {
              throw std::runtime_error("SparseAccessor.to_dense(): wrong values");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      void test_sparse_to_coo() {
          std::cout << "========= SparseAccessor.to_coo() ==================";
      
          pandas::Series<numpy::float64> s({0.0, 1.0, 0.0, 2.0, 0.0});
          auto sparse = s.sparse();
      
          auto [data, rows, cols, shape] = sparse.to_coo();
          if (data.size() != 2) {
              throw std::runtime_error("SparseAccessor.to_coo(): expected 2 data points");
          }
          if (data[0] != 1.0 || data[1] != 2.0) {
              throw std::runtime_error("SparseAccessor.to_coo(): wrong data values");

.. _example-sparseaccessor-to_dense-1:

.. dropdown:: to_dense (pd_test_1_all.cpp:3272)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 3262
      :emphasize-lines: 11

      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_sparse_array_to_dense() {
              std::cout << "========= SparseArray: to_dense ======================= ";
      
              std::vector<numpy::float64> data = {0.0, 1.0, 0.0, 2.0, 0.0};
              pandas::SparseArray<numpy::float64> arr(data, 0.0);
      
              auto dense = arr.to_dense();
              if (dense.getSize() != 5) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_to_dense() : dense size != 5" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_to_dense failed: dense size != 5");
              }
      
              if (dense.getElementAt({0}) != 0.0 ||
                  dense.getElementAt({1}) != 1.0 ||
                  dense.getElementAt({2}) != 0.0 ||
                  dense.getElementAt({3}) != 2.0 ||
                  dense.getElementAt({4}) != 0.0) {

.. _example-sparseaccessor-is_fill-2:

.. dropdown:: is_fill (pd_test_1_all.cpp:3314)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 3304
      :emphasize-lines: 11

                  throw std::runtime_error("pd_test_sparse_array_element_access failed: arr[3] != 10.0");
              }
      
              // Access fill values
              if (arr[0] != 0.0) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_element_access() : arr[0] != fill_value" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_element_access failed: arr[0] != fill_value");
              }
      
              // Test is_fill
              if (!arr.is_fill(0)) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_element_access() : is_fill(0) should be true" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_element_access failed: is_fill(0) should be true");
              }
      
              if (arr.is_fill(1)) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_element_access() : is_fill(1) should be false" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_element_access failed: is_fill(1) should be false");
              }
      
              std::cout << " -> tests passed" << std::endl;

.. _example-sparseaccessor-is_sparse-3:

.. dropdown:: is_sparse (pd_test_3_all.cpp:20749)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 20739
      :emphasize-lines: 11

      
          if (std::abs(dense[1] - 1.0) > 0.01 || std::abs(dense[3] - 2.0) > 0.01) {
              std::cout << "  [FAIL] : to_dense() values failed" << std::endl;
              throw std::runtime_error("pd_test_sparse_to_dense: to_dense() values failed");
          }
      
          std::cout << " -> tests passed" << std::endl;
      }
      
      // ============================================================================
      // Test sparse().is_sparse()
      // ============================================================================
      
      void pd_test_sparse_is_sparse() {
          std::cout << "========= Series.sparse().is_sparse() ====================";
      
          // Sparse series (more than 50% zeros)
          pandas::Series<numpy::float64> sparse_s({0.0, 0.0, 1.0, 0.0, 0.0});
          if (sparse_s.sparse(0.0).is_sparse() != true) {
              std::cout << "  [FAIL] : is_sparse() for sparse data failed" << std::endl;
              throw std::runtime_error("pd_test_sparse_is_sparse: is_sparse() for sparse data failed");

.. _example-sparseaccessor-density-4:

.. dropdown:: density (pd_test_1_all.cpp:3247)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 3237
      :emphasize-lines: 11

                  std::cout << "  [FAIL] : in pd_test_sparse_array_fill_value_property() : default float fill_value should be NaN" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_fill_value_property failed: default float fill_value should be NaN");
              }
      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_sparse_array_density() {
              std::cout << "========= SparseArray: density ======================= ";
      
              // 20% density (2 non-fill out of 10)
              std::vector<numpy::float64> data = {0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 2.0, 0.0};
              pandas::SparseArray<numpy::float64> arr(data, 0.0);
      
              double density = arr.density();
              if (std::abs(density - 0.2) > 0.001) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_density() : density != 0.2, got " << density << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_density failed: density != 0.2");
              }
      
              double sparsity = arr.sparsity();

.. _example-sparseaccessor-fill_value-5:

.. dropdown:: fill_value (pd_test_1_all.cpp:3229)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 3219
      :emphasize-lines: 11

      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_sparse_array_fill_value_property() {
              std::cout << "========= SparseArray: fill_value property ======================= ";
      
              std::vector<numpy::int64> data = {-1, 5, -1, 10, -1};
              pandas::SparseArray<numpy::int64> arr(data, static_cast<numpy::int64>(-1));
      
              if (arr.fill_value() != -1) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_fill_value_property() : fill_value != -1" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_fill_value_property failed: fill_value != -1");
              }
      
              // Test default fill_value for float (NaN)
              pandas::SparseArray<numpy::float64> arr_float;
              if (!std::isnan(arr_float.fill_value())) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_fill_value_property() : default float fill_value should be NaN" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_fill_value_property failed: default float fill_value should be NaN");
              }

.. _example-sparseaccessor-npoints-6:

.. dropdown:: npoints (pd_test_1_all.cpp:3171)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 3161
      :emphasize-lines: 11

                  dense.setElementAt({i}, (i == 3 || i == 7) ? 5.0 : 0.0);
              }
      
              auto sparse = pandas::SparseArray<numpy::float64>::from_dense(dense, 0.0);
      
              if (sparse.size() != 10) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_from_dense() : size != 10" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_from_dense failed: size != 10");
              }
      
              if (sparse.npoints() != 2) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_from_dense() : npoints != 2" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_from_dense failed: npoints != 2");
              }
      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_sparse_array_sp_values_property() {
              std::cout << "========= SparseArray: sp_values property ======================= ";
      

.. _example-sparseaccessor-sp_index-7:

.. dropdown:: sp_index (pd_test_1_all.cpp:3207)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 3197
      :emphasize-lines: 11

      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_sparse_array_sp_index_property() {
              std::cout << "========= SparseArray: sp_index property ======================= ";
      
              std::vector<numpy::float64> data = {0.0, 1.0, 0.0, 2.0, 0.0, 3.0};
              pandas::SparseArray<numpy::float64> arr(data, 0.0);
      
              const auto& sp_idx = arr.sp_index();
              if (sp_idx.getSize() != 3) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_sp_index_property() : sp_index size != 3" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_sp_index_property failed: sp_index size != 3");
              }
      
              if (sp_idx.getElementAt({0}) != 1 ||
                  sp_idx.getElementAt({1}) != 3 ||
                  sp_idx.getElementAt({2}) != 5) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_sp_index_property() : sp_index content mismatch" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_sp_index_property failed: sp_index content mismatch");

.. _example-sparseaccessor-sp_values-8:

.. dropdown:: sp_values (pd_test_1_all.cpp:3185)
   :class-title: example-dropdown

   .. code-block:: cpp
      :linenos:
      :lineno-start: 3175
      :emphasize-lines: 11

      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_sparse_array_sp_values_property() {
              std::cout << "========= SparseArray: sp_values property ======================= ";
      
              std::vector<numpy::float64> data = {0.0, 1.0, 0.0, 2.0, 0.0, 3.0};
              pandas::SparseArray<numpy::float64> arr(data, 0.0);
      
              const auto& sp_vals = arr.sp_values();
              if (sp_vals.getSize() != 3) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_sp_values_property() : sp_values size != 3" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_sp_values_property failed: sp_values size != 3");
              }
      
              if (sp_vals.getElementAt({0}) != 1.0 ||
                  sp_vals.getElementAt({1}) != 2.0 ||
                  sp_vals.getElementAt({2}) != 3.0) {
                  std::cout << "  [FAIL] : in pd_test_sparse_array_sp_values_property() : sp_values content mismatch" << std::endl;
                  throw std::runtime_error("pd_test_sparse_array_sp_values_property failed: sp_values content mismatch");