Types

Stability: Stable

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.

name

The human-readable name.

Type:

str

channel

The associated data channel.

Type:

gwpy.detector.Channel

unit

The physical unit of the data.

Type:

astropy.units.UnitBase

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.

property name

Return the name of the metadata.

property channel

Return the channel name of the metadata.

property unit

Return the physical unit of the metadata.

classmethod from_series(series)

Create a MetaData instance from a GWpy Series object.

as_meta(obj)

Coerce an object into a MetaData instance.

If obj is already a MetaData instance it is returned unchanged. Otherwise a new MetaData is constructed whose name and channel are inherited from self and whose unit is 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

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 names: list[str]

List of names from all MetaData entries.

property channels: list[Channel]

List of channels from all MetaData entries.

property units: list[UnitBase]

List of units from all MetaData entries.

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.

write(path, **kwargs)

Write the metadata collection to a CSV file.

classmethod read(path, **kwargs)

Read a metadata collection from a CSV file.

classmethod from_series(collection)

Create a MetaDataCollection from a group of series.

class gwexpy.types.MetaDataMatrix(input_array=None, shape=None, default=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).

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.

property names

Return a matrix of metadata names.

property units

Return a matrix of physical units.

property channels

Return a matrix of channel names.

classmethod from_array(array2d)

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

to_dataframe()

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

classmethod from_dataframe(df, shape=None)

Create a MetaDataMatrix from a long-format pandas DataFrame.

write(filepath, **kwargs)

Write the matrix to a CSV file.

classmethod read(filepath, **kwargs)

Read a matrix from a CSV file.

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

Bases: object

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

name: str

index: Quantity

property unit

Return the axis unit.

property size

Return the number of axis samples.

property regular: bool

Return whether the axis spacing is regular.

property delta: Quantity | None

Return the constant axis spacing when the axis is regular.

to_value(q)

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

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.

class gwexpy.types.AxisApiMixin

Bases: ABC

Mixin that exposes axis-aware selection and permutation helpers.

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

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

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.

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

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

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.

property T

Return the transposed view using reversed axis order.

class gwexpy.types.Array(data, axis_names=None, **kwargs)

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, axis_names=None, **kwargs)

Bases: AxisApiMixin, StatisticalMethodsMixin, Array2D

2D array with a unified axis API.

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.

class gwexpy.types.Plane2D(data, axis1_name: str = 'axis1', axis2_name: str = 'axis2', **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(data, unit=None, axis0=None, axis1=None, axis2=None, axis_names=None, **kwargs)

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(data, unit=None, axis0=None, axis1=None, axis2=None, axis3=None, axis_names=None, **kwargs)

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.

keys() → Any

Return keys of the metadata collection.

values() → Any

Return MetaData instances.

items() → Any

Return (key, MetaData) pairs.