plesty.lib.data.array
=====================

.. py:module:: plesty.lib.data.array

.. autoapi-nested-parse::

   Data definitions for Plesty.

   For data from physical experiments, we need to strictly define the meta information
   about the numerical data, such as the unit and the description. This is important for
   the data to be properly interpreted and used in the future.



Classes
-------

.. autoapisummary::

   plesty.lib.data.array._PlestyArrayMeta
   plesty.lib.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.

   :ivar name: Optional name for the data.
   :ivar range: Optional range for the data values, can be a tuple of (min, max).
   :ivar options: Optional list of possible values for the data, if applicable.
   :ivar unit: Optional unit for the data, e.g., "nm", "s", "m/s", etc.
   :ivar description: Optional description for the data, providing more context and information.


   Usage:

   .. code-block:: python

       from plesty.lib.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"

   Create a new PlestyArray instance with optional metadata.


   .. py:attribute:: _META_KEYS


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



   .. py:attribute:: name
      :type:  Optional[str]


   .. py:attribute:: range
      :type:  Optional[Tuple[float, float] | Tuple[int, int]]


   .. py:attribute:: options
      :type:  Optional[List[Any]]


   .. py:attribute:: unit
      :type:  Optional[str]


   .. py:attribute:: description
      :type:  Optional[str]


   .. py:method:: update_meta(**kwargs) -> None

      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)

      Finalize the PlestyArray after creation, copying metadata from source.



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

      Handle NumPy ufuncs with unit-aware metadata propagation.



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

      Dispatch NumPy functions while preserving PlestyArray metadata.



   .. py:method:: __repr__()

      Return a developer-friendly representation of the PlestyArray.



   .. py:method:: __str__()

      Return a human-readable string representation of the PlestyArray.