neurochat.nc_utils module

This module implements utility functions and classes for NeuroChaT software.

@author: Md Nurul Islam; islammn at tcd dot ie

class neurochat.nc_utils.NLog

Bases: logging.Handler

Class for handling log information (messages, errors and warnings).

It formats the incoming message in HTML and sends it to the log interface of NeuroChaT.

emit(record)

Format the incoming record and display it.

Parameters:record – Log record to display or store Returns:None

setup()

Remove all the logging handlers and set up a logger in HTML format.

Parameters:None – Returns:None

class neurochat.nc_utils.RecPos(file_name=None, load=True)

Bases: object

Read .pos file.

Work in progress and does not support head direction.

pos_file

The path to the position file.

Type:str

x

The x position data

Type:np.ndarray

y

The y position data

Type:np.ndarray

speed

The speed in cm/s

Type:np.ndarray

head_direction

The head direction data

Type:np.ndarray

raw_position

The raw position data decoded from .pos file.

Type:dict

Parameters:

• file_name (str) – The path to the .set file or .pos file to load the data from
• load (bool) – If file_name is passed, load the data from this

calculate_angular()

calculate_position(raw=False)

calculate_speed(num_samples=5, smooth_size=5, smooth=False)

Calculate the speed.

Performs as follows: 1. Get the box smoothed position data. 2. Calculate the speed at 10Hz (real sample rate is 50Hz). 2a. Do this calculating the speed at time x by using positions at

time x + 0.1, and x - 0.1. Want the real time point in the middle.

4. Interpolate these values to get speed at every time point(50Hz)
5. Smooth the interpolated speeds to remove bumps around sample times.

filter_max_speed(x, y, max_speed=4)

get_angular_pos()

get_cam_view()

get_pixel_per_metre()

get_position(raw=False)

get_raw_pos()

get_speed()

get_window_view()

load(file_name=None)

Load data, optionally from given file name.

load_raw()

Load raw position data.

set_file(file_name)

Set the input file - can be .pos or .set

class neurochat.nc_utils.Singleton

Bases: object

Create a Singleton object created from a subclass of this class.

static __new__(cls, *arg, **kwarg)

Create a Singleton object created from a subclass of this class.

neurochat.nc_utils.angle_between_points(a, b, c)

Return the angle between the lines ab and bc, <abc.

This function always returns an angle less than 180degrees. The orientation of the lines can be used to determine which side of the lines this angle is formed from.

Returns np.nan if ab and bc are the same point.

Parameters:

• a (ndarray) – The first point
• b (ndarray) – The second point
• c (the last point) –

Returns:

float – The angle in degrees

neurochat.nc_utils.bhatt(X1, X2)

Calculate Bhattacharyya coefficient and distance between distributions.

Parameters:X2 (X1,) – Distributions under consideration Returns:bc, d (float) – Bhattacharyya coefficient and Bhattacharyya distance

neurochat.nc_utils.butter_filter(x, Fs, *args)

Filter using bidirectional zero-phase shift Butterworth filter.

Parameters:

• x (ndarray) – Data or signal to filter
• Fs (Sampling frequency) –
• *kwargs – Arguments with filter paramters

Returns:

ndarray – Filtered signal

neurochat.nc_utils.centre_of_mass(co_ords, weights, axis=0)

Calculate the co-ordinate centre of mass for a 2D system of particles.

The particles all have co-ords and weights.

Parameters:

• co_ords (ndarray) – Array of co-ordinate positions, assumed to have co_ords.shape[axis] co-ordinates.
• weights (ndarray) – Array of corresponding weights
• axis (int, default 0) – The axis along which the co-ordinates are specified, expected 0 or 1

Returns:

ndarray – Co-ordinate of the centre of mass

neurochat.nc_utils.chop_edges(x, xlen, ylen)

Chop the edges of a firing rate map.

They are considered to be the edges if they are not visited at all or with zero firing rate.

Parameters:

• x (ndarray) – Matrix of firing rate
• xlen (int) – Maximum length of the x-axis
• ylen (int) – Maximum length of the y-axis

Returns:

• low_ind (list of int) – Index of low end of valid edges
• hig_end – Index of high end of valid edges
• y (ndarray) – Chopped firing map

neurochat.nc_utils.corr_coeff(x1, x2)

Correlation coefficient between two numeric series or two signals.

Parameters:x2 (x1,) – Input numeric array or signals Returns:float – Correlation coefficient of input arrays

neurochat.nc_utils.distinct_window_rms(a, N)

Calculate the rms of an array in windows of N data points.

Parameters:

• a (np.ndarray) – The input array to compute the RMS of.
• N (int) – The length of the window to compute RMS in.

Returns:

list – The RMS in each window.

