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
¶
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
|
|
'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
¶
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
¶
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:
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
¶
ephysiopy.common.utils.window_rms(a: np.ndarray, window_size: int | float) -> np.ndarray
¶
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:
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, |
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)
¶
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)
¶
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.