plesty.lib.data.array

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

_PlestyArrayMeta

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

PlestyArray

Data definition for a numerical array with meta information.

Module Contents

class plesty.lib.data.array._PlestyArrayMeta

Bases: type(np.ndarray)

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

Example:

PlestyArray.zeros((10, 2), unit="nm")
__getattr__(name: str)
Parameters:

name (str)

class plesty.lib.data.array.PlestyArray(shape, dtype=float, buffer=None, offset=0, strides=None, order=None)

Bases: 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.

Variables:

  • name – Optional name for the data.

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

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

  • unit – Optional unit for the data, e.g., “nm”, “s”, “m/s”, etc.

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

Usage:

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.

_META_KEYS
__array_priority__ = 1000
name: str | None
range: Tuple[float, float] | Tuple[int, int] | None
options: List[Any] | None
unit: str | None
description: str | None
update_meta(**kwargs) → None

Update meta information for the PlestyArray.

Example:

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

None

_meta_kwargs() → Dict[str, Any]
Return type:

Dict[str, Any]

classmethod _find_meta_source(items) → PlestyArray | None
Return type:

Optional[PlestyArray]

static _unit_text(unit: str | None) → str
Parameters:

unit (Optional[str])

Return type:

str

classmethod _build_binary_meta(left: PlestyArray, right: PlestyArray, op_symbol: str) → Dict[str, Any]
Parameters:
Return type:

Dict[str, Any]

classmethod _split_meta_kwargs(kwargs: Dict[str, Any]) → Tuple[Dict[str, Any], Dict[str, Any]]
Parameters:

kwargs (Dict[str, Any])

Return type:

Tuple[Dict[str, Any], Dict[str, Any]]

classmethod _wrap_numpy_result(result: Any, meta_kwargs: Dict[str, Any])
Parameters:

  • result (Any)

  • meta_kwargs (Dict[str, Any])

classmethod _call_numpy(np_func, *args, **kwargs)
__array_finalize__(obj)

Finalize the PlestyArray after creation, copying metadata from source.

__array_ufunc__(ufunc, method, *inputs, **kwargs)

Handle NumPy ufuncs with unit-aware metadata propagation.

__array_function__(func, types, args, kwargs)

Dispatch NumPy functions while preserving PlestyArray metadata.

__repr__()

Return a developer-friendly representation of the PlestyArray.

__str__()

Return a human-readable string representation of the PlestyArray.