cedalion.dataclasses.accessors

Accessors for Cedalion data types.

Classes

`CedalionAccessor`(xarray_obj)	Accessor for time series data stored in xarray DataArrays.
`PointsAccessor`(xarray_obj)	Accessor for `LabeledPoints` DataArrays.
`SMCallableWrapper`(accessor, attr_name)	Wraps a callable attribute of a statsmodels result object.
`StatsModelsAccessor`(array)	Accessor for DataArrays containing statsmodel results.
`StimAccessor`(pandas_obj)	Accessor for stimulus DataFrames.

class cedalion.dataclasses.accessors.CedalionAccessor(xarray_obj)[source]

Bases: object

Accessor for time series data stored in xarray DataArrays.

property sampling_rate[source]

Return the sampling rate of the time series.

The sampling rate is calculated as the reciprocal of the mean time difference: between consecutive samples.

to_epochs( df_stim: pd.DataFrame, trial_types: list[str], before: cdt.QTime, after: cdt.QTime, )[source]

Extract epochs from the time series based on stimulus events.

Parameters:

df_stim – DataFrame containing stimulus events.
trial_types – List of trial types to include in the epochs.
before – Time before stimulus event to include in epoch.
after – Time after stimulus event to include in epoch.

Returns:

Array containing the extracted epochs.

Return type:

xarray.DataArray

freq_filter(fmin, fmax, butter_order=4)[source]

Apply a Butterworth bandpass filter.

Parameters:

fmin (float) – The lower cutoff frequency.
fmax (float) – The upper cutoff frequency.
butter_order (int) – The order of the Butterworth filter.

Returns:

The filtered time series.

Return type:

result (xarray.DataArray)

class cedalion.dataclasses.accessors.PointsAccessor(xarray_obj)[source]

Bases: object

Accessor for LabeledPoints DataArrays.

Attached as the .points attribute on any DataArray that carries a "label" dimension and coordinate (i.e. a labeled point cloud such as geo3d or geo2d).

to_homogeneous()[source]

Return the point cloud augmented with a homogeneous coordinate of 1.

Appends a column of ones so that affine transforms can be applied with a single matrix multiplication. Units are preserved.

Returns:: LabeledPoints DataArray with shape (n_points, n_coords + 1).

rename(translations: Dict[str, str])[source]

Rename point labels according to a translation dictionary.

Parameters:: translations – Mapping from old label strings to new label strings. Labels not present in the mapping are kept unchanged.
Returns:: LabeledPoints DataArray with updated "label" coordinate.

common_labels( other: DataArray, ) → List[str][source]

Return labels present in both this and other LabeledPoints arrays.

Parameters:: other – Second LabeledPoints DataArray. Must have a "label" dimension and coordinate.
Returns:: Sorted list of label strings shared by both point clouds.

apply_transform(transform: cdt.AffineTransform | np.ndarray)[source]

Apply an affine transform to this point cloud.

Accepts either a cedalion AffineTransform (a 4×4 xr.DataArray with CRS-named dimensions and pint units) or a plain 4×4 numpy.ndarray.

Parameters:

transform – 4×4 affine transformation. If an xr.DataArray, the source CRS must match the current CRS of the point cloud.

Returns:

Transformed LabeledPoints DataArray in the new coordinate system.

Raises:

CRSMismatchError – If a DataArray transform’s source CRS does not match the current point cloud CRS.
ValueError – If transform is not a DataArray or ndarray.

property crs[source]

Name of the coordinate reference system dimension (the non-label dim).

Returns:: String name of the spatial dimension, e.g. "pos", "ras".

set_crs(value: str)[source]

Return a copy of this point cloud with the CRS dimension renamed.

Parameters:: value – New name for the spatial dimension.
Returns:: LabeledPoints DataArray with the CRS dimension renamed to value.

add( label: str | List[str], coordinates: ArrayLike, type: PointType | List[PointType], group: str | List[str] = None, ) → cdt.LabeledPoints[source]

Append one or more points to this point cloud.

Parameters:

label – Label string (single point) or list of label strings.
coordinates – Coordinates of the new point(s). Shape (3,) for a single point or (n, 3) for multiple points.
type – PointType (single point) or list thereof for multiple points.
group – Optional group string or list of group strings.

Returns:

New LabeledPoints DataArray with the added point(s) concatenated.

Raises:

KeyError – If a label already exists in the point cloud.

remove(label)[source]

class cedalion.dataclasses.accessors.StimAccessor(pandas_obj)[source]

Bases: object

Accessor for stimulus DataFrames.

rename_events(rename_dict)[source]

Renames trial types in the DataFrame based on the provided dictionary.

Parameters:: rename_dict (dict) – A dictionary with the old trial type as key and the new trial type as value.

conditions()[source]

Return the unique trial-type labels in the stimulus DataFrame.

Returns:: Array of unique trial-type strings.

to_xarray(time: DataArray)[source]

class cedalion.dataclasses.accessors.SMCallableWrapper(accessor, attr_name)[source]

Bases: object

Wraps a callable attribute of a statsmodels result object.

When StatsModelsAccessor resolves a callable attribute (e.g. summary()), it returns one of these wrappers. Calling the wrapper applies the method to every element in the 2-D array of result objects and collects the outputs into an xr.DataArray.

class cedalion.dataclasses.accessors.StatsModelsAccessor(array: DataArray)[source]

Bases: object

Accessor for DataArrays containing statsmodel results.

map(func: Callable, name: str = 'map')[source]

Applies a callable to each object in the array and returns a xr.DataArray.

Parameters:

func – a Callable that expects one argument, the object
name – used to name dimensions in the result array

Returns:

an xr.DataArray whose first to dimensions match our array and that holds in each cell the result of the function call.

regressor_variances()[source]

Return the variance of each regressor coefficient across all models.

Extracts the diagonal of the covariance matrix of parameter estimates for each model in the array.

Returns:: DataArray with the same first two dims as the results array plus a "regressor" dimension.
Raises:: NotImplementedError – If the underlying result objects are ContrastResults (which carry no parameter estimates).

t_values()[source]

Returns the t-values from each model result as a DataArray.

Returns:: An xarray.DataArray containing the t-values from each model result.

p_values()[source]

Return the p-values from each hypothesis test in the result objects.

Returns:: DataArray with the same first two dims as the results array plus a "hypothesis" dimension containing the p-values.
Raises:: NotImplementedError – If the result objects do not expose a pvalue attribute.