neurochat.nc_spatial module

This module implements NSpatial Class for NeuroChaT software.

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

class neurochat.nc_spatial.NSpatial(**kwargs)

Bases: neurochat.nc_base.NAbstract

This data class contains the spatial behaviour of the animal.

It decodes data from different formats and analyses the correlation of spatial information with the spiking activity of a unit.

_time

The times of each spatial sample.

Type:np.ndarray

_fs

The sampling frequency of the spatial data.

Type:float

_pos_x

The x position of each spatial sample.

Type:np.ndarray

_pos_y

The y position of each spatial sample.

Type:np.ndarray

_direction

The head direction of the animal.

Type:np.ndarray

_speed

The speed of the animal.

Type:np.ndarray

_ang_val

The angular head velocity of the animal.

Type:np.ndarray

_border_dist

The distance to the border of the animal.

Type:np.ndarray

__str__()

Return a friendly string representation of this object.

angular_velocity(ftimes, **kwargs)

Calculate the firing rate of the unit at binned angular head velocity.

The spike rate vs speed is fitted with a linear equation individually for the negative and positive angular velocities, and goodness of fit is measured

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

border(ftimes, **kwargs)

Analysis of the firing of a unit with respect to the border.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

calc_ang_vel(npoint=5)

Calculate the angular head velocity of the animal from the direction.

Each sample is the slope of a fitted line of five directional data centred around current sample.

Parameters:None – Returns:None

calc_border(**kwargs)

Identify the border of the recording arena.

This is inferred from the trace of the foraging of the animal in the arena.

Parameters:**kwargs – Keyword arguments Returns:

• border_dist (ndarray) – Distance of the animal from the border at each behavioural samples
• xedges (ndarray) – Pixelated edge of the x-axis
• yedges (ndarray) – Pixelated edge of the y-axis
• dist_mat (ndarray) – A matrix of distance of each pixel of the arena from the identified border

get_ang_vel()

Return angular head velocity of the animal.

Parameters:None – Returns:ndarray – Angular head velocity of the animal

get_border()

Return animal’s distance from the border.

Parameters:None – Returns:ndarray – Animal’s distance from the border

get_direction()

Return head direction of the animal.

Parameters:None – Returns:ndarray – Head direction of the animal

get_duration()

Return the duration of the experiment.

Parameters:None – Returns:float – Duration of the experiment

get_event_loc(ftimes, **kwargs)

Calculate location of the event from its timestamps.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking or any other events
• **kwargs – Keyword arguments

Returns:

• (ndarray, [ndarray, ndarray], ndarray)

• ndarray – Index of the events in spatial-timestamps

• [ Two item list containing –

  ndarray

  x-coordinates of the event location

  ndarray

  y-ccordinates of the event location

• ]

• ndarray – direction of the animal at the time of the event

get_non_moving_times(**kwargs)

Return the times where the subject is not moving.

Keyword arguments are passed to non_moving_periods()

Returns:list – A list of times where the subject is not moving

get_pixel_size()

Return the pixel size of the recorded arena.

Parameters:None – Returns:int – Pixel size

get_pos_x()

Return the X-coordinates of animal’s location.

Parameters:None – Returns:ndarray – X-coordinates of animal’s location

get_pos_y()

Return the Y-coordinates of animal’s location.

Parameters:None – Returns:ndarray – Y-coordinates of animal’s location

get_sampling_rate()

Return the sampling rate of the spatial samples.

Parameters:None – Returns:int – Spatial data sampling rate

get_speed()

Return speed of the animal.

Parameters:None – Returns:ndarray – Speed of the animal

get_time()

Return the time of individual spatial samples.

Parameters:None – Returns:int – Total spatial samples

get_timestamp()

Return the temporal resolution of spatial samples.

Parameters:None – Returns:int – Temporal resolution of spatial samples

get_total_samples()

Return the number of spatial samples.

Parameters:None – Returns:int – Total spatial samples

get_type()

Return the type of object.

For NSpatial, this is always spatial type.

Parameters:None – Returns:str

gradient(ftimes, **kwargs)

Analysis of gradient cell.

A gradient cell is a unit whose firing rate gradually increases as the animal traverses from the border to the center of the environment.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

grid(ftimes, **kwargs)

Analysis of Grid cells.

These are characterised by formation of grid-like pattern of high activity in the firing-rate map.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

hd_rate(ftimes, **kwargs)

Calculate head directional firing related measures and plots.

The firing rate of the unit with respect to the head- direciton of the animal in the environment is called the Tuning curve.

Precited firing map from the locational firing is also calculated and distributive ratio is measured along with the Skaggs information.

Spike-plot similar to locational firing is developed but in the circular bins which shows the direction of the animal’s head at each spike’s occurring time.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

hd_rate_ccw(ftimes, **kwargs)

