Development documentation · 0.2.3 30c2f8ba · Intro examples tested with 0.2.3 · Version details · Known limitations

Types

gwexpy.types - Data type definitions and utilities.

class gwexpy.types.MetaData(**kwargs)

Bases: dict

A dictionary-like container for metadata describing a single data object.

This class serves as the core metadata container for channels, parameters, or matrix rows/columns in GWexpy. It ensures type safety and consistency for crucial physical attributes, particularly the physical unit.

Parameters:

• name (str, optional) – A human-readable name or label (default: “”).

• channel (str or gwpy.detector.Channel, optional) – The data channel associated with this metadata (default: “”).

• unit (str, astropy.units.UnitBase, or pint.Unit, optional) – The physical unit of the data. Automatically converted to an astropy.units.UnitBase instance (default: dimensionless).

• **kwargs – Additional arbitrary metadata key-value pairs.

Variables:

• name (str) – The human-readable name.

• channel (gwpy.detector.Channel) – The associated data channel.

• unit (astropy.units.UnitBase) – The physical unit of the data.

Examples

>>> from gwexpy.types.metadata import MetaData
>>> from astropy import units as u
>>> meta = MetaData(name="strain", channel="H1:STRAIN", unit="m")
>>> meta.unit
Unit("m")
>>> meta.name
'strain'

Notes

When performing arithmetic with MetaData instances (e.g., using NumPy ufuncs), the unit attribute is automatically propagated correctly. For example, multiplying two MetaData objects will result in a new MetaData object with the multiplied units.

as_meta(obj)

Coerce an object into a MetaData instance.

If obj is already a MetaData instance it is returned unchanged. Otherwise an independent MetaData copy retains every field from self and replaces only its unit, inferred from obj via get_unit().

Parameters:

obj (MetaData, astropy.Quantity, numeric, or any object with a .unit) – The object to coerce.

Return type:

MetaData

property channel

Return the channel name of the metadata.

classmethod from_series(series)

Create a MetaData instance from a GWpy Series object.

property name

Return the name of the metadata.

property unit

Return the physical unit of the metadata.

class gwexpy.types.MetaDataDict(entries: dict | list | DataFrame | MetaDataDict | None = None, expected_size: int | None = None, key_prefix: str = 'key')

Bases: OrderedDict[str, MetaData]

Ordered dictionary mapping keys to MetaData instances.

This container enforces that all values are MetaData objects, providing a type-safe collection for row/column metadata in SeriesMatrix and related classes.

property channels: list[Channel]

List of channels from all MetaData entries.

classmethod from_series(collection)

Create a MetaDataCollection from a group of series.

property names: list[str]

List of names from all MetaData entries.

classmethod read(path, **kwargs)

Read a metadata collection from a CSV file.

to_dataframe()

Convert the metadata collection to a pandas DataFrame.

The unit column is serialised as a string so that the DataFrame can be written to CSV and read back without loss of unit information.

property units: list[UnitBase]

List of units from all MetaData entries.

write(path, **kwargs)

Write the metadata collection to a CSV file.

class gwexpy.types.MetaDataMatrix(input_array=None, shape=None, default=None, row_keys=None, col_keys=None)

Bases: ndarray

A matrix container for multiple MetaData instances.

This class extends numpy.ndarray to provide a grid-like view of metadata, supporting vectorized attribute access (names, units, channels).

property channels

Return a matrix of channel names.

fill(value)

Fill the matrix with a single MetaData value.

Parameters:

value (MetaData | dict) – MetaData instance used as-is, or mapping passed once to MetaData(**value).

Notes

Each cell receives an independent MetaData copy to avoid shared references.

classmethod from_array(array2d)

Create a MetaDataMatrix from a 2D array of MetaData objects.

classmethod from_dataframe(df, shape=None)

Create a MetaDataMatrix from a long-format pandas DataFrame.

property names

Return a matrix of metadata names.

classmethod read(filepath, **kwargs)

