Skip to content

Utility classes and functions

Add some preamble about what's in this module...

ephysiopy.common.utils.BinnedData(variable: VariableToBin, map_type: MapType, binned_data: list[np.ma.MaskedArray], bin_edges: list[np.ndarray], cluster_id: list[ClusterID] = [ClusterID(0, 0)]) dataclass

A dataclass to store binned data. The binned data is stored in a list of numpy arrays. The bin edges are stored in a list of numpy arrays. The variable to bin is stored as an instance of the VariableToBin enum. The map type is stored as an instance of the MapType enum. The binned data and bin edges are initialized as empty lists. bin_units is how to conver the binned data to "real" units e.g. for XY it might be how to convert to cms, for time to seconds etc. You multiply the binned data by that number to get the real values. Note that this might not make sense / be obvious for some binning (i.e. SPEED_DIR)

The BinnedData class is the output of the main binning function in the ephysiopy.common.binning.RateMap class. It is used to store the binned data as a convenience mostly for easily iterating over the binned data and using the bin_edges to plot the data. As such, it is used as a convenience for plotting as the bin edges are used when calling pcolormesh in the plotting functions.

Methods:

Name Description
get_cluster

Returns the binned data for the specified cluster id

correlate

This method is used to correlate the binned data of this BinnedData

get_cluster(id: ClusterID)

Returns the binned data for the specified cluster id

Parameters:

Name Type Description Default
id ClusterID

The cluster id to return

required

Returns:

Type Description
BinnedData

A new BinnedData instance with the binned data for the specified cluster id

correlate(other=None, as_matrix=False) -> np.ndarray

This method is used to correlate the binned data of this BinnedData instance with the binned data of another BinnedData instance.

Parameters:

Name Type Description Default
other BinnedData

The other BinnedData instance to correlate with. If None, then correlations are performed between all the data held in the list self.binned_data

None
as_matrix bool

If True will return the full correlation matrix for all of the correlations in the list of data in self.binned_data. If False, a list of the unique correlations for the comparisons in self.binned_data are returned.

False

Returns:

Type Description
ndarray

The result of the correlations

ephysiopy.common.utils.TrialFilter(name: str, start: float | str, end: float | str = None) dataclass

A basic dataclass for holding filter values

Notes

Units: time: seconds dir: degrees speed: cm/s x/ x: cm

name : str The name of the filter type start : float, str start value of filter end : float, str end value of filter

ephysiopy.common.utils.VariableToBin

Bases: Enum

Holds a human readable representation of the variable being binned

Attributes:

Name Type Description
XY
DIR
SPEED
XY_TIME
SPEED_DIR
EGO_BOUNDARY
TIME
X
Y
PHI

XY = 1 class-attribute instance-attribute

DIR = 2 class-attribute instance-attribute

SPEED = 3 class-attribute instance-attribute

XY_TIME = 4 class-attribute instance-attribute

SPEED_DIR = 5 class-attribute instance-attribute

EGO_BOUNDARY = 6 class-attribute instance-attribute

TIME = 7 class-attribute instance-attribute

X = 8 class-attribute instance-attribute

Y = 9 class-attribute instance-attribute

PHI = 10 class-attribute instance-attribute

ephysiopy.common.utils.MapType

Bases: Enum

A human readable representation of the map type

Attributes:

Name Type Description
RATE
POS
SPK
ADAPTIVE
AUTO_CORR
CROSS_CORR

RATE = 1 class-attribute instance-attribute

POS = 2 class-attribute instance-attribute

SPK = 3 class-attribute instance-attribute

ADAPTIVE = 4 class-attribute instance-attribute

AUTO_CORR = 5 class-attribute instance-attribute

CROSS_CORR = 6 class-attribute instance-attribute

ephysiopy.common.utils.ClusterID = namedtuple('ClusterID', ['Cluster', 'Channel']) module-attribute

Miscellaneous functions

ephysiopy.common.utils.get_z_score(x: np.ndarray, mean=None, sd=None, axis: int = 0) -> np.ndarray

Calculate the z-scores for array x based on the mean and standard deviation in that sample, unless stated

