1. User guide

Users of the cpforager Python package only have to define a parameters dictionary that will be used for the data processing.

To do so, users must write a .yml configuration file containing both the name and the value of every required parameters. An example of a .yml configuration file can be found below :

# colony parameters
colony:
    name: BRA_FDN_MEI
    center: [-32.39280, -3.81980]
    box_longitude: [-32.3958, -32.3898]
    box_latitude: [-3.8226, -3.8170]

# local timezone
local_tz : America/Noronha

# cleaning parameters
max_possible_speed: 150.0

# trip segmentation parameters
dist_threshold: 2.0
speed_threshold: 5.0
nesting_speed: 1.0
trip_min_duration: 1200.0
trip_max_duration: 1209600.0
trip_min_length: 10.0
trip_max_length: 10000.0
trip_min_steps: 10

# dive segmentation parameters
diving_depth_threshold: -1.0
dive_min_duration: 2.0

# zero-offset correction
zoc_time_windows: [5.0, 3600.0]
zoc_quantiles: [0.5, 0.02]

# accelerometer parameters
odba_p_norm : 1
filter_type: rolling_avg
acc_time_window: 2.0

Details about each parameter can be found in cpforager.parameters.get_params(). Then, users can build the parameters dictionary using the cpforager.parameters.get_params() function and the path toward the .yml configuration file :

from cpforager import parameters
params = parameters.get_params([config_all])

This parameters dictionary is a required argument to the cpforager.GPS(), cpforager.TDR(), cpforager.AXY() and cpforager.GPS_TDR() constructors implemented in cpforager.

In case users want to use the cpforager package in a more systematic way with diverse datasets, my recommandation is to have one configuration file for each colony and one for each species (that have distinct trip and diving behaviours). These .yml files are then used to build the parameters dictionary :

from cpforager import parameters
params = parameters.get_params([config_colony, config_species, config_general])

Regarding the customisation of plots produced by cpforager, users should modify the plot parameters dictionary as follows :

from cpforager import parameters
plot_params = parameters.get_plot_params()
plot_params["fig_dpi"] = 300

Details about each parameter can be found in cpforager.parameters.get_plot_params(). For more practical details, see Examples section.