plestylib.data#

Submodules#

Classes#

`PlestyArray`	Data definition for a numerical array with meta information.
`Units`	Standardized unit expression parser and composer.
`TableHeader`	Represents the header of a PlestyTable, defining column names and types.
`PlestyTable2D`	A simple 2D table structure that holds a list of 1d PlestyArrays,
`PlestyTable3D`	A simple 3D table structure that holds a list of 2d PlestyTables,

Functions#

`resolve_dtype`(→ type \| None)	Resolve schema dtype strings into Python types.
`resolve_array_item_dtype`(→ Any)
`normalize_shape`(→ tuple[Any, Ellipsis] \| None)
`istype`(value, dtype)	Helper function to check if a value is of a specified data type, including basic types and iterable types.
`cast_basic_type`(value, dtype)

Package Contents#

class plestylib.data.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.

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 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"

_META_KEYS#

__array_priority__ = 1000#

update_meta(**kwargs)#

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

_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:

left (PlestyArray)
right (PlestyArray)
op_symbol (str)

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)#

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

__array_function__(func, types, args, kwargs)#

__repr__()#

__str__()#

class plestylib.data.Units(dims: Dict[str, int] | None = 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

Parameters:

dims (Optional[Dict[str, int]])
factor (float)

SYMBOLS#

BASE_SYMBOLS#

dims#

factor#

classmethod scalar() → Units#

Return type:: Units

classmethod parse(unit_str: str | None) → Units | None#

Parameters:: unit_str (Optional[str])
Return type:: Optional[Units]

classmethod standardize(unit_str: str | None) → str | None#

Parameters:: unit_str (Optional[str])
Return type:: Optional[str]

compatible(other: Units) → bool#

Parameters:: other (Units)
Return type:: bool

conversion_scale_to(target: Units) → float#

Parameters:: target (Units)
Return type:: float

multiply(other: Units) → Units#

Parameters:: other (Units)
Return type:: Units

divide(other: Units) → Units#

Parameters:: other (Units)
Return type:: Units

power(exponent: int) → Units#

Parameters:: exponent (int)
Return type:: Units

to_unit_string() → str | None#

Return type:: Optional[str]

plestylib.data.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.

Parameters:: dtype (Any)
Return type:: type | None

plestylib.data.resolve_array_item_dtype(dtype: Any) → Any#

Parameters:: dtype (Any)
Return type:: Any

plestylib.data.normalize_shape(shape: Any) → tuple[Any, Ellipsis] | None#

Parameters:: shape (Any)
Return type:: tuple[Any, Ellipsis] | None

plestylib.data.istype(value, dtype)#: Helper function to check if a value is of a specified data type, including basic types and iterable types.

plestylib.data.cast_basic_type(value, dtype)#

class plestylib.data.TableHeader#

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

name: str#

dtype: type | None = None#

unit: str | None = None#

description: str | None = None#

class plestylib.data.PlestyTable2D#

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

name: str#

data: list[plestylib.data.array.PlestyArray]#

header: list[TableHeader] | None = None#

description: str | None = None#

class plestylib.data.PlestyTable3D#

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

name: str#

shape: tuple[int, int]#

data: list[list[plestylib.data.array.PlestyArray]]#

rheader: list[TableHeader] | None = None#

cheader: list[TableHeader] | None = None#

description: str | None = None#

get_item_at(row: int, col: int) → plestylib.data.array.PlestyArray#

Get the item at the specified row and column.

Parameters:

row (int)
col (int)

Return type:

plestylib.data.array.PlestyArray