Calculate the tuning curve but split by direction.

Splits are into clock-wise vs counterclockwise head-directional movement.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

hd_shift(ftimes, shift_ind=array([-10, -9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]))

Head directional analyses performed shifted in time.

Analysis of firing specificity of the unit with respect to animal’s head direction to oberve whether it represents past direction or anicipates a future direction.

Parameters:shift_ind (ndarray) – Index of spatial resolution shift for the spike event time. Shift -1 implies shift to the past by 1 spatial time resolution, and +2 implies shift to the future by 2 spatial time resoultion. Returns:dict – Graphical data of the analysis

hd_shuffle(ftimes, **kwargs)

Shuffling analysis of the unit.

This is used to see if the head-directional firing specifity is by chance or actually correlated to the head-direction of the animal.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

hd_time_lapse(ftimes)

Calculate the tuning curve over small time intervals.

This method is useful in observing the evolution of unit-activity as the animal traverses the environment.

Following intervals ar used:

0-1min, 0-2min, 0-4min, 0-8min, 0-16min or 0-end depending on the recording duration 0-1min, 1-2min, 2-4min, 4-8min, 8-16min or 16-end depending on the recording duration

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

interdependence(ftimes, **kwargs)

Interdependence analysis.

The firing rate of each variable is predicted from another variable and the distributive ratio is measured between the predicted firing rate and the caclulated firing rate.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

None

load(filename=None, system=None)

Load the spatial object.

Parameters:None – Returns:None

load_lfp()

Load the composite lfp object.

Parameters:None – Returns:None

load_spatial_Axona(file_name)

Load Axona format spatial data to the NSpatial() object.

Parameters:None – Returns:None

load_spatial_NWB(file_name)

Load HDF5 format spatial data to the NSpatial() object.

Parameters:None – Returns:None

load_spatial_Neuralynx(file_name)

Load Neuralynx format spatial data to the NSpatial() object.

Parameters:None – Returns:None

load_spike()

Load the composing spike object.

Parameters:None – Returns:None

loc_auto_corr(ftimes, **kwargs)

Calculate the two-dimensional correlation of firing map.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

loc_rot_corr(ftimes, **kwargs)

Calculate the rotational correlation of the firing map.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

loc_shift(ftimes, shift_ind=array([-10, -9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]), **kwargs)

Locational analysis shifted in time.

Analysis of firing specificity of the unit with respect to animal’s location to oberve whether it represents past location of the animal or anicipates a future location.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• shift_ind (ndarray) – Index of spatial resolution shift for the spike event time. Shift -1 implies shift to the past by 1 spatial time resolution, and +2 implies shift to the future by 2 spatial time resoultion.
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

loc_shuffle(ftimes, **kwargs)

Shuffling analysis of the unit.

This is used to see if the locational firing specifity is by chance or actually correlated to the location of the animal.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

loc_time_lapse(ftimes, **kwargs)

Calculate the firing rate map over small time intervals.

This method is useful in observing the evolution of unit-activity as the animal traverses the environment.

Following intervals are used:

0-1min, 0-2min, 0-4min, 0-8min, 0-16min or 0-end depending on the recording duration 0-1min, 1-2min, 2-4min, 4-8min, 8-16min or 16-end depending on the recording duration

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

multiple_regression(ftimes, **kwargs)

Multiple-rgression analysis.

In this, the firing rate for each variable, namely location, head-direction, speed, AHV, and distance from border, are used to regress the instantaneous firing rate of the unit.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

non_moving_periods(**kwargs)

Return tuples indicating ranges where the subject is not moving.

Keyword Arguments:  

• should_smooth (bool) – flags if the speed data should be smoothed, default False
• min_range (float) – the minimum amount of time that the subject should not be moving for
• moving_thresh (float) – any speed above this thresh is considered to be movement

Returns:

list of tuples

place(ftimes, **kwargs)

Calculate location based measures, used in Firing map.

This is used to get the two-dimensional firing rate of the unit with respect to the location of the animal in the environment. This is commonly called the Firing map.

Specificity indices are measured to assess the quality of location-specific firing of the unit.

This method is also used to get the events of spike occurring superimposed on the trace of the animal in the arena, commonly known as Spike Plot.

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

static place_field(pmap, thresh=0.2, required_neighbours=9)

Identify high firing neighbouring bins in the place map.

For each bin in the place map, it is assigned to an integer group. These groups denote which neighbouring area the bin belongs to. The default group is 0, which every bin belongs to initially.

Parameters:

• pmap (ndarray) – The firing map to calculate place fields from
• thresh (float) – The fraction of the peak firing that a bin must exceed
• required_neighbours (int) – The number of adjacent bins that must be together to form a field

Returns:

