spiketools.spatial.occupancy.compute_occupancy

spiketools.spatial.occupancy.compute_occupancy(position, timestamps, bins, area_range=None, speed=None, min_speed=None, max_speed=None, min_time=None, max_time=None, check_range=True, minimum=None, normalize=False, set_nan=False)

Compute 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].

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.

check_rangebool, optional, default: True

Whether to check the given bin definition range against the position values.

minimumfloat, optional

The minimum required occupancy. If defined, any values below this are set to zero.

normalizebool, optional, default: False

Whether to normalize occupancy to sum to 1.

set_nanbool, optional, default: False

Whether to set zero occupancy locations as NaN.

Returns:

occupancy1d or 2d array

Computed occupancy across the space. For 2d, has shape [n_y_bins, n_x_bins] (see notes).

Notes

For the 2d case, note that while the inputs to this function list the x-axis first, the output of this function, being a 2d array, follows the numpy convention in which columns (y-axis) are on the 0th dimension, and rows (x-axis) are on the 1th dimension.

Examples

Compute occupancy for a set of 1d position values:

>>> position = np.array([1.0, 1.5, 2.5, 3.5, 5])
>>> timestamps = np.linspace(0, 1, position.shape[0])
>>> compute_occupancy(position, timestamps, bins=[4])
array([0.5 , 0.25, 0.25, 0.  ])

Compute occupancy for a set of 2d position values:

>>> position = np.array([[1.0, 2.5, 1.5, 3.0, 3.5, 5.0],
...                      [5.0, 7.5, 6.5, 5.0, 8.5, 9.0]])
>>> timestamps = np.linspace(0, 1, position.shape[1])
>>> compute_occupancy(position, timestamps, bins=[2, 2])
array([[0.4, 0.2],
       [0.2, 0.2]])