neurochat.nc_utils.extrema(x, mincap=None, maxcap=None)

Find the extrema in a numeric array or a signal.

Parameters:

• mincap – Maximum value for the minima
• maxcap – Minimum value for the maxima

Returns:

• xmax (ndarray) – Maxima values
• imax (ndarray) – Maxima indices
• xmin (ndarray) – Minima values
• imin (ndarray) – Minima indices

neurochat.nc_utils.fft_psd(x, Fs, nfft=None, side='one', ptype='psd')

Calculate the Fast Fourier Transform (FFT) of a signal.

Parameters:

• x (ndarray) – Input signal
• Fs – Sampling frequency
• nfft (int) – Number of FFT points
• side (str) – ‘one’-sided or ‘two’-sided FFT
• ptype (str) – Calculates power-spectral density if set to ‘psd’

Returns:

• x_fft (ndarray) – FFT of input
• f (ndarray) – FFt frequency

neurochat.nc_utils.find(X, n=None, direction='all')

Find the non-zero entries of a signal or array.

Parameters:

• X (ndarray or list) – Array or list of numbers whose non-zero entries need to find out
• n (int) – Number of such entries
• direction (str) – If ‘all’, all entries of length n are returned. If ‘first’, first n entries are returned. If ‘last’, last n entries are returned.

Returns:

ndarray – Indices of non-zero entries.

neurochat.nc_utils.find2d(X, n=None)

Find the non-zero entries of a matrix.

Parameters:

• X (ndarray) – Matrix whose non-zero entries need to find out
• n (int) – Number of such entries

Returns:

• ndarray – x-indices of non-zero entries.
• ndarray – y-indices of non-zero entries.

neurochat.nc_utils.find_chunk(x)

Find size and indices of chunks of non-zero segments in an array.

Parameters:x (ndarray) – Inout array whose non-zero chunks are to be explored Returns:

• segsize (ndarray) – Lengths of non-zero chunks
• segind (ndarray) – Indices of non-zero chunks

neurochat.nc_utils.find_peaks(data, **kwargs)

Return the peaks in the data based on gradient calculations.

Parameters:kwargs –

start : int

Where to start looking for peaks in the data, default 0

end : int

Where to stop looking for peaks in the data, default data.size - 1

thresh : float

Don’t consider any peaks with a value below this, default 0

neurochat.nc_utils.find_true_ranges(arr, truth_arr, min_range, return_idxs=False)

Return a list of ranges where truth values occur in sorted array.

Also return the corresponding values from the input array.

Note

The input array arr is assumed to be a sorted list.

Parameters:

• arr (ndarray) – list of values to get ranges from, equal in length to truth_arr
• truth_arr (ndarray) – list of truth values to make the ranges
• min_range (int or float) – the minimum length of range

Returns:

list – A list of tuples, ranges in arr where truth values are truth_arr

neurochat.nc_utils.get_all_files_in_dir(in_dir, ext=None, return_absolute=True, recursive=False, verbose=False, re_filter=None, case_sensitive_ext=False)

Get all files in the directory with the given extension.

Parameters:

• in_dir (str) – The absolute path to the directory
• ext (str, optional. Defaults to None.) – The extension of files to get.
• return_absolute (bool, optional. Defaults to True.) – Whether to return the absolute filename or not.
• recursive (bool, optional. Defaults to False.) – Whether to recurse through directories.
• verbose (bool, optional. Defaults to False.) – Whether to print the files found.
• re_filter (str, optional. Defaults to None) – a regular expression used to filter the results
• case_sensitive_ext (bool, optional. Defaults to False,) – Whether to match the case of the file extension

Returns:

list – A list of filenames

neurochat.nc_utils.get_axona_colours(index=None)

Create Axona cell colours.

Parameters:index (int) – Optional integer to get colours at Returns:list | tuple – A list of colours as rgb tuples with values in 0 to 1. Or a single rgb tuple if index is specified.

neurochat.nc_utils.has_ext(filename, ext, case_sensitive_ext=False)

Check if the filename ends in the extension.

Parameters:

• filename (str) – The name of the file
• ext (str) – The extension, may have leading dot (e.g txt == .txt)
• case_sensitive_ext (bool, optional. Defaults to False,) – Whether to match the case of the file extension

Returns:

bool indicating if the filename has the extension

neurochat.nc_utils.hellinger(X1, X2)

Calculate Hellinger distance between two distributions.

Parameters:X2 (X1,) – Distributions under consideration Returns:d (float) – Calculated Hellinger distance

neurochat.nc_utils.histogram(x, bins)

Calculate the histogram count of input array.

This function is not a replacement of np.histogram; it is created for convenience of binned-based rate calculations and mimicking matlab histc that includes digitized indices

Parameters:

