DataArray
=========

.. cpp:class:: pandas::DataArray

   Extension array type for specialized data storage.

Example
-------

.. code-block:: cpp

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

   // Use DataArray
   DataArray obj;
   // ... operations ...

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

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

   * - Signature
     - Location
     - Example
   * - ``DataArray(const numpy::NDArray<T>& data, const std::vector<std::string>& dims = {}, const std::map<std::string, Coordinate>& coords = {}, const std::map<std::string, std::string>& attrs = {}, const std::optional<std::string>& name = std::nullopt)``
     - pd_xarray.h:166
     - 
   * - ``DataArray(const std::vector<T>& data, const std::string& dim_name = "dim_0", const std::optional<Coordinate>& coord = std::nullopt, const std::optional<std::string>& name = std::nullopt)``
     - pd_xarray.h:200
     - 

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``T at(const std::vector<size_t>& indices) const``
     - T
     - pd_xarray.h:320
     - :ref:`View <example-dataarray-at-0>`
   * - ``const std::map<std::string, std::string>& attrs() const``
     - const std::map<std::string, std::string>&
     - pd_xarray.h:239
     - :ref:`View <example-dataarray-attrs-1>`
   * - ``std::map<std::string, std::string>& attrs()``
     - std::map<std::string, std::string>&
     - pd_xarray.h:240
     - :ref:`View <example-dataarray-attrs-2>`

