Movement Module

Module defining Movement Data class and Movement Analyzer

Either simulated data or data incoming from real telemetry data can be stored in a MovementData object. The main information held in such an object is the full history of individual positions arranged in an array of shape [num_individuals, time_steps, 2]. This information can then be plotted for trajectory visualization, or used in further processing.

Data produced by simulation can be stored in a specialized type of MovementData which also holds movement model information. See Movement.

Movement analysis, such as distribution of velocities, heading angles and turning angles can be extracted and stored in an MovementAnalysis object.

class ollin.core.movement.Movement(site, movement_data, movement_model, velocity, home_range=None)

Class for simulated movement data.

Extension of MovementData class. When movement data arises from simulation, the applied movement model is also stored within the object.

site

Site – Information of Site at which movement took place.

movement_data

array – Array of shape [num_individuals, time_steps, 2] holding coordinate information of individual location through movement.

times

array – Array of shape [time_steps] with time at which the time steps took place. Units are in days.

home_range

float or None – Home range value of species. Only necessary for occupancy calculation. See Occupancy.

movement_model

MovementModel – Movement model used to generate movement.

velocity

float – Mean velocity (in Km/Day) used to movement simulation.

extend(days, inplace=True)

Extend movement data with new simulated movement.

Use last position as starting point to generate new simulated movement and append to existing. This method will use the same mean velocity and movement model to generate new movement.

Parameters:

• days (int) – Number of days of new simulated movement.
• inplace (bool, optional) – If true, only Movement object attributes will be changed, otherwise a copy of the object will be made with the new movement data.

Returns:

extension – Movement object with extended movement data.

Return type:

Movement

classmethod simulate(site, days=None, num=None, occupancy=None, home_range=None, velocity=None, parameters=None, movement_model='variable_levy')

Make simulated movement data.

Use some movement model from the model library to generate simulated movement data for some virtual species with a fixed velocity (in Km/Day).

Number of individuals and mean velocity must be specified, but it is also possible to use home range and/or occupancy as proxies for density and mean velocity, respectively. The faithfulness of these proxies depend on the correct calibration of the parameters associated to the movement model.

If using a movement model from the library, these should be pre-calibrated, and hence home range (or occupancy) can be used to estimate mean velocity (or density) with some degree of accuracy.

Otherwise the user must first be sure that the model is calibrated. See calibration.

Parameters:

• site (Site) – Site in which simulate movement.
• days (int, optional) – Number of simulation days. Movement models include a steps_per_day parameter, so number of simulated time steps is days * steps_per_day. Defaults to 365.
• num (int, optional) – Number of individuals to include in simulation. If not given, occupancy argument must be provided.
• occupancy (float, optional) – If provided the relationship occupancy <-> density will be used to estimate the number of individuals to include in simulation. See core.utils.occupancy_to_density().
• velocity (float, optional) – Mean velocity in Km/Day to use in movement model. If not given, home range argument must be provided.
• home_range (float, optional) – Home range of simulated species. If provided the relationship home_range <-> mean velocity will be used to estimate the mean velocity of species. See core.utils.home_range_to_velocity().
• movement_model (str or movement_models.MovementModel) – Name of movement model in library o MovementModel instance to use to generate simulated movement.

Returns:

mov – Movement instance with simulated movement data.

Return type:

Movement

Raises:

ValueError – If both num and occupancy, or velocity and home_range, are given simultaneously.

class ollin.core.movement.MovementData(site, movement_data, times, home_range=None)

Container for Movement data.

All animal movement data can be stored in an array of shape of shape [num_individuals, time_steps, 2] which represents the positions of every individual along some time interval. If:

x = array[i, j, 0]
y = array[i, j, 1]

then the i-th individual was at the place with (x, y)-coordinates at the j-th time step.

Apart from spatial information, times at which the time steps where taken are stored in another array of shape [time_steps].

site

Site – Information of Site at which movement took place.

movement_data

array – Array of shape [num_individuals, time_steps, 2] holding coordinate information of individual location through movement.

times

array – Array of shape [time_steps] with time at which the time steps took place. Units are in days.

home_range

float or None – Home range value of species. Only necessary for occupancy calculation. See Occupancy.

analyze(analyzer)

Analyze movement with given analyzer.

Parameters:analyzer (str or MovementAnalyzer) – Name of analyzer or movement analyzer class to analyze with. Returns:analyzer – Analyzer instance with analysis results. Return type:MovementAnalyzer Raises:NotImplementedError: – When analyzer name was not found in the library.

num_slice(key)

Extract motion from slice of individuals.

Select a subset of individuals from motion data using a slice.

Parameters:key (int or list or tuple or slice) – If key is an integer the result will be a MovementData object holding only motion data for the corresponding individual. If key is a list or tuple, its contents will be passed to the slice() function, and said slice will be extracted from data array in the first axis, and returned in an MovementData object. Returns:newcopy – New MovementData object sharing site and times attributes but with movement data corresponding to individuals slice. Return type:MovementData

Example

To extract the movement of the first ten individuals:

first_ten = movement.num_slice((None, 10, None))

To extract the movement of the last 20 individuals:

last_20 = movement.num_slice((-20, None, None))

To extract all even individuals:

even = movement.num_slice((None, None, 2))

plot(ax=None, figsize=(10, 10), include=None, num=10, steps=1000, mov_cmap='Greens', simplify=None, **kwargs)

Plot trajectories from Movement data.

Movement Data plotting adds the following optional components to the plot:

1. “trajectories”: If present in include list, some trajectories will be plotted as a broken line. Trajectory simplification is possible through the simplify keyword argument. Several trajectories will be plotted. Color of line will be chosen at random from some colormap.

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

Parameters:

• ax (matplotlib.axes.Axes, optional) – Axes object in which to plot movement trajectories.
• 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.
• num (int, optional) – Number of trajectories to plot. Defaults to 10.
• steps (int, optional) – Number of time steps to plot in trajectories. Defaults to all.
• mov_cmap (str, optional) – Name of colormap to choose trajectories colors from. See matplotlib.cm to see all options. Defaults to ‘Greens’.
• simplify (int, optional) – Trajectories will be forced to consist of this number of points, so if given, some time steps might be skipped.
• kwargs (dict, optional) – All other keyword arguments will be passed to the Site’s plotting method.

Returns:

ax – Return axes for further plotting.

Return type:

matplotlib.axes.Axes

sample(num)

Extract a sample of individual movement.

Select a random sample of individuals of a given size to form a new MovementData object.

Parameters:num (int) – Size of sample Returns:newcopy – Movement data corresponding to sample. Return type:MovementData

select(selection)

Select a subset of individual movement.

Use an array of indices to select a subset of individuals and return movement data of the corresponding individuals.

Parameters:selection (array or tuple or list) – List of indices of selected individuals Returns:newcopy – Movement data of selected individuals. Return type:MovementData

time_slice(key)

Select a slice of timesteps from movement.

Parameters:key (int or list or tuple or slice) – If key is integer the resulting MovementData object will only hold the individuals position at the corresponding timestep. If key is list or tuple, its contents will be passed to the :py:func:slice function and the slice will be used to extract some times steps from the movement data. Returns:newcopy – Movement data with selected time steps. Return type:MovementData

Example

To select the first 10 days of movement:

first_10_days = movement_data.time_slice((None, 10, None))

To select the last 20 days of movement:

last_20_days = movement_data.time_slice((-20, None, None))

To select every other step:

every_other = movement_data.time_slice((None, None, 2))