neurotools.spatial.array module

Statistical routines to extract spatial summary statistics from 2D arrays of complex-valued (phase,amplitude) signals.

neurotools.spatial.array.array_average_amplitude(frames)

Computes the average signal amplitude envelope over multi-electrode array data. Assumes first two dimensions are (x,y) spatial dimensions.

Parameters:

frames (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

The average absolute magnitude over the first two axes

Return type:

np.array

neurotools.spatial.array.array_kuramoto(frames)

Computes the Kuramoto order parameter over 2D multi-electrode array given complex-valued analytic signals. Assumes first two dimensions are (x,y) spatial dimensions.

Parameters:

frames (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

The Kuramotor order parameter over the first two axes

Return type:

np.array

neurotools.spatial.array.array_synchrony(frames)

Computes the average phase syncrony over 2D multi-electrode array given complex-valued analytic signals. Assumes first two dimensions are (x,y) spatial dimensions.

Parameters:

frames (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

The average phase syncrony over the first two axes

Return type:

np.array

neurotools.spatial.array.array_kuramoto_standard_deviation(frames)

Computes the Kuramoto order parameter, transformed to units of radians over 2D multi-electrode array given complex-valued analytic signals. Assumes first two dimensions are (x,y) spatial dimensions.

Parameters:

frames (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

The Kuramotor order parameter transformed to units of radians

Return type:

np.array

neurotools.spatial.array.array_synchrony_standard_deviation(frames)

Computes the average phase syncrony, transformed to units of radians over 2D multi-electrode array given complex-valued analytic signals. Assumes first two dimensions are (x,y) spatial dimensions.

Parameters:

frames (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

The average phase syncrony over the first two axes transformed to units of radians

Return type:

np.array

neurotools.spatial.array.array_phase_gradient(frame)

Assumes complex input (analytic signals) Assumes first 2 dimensions are array dimensions Remaining dimensions can be arbitrary first dimention is Y second is X ( row major ordering )

The differentiation kernel is [1 -1; 1 -1]/2, exept at the boundaries.

The returned phase gradients are two-dimensional, and encoded as a complex number (in analogy to the analytic signal). The gradient along the first dimension (x) is encoded in the real part, and the gradient along the second dimension (y) is encoded in the imaginary part.

Parameters:

frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

Arra phase gradients encoded as complex numbers

Return type:

np.array

neurotools.spatial.array.array_count_centers(data, upsample=3, cut=True, cutoff=0.4, electrode_spacing=0.4)

Counting centers – looks for channels around which phase skips +-np.pi

Parameters:

• data (np.array) – Data should be sent in a 3-dimensional np.array of complex analytic signals, where the first two dimensions are the (x,y) spatial dimensions of the multi-electrode array.

• upsample (int, default is 3) – Upsampling factor for interpolating between electrodes

• cut (bool, default is True) – Whether to apply a spatial frequency cutoff.

• cutoff (float, default is 0.4) – Spatial scale cutoff for analysis, in mm

• electrode_spacing (float, default 0.4) – Spacing between electrodes in array in mm. Default is 0.4mm for the Utah arrays

Returns:

• nclockwise (np.array) – number of clockwise centers found at each time point

• nanticlockwise (np.array) – number of anticlockwise centers found at each time point

neurotools.spatial.array.array_count_critical(data, upsample=3, cut=True, cutoff=0.4, electrode_spacing=0.4)

Count critical points in the phase gradient map

Parameters:

• data (np.array) – Data should be sent in a 3-dimensional np.array of complex analytic signals, where the first two dimensions are the (x,y) spatial dimensions of the multi-electrode array.

• upsample (int, default is 3) – Upsampling factor for interpolating between electrodes

• cut (bool, default is True) – Whether to apply a spatial frequency cutoff.

• cutoff (float, default is 0.4) – Spatial scale cutoff for analysis.

• electrode_spacing (float, default 0.4) – Spacing between electrodes in array in mm. Default is 0.4mm for the Utah arrays

Returns:

• nclockwise (np.array) – number of clockwise centers found at each time point

• nanticlockwise (np.array) – number of anticlockwise centers found at each time point

• nsaddles (np.array) – number of saddle points

• nmaxima (np.array) – number of local maxima

• nminima (np.array) – number of local minima

neurotools.spatial.array.array_phasegradient_local(frame, electrode_spacing=0.4)

The average local gradient magnitude provides an upper bound on spatial frequency ( lower bound on wavelength ).

Parameters:

• frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

• electrode_spacing (float, default 0.4) – Spacing between electrodes in array in mm. Default is 0.4mm for the Utah arrays

Returns:

Average phase gradient magniture across array, in cycles/mm

Return type:

np.array

neurotools.spatial.array.array_phasegradient_planar(frame, electrode_spacing=0.4)

The magnitude of the average gradient provides an accurate estimate of plane-wave wavelength even in the presence of noise.

Parameters:

• frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

• electrode_spacing (float, default 0.4) – Spacing between electrodes in array in mm. Default is 0.4mm for the Utah arrays

Returns:

Magnitude of average phase gradient across array, in cycles/mm

Return type:

np.array

neurotools.spatial.array.array_phasegradient_magnitude_sigma(frame)

Assess standard deviation of phase gradient magnitudes

Parameters:

frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

The standard-deviation of the absolute magnitude of the local phase gradient across an array, in cycles/mm

Return type:

np.array

neurotools.spatial.array.array_phasegradient_magnitude_cv(frame)

Coefficient of variation of the magnitudes of the phase gradients

Parameters:

frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

Coefficient of variation of the magnitudes of the phase gradients, in cycles/mm

Return type:

np.array

neurotools.spatial.array.array_phasegradient_pgd_threshold(frame, thresh=0.5, electrode_spacing=0.4)

The magnitude of the average gradient provides an accurate estimate of wavelength even in the presence of noise.

Waves with phase-gradient directionlity below threshold will be removed to reduce the contribution of noise to wavelength estimates.

Parameters:

• frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

• thresh (float, default 0.5) – The minimum phase-gradient directionality measure. Waves with phase-gradient directionlity below threshold will be removed to further reduce the contribution of noise to wavelength estimates.

• electrode_spacing (float, default 0.4) – Spacing between electrodes in array in mm. Default is 0.4mm for the Utah arrays

Returns:

Magnitude of average phase gradient across array, in cycles/mm for every time-point

Return type:

np.array

neurotools.spatial.array.array_wavelength_pgd_threshold(frame, thresh=0.5)

The magnitude of the average gradient provides a very accurate estimate of wavelength even in the presence of noise. We can further restrict analysis to wavelength with a phase-gradient directionality above a certain threshold.

Parameters:

• frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

• thresh (float, default 0.5) – The minimum phase-gradient directionality measure. Waves with phase-gradient directionlity below threshold will be removed to further reduce the contribution of noise to wavelength estimates.

Returns:

wavelength in mm/cycle for wave events above the PGD threshold

Return type:

np.array

neurotools.spatial.array.array_wavelength_local_pgd_threshold(frame, thresh=0.5, electrode_spacing=0.4)

The average phase gradient magnitude can tolerate non-planar waves, but is sensitive to noise. It may be appropriate to combine this method with spatial smoothing to denoise the data, if it is safe to assume a minimum spatial scale for the underlying wave dynamics.

To be conservative, this routine excludes waves with phase-gradient directionality below the provided threshold.

Parameters:

• frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

• thresh (float, default 0.5) – The minimum phase-gradient directionality measure. Waves with phase-gradient directionlity below threshold will be removed to further reduce the contribution of noise to wavelength estimates.

• electrode_spacing (float, default 0.4) – Spacing between electrodes in array in mm. Default is 0.4mm for the Utah arrays

Returns:

wavelength in mm/cycle for wave events above the PGD threshold

Return type:

np.array

neurotools.spatial.array.array_speed_pgd_threshold(frame, thresh=0.5, FS=1000.0)

Calculate an estimated wave speed for waves above the given PGD threshold.

Parameters:

• frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

• thresh (float, default 0.5) – The minimum phase-gradient directionality measure. Waves with phase-gradient directionlity below threshold will be removed to further reduce the contribution of noise to wavelength estimates.

• electrode_spacing (float, default 0.4) – Spacing between electrodes in array in mm. Default is 0.4mm for the Utah arrays

Returns:

speed for plane waves in mm/s

Return type:

np.array

neurotools.spatial.array.array_speed_local(frame, FS=1000.0)

Accuracy can be improved by restricting analysis to waves with high phase-gradient directionality, where the coherent propagation direction between channels allows for more reliable gradient estimates. High signal-to-noise ratio can also mitigate the impact of noise.

Parameters:

• frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

• FS (float, default 1000) – Sampling rate

Returns:

speed for plane waves in mm/s

Return type:

np.array

neurotools.spatial.array.array_wavelength_local(frame)

phase gradients are in units of radians per electrode

Parameters:

frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

wavelengths in mm/cycle

Return type:

np.array

neurotools.spatial.array.array_wavelength_planar(frame)

phase gradients are in units of radians per electrode

Parameters:

frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

wavelengths in mm/cycle

Return type:

np.array

neurotools.spatial.array.array_synchrony_pgd(frame)

The phase gradient directionality measure from Rubinto et al 2009 is abs(mean(pg))/mean(abs(pg))

Parameters:

frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

Phase gradient directionlity measure for each timepoint

Return type:

np.array

neurotools.spatial.array.array_synchrony_pgd_standard_deviation(frame)

The phase gradient directionality measure from Rubinto et al 2009 is abs(mean(pg))/mean(abs(pg)).

This routine applies a nonlinear transformation so that PGD has units of radians, for easier interpretation.

Parameters:

frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

Phase gradient directionality, transformed to have units of radians in analogy to the standard deviation of a circularly wrapped normal distribution.

Return type:

np.array

neurotools.spatial.array.array_kuramoto_pgd(frame)

A directionality index based on the Kuramoto order parameter. Phase gradient magnitude is discarded.

Parameters:

frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

Kuramoto gradient directionlity measure for each timepoint

Return type:

np.array

neurotools.spatial.array.array_kuramoto_pgd_standard_deviation(frame)

A directionality index based on the Kuramoto order parameter. Phase gradient magnitude is discarded.

The resulting order parameter is nonlinearly transformed to have units of radians in analogy to the standard deviation of a circularly wrapped normal distribution.

Parameters:

frame (np.array) – ND numpy array of complex-valued signals with phase and amplitude. Must be at least 2D. The first 2 dimensions are spatial dimensions (x,y).

Returns:

Kuramoto gradient directionlity measure for each timepoint, transformed to units of radians in analogy to the standard deviation of a circularly wrapped normal distribution.

Return type:

np.array

neurotools.spatial.array.trim_array(arrayMap)

Removes any rows or columns from the array map that are empty ( have no channels )

Parameters:

arrayMap (np.array) – Array map of channel locations. -1 marks missing channels

Returns:

Trimmed map: any rows or columns that are entirely -1 are removed.

Return type:

np.array

neurotools.spatial.array.trim_array_as_if(arrayMap, data)

Removes any rows or columns from data if those rows or columns are empty ( have no channels ) in the arrayMap.

This routine is useful for cropping larger arrays down to smaller sizes, to verify that the statistical estimates do not depend on the array size.

Parameters:

• arrayMap (np.array) – Array map of channel locations. -1 marks missing channels

• data (np.array) – A 3-dimensional np.array where the first two dimensions are the (x,y) spatial dimensions of the multi-electrode array.

Returns:

the data array input, with rows or columns removed where arrayMap is missing channels.

Return type:

np.array

neurotools.spatial.array.pack_array_data(data, arrayMap)

Accepts a collection of signals from array channels, as well as an array map containing indecies (1-indexed for backwards compatibility with matlab) into that list of channel data.

This will interpolate missing channels as an average of nearest neighbors.

Parameters:

• data (np.array) – NChannel x Ntimes

• arrayMap (np.array) – array map, 1-indexed, 0 for missing electrodes

Returns:

LxKxNtimes 3D array of the interpolated channel data

Return type:

np.array