I/O
---

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``std::string to_string() const``
     - std::string
     - pd_xarray.h:338
     - :ref:`View <example-dataarray-to_string-3>`

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

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

   * - Signature
     - Return Type
     - Location
     - Example
   * - ``const Coordinate& coord(const std::string& name) const``
     - const Coordinate&
     - pd_xarray.h:298
     - :ref:`View <example-dataarray-coord-4>`
   * - ``const std::map<std::string, Coordinate>& coords() const``
     - const std::map<std::string, Coordinate>&
     - pd_xarray.h:233
     - :ref:`View <example-dataarray-coords-5>`
   * - ``std::map<std::string, Coordinate>& coords()``
     - std::map<std::string, Coordinate>&
     - pd_xarray.h:234
     - :ref:`View <example-dataarray-coords-6>`
   * - ``const std::vector<std::string>& dims() const``
     - const std::vector<std::string>&
     - pd_xarray.h:228
     - :ref:`View <example-dataarray-dims-7>`
   * - ``bool empty() const { return data_.getSize() == 0``
     - bool
     - pd_xarray.h:282
     - :ref:`View <example-dataarray-empty-8>`
   * - ``bool has_coord(const std::string& name) const``
     - bool
     - pd_xarray.h:291
     - :ref:`View <example-dataarray-has_coord-9>`
   * - ``std::optional<std::string> name() const``
     - std::optional<std::string>
     - pd_xarray.h:245
     - :ref:`View <example-dataarray-name-10>`
   * - ``size_t ndim() const { return dims_.size()``
     - size_t
     - pd_xarray.h:255
     - :ref:`View <example-dataarray-ndim-11>`
   * - ``void set_coord(const std::string& name, const Coordinate& coord)``
     - void
     - pd_xarray.h:309
     - 
   * - ``void set_name(const std::string& name)``
     - void
     - pd_xarray.h:250
     - :ref:`View <example-dataarray-set_name-12>`
   * - ``size_t size() const { return data_.getSize()``
     - size_t
     - pd_xarray.h:265
     - :ref:`View <example-dataarray-size-13>`
   * - ``std::map<std::string, size_t> sizes() const``
     - std::map<std::string, size_t>
     - pd_xarray.h:270
     - 
   * - ``const numpy::NDArray<T>& values() const``
     - const numpy::NDArray<T>&
     - pd_xarray.h:222
     - :ref:`View <example-dataarray-values-14>`
   * - ``numpy::NDArray<T>& values()``
     - numpy::NDArray<T>&
     - pd_xarray.h:223
     - :ref:`View <example-dataarray-values-15>`


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

The following examples are extracted from the test suite.

.. _example-dataarray-at-0:

.. dropdown:: at (pd_test_1_all.cpp:6581)
   :class-title: example-dropdown

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

                  // Test isna/notna with float data
                  {
                      std::map<std::string, std::vector<numpy::float64>> float_data;
                      float_data["X"] = {1.0, std::nan(""), 3.0};
                      float_data["Y"] = {4.0, 5.0, std::nan("")};
                      pandas::DataFrame df_na(float_data);
      
                      auto na_mask = df_na.isna();
                      // Row 1, col 0 (X) should be NA
                      if (!na_mask.getElementAt({1, 0})) {
                          std::cout << "  [FAIL] : in pd_test_dataframe_manipulation() : isna at (1,0) should be true" << std::endl;
                          throw std::runtime_error("pd_test_dataframe_manipulation failed: isna at (1,0)");
                      }
                      // Row 2, col 1 (Y) should be NA
                      if (!na_mask.getElementAt({2, 1})) {
                          std::cout << "  [FAIL] : in pd_test_dataframe_manipulation() : isna at (2,1) should be true" << std::endl;
                          throw std::runtime_error("pd_test_dataframe_manipulation failed: isna at (2,1)");
                      }
                      // Row 0, col 0 should NOT be NA
                      if (na_mask.getElementAt({0, 0})) {
                          std::cout << "  [FAIL] : in pd_test_dataframe_manipulation() : isna at (0,0) should be false" << std::endl;

.. _example-dataarray-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<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) {

.. _example-dataarray-attrs-2:

.. 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<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) {

.. _example-dataarray-to_string-3:

.. dropdown:: to_string (pd_test_1_all.cpp:2693)
   :class-title: example-dropdown

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

              pandas::PeriodArray arr_m(std::vector<std::string>{
                  "2020-01",
                  "NaT",
                  "2025-06"
              }, "M");
      
              // Year
              auto years = arr_m.year();
              auto y0 = years[0];
              if (!y0.has_value() || y0.value() != 2020) {
                  std::cout << "  [FAIL] : year[0] should be 2020, got " << (y0.has_value() ? std::to_string(y0.value()) : "NA") << std::endl;
                  throw std::runtime_error("pd_test_period_array_year_month_quarter failed: year[0]");
              }
      
              auto y1 = years[1];
              if (y1.has_value()) {
                  std::cout << "  [FAIL] : year[1] should be NA (NaT)" << std::endl;
                  throw std::runtime_error("pd_test_period_array_year_month_quarter failed: year[1] should be NA");
              }
      
              auto y2 = years[2];

.. _example-dataarray-coord-4:

.. dropdown:: coord (pd_test_2_all.cpp:17025)
   :class-title: example-dropdown

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

      
                  // Create DataFrame with RangeIndex (default)
                  std::map<std::string, std::vector<numpy::float64>> data = {
                      {"val", {1.0, 2.0, 3.0}}
                  };
      
                  pandas::DataFrame df(data);
                  pandas::Dataset ds = df.to_xarray();
      
                  // Get index coordinate
                  const pandas::Coordinate& idx_coord = ds.coord("index");
      
                  // Verify coordinate size
                  bool passed = (idx_coord.size() == 3);
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_to_xarray_coordinate_values() : wrong coordinate size" << std::endl;
                      throw std::runtime_error("pd_test_to_xarray_coordinate_values failed: wrong size");
                  }
      
                  // Verify coordinate values (0, 1, 2 for RangeIndex)
                  passed = (idx_coord.get_value_str(0) == "0" &&

.. _example-dataarray-coords-5:

.. dropdown:: coords (pd_test_3_all.cpp:14912)
   :class-title: example-dropdown

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

      /**
       * Test Series.to_xarray() coordinates
       */
      void pd_test_series_to_xarray_coordinates() {
          std::cout << "========= Series.to_xarray() coordinates ===============";
      
          pandas::Series<double> s({100.0, 200.0, 300.0}, "prices");
          pandas::DataArray<double> da = s.to_xarray();
      
          // Verify coordinate exists
          auto& coords = da.coords();
          if (coords.find("index") == coords.end()) {
              std::cout << "  [FAIL] : should have 'index' coordinate" << std::endl;
              throw std::runtime_error("pd_test_series_to_xarray_coordinates failed: missing coord");
          }
      
          // Verify coordinate size matches Series
          const pandas::Coordinate& coord = coords.at("index");
          if (coord.size() != 3) {
              std::cout << "  [FAIL] : coordinate size should be 3, got " << coord.size() << std::endl;
              throw std::runtime_error("pd_test_series_to_xarray_coordinates failed: coord size");

.. _example-dataarray-coords-6:

.. dropdown:: coords (pd_test_3_all.cpp:14912)
   :class-title: example-dropdown

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

      /**
       * Test Series.to_xarray() coordinates
       */
      void pd_test_series_to_xarray_coordinates() {
          std::cout << "========= Series.to_xarray() coordinates ===============";
      
          pandas::Series<double> s({100.0, 200.0, 300.0}, "prices");
          pandas::DataArray<double> da = s.to_xarray();
      
          // Verify coordinate exists
          auto& coords = da.coords();
          if (coords.find("index") == coords.end()) {
              std::cout << "  [FAIL] : should have 'index' coordinate" << std::endl;
              throw std::runtime_error("pd_test_series_to_xarray_coordinates failed: missing coord");
          }
      
          // Verify coordinate size matches Series
          const pandas::Coordinate& coord = coords.at("index");
          if (coord.size() != 3) {
              std::cout << "  [FAIL] : coordinate size should be 3, got " << coord.size() << std::endl;
              throw std::runtime_error("pd_test_series_to_xarray_coordinates failed: coord size");

.. _example-dataarray-dims-7:

.. dropdown:: dims (pd_test_2_all.cpp:16997)
   :class-title: example-dropdown

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

                  // Create DataFrame with 4 rows
                  std::map<std::string, std::vector<numpy::int64>> data = {
                      {"x", {10, 20, 30, 40}},
                      {"y", {100, 200, 300, 400}}
                  };
      
                  pandas::DataFrame df(data);
                  pandas::Dataset ds = df.to_xarray();
      
                  // Verify dimensions
                  auto dims = ds.dims();
                  bool passed = (dims.size() == 1 && dims.count("index") == 1 && dims.at("index") == 4);
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_to_xarray_dimensions() : wrong dimensions" << std::endl;
                      std::cout << "    Expected: index: 4" << std::endl;
                      std::cout << "    Got: ";
                      for (const auto& [name, size] : dims) {
                          std::cout << name << ": " << size << " ";
                      }
                      std::cout << std::endl;
                      throw std::runtime_error("pd_test_to_xarray_dimensions failed");

.. _example-dataarray-empty-8:

.. dropdown:: empty (pd_test_1_all.cpp:941)
   :class-title: example-dropdown

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

      
      #include "../pandas/pd_config.h"
      
      namespace dataframe_tests {
      
      namespace dataframe_tests_config {
      
          void pd_test_config_version() {
              std::cout << "========= df_config: version info ======================= ";
              const char* version = pandas::DataFrameInfo::version();
              if (version == nullptr || std::string(version).empty()) {
                  std::cout << "[FAIL] : in pd_test_config_version() : version is null or empty" << std::endl;
                  throw std::runtime_error("pd_test_config_version failed: version is null or empty");
              }
              std::cout << "-> tests passed" << std::endl;
          }
      
          void pd_test_config_na_repr() {
              std::cout << "========= df_config: NA representation ======================= ";
              const char* na_repr = pandas::DataFrameConfig::get_na_repr();
              if (na_repr == nullptr) {

.. _example-dataarray-has_coord-9:

.. dropdown:: has_coord (pd_test_2_all.cpp:16975)
   :class-title: example-dropdown

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

                  }
      
                  // Verify variable names
                  passed = ds.has_var("A") && ds.has_var("B");
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_to_xarray_basic() : missing variable A or B" << std::endl;
                      throw std::runtime_error("pd_test_to_xarray_basic failed: missing variables");
                  }
      
                  // Verify coordinate exists
                  passed = ds.has_coord("index");
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_to_xarray_basic() : missing index coordinate" << std::endl;
                      throw std::runtime_error("pd_test_to_xarray_basic failed: missing index coordinate");
                  }
      
                  std::cout << " -> tests passed" << std::endl;
              }
      
              void pd_test_to_xarray_dimensions() {
                  std::cout << "========= to_xarray dimensions =========================";

.. _example-dataarray-name-10:

.. dropdown:: name (pd_test_1_all.cpp:295)
   :class-title: example-dropdown

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

                  throw std::runtime_error("pd_test_boolean_array_reductions failed: mean");
              }
      
              std::cout << " -> tests passed" << std::endl;
          }
      
          void pd_test_boolean_array_dtype() {
              std::cout << "========= BooleanArray: dtype ======================= ";
      
              pandas::BooleanArray arr;
              if (arr.dtype().name() != "boolean") {
                  std::cout << "  [FAIL] : in pd_test_boolean_array_dtype() : dtype name should be 'boolean'" << std::endl;
                  throw std::runtime_error("pd_test_boolean_array_dtype failed: dtype name");
              }
      
              if (arr.dtype().kind() != "b") {
                  std::cout << "  [FAIL] : in pd_test_boolean_array_dtype() : dtype kind should be 'b'" << std::endl;
                  throw std::runtime_error("pd_test_boolean_array_dtype failed: dtype kind");
              }
      
              std::cout << " -> tests passed" << std::endl;

.. _example-dataarray-ndim-11:

.. dropdown:: ndim (pd_test_1_all.cpp:6195)
   :class-title: example-dropdown

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

                  pandas::DataFrame df(data);
      
                  // Test shape
                  auto shape = df.shape();
                  if (shape.size() != 2 || shape[0] != 4 || shape[1] != 3) {
                      std::cout << "  [FAIL] : in pd_test_dataframe_properties() : shape mismatch" << std::endl;
                      throw std::runtime_error("pd_test_dataframe_properties failed: shape mismatch");
                  }
      
                  // Test ndim
                  if (df.ndim() != 2) {
                      std::cout << "  [FAIL] : in pd_test_dataframe_properties() : ndim != 2" << std::endl;
                      throw std::runtime_error("pd_test_dataframe_properties failed: ndim != 2");
                  }
      
                  // Test empty
                  if (df.empty()) {
                      std::cout << "  [FAIL] : in pd_test_dataframe_properties() : should not be empty" << std::endl;
                      throw std::runtime_error("pd_test_dataframe_properties failed: should not be empty");
                  }
      

.. _example-dataarray-set_name-12:

.. dropdown:: set_name (pd_test_1_all.cpp:11798)
   :class-title: example-dropdown

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

                      throw std::runtime_error("pd_test_index_vector_constructor failed");
                  }
      
                  std::cout << " -> tests passed" << std::endl;
              }
      
              void pd_test_index_copy_constructor() {
                  std::cout << "========= copy constructor ============================";
      
                  pandas::Index<numpy::int64> idx1{1, 2, 3};
                  idx1.set_name("original");
      
                  pandas::Index<numpy::int64> idx2(idx1);
      
                  bool passed = (idx2.size() == 3);
                  passed = passed && (idx2.name().value() == "original");
                  passed = passed && idx2.equals(idx1);
      
                  if (!passed) {
                      std::cout << "  [FAIL] : in pd_test_index_copy_constructor() : copy failed" << std::endl;
                      throw std::runtime_error("pd_test_index_copy_constructor failed");

.. _example-dataarray-size-13:

.. dropdown:: size (pd_test_1_all.cpp:22)
   :class-title: example-dropdown

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

      #include "../pandas/pd_boolean_array.h"
      
      namespace dataframe_tests {
      
      namespace dataframe_tests_boolean_array {
          void pd_test_boolean_array_constructors() {
              std::cout << "========= BooleanArray: constructors ======================= ";
      
              // Default constructor
              pandas::BooleanArray arr1;
              if (arr1.size() != 0) {
                  std::cout << "  [FAIL] : in pd_test_boolean_array_constructors() : default constructor size != 0" << std::endl;
                  throw std::runtime_error("pd_test_boolean_array_constructors failed: default constructor size != 0");
              }
      
              // Initializer list constructor
              pandas::BooleanArray arr2({
                  std::optional<bool>(true),
                  std::optional<bool>(false),
                  std::nullopt,
                  std::optional<bool>(true)

.. _example-dataarray-values-14:

.. dropdown:: values (pd_test_1_all.cpp:364)
   :class-title: example-dropdown

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

              pandas::CategoricalArray arr1;
              if (arr1.size() != 0) {
                  std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : default constructor size != 0" << std::endl;
                  throw std::runtime_error("pd_test_categorical_array_constructors failed: default constructor size != 0");
              }
              if (arr1.ordered()) {
                  std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : default should be unordered" << std::endl;
                  throw std::runtime_error("pd_test_categorical_array_constructors failed: default should be unordered");
              }
      
              // Constructor from values (infer categories)
              std::vector<std::optional<std::string>> values = {
                  std::optional<std::string>("a"),
                  std::optional<std::string>("b"),
                  std::optional<std::string>("a"),
                  std::optional<std::string>("c")
              };
              pandas::CategoricalArray arr2(values);
              if (arr2.size() != 4) {
                  std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : values constructor size != 4" << std::endl;
                  throw std::runtime_error("pd_test_categorical_array_constructors failed: values constructor size != 4");

.. _example-dataarray-values-15:

.. dropdown:: values (pd_test_1_all.cpp:364)
   :class-title: example-dropdown

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

              pandas::CategoricalArray arr1;
              if (arr1.size() != 0) {
                  std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : default constructor size != 0" << std::endl;
                  throw std::runtime_error("pd_test_categorical_array_constructors failed: default constructor size != 0");
              }
              if (arr1.ordered()) {
                  std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : default should be unordered" << std::endl;
                  throw std::runtime_error("pd_test_categorical_array_constructors failed: default should be unordered");
              }
      
              // Constructor from values (infer categories)
              std::vector<std::optional<std::string>> values = {
                  std::optional<std::string>("a"),
                  std::optional<std::string>("b"),
                  std::optional<std::string>("a"),
                  std::optional<std::string>("c")
              };
              pandas::CategoricalArray arr2(values);
              if (arr2.size() != 4) {
                  std::cout << "  [FAIL] : in pd_test_categorical_array_constructors() : values constructor size != 4" << std::endl;
                  throw std::runtime_error("pd_test_categorical_array_constructors failed: values constructor size != 4");