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

.. py:module:: plestylib.data.array


Classes
-------

.. autoapisummary::

   plestylib.data.array._PlestyArrayMeta
   plestylib.data.array.PlestyArray


Module Contents
---------------

.. py:class:: _PlestyArrayMeta

   Bases: :py:obj:`type`\ (\ :py:obj:`np.ndarray`\ )


   Forward NumPy top-level callables as class methods for PlestyArray.

   Example:

   .. code-block:: python

       PlestyArray.zeros((10, 2), unit="nm")


   .. py:method:: __getattr__(name: str)


.. 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__()


