plot_occupancy#

movement.plots.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, their occupancies are aggregated.

Points whose corresponding spatial coordinates have NaN values are ignored.

This function returns the figure and axes containing the histogram, as well as a dictionary containing the histogram data returned by matplotlib.axes.Axes.hist2d().

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.axes.Axes.hist2d().

Return type:

tuple[Figure | SubFigure, Axes, dict[Literal['h', 'xedges', 'yedges'], ndarray]]

Returns:

fig (matplotlib.figure.Figure or matplotlib.figure.SubFigure) – Plot handle containing the rendered 2D histogram. If ax is supplied, this will be the matplotlib.figure.Figure or matplotlib.figure.SubFigure that ax belongs to.
ax (matplotlib.axes.Axes) – Axes on which the histogram was drawn. If ax is supplied, the input will be directly modified and returned in this value.
hist2d_info (dict[Literal[‘h’, ‘xedges’, ‘yedges’], np.ndarray]) – Dictionary containing the h, xedges, and yedges outputs from matplotlib.axes.Axes.hist2d() that would otherwise be lost if only the figure and axes handles were returned.

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