• x (ndarray) – Array whose histogram needs to be calculated
• bins – Number of histogram bins

Returns:

• ndarray – Histogram count
• ndarray – Histogram bins(lowers edges)

neurochat.nc_utils.histogram2d(y, x, ybins, xbins)

Calculate the joint histogram count of two arrays.

This function is not a replacement of np.histogram2d; it is created for convenience of binned-based rate calculations and mimicking matlab histc that includes digitized indices

Parameters:

• x (y,) – Arrays whose histogram needs to be calculated
• ybins – Number of histogram bins in y-axis
• xbins – Number of histogram bins in x-axis

Returns:

• ndarray – Histogram count
• ndarray – Histogram bins in x-axis (lowers edges)
• ndarray – Histogram bins in y-axis (lowers edges)

neurochat.nc_utils.linfit(X, Y, getPartial=False)

Calculate the linear regression coefficients in least-square sense.

Parameters:

• X (ndarray) – Matrix with input variables or factors (num_dim X num_obs)
• Y (ndarray) – Array of oservation data
• getPartial (bool) – Get the partial correlation coefficients if ‘True’

Returns:

_results (dict) – Dictionary with results of least-square optimization of linear regression

neurochat.nc_utils.log_exception(ex, more_info='')

Log an expection and additional info.

Parameters:

• ex (Exception) – The python exception that occured
• more_info (str, optional) – Additional string to log. Default is “”.

Returns:

None

neurochat.nc_utils.make_dir_if_not_exists(location)

Make directory structure for given location.

neurochat.nc_utils.nxl_write(file_name, data_frame, sheet_name='Sheet1', startRow=0, startColumn=0)

Write Pandas DataFrame to excel file, wraps Pandas.ExcelWriter().

Parameters:

• filename (str) – Name of the output file
• data_frame (pandas.DataFrame) – DataFrame to export
• sheet_name (str) – Sheet name of the Excel file where the data is written
• startRow (int) – Which row in the file the data writing should start
• startColumn (int) – Which column in the file the data writing should start

Returns:

None

neurochat.nc_utils.remove_extension(filename, keep_dot=True, return_ext=False)

Return the filename without the extension.

Very similar to os.path.splitext()

Parameters:

• filename (str) – The filename to remove extension from.
• keep_dot (bool) – Whether to return filename + “.”.
• return_ext (bool) – Whether to return filename or filename, ext.

Returns:

str | tuple – str if return_ext is False, the filename with no ext (str, str) if return_ext is True, (filename, ext)

neurochat.nc_utils.residual_stat(y, y_fit, p)

Calculate the goodness of fit and other residual statistics.

These are calculated between observed and fitted values from a model.

Parameters:

• y (ndarray) – Observed data
• y_fit (ndarray) – Fitted data to a linear model
• p (int) – Model order

Returns:

_results (dict) – Dictionary of residual statistics

neurochat.nc_utils.rot_2d(x, theta)

Rotate a firing map by a specified angle.

Parameters:

• x (ndarray) – Matrix of firing rate map
• theta – Angle of rotation in theta

Returns:

ndarray – Rotated matrix

neurochat.nc_utils.smooth_1d(x, kernel_type='b', kernel_size=5, axis=0, **kwargs)

Filter a 1D array or signal.

Parameters:

• x (ndarray) – Array or signal to be filtered. If matrix, each column or row is filtered individually depending on ‘dir’ parameter that takes either ‘0’ for along-column and ‘1’ for along-row filtering.
• kernel_type (str) – ‘b’ for moving average or box filter. ‘g’ for Gaussian filter. ‘hs’ for Heaviside filter ‘hg’ for half-Gaussian filter
• kernel_size (int) – Box size for box filter and sigma for Gaussian filter
• axis (int) – Defaults to 0. The axis along which to smooth matrices.

Returns:

ndarray – Filtered data

neurochat.nc_utils.smooth_2d(x, filttype='b', filtsize=5)

Filter a 2D array or signal.

Parameters:

• x (ndarray) – Matrix to be filtered
• filttype (str) – ‘b’ for moving average or box filter. ‘g’ for Gaussian filter.
• filtsize – Box size for box filter and sigma for Gaussian filter

Returns:

smoothX – Filtered matrix

neurochat.nc_utils.static_vars(**kwargs)

Return decorator to create a function with static variables.

neurochat.nc_utils.window_rms(a, window_size, mode='same')

Calculate the rms envelope, similar to matlab.

Parameters:

• a (ndarray) – The input signal to envelope.
• window_size (int) – The length of the window to convolve the signal with.
• mode (str) – The mode determines how many points are output mode “valid” will have no border effects mode “same” will produce a value for each input See np.convolve for more information.

Returns:

np.ndarray – The RMS envelope of the signal