NDFrame ======= .. cpp:class:: pandas::NDFrame Core data container class in the pandas namespace. Example ------- .. code-block:: cpp #include using namespace pandas; // Use NDFrame NDFrame obj; // ... operations ... Constructors ------------ .. list-table:: :widths: 55 25 20 :header-rows: 1 * - Signature - Location - Example * - ``NDFrame() = default`` - pd_ndframe.h:102 - * - ``NDFrame(const NDFrame& other)`` - pd_ndframe.h:106 - * - ``NDFrame(NDFrame&& other) noexcept`` - pd_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& - pd_ndframe.h:167 - :ref:`View ` * - ``Attrs& attrs() override`` - Attrs& - pd_ndframe.h:172 - :ref:`View ` Data Manipulation ----------------- .. list-table:: :widths: 40 20 15 25 :header-rows: 1 * - Signature - Return Type - Location - Example * - ``Derived rename_axis(const std::optional& mapper, int axis = 0) const`` - Derived - pd_ndframe.h:297 - :ref:`View ` * - ``Derived& set_axis(std::unique_ptr labels, int axis = 0)`` - Derived& - pd_ndframe.h:280 - :ref:`View ` Reshaping --------- .. list-table:: :widths: 40 20 15 25 :header-rows: 1 * - Signature - Return Type - Location - Example * - ``Derived T_() const`` - Derived - pd_ndframe.h:381 - :ref:`View ` * - ``Derived transpose() const`` - Derived - pd_ndframe.h:389 - :ref:`View ` I/O --- .. list-table:: :widths: 40 20 15 25 :header-rows: 1 * - Signature - Return Type - Location - Example * - ``numpy::NDArray to_numpy() const`` - numpy::NDArray - pd_ndframe.h:401 - :ref:`View ` Conversion ---------- .. list-table:: :widths: 40 20 15 25 :header-rows: 1 * - Signature - Return Type - Location - Example * - ``void copy_metadata_from(const NDFrame& other)`` - void - pd_ndframe.h:414 - Iteration --------- .. list-table:: :widths: 40 20 15 25 :header-rows: 1 * - Signature - Return Type - Location - Example * - ``void items(Func&& func) const`` - void - pd_ndframe.h:353 - :ref:`View ` * - ``std::vector keys() const`` - std::vector - pd_ndframe.h:365 - :ref:`View ` Set Operations -------------- .. list-table:: :widths: 40 20 15 25 :header-rows: 1 * - Signature - Return Type - Location - Example * - ``numpy::NDArray isin(const std::vector& values) const`` - numpy::NDArray - pd_ndframe.h:323 - :ref:`View ` Other Methods ------------- .. list-table:: :widths: 40 20 15 25 :header-rows: 1 * - Signature - Return Type - Location - Example * - ``bool all(int axis = 0, bool bool_only = false, bool skipna = true) const override`` - bool - pd_ndframe.h:212 - :ref:`View ` * - ``bool any(int axis = 0, bool bool_only = false, bool skipna = true) const override`` - bool - pd_ndframe.h:245 - :ref:`View ` * - ``std::string dtype_name() const override`` - std::string - pd_ndframe.h:140 - :ref:`View ` * - ``const Flags& flags() const override`` - const Flags& - pd_ndframe.h:182 - :ref:`View ` * - ``Flags& flags_mutable()`` - Flags& - pd_ndframe.h:187 - * - ``func(idx.get_value_str(i), vals.getElementAt({i}))`` - - pd_ndframe.h:357 - :ref:`View ` * - ``void propagate_attrs(Derived& result) const`` - void - pd_ndframe.h:423 - * - ``Derived& self() { return static_cast(\*this)`` - Derived& - pd_ndframe.h:90 - :ref:`View ` * - ``const Derived& self() const { return static_cast(\*this)`` - const Derived& - pd_ndframe.h:95 - :ref:`View ` * - ``self().set_index(std::move(labels))`` - - pd_ndframe.h:282 - :ref:`View ` * - ``void set_attrs(const Attrs& attrs) override`` - void - pd_ndframe.h:177 - * - ``void set_flags(const Flags& flags, bool copy = true, bool allows_duplicate_labels = true)`` - void - pd_ndframe.h:195 - :ref:`View ` Code Examples ------------- The following examples are extracted from the test suite. .. _example-ndframe-attrs-0: .. dropdown:: attrs (pd_test_1_all.cpp:16361) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 16351 :emphasize-lines: 11 // ===================================================================== // Series Attrs Integration Tests // ===================================================================== void pd_test_ndframe_series_attrs() { std::cout << "========= series attrs integration =============================" << std::endl; pandas::Series s({1.0, 2.0, 3.0}); // Test setting attrs on Series s.attrs().set("source", std::string("test_data")); s.attrs().set("timestamp", 1234567890); bool passed = s.attrs().get("source") == "test_data"; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_series_attrs() : set/get source" << std::endl; throw std::runtime_error("pd_test_ndframe_series_attrs failed: set/get source"); } passed = s.attrs().get("timestamp") == 1234567890; if (!passed) { .. _example-ndframe-attrs-1: .. dropdown:: attrs (pd_test_1_all.cpp:16361) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 16351 :emphasize-lines: 11 // ===================================================================== // Series Attrs Integration Tests // ===================================================================== void pd_test_ndframe_series_attrs() { std::cout << "========= series attrs integration =============================" << std::endl; pandas::Series s({1.0, 2.0, 3.0}); // Test setting attrs on Series s.attrs().set("source", std::string("test_data")); s.attrs().set("timestamp", 1234567890); bool passed = s.attrs().get("source") == "test_data"; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_series_attrs() : set/get source" << std::endl; throw std::runtime_error("pd_test_ndframe_series_attrs failed: set/get source"); } passed = s.attrs().get("timestamp") == 1234567890; if (!passed) { .. _example-ndframe-rename_axis-2: .. dropdown:: rename_axis (pd_test_1_all.cpp:6760) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 6750 :emphasize-lines: 11 throw std::runtime_error("pd_test_dataframe_index_ops failed: get_optional Z"); } } // Test rename_axis { std::map> data; data["A"] = {1, 2, 3}; pandas::DataFrame df(data); auto renamed = df.rename_axis("my_index", 0); // Should not throw } // Test reindex_like { std::map> data1; data1["A"] = {1, 2}; data1["B"] = {3, 4}; pandas::DataFrame df1(data1); .. _example-ndframe-set_axis-3: .. dropdown:: set_axis (pd_test_1_all.cpp:6673) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 6663 :emphasize-lines: 11 std::cout << " -> tests passed" << std::endl; } // ===================================================================== // Test: Index Operations // ===================================================================== void pd_test_dataframe_index_ops() { std::cout << "========= index operations ================="; // Test set_axis (rows) { std::map> data; data["A"] = {1, 2, 3}; pandas::DataFrame df(data); auto renamed = df.set_axis({"x", "y", "z"}, 0); std::string idx0 = renamed.index().get_value_str(0); if (idx0 != "x") { std::cout << " [FAIL] : in pd_test_dataframe_index_ops() : set_axis first label should be 'x'" << std::endl; throw std::runtime_error("pd_test_dataframe_index_ops failed: set_axis"); .. _example-ndframe-t_-4: .. dropdown:: T_ (pd_test_1_all.cpp:16634) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 16624 :emphasize-lines: 11 // ===================================================================== // Transpose Tests // ===================================================================== void pd_test_ndframe_transpose() { std::cout << "========= transpose ============================================" << std::endl; pandas::Series s({1, 2, 3}); // For Series, T_() returns a copy auto transposed = s.T_(); bool passed = transposed.size() == s.size(); if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_transpose() : T_() size" << std::endl; throw std::runtime_error("pd_test_ndframe_transpose failed: T_() size"); } passed = transposed[0] == 1 && transposed[1] == 2 && transposed[2] == 3; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_transpose() : T_() values" << std::endl; .. _example-ndframe-transpose-5: .. dropdown:: transpose (pd_test_1_all.cpp:16648) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 16638 :emphasize-lines: 11 std::cout << " [FAIL] : in pd_test_ndframe_transpose() : T_() size" << std::endl; throw std::runtime_error("pd_test_ndframe_transpose failed: T_() size"); } passed = transposed[0] == 1 && transposed[1] == 2 && transposed[2] == 3; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_transpose() : T_() values" << std::endl; throw std::runtime_error("pd_test_ndframe_transpose failed: T_() values"); } // Test transpose() alias auto transposed2 = s.transpose(); passed = transposed2.size() == s.size(); if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_transpose() : transpose() size" << std::endl; throw std::runtime_error("pd_test_ndframe_transpose failed: transpose() size"); } std::cout << " -> tests passed" << std::endl; } .. _example-ndframe-to_numpy-6: .. dropdown:: to_numpy (pd_test_1_all.cpp:16764) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 16754 :emphasize-lines: 11 // ===================================================================== // to_numpy Tests // ===================================================================== void pd_test_ndframe_to_numpy() { std::cout << "========= to_numpy =============================================" << std::endl; pandas::Series s({10, 20, 30}); auto arr = s.to_numpy(); bool passed = arr.getSize() == 3; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_to_numpy() : size" << std::endl; throw std::runtime_error("pd_test_ndframe_to_numpy failed: size"); } passed = arr.getElementAt({0}) == 10 && arr.getElementAt({1}) == 20 && arr.getElementAt({2}) == 30; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_to_numpy() : values" << std::endl; .. _example-ndframe-items-7: .. dropdown:: items (pd_test_1_all.cpp:16554) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 16544 :emphasize-lines: 11 // ===================================================================== // Iteration Tests (items, keys) // ===================================================================== void pd_test_ndframe_items_keys() { std::cout << "========= items/keys ===========================================" << std::endl; pandas::Series s({10, 20, 30}); // Test items() std::vector collected_keys; std::vector collected_values; s.items([&](const std::string& key, int value) { collected_keys.push_back(key); collected_values.push_back(value); }); bool passed = collected_keys.size() == 3; if (!passed) { .. _example-ndframe-keys-8: .. dropdown:: keys (pd_test_1_all.cpp:16319) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 16309 :emphasize-lines: 11 } // Test default value passed = attrs.get("missing", 99) == 99; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_attrs() : default value" << std::endl; throw std::runtime_error("pd_test_ndframe_attrs failed: default value"); } // Test keys auto keys = attrs.keys(); passed = keys.size() == 3; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_attrs() : keys()" << std::endl; throw std::runtime_error("pd_test_ndframe_attrs failed: keys()"); } // Test remove passed = attrs.remove("count") && !attrs.contains("count"); if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_attrs() : remove" << std::endl; .. _example-ndframe-isin-9: .. dropdown:: isin (pd_test_1_all.cpp:5938) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 5928 :emphasize-lines: 11 std::cout << " -> tests passed" << std::endl; } void pd_test_categorical_index_isin() { std::cout << "========= inherited isin =============================="; pandas::CategoricalArray arr({"a", "b", "c", "d"}); pandas::CategoricalIndex idx(arr); std::vector values = {"a", "c"}; numpy::NDArray mask = idx.isin(values); bool passed = (mask.getSize() == 4 && mask.getElementAt({0}) == true && // a mask.getElementAt({1}) == false && // b mask.getElementAt({2}) == true && // c mask.getElementAt({3}) == false); // d if (!passed) { std::cout << " [FAIL] : in pd_test_categorical_index_isin()" << std::endl; throw std::runtime_error("pd_test_categorical_index_isin failed"); } .. _example-ndframe-all-10: .. dropdown:: all (pd_test_1_all.cpp:247) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 237 :emphasize-lines: 11 pandas::BooleanArray has_true({ std::optional(false), std::optional(true) }); any_result = has_true.any(); if (!any_result.has_value() || !any_result.value()) { std::cout << " [FAIL] : in pd_test_boolean_array_reductions() : any() with True" << std::endl; throw std::runtime_error("pd_test_boolean_array_reductions failed: any() with True"); } // Test all() pandas::BooleanArray all_true({ std::optional(true), std::optional(true) }); auto all_result = all_true.all(); if (!all_result.has_value() || !all_result.value()) { std::cout << " [FAIL] : in pd_test_boolean_array_reductions() : all() of all True" << std::endl; throw std::runtime_error("pd_test_boolean_array_reductions failed: all() all True"); } .. _example-ndframe-any-11: .. dropdown:: any (pd_test_1_all.cpp:226) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 216 :emphasize-lines: 11 std::cout << " [FAIL] : in pd_test_boolean_array_kleene_not() : ~NA should be NA" << std::endl; throw std::runtime_error("pd_test_boolean_array_kleene_not failed: ~NA"); } std::cout << " -> tests passed" << std::endl; } void pd_test_boolean_array_reductions() { std::cout << "========= BooleanArray: reductions ======================= "; // Test any() pandas::BooleanArray all_false({ std::optional(false), std::optional(false) }); auto any_result = all_false.any(); if (!any_result.has_value() || any_result.value()) { std::cout << " [FAIL] : in pd_test_boolean_array_reductions() : any() of all False" << std::endl; throw std::runtime_error("pd_test_boolean_array_reductions failed: any() all False"); } .. _example-ndframe-dtype_name-12: .. dropdown:: dtype_name (pd_test_1_all.cpp:10104) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 10094 :emphasize-lines: 11 } void pd_test_extension_index_array_constructor() { std::cout << "========= array constructor ========================="; pandas::CategoricalArray arr({"apple", "banana", "apple", "cherry"}); pandas::CategoricalIndex idx(arr, "fruits"); bool passed = (idx.size() == 4 && !idx.empty() && idx.name().has_value() && *idx.name() == "fruits" && idx.dtype_name() == "category"); if (!passed) { std::cout << " [FAIL] : in pd_test_extension_index_array_constructor() : array constructor check failed" << std::endl; throw std::runtime_error("pd_test_extension_index_array_constructor failed"); } std::cout << " -> tests passed" << std::endl; } void pd_test_extension_index_copy_constructor() { std::cout << "========= copy constructor ========================="; .. _example-ndframe-flags-13: .. dropdown:: flags (pd_test_1_all.cpp:16397) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 16387 :emphasize-lines: 11 // ===================================================================== // Series Flags Integration Tests // ===================================================================== void pd_test_ndframe_series_flags() { std::cout << "========= series flags integration =============================" << std::endl; pandas::Series s({1, 2, 3}); // Test default flags bool passed = s.flags().allows_duplicate_labels == true; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_series_flags() : default allows_duplicate_labels" << std::endl; throw std::runtime_error("pd_test_ndframe_series_flags failed: default allows_duplicate_labels"); } passed = s.flags().copy_on_write == false; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_series_flags() : default copy_on_write" << std::endl; throw std::runtime_error("pd_test_ndframe_series_flags failed: default copy_on_write"); } .. _example-ndframe-func-14: .. dropdown:: func (pd_test_3_all.cpp:13837) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 13827 :emphasize-lines: 11 // ============================================================================ // Read Stubs Tests (verify they throw correctly) // ============================================================================ void pd_test_top_level_read_stubs() { std::cout << "========= read_* stubs ================================"; // Test that read functions throw as expected (they are stubs) auto test_throws = [](const std::string& name, auto func) { try { func(); std::cout << " [FAIL] : " << name << " should throw" << std::endl; return false; } catch (const std::exception&) { return true; } }; bool all_passed = true; all_passed &= test_throws("read_clipboard", []() { pandas::read_clipboard(); }); all_passed &= test_throws("read_excel", []() { pandas::read_excel("test.xlsx"); }); .. _example-ndframe-self-15: .. dropdown:: self (pd_test_3_all.cpp:1747) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 1737 :emphasize-lines: 11 void pd_test_3_all_dataframe_unstack() { std::cout << "========= DataFrame.unstack() ========================"; std::map> data = { {"A", {1.0, 2.0, 3.0}}, {"B", {4.0, 5.0, 6.0}} }; pandas::DataFrame df(data); // Without MultiIndex, unstack() returns self (matches pandas behavior) pandas::DataFrame result = df.unstack(); if (result.nrows() != 3 || result.ncols() != 2) { std::cout << " [FAIL] : in pd_test_3_all_dataframe_unstack() : shape mismatch" << std::endl; throw std::runtime_error("pd_test_3_all_dataframe_unstack failed: shape"); } // Single column without MultiIndex also returns self std::map> single_col = { {"A", {1.0, 2.0, 3.0}} .. _example-ndframe-self-16: .. dropdown:: self (pd_test_3_all.cpp:1747) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 1737 :emphasize-lines: 11 void pd_test_3_all_dataframe_unstack() { std::cout << "========= DataFrame.unstack() ========================"; std::map> data = { {"A", {1.0, 2.0, 3.0}}, {"B", {4.0, 5.0, 6.0}} }; pandas::DataFrame df(data); // Without MultiIndex, unstack() returns self (matches pandas behavior) pandas::DataFrame result = df.unstack(); if (result.nrows() != 3 || result.ncols() != 2) { std::cout << " [FAIL] : in pd_test_3_all_dataframe_unstack() : shape mismatch" << std::endl; throw std::runtime_error("pd_test_3_all_dataframe_unstack failed: shape"); } // Single column without MultiIndex also returns self std::map> single_col = { {"A", {1.0, 2.0, 3.0}} .. _example-ndframe-self-17: .. dropdown:: self (pd_test_3_all.cpp:1747) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 1737 :emphasize-lines: 11 void pd_test_3_all_dataframe_unstack() { std::cout << "========= DataFrame.unstack() ========================"; std::map> data = { {"A", {1.0, 2.0, 3.0}}, {"B", {4.0, 5.0, 6.0}} }; pandas::DataFrame df(data); // Without MultiIndex, unstack() returns self (matches pandas behavior) pandas::DataFrame result = df.unstack(); if (result.nrows() != 3 || result.ncols() != 2) { std::cout << " [FAIL] : in pd_test_3_all_dataframe_unstack() : shape mismatch" << std::endl; throw std::runtime_error("pd_test_3_all_dataframe_unstack failed: shape"); } // Single column without MultiIndex also returns self std::map> single_col = { {"A", {1.0, 2.0, 3.0}} .. _example-ndframe-set_flags-18: .. dropdown:: set_flags (pd_test_1_all.cpp:16410) :class-title: example-dropdown .. code-block:: cpp :linenos: :lineno-start: 16400 :emphasize-lines: 11 throw std::runtime_error("pd_test_ndframe_series_flags failed: default allows_duplicate_labels"); } passed = s.flags().copy_on_write == false; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_series_flags() : default copy_on_write" << std::endl; throw std::runtime_error("pd_test_ndframe_series_flags failed: default copy_on_write"); } // Test set_flags s.set_flags(pandas::Flags(false, true)); passed = s.flags().allows_duplicate_labels == false; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_series_flags() : set allows_duplicate_labels" << std::endl; throw std::runtime_error("pd_test_ndframe_series_flags failed: set allows_duplicate_labels"); } passed = s.flags().copy_on_write == true; if (!passed) { std::cout << " [FAIL] : in pd_test_ndframe_series_flags() : set copy_on_write" << std::endl; throw std::runtime_error("pd_test_ndframe_series_flags failed: set copy_on_write");