spiketools.spatial.occupancy.compute_trial_occupancy

spiketools.spatial.occupancy.compute_trial_occupancy(position, timestamps, bins, start_times, stop_times, area_range=None, speed=None, min_speed=None, max_speed=None, min_time=None, max_time=None, orientation=None, **occupancy_kwargs)

Compute trial-level occupancy across spatial bin positions.

Parameters:

position1d or 2d array

Position values.

timestamps1d array

Timestamps, in seconds, corresponding to the position values.

binsint or list of [int, int]

The bin definition for dividing up the space. If 1d, can be integer. If 2d should be a list, defined as [number of x_bins, number of y_bins].

start_times, stop_times1d array

The start and stop times, in seconds, of each trial.

area_rangelist of list, optional

Edges of the area to bin, defined as [[x_min, x_max], [y_min, y_max]].

speed1d array, optional

Speed values corresponding to each position. Should be the same length as timestamps.

min_speed, max_speedfloat, optional

Minimum and/or maximum speed thresholds to apply. Any entries with an associated speed below the minimum or above maximum are dropped.

min_time, max_timefloat, optional

Minimum and/or maximum time thresholds, per bin observation, to apply. Any entries with an associated time length below the minimum or above maximum are dropped.

orientation{‘row’, ‘column’}, optional

The orientation of the position data. If not provided, is inferred from the position data.

occupancy_kwargs

Additional arguments to pass into the the compute_occupancy function.

Returns:

trial_occupancyndarray

Occupancy data across trials.

Examples

Compute trial-level occupancy for 1d position data:

>>> bins = 2
>>> position = np.array([1, 3, 5, 6, 9, 10, 2, 4, 6, 7, 9])
>>> timestamps = np.linspace(0, 50, len(position))
>>> start_times, stop_times = [0, 25], [26, 50]
>>> compute_trial_occupancy(position, timestamps, bins, start_times, stop_times)
array([[15., 10.],
       [10., 15.]])

Compute trial-level occupancy for 2d position data:

>>> bins = [2, 3]
>>> position = np.array([[1, 2, 4, 4.5, 5, 2, 2.5, 3.5, 4, 5, 5.5],
...                      [6, 7, 8, 8.5, 9.5, 10, 6, 6.5, 7, 8, 10]])
>>> timestamps = np.linspace(0, 50, position.shape[1])
>>> start_times, stop_times = [0, 25], [26, 50]
>>> compute_trial_occupancy(position, timestamps, bins, start_times, stop_times)
array([[[10.,  0.],
        [ 0., 10.],
        [ 0.,  5.]],

       [[10.,  5.],
        [ 0.,  5.],
        [ 5.,  0.]]])