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 thatax
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, andNy
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 frommatplotlib.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 thematplotlib
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", ... )
See also
matplotlib.pyplot.Axes.hist2d
The underlying plotting function.