Occupancy Module

Module for occupancy class and calculation.

Occupancy can be loosely defined as proportion of area occupied by some target species. Unfortunately this definition is not rigorous enough to define a single concept. Hence definitions have proliferated in the literature, mainly guided by study restriction and convenience.

Three main issues arise when trying to clearly define occupancy:

  1. The definition of space being occupied by some species: In some cases, where niches are sharply delimited by geographical features, such as ponds, occupancy refers to the proportion of such areas occupied by some target species at an instant in time. But when movement is not restrained by clear boundaries occupancy is harder to define. One approach is defining occupancy as the proportion of points at which individuals of the target species are observed, having preselected the points as being “representative”. This seems to be an ad hoc definition for camera trap studies. Finally when movement data is available occupancy can be defined, more faithful to the original concept, as the area visited by the individuals of the target species. But this also introduces the following two problems:
  2. Calculation of area visited by an individual usually starts by some sort discretization of space, and is done by counting the number of cells of discretized space that individuals touch along its movement. This implies that there will be some dependence of the final occupancy value on the method of space discretization.
  3. Finally, when occupancy is calculated from movement data, there must be a choice of time span for which to calculate occupancy. Occupancy values will be sensitive to choice of time span, or could even be result in a useless feature if, for example, individuals of species fully roam the available land given enough time, even though they usually take a small proportion of land area at smaller time scales.

Due to the nature of the data generated in movement simulations we have chosen to define occupancy as the result of the following calculations:

  1. Select some definite time span, say 90 days of movement.

  2. Use some pre defined function to obtain spatial resolution from home range data and discretize study site with such resolution. Symbolically:

    resolution = f(home_range, parameters)

    See occupancy_resolution()

  3. For each time step mark as visited all cells that have some individual of the target species contained in it.

  4. For each cell of discretized space, calculate the proportion of times the cell was visited.

  5. Occupancy is defined as the average of this proportion of times cells where visited.

We have chosen to use proportion of occupancy, or rate of occupancy, since this value is less sensitive to changes in time span selected for occupancy calculation. In simulated situations it will always converge to some specific value as time span grows.

All values used in the occupancy calculation, such as the grid of visited cells per time step, number of times a cell was visited and others, are stored within a Occupancy object.

class ollin.core.occupancy.Occupancy(movement, resolution=None)[source]

Occupancy information and calculation class.

Occupancy can be calculated from movement data in the following way:

  1. Select some spatial resolution to use in space discretization.

  2. Discretize site to obtain n x m cells.

  3. Initialize an array of shape [time_steps, n, m] to zeros.

  4. Set

    array[t, i, j] = 1

    if some individual is in cell (i,j) at time step t.

  5. Occupancy is the average of this array.

movement

MovementData – Movement data for which to calculate occupancy.

steps

int – Number of movement steps contained in movement data.

resolution

float – Spatial resolution (in Km) for site discretization.

grid

array – Array of shape [time_steps, x, y] where [x, y] is the size of the discretized site. Holds cell occupancy at each time step.

cell_occupancy

array – Array of shape [x, y] where [x, y] is the size of the discretized site. Holds cell occupancy.

occupancy

float – Occupancy measure.

plot(ax=None, figsize=(10, 10), include=None, occupancy_cmap='Blues', occupancy_level=0.2, occupancy_alpha=0.3, **kwargs)[source]

Plot discretized space occupancy information.

Occupancy plotting adds the following optional components to the plot:

  1. “occupancy”:
    If present in include list, cells of discretized space will be shown with a color representing the rate of occupation of such cell. Colors will be selected using a color map. See matplotlib.cm to see all colormap options.
  2. “occupancy_contour”:
    If present in include list, the border of the region containing all cells with occupancy higher than some threshold will be plotted.

All other components in the include list will be passed down to the MovementData plotting method. See MovementData.plot() for all plot components defined at that level.

Parameters:
  • ax (matplotlib.axes.Axes, optional) – Axes object in which to plot occupancy information.
  • figsize (list or tuple, optional) – Size of figure to create if no axes object was given. Defaults to (10, 10).
  • include (list or tuple, optional) – List of components to add to the plot. Components list will be passed to the Site object to add the corresponding components.
  • occupancy_cmap (str, optional) – Colormap to use to codify occupancy level to color. Defaults to ‘Blues’.
  • occupancy_level (float, optional) – Threshold at which to draw boundary for occupancy contour.
  • occupancy_alpha (float, optional) – Alpha value of cell colors.
  • kwargs (dict, optional) – All other keyword arguments will be passed to the MovementData’s plotting method.
Returns:

ax – Return axes for further plotting.
Return type:

matplotlib.axes.Axes
plot_occupancy_timeseries(ax=None, figsize=(10, 10), color='red', label='')[source]

Plot occupancy values at different times.

Occupancy is defined as the mean rate of occupation. The rate of occupation is calculated over some timespan. This method calculates occupancy at all possible timespans and plots the resulting timeseries for visual comparison.

Parameters:
  • ax (matplotlib.axes.Axes, optional) – Axes in which to plot timeseries. If not provided new axes will be created.
  • figsize (tuple or list, optional) – Size of figure to be created if no axes where provided.
  • color (str, optional) – Name of color to use for plot.
  • label (str, optional) – Label of plot.
Returns:

ax – Axes of plot, returned for further plotting.
Return type:

matplotlib.axes.Axes, optional