Parameters:

Name Type Description Default
x ndarray

The array to z-score

required
mean float

The mean of x. Calculated from x if not provided

None
sd float

The standard deviation of x. Calculated from x if not provided

None
axis int

The axis along which to operate

0

Returns:

Type Description
ndarray

The z-scored version of the input array x

ephysiopy.common.utils.filter_trial_by_time(duration: int | float, how: str = 'in_half') -> tuple[list[TrialFilter], ...]

Filters the data in trial by time

Parameters:

Name Type Description Default
duration int | float
required
how str
    Legal values: "in_half" or "odd_even"
    "in_half" filters for first n seconds and last n second
    "odd_even" filters for odd vs even minutes
'in_half'

Returns:

Type Description
tuple of TrialFilter

A tuple of TrialFilter instances, one for each half or odd/even minutes

ephysiopy.common.utils.mean_norm(x: np.ndarray, mn=None, axis: int = 0) -> np.ndarray

Mean normalise an input array

Parameters:

Name Type Description Default
x ndarray

The array t normalise

required
mn float

The mean of x

None
axis int

The axis along which to operate

0

Returns:

Type Description
ndarray

The mean normalised version of the input array

ephysiopy.common.utils.min_max_norm(x: np.ndarray, min=None, max=None, axis: int = 0) -> np.ndarray

Normalise the input array x to lie between min and max

Parameters:

Name Type Description Default
x ndarray

the array to normalise

required
min float

the minimun value in the returned array

None
max float

the maximum value in the returned array

None
axis int

the axis along which to operate. Default 0

0

Returns:

Type Description
ndarray

the normalised array

ephysiopy.common.utils.remap_to_range(x: np.ndarray, new_min=0, new_max=1, axis=0) -> np.ndarray

Remap the values of x to the range [new_min, new_max].

Parameters:

Name Type Description Default
x ndarray

the array to remap

required
new_min float

the minimun value in the returned array

0
new_max float

the maximum value in the returned array

1

Returns:

Type Description
ndarray

The remapped values

ephysiopy.common.utils.flatten_list(list_to_flatten: list) -> list

Flattens a list of lists

Parameters:

Name Type Description Default
list_to_flatten list

the list to flatten

required

Returns:

Type Description
list

The flattened list

ephysiopy.common.utils.smooth(x, window_len=9, window='hanning')

Smooth the data using a window with requested size.

This method is based on the convolution of a scaled window with the signal. The signal is prepared by introducing reflected copies of the signal (with the window size) in both ends so that transient parts are minimized in the beginning and end part of the output signal.

Parameters:

Name Type Description Default
x ndarray

The input signal.

required
window_len int

The length of the smoothing window.

9
window str

The type of window from 'flat', 'hanning', 'hamming', 'bartlett', 'blackman'. 'flat' window will produce a moving average smoothing.

'hanning'

Returns:

Type Description
ndarray

The smoothed signal.

Examples:

>>> t=linspace(-2,2,0.1)
>>> x=sin(t)+randn(len(t))*0.1
>>> y=smooth(x)
See Also

numpy.hanning, numpy.hamming, numpy.bartlett, numpy.blackman, numpy.convolve, scipy.signal.lfilter

Notes

The window parameter could be the window itself if an array instead of a string.

ephysiopy.common.utils.blur_image(im: BinnedData, n: int, ny: int = 0, ftype: str = 'boxcar', **kwargs) -> BinnedData

Smooths all the binned_data in an instance of BinnedData by convolving with a filter.

Parameters:

Name Type Description Default
im BinnedData

Contains the array to smooth.

required
n int

The size of the smoothing kernel.

required
ny int

The size of the smoothing kernel.

required
ftype str

The type of smoothing kernel. Either 'boxcar' or 'gaussian'.

'boxcar'

Returns:

Type Description
BinnedData

BinnedData instance with the smoothed data.

Notes

This essentially does the smoothing in-place

ephysiopy.common.utils.shift_vector(v, shift, maxlen=None)