Read a matrix from a CSV file.

to_dataframe()

Convert the matrix to a long-format pandas DataFrame (row, col, name, etc.).

property units

Return a matrix of physical units.

write(filepath, **kwargs)

Write the matrix to a CSV file.

class gwexpy.types.AxisDescriptor(name: str, index: Quantity)

Bases: object

Describe a named one-dimensional axis and its coordinate values.

property delta: Quantity | None

Return the constant axis spacing when the axis is regular.

iloc_nearest(value)

Return the integer index nearest to value.

iloc_slice(s: slice)

Convert a coordinate slice (start, stop, step) to an integer slice.

Coordinate start and stop bounds require an ascending axis because they are resolved with numpy.searchsorted(). Descending and unordered axes remain valid for iloc_nearest().

property regular: bool

Return whether the axis has regular linear spacing.

Integer coordinates are compared exactly. Other numeric coordinates have adjacent intervals compared with a relative tolerance of 2.5e-14 and an absolute tolerance of one ULP at the largest represented interval magnitude. This keeps delta consistent with every represented interval while allowing bounded accumulated floating-point round-off.

Logarithmic (equal-ratio) axes are not regular under this linear-spacing contract.

property size

Return the number of axis samples.

to_value(q)

Convert Quantity to axis unit value, or return float if dimensionless/compatible.

property unit

Return the axis unit.

name: str

index: Quantity

class gwexpy.types.AxisApiMixin

Bases: ABC

Mixin that exposes axis-aware selection and permutation helpers.

property T

Return the transposed view using reversed axis order.

abstract property axes: tuple[AxisDescriptor, ...]

Tuple of AxisDescriptor objects for each dimension.

Returns:

Each descriptor contains the axis name and index values.

Return type:

tuple of AxisDescriptor

axis(key: int | str) → AxisDescriptor

Get an axis descriptor by index or name.

Parameters:

key (int or str) – Axis index (0-based) or name.

Returns:

The requested axis descriptor.

Return type:

AxisDescriptor

Raises:

• KeyError – If axis name not found.

• TypeError – If key is not int or str.

property axis_names: tuple[str, ...]

Names of all axes as a tuple of strings.

Returns:

The name of each axis in order.

Return type:

tuple of str

isel(indexers=None, **kwargs)

Select by integer indices along specified axes.

Parameters:

• indexers (dict, optional) – Mapping of axis name/index to integer index or slice.

• **kwargs – Additional indexers as keyword arguments.

Returns:

Sliced array.

Return type:

subset

rename_axes(mapping: dict[str, str], *, inplace: bool = False) → Any

Rename axes using a mapping of old names to new names.

Parameters:

• mapping (dict) – Mapping from old axis names to new names.

• inplace (bool, optional) – If True, modify in place. Otherwise return a copy.

Return type:

self or copy

sel(indexers=None, *, method='nearest', **kwargs)

Select by coordinate values along specified axes.

Parameters:

• indexers (dict, optional) – Mapping of axis name to coordinate value or slice.

• method (str, optional) – Selection method: ‘nearest’ (default).

• **kwargs – Additional indexers as keyword arguments.

Returns:

Sliced array at nearest coordinate values.

Return type:

subset

swapaxes(axis1: int | str, axis2: int | str) → Any

Swap two axes by index or name.

transpose(*axes)

Permute the dimensions of an array.

class gwexpy.types.Array(value, *, unit=None, name=None, epoch=None, channel=None, dtype=None, copy=True, subok=True, order=None, ndmin=0, axis_names=None)

Bases: AxisApiMixin, StatisticalMethodsMixin, Array

N-dimensional array with a unified axis API.

property axes

Return axis descriptors for each dimension.

rms(axis=None, keepdims=False, ignore_nan=True)

Return the RMS value along the requested axis.

class gwexpy.types.Array2D(data, unit=None, x0=None, dx=None, xindex=None, xunit=None, y0=None, dy=None, yindex=None, yunit=None, *, axis_names=None, **kwargs)

