NDFrame

class pandas::NDFrame

Core data container class in the pandas namespace.

Example

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

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

Constructors

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

Signature	Return Type	Location	Example
const Attrs& attrs() const override	const Attrs&	pd_ndframe.h:167	View
Attrs& attrs() override	Attrs&	pd_ndframe.h:172	View

Data Manipulation

Signature	Return Type	Location	Example
Derived rename_axis(const std::optional<std::string>& mapper, int axis = 0) const	Derived	pd_ndframe.h:297	View
Derived& set_axis(std::unique_ptr<IndexBase> labels, int axis = 0)	Derived&	pd_ndframe.h:280	View

Reshaping

Signature	Return Type	Location	Example
Derived T_() const	Derived	pd_ndframe.h:381	View
Derived transpose() const	Derived	pd_ndframe.h:389	View

I/O

Signature	Return Type	Location	Example
numpy::NDArray<T> to_numpy() const	numpy::NDArray<T>	pd_ndframe.h:401	View

Conversion

Signature	Return Type	Location	Example
void copy_metadata_from(const NDFrame& other)	void	pd_ndframe.h:414

Iteration

Signature	Return Type	Location	Example
void items(Func&& func) const	void	pd_ndframe.h:353	View
std::vector<std::string> keys() const	std::vector<std::string>	pd_ndframe.h:365	View

Set Operations

Signature	Return Type	Location	Example
numpy::NDArray<numpy::bool_> isin(const std::vector<T>& values) const	numpy::NDArray<numpy::bool_>	pd_ndframe.h:323	View

Other Methods

Signature	Return Type	Location	Example
bool all(int axis = 0, bool bool_only = false, bool skipna = true) const override	bool	pd_ndframe.h:212	View
bool any(int axis = 0, bool bool_only = false, bool skipna = true) const override	bool	pd_ndframe.h:245	View
std::string dtype_name() const override	std::string	pd_ndframe.h:140	View
const Flags& flags() const override	const Flags&	pd_ndframe.h:182	View
Flags& flags_mutable()	Flags&	pd_ndframe.h:187
func(idx.get_value_str(i), vals.getElementAt({i}))		pd_ndframe.h:357	View
void propagate_attrs(Derived& result) const	void	pd_ndframe.h:423
Derived& self() { return static_cast<Derived&>(\*this)	Derived&	pd_ndframe.h:90	View
const Derived& self() const { return static_cast<const Derived&>(\*this)	const Derived&	pd_ndframe.h:95	View
self().set_index(std::move(labels))		pd_ndframe.h:282	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	View

Code Examples

The following examples are extracted from the test suite.

attrs (pd_test_1_all.cpp:16361)

        // =====================================================================
        // Series Attrs Integration Tests
        // =====================================================================

        void pd_test_ndframe_series_attrs() {
            std::cout << "========= series attrs integration =============================" << std::endl;

            pandas::Series<double> 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<std::string>("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<int>("timestamp") == 1234567890;
            if (!passed) {

attrs (pd_test_1_all.cpp:16361)

        // =====================================================================
        // Series Attrs Integration Tests
        // =====================================================================

        void pd_test_ndframe_series_attrs() {
            std::cout << "========= series attrs integration =============================" << std::endl;

            pandas::Series<double> 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<std::string>("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<int>("timestamp") == 1234567890;
            if (!passed) {

rename_axis (pd_test_1_all.cpp:6760)

                    throw std::runtime_error("pd_test_dataframe_index_ops failed: get_optional Z");
                }
            }

            // Test rename_axis
            {
                std::map<std::string, std::vector<int>> 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<std::string, std::vector<int>> data1;
                data1["A"] = {1, 2};
                data1["B"] = {3, 4};
                pandas::DataFrame df1(data1);

set_axis (pd_test_1_all.cpp:6673)

            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<std::string, std::vector<int>> 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");

T_ (pd_test_1_all.cpp:16634)

        // =====================================================================
        // Transpose Tests
        // =====================================================================

        void pd_test_ndframe_transpose() {
            std::cout << "========= transpose ============================================" << std::endl;

            pandas::Series<int> 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;

transpose (pd_test_1_all.cpp:16648)

                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;
        }

to_numpy (pd_test_1_all.cpp:16764)

        // =====================================================================
        // to_numpy Tests
        // =====================================================================

        void pd_test_ndframe_to_numpy() {
            std::cout << "========= to_numpy =============================================" << std::endl;

            pandas::Series<int> 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;

items (pd_test_1_all.cpp:16554)

        // =====================================================================
        // Iteration Tests (items, keys)
        // =====================================================================

        void pd_test_ndframe_items_keys() {
            std::cout << "========= items/keys ===========================================" << std::endl;

            pandas::Series<int> s({10, 20, 30});

            // Test items()
            std::vector<std::string> collected_keys;
            std::vector<int> 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) {

keys (pd_test_1_all.cpp:16319)

            }

            // Test default value
            passed = attrs.get<int>("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;

isin (pd_test_1_all.cpp:5938)

    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<std::string> values = {"a", "c"};
    numpy::NDArray<numpy::bool_> 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");
    }

all (pd_test_1_all.cpp:247)

        pandas::BooleanArray has_true({
            std::optional<bool>(false),
            std::optional<bool>(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<bool>(true),
            std::optional<bool>(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");
        }

any (pd_test_1_all.cpp:226)

            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<bool>(false),
            std::optional<bool>(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");
        }

dtype_name (pd_test_1_all.cpp:10104)

}

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 =========================";

flags (pd_test_1_all.cpp:16397)

        // =====================================================================
        // Series Flags Integration Tests
        // =====================================================================

        void pd_test_ndframe_series_flags() {
            std::cout << "========= series flags integration =============================" << std::endl;

            pandas::Series<int> 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");
            }

func (pd_test_3_all.cpp:13837)

// ============================================================================
// 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"); });

self (pd_test_3_all.cpp:1747)

void pd_test_3_all_dataframe_unstack() {
    std::cout << "========= DataFrame.unstack() ========================";

    std::map<std::string, std::vector<double>> 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<std::string, std::vector<double>> single_col = {
        {"A", {1.0, 2.0, 3.0}}

self (pd_test_3_all.cpp:1747)

void pd_test_3_all_dataframe_unstack() {
    std::cout << "========= DataFrame.unstack() ========================";

    std::map<std::string, std::vector<double>> 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<std::string, std::vector<double>> single_col = {
        {"A", {1.0, 2.0, 3.0}}

self (pd_test_3_all.cpp:1747)

void pd_test_3_all_dataframe_unstack() {
    std::cout << "========= DataFrame.unstack() ========================";

    std::map<std::string, std::vector<double>> 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<std::string, std::vector<double>> single_col = {
        {"A", {1.0, 2.0, 3.0}}

set_flags (pd_test_1_all.cpp:16410)

                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");