Shifts the elements of a vector by a given amount. A bit like numpys roll function but when the shift goes beyond some limit that limit is subtracted from the shift. The result is then sorted and returned.

Parameters:

Name Type Description Default
v array_like

The input vector.

required
shift int

The amount to shift the elements.

required

Returns:

Type Description
ndarray

The shifted vector.

ephysiopy.common.utils.count_to(n: np.ndarray) -> np.ndarray

This function is equivalent to hstack((arange(n_i) for n_i in n)). It seems to be faster for some possible inputs and encapsulates a task in a function.

Examples:

>>> n = np.array([0, 0, 3, 0, 0, 2, 0, 2, 1])
>>> count_to(n)
array([0, 1, 2, 0, 1, 0, 1, 0])

ephysiopy.common.utils.window_rms(a: np.ndarray, window_size: int | float) -> np.ndarray

Calculates the root mean square of the input a over a window of size window_size

Parameters:

Name Type Description Default
a ndarray

The input array

required
window_size (int, float)

The size of the smoothing window

required

Returns:

Type Description
ndarray

The rms'd result

ephysiopy.common.utils.find_runs(x)

Find runs of consecutive items in an array.

Parameters:

Name Type Description Default
x (ndarray, list)

The array to search for runs in

required

Returns:

Name Type Description
run_values ndarray

the values of each run

run_starts ndarray

the indices into x at which each run starts

run_lengths ndarray

The length of each run

Examples:

>>> n = np.array([0, 0, 3, 3, 0, 2, 0,0, 1])
>>> find_runs(n)
(array([0, 3, 0, 2, 0, 1]),
array([0, 2, 4, 5, 6, 8]),
array([2, 2, 1, 1, 2, 1]))
Notes

Taken from: https://gist.github.com/alimanfoo/c5977e87111abe8127453b21204c1065

ephysiopy.common.utils.repeat_ind(n: np.ndarray) -> np.ndarray

Repeat a given index a specified number of times.

The input specifies how many times to repeat the given index. It is equivalent to something like this:

hstack((zeros(n_i,dtype=int)+i for i, n_i in enumerate(n)))

But this version seems to be faster, and probably scales better. At any rate, it encapsulates a task in a function.

Parameters:

Name Type Description Default
n ndarray

A 1D array where each element specifies the number of times to repeat its index.

required

Returns:

Type Description
ndarray

A 1D array with indices repeated according to the input array.

Examples:

>>> n = np.array([0, 0, 3, 0, 0, 2, 0, 2, 1])
>>> repeat_ind(n)
array([2, 2, 2, 5, 5, 7, 7, 8])

ephysiopy.common.utils.rect(r, w, deg=False)

Convert from polar (r, w) to rectangular (x, y) coordinates.

Parameters:

Name Type Description Default
r float or ndarray

Radial coordinate(s).

required
w float or ndarray

Angular coordinate(s).

required
deg bool

If True, w is in degrees. Default is False (radians).

False

Returns:

Type Description
tuple

A tuple containing: - x : float or np.ndarray X coordinate(s). - y : float or np.ndarray Y coordinate(s).

ephysiopy.common.utils.polar(x, y, deg=False)

Converts from rectangular coordinates to polar ones.

Parameters:

Name Type Description Default
x array_like

The x coordinates.

required
y array_like

The y coordinates.

required
deg bool

If True, returns the angle in degrees. Default is False (radians).

False

Returns:

Name Type Description
r array_like

The radial coordinates.

theta array_like

The angular coordinates.

ephysiopy.common.utils.labelledCumSum(X, L)

Compute the cumulative sum of an array with labels, resetting the sum at label changes.

Parameters:

Name Type Description Default
X ndarray

Input array to compute the cumulative sum.

required
L ndarray

Label array indicating where to reset the cumulative sum.

required

Returns:

Type Description
MaskedArray

The cumulative sum array with resets at label changes, masked appropriately.

ephysiopy.common.utils.cart2pol(x, y)

Convert Cartesian coordinates to polar coordinates.

Parameters:

Name Type Description Default
x float or ndarray

X coordinate(s).