Bases: AxisApiMixin, StatisticalMethodsMixin, Array2D

2D array with a unified axis API.

property T

Return the GWpy two-dimensional transpose with swapped axes.

property axes

Return axis descriptors for both dimensions.

imshow(**kwargs)

Plot this array with matplotlib.axes.Axes.imshow.

Inherited from GWpy.

pcolormesh(**kwargs)

Plot this array with matplotlib.axes.Axes.pcolormesh.

Inherited from GWpy.

swapaxes(axis1, axis2)

Swap axes, preserving GWpy metadata on numeric calls.

transpose(*axes)

Transpose through GWpy unless a named-axis extension is used.

class gwexpy.types.Plane2D(data, unit=None, x0=None, dx=None, xindex=None, xunit=None, y0=None, dy=None, yindex=None, yunit=None, *, axis1_name: str = 'axis1', axis2_name: str = 'axis2', axis_names=None, **kwargs)

Bases: FittingMixin, Array2D

Two-dimensional array with explicit semantic names for each axis.

Plane2D is used by field and transform APIs when a derived slice should keep human-readable axis meaning instead of anonymous array dimensions.

Examples

>>> import numpy as np
>>> from gwexpy.types import Plane2D
>>> plane = Plane2D(np.ones((2, 3)), axis1_name="time", axis2_name="frequency")
>>> plane.axis1.name, plane.axis2.name
('time', 'frequency')

property axis1

First axis descriptor (dimension 0).

property axis2

Second axis descriptor (dimension 1).

class gwexpy.types.Array3D(value, *, unit=None, name=None, epoch=None, channel=None, dtype=None, copy=True, subok=True, order=None, ndmin=0, axis0=None, axis1=None, axis2=None, axis_names=None)

Bases: Array

3D array with explicit axis management.

property axes

Return axis descriptors for all three dimensions.

plane(drop_axis, drop_index, *, axis1=None, axis2=None)

Extract a 2D plane by dropping one axis at a single index.

class gwexpy.types.Array4D(value, *, unit=None, name=None, epoch=None, channel=None, dtype=None, copy=True, subok=True, order=None, ndmin=0, axis0=None, axis1=None, axis2=None, axis3=None, axis_names=None)

Bases: Array

4D Array with explicit axis management.

This class extends Array to provide explicit management of 4 axes, each with a name and index (Quantity array).

Parameters:

• data (array-like) – 4-dimensional input data.

• unit (~astropy.units.Unit, optional) – Physical unit of the data.

• axis0 (~astropy.units.Quantity or array-like, optional) – Index values for axis 0 (1D).

• axis1 (~astropy.units.Quantity or array-like, optional) – Index values for axis 1 (1D).

• axis2 (~astropy.units.Quantity or array-like, optional) – Index values for axis 2 (1D).

• axis3 (~astropy.units.Quantity or array-like, optional) – Index values for axis 3 (1D).

• axis_names (iterable of str, optional) – Names for each axis (length 4). Defaults to ["axis0", "axis1", "axis2", "axis3"].

• **kwargs – Additional keyword arguments passed to Array.

Raises:

ValueError – If the input data is not 4-dimensional.

property axes

Tuple of AxisDescriptor objects for each dimension.

class gwexpy.types.MetaDataLike(*args, **kwargs)

Bases: Protocol

Protocol for single-object metadata containers.

This represents objects that carry name, channel, and unit information for a single data series or field component.

name: str

channel: Any

unit: UnitBase

class gwexpy.types.MetaDataDictLike(*args, **kwargs)

Bases: Protocol

Protocol for ordered collections of metadata.

This represents dict-like containers mapping keys to MetaData objects, used for row/column metadata in SeriesMatrix.

items() → Any

Return (key, MetaData) pairs.

keys() → Any

Return keys of the metadata collection.

values() → Any

Return MetaData instances.