plot_occupancy#

movement.plots.occupancy.plot_occupancy(da, individuals=None, keypoints=None, ax=None, **kwargs)[source]#

Create a 2D occupancy histogram.

If there are multiple keypoints selected, the occupancy of the centroid
of these keypoints is computed.
If there are multiple individuals selected, the their occupancies are
aggregated.

Points whose corresponding spatial coordinates have NaN values are ignored.

Histogram information is returned as the third output value (see Notes).

Parameters:

da (xarray.DataArray) – Spatial data to create histogram for. NaN values are dropped.
individuals (Hashable, optional) – The name of the individual(s) to be aggregated and plotted. By default, all individuals are aggregated.
keypoints (Hashable | list[Hashable], optional) – Name of a keypoint or list of such names. The centroid of all provided keypoints is computed, then plotted in the histogram.
ax (matplotlib.axes.Axes, optional) – Axes object on which to draw the histogram. If not provided, a new figure and axes are created and returned.
kwargs (Any) – Keyword arguments passed to matplotlib.pyplot.hist2d

Return type:

tuple[Figure, Axes, dict[Literal['counts', 'xedges', 'yedges'], ndarray]]

Returns:

matplotlib.pyplot.Figure – Plot handle containing the rendered 2D histogram. If ax is supplied, this will be the figure that ax belongs to.
matplotlib.axes.Axes – Axes on which the histogram was drawn. If ax was supplied, the input will be directly modified and returned in this value.
dict[str, numpy.ndarray] – Information about the created histogram (see Notes).

Notes

The third return value of this method exposes the outputs from matplotlib.pyplot.hist2d that would otherwise be lost if only the figure and axes handles were returned. This information is returned as a dictionary.

For data with Nx bins in the 1st spatial dimension, and Ny bins in the 2nd spatial dimension, the dictionary output has key-value pairs; - xedges, an (Nx+1,) numpy array specifying the bin edges in the 1st spatial dimension. - yedges, an (Ny+1,) numpy array specifying the bin edges in the 2nd spatial dimension. - counts, an (Nx, Ny) numpy array with the count for each bin.

counts[x, y] is the number of datapoints in the (xedges[x], xedges[x+1]), (yedges[y], yedges[y+1]) bin. These values are those returned from matplotlib.pyplot.Axes.hist2d.

Examples

Simple use-case is to plot a histogram of the centroid of all keypoints, aggregated over all individuals.

>>> from movement import sample_data
>>> from movement.plots import plot_occupancy
>>> positions = sample_data.fetch_dataset(
...     "DLC_two-mice.predictions.csv"
... ).position
>>> plot_occupancy(positions)

However, one can restrict the histogram to only counting the positions of (the centroid of) certain keypoints and/or individuals.

>>> print("Available individuals:", positions["individuals"])
>>> plot_occupancy(
...     positions,
...     # plot the centroid of keypoints located on the head
...     keypoints=["snout", "leftear", "rightear"],
...     # only plot data for 1 individual
...     individuals="individual1",
... )

kwargs are passed to the matplotlib backend as keyword-arguments to this function.

>>> plot_occupancy(
...     positions,
...     # plot the centroid of keypoints located on the head
...     keypoints=["snout", "leftear", "rightear"],
...     # only plot data for 1 individual
...     individuals="individual1",
...     # fix the number of bins to use
...     bins=[30, 20],
...     # set the minimum count (bins with a lower count show as 0 count).
...     # This effectively only displays bins that were visited at least
...     # twice.
...     cmin=1,
...     # Normalise the plot, scaling the counts to [0, 1]
...     norm="log",
... )

plot_occupancy#

This Page