Utils Module

Helper functions.

ollin.core.utils.density_to_occupancy(density, home_range_proportion, niche_size, parameters=None)

Get estimated occupancy from density information.

Notes

This function is used throughout the package to translate density to occupancy information. This relation also depends on the size of the home range in relation to the whole site’s area, and to the proportion of available adequate space, or size of true niche, see BaseSite.get_niche_size(). Each movement model produces a different relation between occupancy and density, but a single model (or family of functions) is applied to all movement models. The general relationship assumed is:

\[logit(o) = \alpha+\beta_1 log(d)+\beta_2 log(ns)+\beta_3 log(hrp)\]

where \(o, d, ns, hrp\) stand for occupancy, density, niche size and home range proportion, and \(logit(x) = - log(-1 + 1/x)\). Equivalently:

\[o = \frac{\alpha \cdot d^{\beta_1} \cdot ns^{\beta_2} \cdot hrp^{\beta_3}}{1 + \alpha \cdot d^{\beta_1} \cdot ns^{\beta_2} \cdot hrp^{\beta_3}}\]

Parameters are then fitted using simulated data.

Parameters:

• density (float) –
• home_range_proportion (float) – Number in [0, 1] range representing the proportion of home range area to total area.
• niche_size (float) – Proportion of total area that is adequate for species.
• parameters (dict) – The parameters dictionary must contain four keys: “alpha”, “hr_exp”, “density_exp” and “niche_size_exp”.

Returns:

occupancy

Return type:

float

ollin.core.utils.home_range_resolution(velocity, parameters=None)

Get discretization resolution from mean velocity.

Notes

This function is used throughout the package to select spatial resolution of site discretization for all home range calculations. Such resolution is dependant on mean velocity information, and possibly other model parameters.

Currently, the relation assumed is

\[resolution = velocity\]

More complicated relations might be used in the future.

Parameters:

• velocity (float) –
• parameters (dict, optional) – Possible parameters affecting the velocity -> resolution relation.

Returns:

resolution

Return type:

float

ollin.core.utils.home_range_to_velocity(home_range, parameters=None)

Get mean velocity from home range information.

Notes This function is used throughout the package to translate home range information to mean velocity. Each movement model produces a different relation between home range and mean velocity, but a single model is applied to all movement models. The general relationship assumed is:

\[home\_range = \alpha \cdot velocity^{\beta}\]

Parameters are then fitted using simulated data.

Parameters:

• home_range (float) –
• parameters (dict) – The parameters dictionary must contain at two keys, “exponent” and “alpha”.

Returns:

velocity

Return type:

float

ollin.core.utils.logit(y)

Logit function.

\[\mathop{logit}(y) = -log\left(\frac{1 - y}{y}\right)\]

ollin.core.utils.occupancy_resolution(home_range, parameters=None)

Get discretization resolution from home range.

Notes

This function is used throughout the package to select spatial resolution of site discretization for all occupancy calculations. Such resolution is dependant on home range information, and possibly some model parameters.

Currently, the relation assumed is

\[resolution = \sqrt{home\_range}\]

Parameters:

• home_range (float) –
• parameters (dict, optional) – Possible parameters affecting the home_range -> resolution relation.

Returns:

resolution

Return type:

float

ollin.core.utils.occupancy_to_density(occupancy, home_range_proportion, niche_size, parameters=None)

Get estimated density from occupancy information.

Notes

This function is used throughout the package to translate occupancy to density information. This relation also depends on the size of the home range in relation to the whole site’s area, and to the proportion of available adequate space, or size of true niche, see BaseSite.get_niche_size(). Each movement model produces a different relation between occupancy and density, but a single model (or family of functions) is applied to all movement models. The general relationship assumed is:

\[logit(o) = \alpha+\beta_1 log(d)+\beta_2 log(ns)+\beta_3 log(hrp)\]

where \(o, d, ns, hrp\) stand for occupancy, density, niche size and home range proportion, and \(logit(x) = - log(-1 + 1/x)\). Equivalently:

\[o = \frac{\alpha \cdot d^{\beta_1} \cdot ns^{\beta_2} \cdot hrp^{\beta_3}}{1 + \alpha \cdot d^{\beta_1} \cdot ns^{\beta_2} \cdot hrp^{\beta_3}}\]

Parameters are then fitted using simulated data.

Parameters:

• occupancy (float) –
• home_range_proportion (float) – Number in [0, 1] range representing the proportion of home range area to total area.
• niche_size (float) – Proportion of total area that is adequate for species.
• parameters (dict) – The parameters dictionary must contain four keys: “alpha”, “hr_exp”, “density_exp” and “niche_size_exp”.

Returns:

home_range

Return type:

float

ollin.core.utils.sigmoid(x)

Sigmoid function.

\[\sigma(x) = \frac{1}{1 + e^{-x}}\]

ollin.core.utils.velocity_modification(niche_size, parameters)

Get velocity modification at niche size.

Although for many movement models steps sizes are typically drawn from a distribution with a known mean, so that mean velocity can be controlled, some models include niche information in step size selection which could possible perturb mean step size. Therefore velocity correction is necessary.

The correction depends on the overall niche size, which is the proportion of total area with an adequate level of niche value (see BaseSite.get_niche_size()) and also on the movement model used.

Based on simulated data, the correct parameters for velocity correction can be obtained. See calibration.

Parameters:

• niche_size (float) –
• parameters (dict) – Dictionary holding the movement model parameters for velocity correction.

ollin.core.utils.velocity_to_home_range(velocity, parameters=None)

Get home range from mean velocity information.

Notes

This function is used throughout the package to translate mean velocity to home range information. Each movement model produces a different relation between home range and mean velocity, but a single model is applied to all movement models. The general relationship assumed is:

\[home\_range = \alpha \cdot velocity^{\beta}\]

Parameters are then fitted using simulated data.

Parameters:

• velocity (float) –
• parameters (dict) – The parameters dictionary must contain at two keys, “exponent” and “alpha”.

Returns:

home_range

Return type:

float