required
y float or ndarray

Y coordinate(s).

required

Returns:

Name Type Description
r float or ndarray

Radial coordinate(s).

th float or ndarray

Angular coordinate(s) in radians.

ephysiopy.common.utils.pol2cart(r, theta)

Convert polar coordinates to Cartesian coordinates.

Parameters:

Name Type Description Default
r float or ndarray

Radial coordinate(s).

required
theta float or ndarray

Angular coordinate(s) in radians.

required

Returns:

Name Type Description
x float or ndarray

X coordinate(s).

y float or ndarray

Y coordinate(s).

ephysiopy.common.utils.applyFilter2Labels(M, x)

M is a logical mask specifying which label numbers to keep x is an array of positive integer labels

This method sets the undesired labels to 0 and renumbers the remaining labels 1 to n when n is the number of trues in M

ephysiopy.common.utils.getLabelStarts(x)

Get the indices of the start of contiguous runs of non-zero values in a 1D numpy array.

Parameters:

Name Type Description Default
x ndarray

The input 1D numpy array.

required

Returns:

Type Description
ndarray

An array of indices marking the start of each contiguous run of non-zero values.

ephysiopy.common.utils.getLabelEnds(x)

Get the indices of the end of contiguous runs of non-zero values in a 1D numpy array.

Parameters:

Name Type Description Default
x ndarray

The input 1D numpy array.

required

Returns:

Type Description
ndarray

An array of indices marking the end of each contiguous run of non-zero values.

ephysiopy.common.utils.circ_abs(x)

Calculate the absolute value of an angle in radians, normalized to the range [-pi, pi].

Parameters:

Name Type Description Default
x float or ndarray

Angle(s) in radians.

required

Returns:

Type Description
float or ndarray

Absolute value of the angle(s) normalized to the range [-pi, pi].

ephysiopy.common.utils.labelContigNonZeroRuns(x)

Label contiguous non-zero runs in a 1D numpy array.

Parameters:

Name Type Description Default
x ndarray

The input 1D numpy array.

required

Returns:

Type Description
ndarray

An array where each element is labeled with an integer representing the contiguous non-zero run it belongs to.

ephysiopy.common.utils.fixAngle(a)

Ensure angles lie between -pi and pi.

Parameters:

Name Type Description Default
a float or ndarray

Angle(s) in radians.

required

Returns:

Type Description
float or ndarray

Angle(s) normalized to the range [-pi, pi].

ephysiopy.common.utils.bwperim(bw, n=4)

Finds the perimeter of objects in binary images.

A pixel is part of an object perimeter if its value is one and there is at least one zero-valued pixel in its neighborhood.

By default, the neighborhood of a pixel is 4 nearest pixels, but if n is set to 8, the 8 nearest pixels will be considered.

Parameters:

Name Type Description Default
bw array_like

A black-and-white image.

required
n int

Connectivity. Must be 4 or 8. Default is 4.

4

Returns:

Name Type Description
perim array_like

A boolean image.

ephysiopy.common.utils.count_runs_and_unique_numbers(arr: np.ndarray) -> tuple

Counts the number of continuous runs of numbers in a 1D numpy array.

Parameters:

Name Type Description Default
arr ndarray

The input 1D numpy array of numbers.

required

Returns:

Type Description
tuple

A tuple containing: - dict: A dictionary with the count of runs for each unique number. - set: The set of unique numbers in the array.

ephysiopy.common.utils.corr_maps(map1, map2, maptype='normal') -> float

Correlates two rate maps together, ignoring areas that have zero sampling.

Parameters:

Name Type Description Default
map1 ndarray

The first rate map to correlate.

required
map2 ndarray

The second rate map to correlate.

required
maptype str

The type of correlation to perform. Options are "normal" and "grid". Default is "normal".

'normal'

Returns:

Type Description
float

The correlation coefficient between the two rate maps.

Notes

If the shapes of the input maps are different, the smaller map will be resized to match the shape of the larger map using reflection mode.

The "normal" maptype considers non-zero and non-NaN values for correlation, while the "grid" maptype considers only finite values.