NDFrame
=======

.. cpp:class:: numpy::NDFrame

   numpy C++ class.

Example
-------

.. code-block:: cpp

   #include <numpy/np_ndarray.h>
   using namespace numpy;

   // Use NDFrame
   NDFrame obj;
   // ... operations ...

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

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

   * - Signature
     - Location
     - Example
   * - ``NDFrame() = default``
     - df_ndframe.h:102
     - 
   * - ``NDFrame(const NDFrame& other)``
     - df_ndframe.h:106
     - 
   * - ``NDFrame(NDFrame&& other) noexcept``
     - df_ndframe.h:111
     - 

Indexing / Selection
--------------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``const Attrs& attrs() const override``
     - const Attrs&
     - df_ndframe.h:151
     - 
   * - ``Attrs& attrs() override``
     - Attrs&
     - df_ndframe.h:156
     - 
   * - ``void items(Func&& func) const``
     - void
     - df_ndframe.h:317
     - 

Shape Manipulation
------------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``Derived T\_() const``
     - Derived
     - df_ndframe.h:345
     - 
   * - ``Derived transpose() const``
     - Derived
     - df_ndframe.h:353
     - :ref:`View <example-ndframe-transpose-0>`

Logical
-------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``bool all(bool skipna = true) const override``
     - bool
     - df_ndframe.h:182
     - :ref:`View <example-ndframe-all-1>`
   * - ``bool any(bool skipna = true) const override``
     - bool
     - df_ndframe.h:211
     - :ref:`View <example-ndframe-any-2>`

Set Operations
--------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``numpy::NDArray<numpy::bool\_> isin(const std::vector<T>& values) const``
     - numpy::NDArray<numpy::bool\_>
     - df_ndframe.h:287
     - :ref:`View <example-ndframe-isin-3>`

I/O
---

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``numpy::NDArray<T> to_numpy() const``
     - numpy::NDArray<T>
     - df_ndframe.h:365
     - :ref:`View <example-ndframe-to_numpy-4>`

