Sites Module

Module for virtual world creation.

All simulations take place withing a rectangular region of the plane called a site. The dimensions of such site are specified in the range variable.

Additionally, since such a site is meant to be the moving field of some specific species, any site is complemented with niche information. This niche information is encoded in a scalar field, a function of the two coordinates, that provides a measure of “adequacy” of position for the species. The function values should be in the [0, 1] range, taking a value of 1 to mean the highest level of adequacy. The function is stored as an array representing the rectangular region at some spatial resolution. The niche information can then be exploited to guide individuals in their movements.

Sites can be created randomly by placing a random number of cluster points in range and making a Gaussian kernel density estimation, or by specifying points at which niche values are known to be high and extrapolating by some kernel density estimation. This data could possibly arise from ecological and climatic variables, real telemetry data, or presence/absence data from camera traps studies.

class ollin.core.sites.BaseSite(range, niche)

Base class for all types of site.

range

array – Array of shape [2], specifying the dimensions of site (in Km).

niche

array – Matrix representing the values of adequacy at different points in site.

niche_size

float – Proportion of total area adequate for species. This are points at which niche value is above some threshold.

resolution

float – Spatial resolution (in Km) of niche array. If range = (x, y) and niche.shape = [n, m] then resolution = (x/n + y/m)/2.

static get_niche_resolution(niche, range)

Get spatial resolution used in niche array.

static get_niche_size(niche)

Calculate proportion of area of adequate space.

static get_true_niche(niche, threshold=0.25)

Select cells with good level of niche adequacy.

plot(ax=None, figsize=(10, 10), include=None, niche_cmap='Reds', niche_alpha=1.0, boundary_color='black', **kwargs)

Plot BaseSite information.

Site plotting adds the following optional components to the plot:

1. “rectangle”:

   If present in include list, axes will be fitted to Site’s range and no ticks will be placed.

2. “niche”:

   If present in include list, a heatmap plot of niche’s adequacy values will be placed within range. A colormap will be used to translate adequacy values to colors.

2. “niche_boundary”:

   If present in include list, the boundary defining the true niche will be plotted. The true niche is defined as those cells where adequacy value is higher than some threshold, see BaseSite.get_true_niche().

Parameters:

• ax (matplotlib.axes.Axes, optional) – Axes object in which to plot site 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.
• niche_cmap (str, optional) – Colormap to use to codify niche adequacy level to color. Defaults to ‘Reds’.
• niche_alpha (float, optional) – Alpha value of niche cell colors.
• boundary_color (str, optional) – Color of boundary of true niche.

Returns:

ax – Return axes for further plotting.

Return type:

matplotlib.axes.Axes

sample(num)

Sample n random points from site.

class ollin.core.sites.Site(range, points, resolution=0.1, kde_bandwidth=0.3, max_niche_value=1)

Site with niche from gaussian kernel density estimation.

A simple way of obtaining an estimate of niche adequacy value, or for random niche creation, is to select points in space which are known to be adequate for the target species. Interpolation to unknown points in space can be accomplished with a gaussian kernel density estimation. Selecting different bandwidths for the kernel density estimation will result in tighter or more diffuse niche values.

points

array – Array of shape [num_points, 2] containing the coordinates of the points used for the kernel density estimation.

kde_bandwidth

float – Bandwidth used in the gaussian kernel density estimation.

kde

scipy.stats.gaussian_kde – Density estimation object.

range

array – Array of shape [2], specifying the dimensions of site (in Km).

niche

array – Matrix representing the values of adequacy at different points in site.

niche_size

float – Proportion of total area adequate for species. This are points at which niche value is above some threshold.

resolution

float – Spatial resolution used for niche array construction, in Km.

static make_niche(points, range, kde_bandwidth, resolution=1.0)

Make niche array from points.

static make_niche_from_kde(kde, range, resolution=1.0)

Make niche array from kernel density estimation.

classmethod make_random(niche_size, resolution=None, range=None, min_clusters=None, max_clusters=None, min_cluster_points=None, max_cluster_points=None, max_niche_value=1)

Make random site.

Process for random site creation follows the next steps:

1. Select a random number of clusters. The number is selected within the [min_clusters, max_clusters] range.
2. For each cluster select a central point randomly, using a uniform distribution, within site’s range.
3. For each cluster, select a random number of cluster points, within the range [min_cluster_points, max_cluster_points], around the cluster center, using a gaussian distribution with random covariance matrix.
4. Collect all generated points for use in kernel density estimation.
5. Select kernel density estimation bandwidth so that niche size (see BaseSite.get_niche_size()) is recovered.

Parameters:

• niche_size (float) – Number in [0, 1] range representing the desired proportion of adequate niche space to total area.
• resolution (float, optional) – Spatial resolution to use for niche creation. If none is given it will be taken from the global constants. See GLOBAL_CONSTANTS.
• range (int or float or list or tuple or array, optional) – Size of created site. If int or float it will be assumed that site is square. If none is given it will be taken from the global constants.
• min_clusters (int, optional) – Minimum number of clusters used in random niche creation. If none is given it will be taken from the global constants.
• max_clusters (int, optional) – Maximum number of clusters used in random niche creation. If none is given it will be taken from the global constants.
• min_cluster_points (int, optional) – Minimum number points per cluster used in random niche creation. If none is given it will be taken from the global constants.
• max_cluster_points (int, optional) – Maximum number points per cluster used in random niche creation. If none is given it will be taken from the global constants.
• max_niche_value (float, optional) – Number in [0, 1] range. Final niche value will have this number as a maximum value.

plot(ax=None, figsize=(10, 10), include=None, points_color='red', **kwargs)

Plot Site information.

Site plotting adds the following optional components to the plot:

1. “points”:

   If present in include list, points used for kernel density estimation will be show in plot.

All other components in include list will be passed to BaseSite plotting method. See BaseSite.plot() to see all components defined at that level.

Parameters:

• ax (matplotlib.axes.Axes, optional) – Axes object in which to plot site 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 BaseSite plotting method to add the corresponding components.
• points_color (str, optional) – Color of points used for kernel density estimation. Defaults to ‘red’.
• **kwargs (dict, optional) – All other keyword arguments will be passed to BaseSite plotting method.

Returns:

ax – Return axes for further plotting.

Return type:

matplotlib.axes.Axes

sample(num)

Use kernel density estimation to sample random points form site.