plestylib.data
==============

.. py:module:: plestylib.data


Submodules
----------

.. toctree::
   :maxdepth: 1

   /reference/plestylib/data/array/index
   /reference/plestylib/data/ctype_manager/index
   /reference/plestylib/data/table/index
   /reference/plestylib/data/types/index
   /reference/plestylib/data/units/index


Classes
-------

.. autoapisummary::

   plestylib.data.PlestyArray
   plestylib.data.Units
   plestylib.data.TableHeader
   plestylib.data.PlestyTable2D
   plestylib.data.PlestyTable3D


Functions
---------

.. autoapisummary::

   plestylib.data.resolve_dtype
   plestylib.data.resolve_array_item_dtype
   plestylib.data.normalize_shape
   plestylib.data.istype
   plestylib.data.cast_basic_type


Package Contents
----------------

.. py:class:: PlestyArray(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)

   Bases: :py:obj:`numpy.ndarray`


   Data definition for a numerical array with meta information.
   The array inherits from numpy.ndarray, so it can be used as a regular numpy array,
   but it also has additional attributes for meta information and additional methods
   for data manipulation.

   .. attribute:: name

      Optional name for the data.

   .. attribute:: range

      Optional range for the data values, can be a tuple of (min, max).

   .. attribute:: options

      Optional list of possible values for the data, if applicable.

   .. attribute:: unit

      Optional unit for the data, e.g., "nm", "s", "m/s", etc.

   .. attribute:: description

      Optional description for the data, providing more context and information.

   Usage:

   .. code-block:: python

       from plestylib.data import PlestyArray as PArray
       data = PArray([1.0, 2.0, 3.0], name="Example Data", unit="nm",
                     description="This is an example data array.")
       np_arr = np.random.rand(3)
       plesty_arr = PArray(np_arr, name="Random Data", unit="s",
                           description="This is a random data array.")

       # NumPy-like constructors on PlestyArray
       z = PArray.zeros((10, 2), unit="a.u.", description="Zero-filled matrix")
       o = PArray.ones(5, name="weights")
       x = PArray.arange(0, 1, 0.1, unit="s")
       grid = PArray.linspace(400, 700, 5, unit="nm", name="wavelength")

       # Unit-aware operations with metadata updates
       speed = PArray([10.0, 12.0], name="speed", unit="m/s", description="Speed of Rocket")
       time = PArray([2.0, 3.0], name="time", unit="s", description="Time")
       distance = speed * time
       # distance.unit -> "m"
       # distance.name -> "speed(m/s) * time(s)"
       # distance.description -> "speed: Speed of Rocket; time: Time"


   .. py:attribute:: _META_KEYS


   .. py:attribute:: __array_priority__
      :value: 1000



   .. py:method:: update_meta(**kwargs)

      Update meta information for the PlestyArray.

      Example:

      .. code-block:: python

          arr = PlestyArray([1.0, 2.0, 3.0], name="Example Data", unit="nm")
          arr.update_meta(description="Updated description", range=(0.0, 5.0))



   .. py:method:: _meta_kwargs() -> Dict[str, Any]


   .. py:method:: _find_meta_source(items) -> Optional[PlestyArray]
      :classmethod:



   .. py:method:: _unit_text(unit: Optional[str]) -> str
      :staticmethod:



   .. py:method:: _build_binary_meta(left: PlestyArray, right: PlestyArray, op_symbol: str) -> Dict[str, Any]
      :classmethod:



   .. py:method:: _split_meta_kwargs(kwargs: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]
      :classmethod:



   .. py:method:: _wrap_numpy_result(result: Any, meta_kwargs: Dict[str, Any])
      :classmethod:



   .. py:method:: _call_numpy(np_func, *args, **kwargs)
      :classmethod:



   .. py:method:: __array_finalize__(obj)


   .. py:method:: __array_ufunc__(ufunc, method, *inputs, **kwargs)


   .. py:method:: __array_function__(func, types, args, kwargs)


   .. py:method:: __repr__()


   .. py:method:: __str__()


.. py:class:: Units(dims: Optional[Dict[str, int]] = None, factor: float = 1.0)

   Standardized unit expression parser and composer.

   The internal representation tracks:
   - ``dims``: dimension exponents, e.g. {"L": 1, "T": -1} for speed
   - ``factor``: numeric scaling factor to SI base units


   .. py:attribute:: SYMBOLS


   .. py:attribute:: BASE_SYMBOLS


   .. py:attribute:: dims


   .. py:attribute:: factor


   .. py:method:: scalar() -> Units
      :classmethod:



   .. py:method:: parse(unit_str: Optional[str]) -> Optional[Units]
      :classmethod:



   .. py:method:: standardize(unit_str: Optional[str]) -> Optional[str]
      :classmethod:



   .. py:method:: compatible(other: Units) -> bool


   .. py:method:: conversion_scale_to(target: Units) -> float


   .. py:method:: multiply(other: Units) -> Units


   .. py:method:: divide(other: Units) -> Units


   .. py:method:: power(exponent: int) -> Units


   .. py:method:: to_unit_string() -> Optional[str]


.. py:function:: resolve_dtype(dtype: Any) -> type | None

   Resolve schema dtype strings into Python types.

   Supports scalar aliases and array types in the form array_<numpy_dtype>,
   e.g. array_float, array_int32, array_float64.


.. py:function:: resolve_array_item_dtype(dtype: Any) -> Any

.. py:function:: normalize_shape(shape: Any) -> tuple[Any, Ellipsis] | None

.. py:function:: istype(value, dtype)

   Helper function to check if a value is of a specified data type, including basic types and iterable types.


.. py:function:: cast_basic_type(value, dtype)

.. py:class:: TableHeader

   Represents the header of a PlestyTable, defining column names and types.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: dtype
      :type:  type | None
      :value: None



   .. py:attribute:: unit
      :type:  str | None
      :value: None



   .. py:attribute:: description
      :type:  str | None
      :value: None



.. py:class:: PlestyTable2D

   A simple 2D table structure that holds a list of 1d PlestyArrays,
   each representing a row/column of the table.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: data
      :type:  list[plestylib.data.array.PlestyArray]


   .. py:attribute:: header
      :type:  list[TableHeader] | None
      :value: None



   .. py:attribute:: description
      :type:  str | None
      :value: None



.. py:class:: PlestyTable3D

   A simple 3D table structure that holds a list of 2d PlestyTables,
   each representing a layer of the table.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: shape
      :type:  tuple[int, int]


   .. py:attribute:: data
      :type:  list[list[plestylib.data.array.PlestyArray]]


   .. py:attribute:: rheader
      :type:  list[TableHeader] | None
      :value: None



   .. py:attribute:: cheader
      :type:  list[TableHeader] | None
      :value: None



   .. py:attribute:: description
      :type:  str | None
      :value: None



   .. py:method:: get_item_at(row: int, col: int) -> plestylib.data.array.PlestyArray

      Get the item at the specified row and column.



