spiketools.spatial.occupancy.compute_bin_assignment

spiketools.spatial.occupancy.compute_bin_assignment(position, x_edges, y_edges=None, check_range=True, include_edge=True)[source]

Compute spatial bin assignment.

Parameters:
position1d or 2d array

Position values.

x_edges1d array

Edge definitions for the x dimension of the spatial binning.

y_edges1d array, optional, default: None

Edge definitions for the y dimension of the spatial binning. Only used if position is 2d.

check_rangebool, optional, default: True

Whether to check if the given edges fully cover the given data. If True, runs a check that raises a warning if any data values exceed edge ranges.

include_edgebool, optional, default: True

Whether to include positions on the edge into the bin.

Returns:
x_bins1d array

Bin assignments for the x-dimension for each position.

y_bins1d array

Bin assignments for the y-dimension for each position. Only returned in 2d case.

Notes

  • Values in the edge array(s) should be monotonically increasing.

  • If there are no outliers (all position values are within edge ranges), the returned bin assignments will range from (0, n_bins-1).

  • Outliers (position values beyond the given edges definitions), will be encoded as -1 (left side) or n_bins (right side). If check_range is True, a warning will be raised.

  • By default position values equal to the left-most & right-most edges are treated as within the bounds (not treated as outliers), unless include_edge is set as False.

Examples

Compute bin assignment for 1d position values, given precomputed bin edges:

>>> position = np.array([1.5, 2.5, 3.5, 5])
>>> x_edges = np.array([1, 2, 3, 4, 5])
>>> compute_bin_assignment(position, x_edges)
array([0, 1, 2, 3])

Compute bin assignment for 2d position values, given precomputed bin edges:

>>> position = np.array([[1.5, 2.5, 3.5, 5],
...                      [6.5, 7.5, 8.5, 9]])
>>> x_edges = np.array([1, 2, 3, 4, 5])
>>> y_edges = np.array([6, 7, 8, 9, 10])
>>> compute_bin_assignment(position, x_edges, y_edges)
(array([0, 1, 2, 3]), array([0, 1, 2, 3]))