Type Handling
-------------

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``void copy_metadata_from(const NDFrame& other)``
     - void
     - df_ndframe.h:378
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``std::string dtype_name() const override``
     - std::string
     - df_ndframe.h:140
     - :ref:`View <example-ndframe-dtype_name-5>`
   * - ``const Flags& flags() const override``
     - const Flags&
     - df_ndframe.h:166
     - :ref:`View <example-ndframe-flags-6>`
   * - ``func(idx.get_value_str(i), vals.getElementAt(``
     - 
     - df_ndframe.h:321
     - 
   * - ``std::vector<std::string> keys() const``
     - std::vector<std::string>
     - df_ndframe.h:329
     - :ref:`View <example-ndframe-keys-7>`
   * - ``\* Note: This renames the index name (e.g., index.name = "my_index"),``
     - \* Note: This renames the index
     - df_ndframe.h:258
     - :ref:`View <example-ndframe-name-8>`
   * - ``void propagate_attrs(Derived& result) const``
     - void
     - df_ndframe.h:387
     - 
   * - ``Derived rename_axis(const std::optional<std::string>& mapper, int axis = 0) const``
     - Derived
     - df_ndframe.h:261
     - 
   * - ``\* Series<int> s(``
     - \*     Series<int>
     - df_ndframe.h:283
     - 
   * - ``Derived& self()``
     - Derived&
     - df_ndframe.h:90
     - :ref:`View <example-ndframe-self-9>`
   * - ``const Derived& self() const``
     - const Derived&
     - df_ndframe.h:95
     - :ref:`View <example-ndframe-self-10>`
   * - ``self().set_index(std::move(labels))``
     - 
     - df_ndframe.h:246
     - :ref:`View <example-ndframe-self-11>`
   * - ``void set_attrs(const Attrs& attrs) override``
     - void
     - df_ndframe.h:161
     - 
   * - ``Derived& set_axis(std::unique_ptr<IndexBase> labels, int axis = 0)``
     - Derived&
     - df_ndframe.h:244
     - 
   * - ``void set_flags(const Flags& flags) override``
     - void
     - df_ndframe.h:171
     - 
   * - ``\* For 1D structures (Series), returns a copy since transpose is a no-op.``
     - \* For 1D
     - df_ndframe.h:340
     - 
   * - ``\* For 2D structures (DataFrame), swaps rows and columns.``
     - \* For 2D
     - df_ndframe.h:341
     - 


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

The following examples are extracted from the test suite.

.. _example-ndframe-transpose-0:

.. dropdown:: transpose (np_test_2_all.cpp:4973)
   :class-title: example-dropdown

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

          }
      
          /**
           * Test matrix properties and methods
           */
          void testMatrixProperties() {
            std::cout << "========= testMatrixProperties =======================";
      
            // Test transpose
            numpy::Matrix<double> m("1 2 3; 4 5 6");
            auto mt = m.transpose();
            assert_test(mt.rows() == 3, "Transpose rows");
            assert_test(mt.cols() == 2, "Transpose cols");
            assert_test(std::abs(mt(0, 1) - 4.0) < 1e-10, "Transpose element");
            assert_test(std::abs(mt(2, 0) - 3.0) < 1e-10, "Transpose element");
      
            // Test trace for square matrix
            numpy::Matrix<double> square("1 2; 3 4");
            double tr = square.trace();
            assert_test(std::abs(tr - 5.0) < 1e-10, "Matrix trace");
      

.. _example-ndframe-all-1:

.. dropdown:: all (np_test_4_all.cpp:23928)
   :class-title: example-dropdown

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

                              }
                          }
                      }
      
                      auto result = numpy::einsum<numpy::float64>("ijk->ik", {A});
      
                      if (result.getShape()[0] != 2 || result.getShape()[1] != 2) {
                          throw std::runtime_error("einsum partial sum shape wrong");
                      }
      
                      // Sum over j: 1+2+3 = 6 for all (i,k) positions
                      if (std::abs(result.getElementAt({0, 0}) - 6.0) > 1e-10 ||
                          std::abs(result.getElementAt({1, 1}) - 6.0) > 1e-10) {
                          throw std::runtime_error("einsum partial sum values wrong");
                      }
      
                      // std::cout << "  OK: Partial sum: 'ijk->ik'\n";
                  }
      
                  // Test 5: Size-1 dimension handling
                  {

.. _example-ndframe-any-2:

.. dropdown:: any (np_test_2_all.cpp:16758)
   :class-title: example-dropdown

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

          // ANY() TESTS - SCALAR RESULT
          // ============================================================================
      
          void np_test_logic_any_scalar_all_false() {
            std::cout << "========= any: all false elements =======================";
      
            // Create array with all false/zero elements
            std::vector<double> data = { 0.0, 0.0, 0.0 };
            numpy::NDArray<double> arr = numpy::createArrayFromVector<double>({ 3 }, data);
      
            bool result = numpy::any(arr);
      
            if (result != false) {
              std::cout << "  [FAIL] : in np_test_logic_any_scalar_all_false() : expected false for all-zero array";
              throw std::runtime_error("np_test_logic_any_scalar_all_false failed: expected false");
            }
      
            std::cout << " -> tests passed" << std::endl;
          }
      
          void np_test_logic_any_scalar_all_true() {

.. _example-ndframe-isin-3:

.. dropdown:: isin (np_test_1_all.cpp:19434)
   :class-title: example-dropdown

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

              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          if (!(membership.getElementAt({ 5 }) == false)) {
              std::string description = std::string("testMembershipOperations():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(membership.getElementAt({ 5 }) == false)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          // std::cout << "[OK] Membership testing (in1d) works correctly\n";
      
          // Test isin (alias for in1d)
          auto isin_result = isin(test_array, test_values);
      
          // Should be identical to in1d result
          for (size_t i = 0; i < membership.getSize(); ++i) {
            if (!(isin_result.getElementAt({ i }) == membership.getElementAt({ i }))) {
                std::string description = std::string("testMembershipOperations():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(isin_result.getElementAt({ i }) == membership.getElementAt({ i }))";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
          }

.. _example-ndframe-to_numpy-4:

.. dropdown:: to_numpy (np_test_5_all.cpp:21373)
   :class-title: example-dropdown

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

          if (errors == 0) {
              std::cout << "np_test_timedelta_components -> tests passed" << std::endl;
          }
          return errors;
      }
      
      // =============================================================================
      // Test 4: Total Conversion Properties
      // =============================================================================
      int np_test_timedelta_total_conversions() {
          int errors = 0;
      
          numpy::Timedelta td(1, 12, 0);  // 1 day 12 hours = 1.5 days = 36 hours
      
          // total_seconds
          {
              double secs = td.total_seconds();
              double expected = (24 + 12) * 3600.0;
              if (std::abs(secs - expected) > 0.0001) {
                  std::cout << "[FAIL] np_test_timedelta_total_conversions: total_seconds expected "
                            << expected << ", got " << secs << std::endl;

.. _example-ndframe-dtype_name-5:

.. dropdown:: dtype_name (np_test_2_all.cpp:3567)
   :class-title: example-dropdown

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

                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            if (!(flags_info.writeable == true)) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(flags_info.writeable == true)";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
      
            // Test dtype functions
            if (!(dtype_name(arr) == "float64")) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(dtype_name(arr) == \"float64\")";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            if (!(dtype_itemsize(arr) == sizeof(double))) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(dtype_itemsize(arr) == sizeof(double))";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
      

.. _example-ndframe-flags-6:

.. dropdown:: flags (np_test_2_all.cpp:3554)
   :class-title: example-dropdown

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

            }
      
            // Test nbytes
            if (!(nbytes(arr) == 24 * sizeof(double))) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(nbytes(arr) == 24 * sizeof(double))";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
      
            // Test flags
            auto flags_info = flags(arr);
            if (!(flags_info.owndata == true)) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(flags_info.owndata == true)";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }
            if (!(flags_info.writeable == true)) {
                std::string description = std::string("testArrayInfo():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(flags_info.writeable == true)";
                std::cout << std::string("[FAIL] ") + description << std::endl;
                throw std::runtime_error(description);
            }

.. _example-ndframe-keys-7:

.. dropdown:: keys (np_test_2_all.cpp:8614)
   :class-title: example-dropdown

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

                if (!indices.empty()) {
                  std::cout << "   IPP empty array test:                                                                   -> [FAIL]";
                  throw std::runtime_error("IPP empty array test: FAILED - should return empty");
                }
                // std::cout << "[OK] IPP empty array test: PASSED" << std::endl;
              }
      
              // Test 6: Large array performance
              {
                const size_t n = 10000;
                std::vector<std::vector<int>> keys(2);
                keys[0].resize(n);
                keys[1].resize(n);
      
                std::mt19937 gen(42);
                std::uniform_int_distribution<int> dist(0, 1000);
      
                for (size_t i = 0; i < n; ++i) {
                  keys[0][i] = dist(gen);
                  keys[1][i] = dist(gen);
                }

.. _example-ndframe-name-8:

.. dropdown:: name (np_test_1_all.cpp:24865)
   :class-title: example-dropdown

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

            uint64_t before_restore = rng.next_uint64();
            rng.set_state(state);
            uint64_t after_restore = rng.next_uint64();
      
            if (before_restore != after_restore) {
              std::cout << "  [FAIL] : in np_test_bitgen_mt19937() : state restore failed";
              throw std::runtime_error("np_test_bitgen_mt19937 failed: state");
            }
      
            // Test name
            if (rng.name() != "MT19937") {
              std::cout << "  [FAIL] : in np_test_bitgen_mt19937() : incorrect name";
              throw std::runtime_error("np_test_bitgen_mt19937 failed: name");
            }
      
            std::cout << " -> tests passed" << std::endl;
          }
      
          // ============================================================================
          // PCG64 TESTS
          // ============================================================================

.. _example-ndframe-self-9:

.. dropdown:: self (np_test_1_all.cpp:2535)
   :class-title: example-dropdown

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

              throw std::runtime_error(description);
          }
          if (!(result.getElementAt({2}) == 0xFFFFFFFF)) {
              std::string description = std::string("testBitwiseXor():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(result.getElementAt({2}) == 0xFFFFFFFF)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
      
          // std::cout << "[OK] Bitwise XOR creates expected patterns\n";
      
          // Test XOR with self (should be zero)
          auto self_xor = bitwise_xor(a, a);
          if (!(self_xor.getElementAt({0}) == 0)) {
              std::string description = std::string("testBitwiseXor():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(self_xor.getElementAt({0}) == 0)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          if (!(self_xor.getElementAt({1}) == 0)) {
              std::string description = std::string("testBitwiseXor():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(self_xor.getElementAt({1}) == 0)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);

.. _example-ndframe-self-10:

.. dropdown:: self (np_test_1_all.cpp:2535)
   :class-title: example-dropdown

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

              throw std::runtime_error(description);
          }
          if (!(result.getElementAt({2}) == 0xFFFFFFFF)) {
              std::string description = std::string("testBitwiseXor():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(result.getElementAt({2}) == 0xFFFFFFFF)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
      
          // std::cout << "[OK] Bitwise XOR creates expected patterns\n";
      
          // Test XOR with self (should be zero)
          auto self_xor = bitwise_xor(a, a);
          if (!(self_xor.getElementAt({0}) == 0)) {
              std::string description = std::string("testBitwiseXor():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(self_xor.getElementAt({0}) == 0)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          if (!(self_xor.getElementAt({1}) == 0)) {
              std::string description = std::string("testBitwiseXor():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(self_xor.getElementAt({1}) == 0)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);

.. _example-ndframe-self-11:

.. dropdown:: self (np_test_1_all.cpp:2535)
   :class-title: example-dropdown

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

              throw std::runtime_error(description);
          }
          if (!(result.getElementAt({2}) == 0xFFFFFFFF)) {
              std::string description = std::string("testBitwiseXor():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(result.getElementAt({2}) == 0xFFFFFFFF)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
      
          // std::cout << "[OK] Bitwise XOR creates expected patterns\n";
      
          // Test XOR with self (should be zero)
          auto self_xor = bitwise_xor(a, a);
          if (!(self_xor.getElementAt({0}) == 0)) {
              std::string description = std::string("testBitwiseXor():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(self_xor.getElementAt({0}) == 0)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);
          }
          if (!(self_xor.getElementAt({1}) == 0)) {
              std::string description = std::string("testBitwiseXor():") + __FILE__ + ":" + std::to_string(__LINE__) + ": !(self_xor.getElementAt({1}) == 0)";
              std::cout << std::string("[FAIL] ") + description << std::endl;
              throw std::runtime_error(description);