• (ptag, largest_group_num)
• ptag (np.ndarray) – A 2D array indicating the tag of each bin in the firing map. The tag is the same as the group the bin belongs to.
• largest_group_num (int) – The tag of the group with the highest firing rate. If it is 0, then no groups were found that satisfy the thresh and required_neighbours conditions.

static place_field_centroid(pfield, fmap, group_num, **kwargs)

Calculate the centroid of a place field.

This is performed as a centre of mass calculation. Where the mass of a bin is the firing rate in that bin.

As such, passing the group number as 0 with pfield containing all zeroes, would return the centre of mass of the entire firing map.

Parameters:

• pfield (ndarray) – Input place field consisting of a map of groups
• fmap (ndarray) – Input firing map
• group_num (int) – The group to get the centroid for
• **kwargs – Keyword arguments

Returns:

ndarray – A list of co-ordinates for each place field group

save_to_hdf5(file_name=None, system=None)

Save spatial dataset to HDF5 file.

Parameters:None – Returns:None

set_ang_vel(ang_vel)

Set the angular head velocity (AHV) of the animal.

Parameters:ang_vel (ndarray) – Angular head velocity (AHV) of the animal Returns:None

set_border(border)

Set the distance of the animal from the arena border.

Parameters:border (ndarray) – Distance of the animal from the arena border Returns:None

set_event(event, **kwargs)

Set the NEvent() object to NSpatial().

Parameters:event – NEvent or its childclass or NEvent() object Returns:NEvent()

set_event_filename(filename=None)

Set the filename for the event.

Parameters:filename (str) – Full file of the event dataset Returns:None

set_event_name(name=None)

Set the name of the event object.

Parameters:name (str) – Name of the vent dataset Returns:None

set_lfp(lfp, **kwargs)

Add the NLfp object to NSpatial object.

Parameters:

• lfp (NLfp) – NLfp object to be added to the NSpatial object. If no spike object is provided, a new NLfp() object is created.
• **kwargs – Keyword argumemts for creating the new NLfp instance

Returns:

None

set_lfp_filename(filename=None)

Set file name of the lfp dataset.

Parameters:name (str) – Full file directory of the lfp dataset Returns:None

set_lfp_name(name=None)

Set the name of the lfp dataset.

Parameters:name (str) – Name of the lfp dataset Returns:None

set_pixel_size(pixel_size)

Set the size of pixel size.

This is the value by which the entire foraged arena is tessellated.

Note

The majority of the analyses in this class instead take in this value per function, as opposed to using this class value.

Parameters:pixel_size (int) – Pixel size of the foraged arena Returns:None

set_spike(spike, **kwargs)

Add the NSpike object to NSpatial object.

Parameters:

• spike (NSpike) – NSpike object to be added to the NSpatial object. If no spike object is provided, a new NSpike() object is created.
• **kwargs – Keyword argumemts for creating the new NSpike instance

Returns:

None

set_spike_filename(filename=None)

Set file name of the spike dataset.

Parameters:name (str) – Full file directory of the spike dataset Returns:None

set_spike_name(name=None)

Set the name of the spike dataset.

Parameters:name (str) – Name of the spike dataset Returns:None

set_system(system=None)

Set the data format or recording system.

Parameters:system (str) – Data format or recording system Returns:None

static skaggs_info(firing_rate, visit_time)

Calculate the Skaggs information content of the spatial firing.

Parameters:

• firing_rate (ndarray) – Firing rate of the unit at each pixelated location or binned information, i.e., binned speed or head-direction
• visit_time (ndarray) – Amount of time animal spent in each pixel or bin

Returns:

float – Skaggs information content

smooth_direction()

Smooth the angular head direction using a moving circular average.

Parameters:None – Returns:None

See also

nc_circular.CircStat()

smooth_speed()

Smooth the speed data using a moving-average box filter.

Parameters:None – Returns:None

static spatial_sparsity(firing_rate, visit_time)

Calculate the spatial sparsity of the spatial firing.

Parameters:

• firing_rate (ndarray) – Firing rate of the unit at each pixelated location
• visit_time (ndarray) – Amount of time animal spent in each pixel

Returns:

float – Spatial sparsity

speed(ftimes, **kwargs)

Calculate the firing rate of the unit at different binned speeds.

The spike rate vs speed is fitted with a linear equation and goodness of fit is measured

Parameters:

• ftimes (ndarray) – Timestamps of the spiking activity of a unit
• **kwargs – Keyword arguments

Returns:

dict – Graphical data of the analysis

subsample(sample_range=None)

Extract a time range from the positions.

Note

Currently, the duration will be longer than sample time. Duration is actually from 0 to max recording length. This is to easier match ndata, which assumes recordings start at 0.

Parameters:sample_range (tuple) – the time in seconds to extract from the positions. Returns:NSpike – subsampled version of initial spatial object