Time-Depth Recorder time series#

Top-level class for interacting with diveMove

The TDR class aims to be a comprehensive class to encapsulate the processing of TDR records from a NetCDF data file.

Processing includes detection and quantification of periods of major activities in a TDR record, calibrating depth readings to generate summaries of diving behaviour. These procedures include wet/dry phase detection, zero-offset correction (ZOC) of depth, detection of dives, as well as proper labelling of the latter, among others utilities for the analysis of TDR records.

All core procedures are encapsulated in TDR, and are controlled by a set of user-defined variables in a configuration file, and systematically executed systematically by function calibrate(). This function can be used as a template for custom processing using different sequences. User-defined variables can also be directly specified as a dictionary, which is a class attribute. The standard approach follows the logical processing sequence described below:

Zero-offset correction
Detection of wet phases
Detection of dives
Detection of dive phases
Speed calibration (if required)
Calculation of statistics

Class TDR methods implement these steps. This module instantiates an R session to interact with low-level functions and methods of package diveMove.

Calibration and phase detection#

`TDR.read_netcdf`(tdr_file[, depth_name, ...])	Instantiate object by loading Dataset from NetCDF file
`TDR.zoc`([method])	Apply zero offset correction to depth measurements
`TDR.detect_wet`([dry_thr, wet_cond, wet_thr, ...])	Detect wet/dry activity phases
`TDR.detect_dives`(dive_thr)	Identify dive events
`TDR.detect_dive_phases`(dive_model[, ...])	Detect dive phases
`TDR.calibrate_speed`([tau, contour_level, z, bad])	Calibrate speed measurements

Analysis and summaries#

`TDR.dive_stats`([depth_deriv])	Calculate dive statistics in TDR records
`TDR.time_budget`([ignore_z, ignore_du])	Summary of wet/dry activities at the broadest time scale
`TDR.stamp_dives`([ignore_z])	Identify the wet activity phase corresponding to each dive

Plotting#

`TDR.plot`([concur_vars, concur_var_titles])	Plot TDR object
`TDR.plot_zoc`([xlim, ylim])	Plot zero-offset correction filters
`TDR.plot_phases`([diveNo, concur_vars, ...])	Plot major phases found on TDR object
`TDR.plot_dive_model`([diveNo])	Plot dive model for selected dive

Accessors#

`TDR.extract_dives`(diveNo, **kwargs)	Extract TDR data corresponding to a particular set of dives
`TDR.get_depth`([kind])	Retrieve depth records
`TDR.get_dive_deriv`(diveNo[, phase])	Retrieve depth spline derivative for a given dive
`TDR.get_dives_details`(key[, columns])	Accessor for the dives attribute
`TDR.get_phases_params`(key)	Return parameters used for identifying wet/dry or diving phases.
`TDR.get_speed`([kind])	Retrieve speed records
`TDR.get_tdr`([calib_depth, calib_speed])	Return a copy of TDR Dataset

Functions#

`calibrate`(tdr_file[, config_file])	Perform all major TDR calibration operations
`dump_config_template`(fname)	Dump configuration template file

class skdiveMove.TDR(*args, **kwargs)[source]#

Base class encapsulating TDR objects and processing

Comprehensive TDR processing methods.

speed_calib_fit#

Model object fit by quantile regression for speed calibration.

Type:: quantreg model fit

Notes

See help(TDR) for inherited attributes. This class extends TDRPhases.

See also

xarray.Dataset

Examples

Construct an instance from diveMove example dataset

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()

Plot the TDR object

>>> tdrX.plot()  
(<Figure ... 1 Axes>, <Axes: ...>)

calibrate_speed(tau=0.1, contour_level=0.1, z=0, bad=[0, 0], **kwargs)[source]#

Calibrate speed measurements

Set the speed_calib_fit attribute. This method calibrates speed readings following the procedure outlined in Blackwell et. al. (1999) [1].

Parameters:

tau (float, optional) – Quantile on which to regress speed on rate of depth change.
contour_level (float, optional) – The mesh obtained from the bivariate kernel density estimation corresponding to this contour will be used for the quantile regression to define the calibration line.
z (float, optional) – Only changes in depth larger than this value will be used for calibration.
bad (array_like, optional) – Two-element array_like indicating that only rates of depth change and speed greater than the given values should be used for calibration, respectively.
**kwargs – Optional keyword arguments listed below.
plot (bool, default True) – Whether to plot calibration results.
ax (matplotlib.Axes, optional) – A Axes instance to use as target. Default is to create one.

References

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd(has_speed=True)
>>> tdrX.zoc("offset", offset=3)
>>> tdrX.calibrate_speed(z=2)

detect_dive_phases(dive_model, smooth_par=0.1, knot_factor=3, descent_crit_q=0, ascent_crit_q=0)#

Detect dive phases

Complete filling the dives attribute. The process for each dive begins by taking all observations below the dive detection threshold, and setting the beginning and end depths to zero, at time steps prior to the first and after the last, respectively. The latter ensures that descent and ascent derivatives are non-negative and non-positive, respectively, so that the end and beginning of these phases are not truncated. The next step is to fit a model to each dive. Two models can be chosen for this purpose: unimodal (default) and smooth.spline (see Notes).

Both models consist of a cubic spline, and its first derivative is evaluated to investigate changes in vertical rate. Therefore, at least 4 observations are required for each dive, so the time series is linearly interpolated at equally spaced time steps if this limit is not achieved in the current dive. Wiggles at the beginning and end of the dive are assumed to be zero offset correction errors, so depth observations at these extremes are interpolated between zero and the next observations when this occurs.

This procedure generates a categorical variable with levels D, DB, B, BA, DA, A, and X, breaking the input into descent, descent/bottom, bottom, bottom/ascent, ascent, descent/ascent (occurring when no bottom phase can be detected) and non-dive (surface), respectively.

Parameters:

dive_model ({"unimodal", "smooth.spline"}) – Model to use for each dive for the purpose of dive phase identification. One of smooth.spline or unimodal, to choose among smoothing spline or unimodal regression. For dives with less than five observations, smoothing spline regression is used regardless.
smooth_par (float, optional) – Amount of smoothing when dive.model="smooth.spline". If it is None, then the smoothing parameter is determined by Generalized Cross-validation (GCV). Ignored with default dive.model="unimodal".
knot_factor (int, optional) – Multiplier for the number of samples in the dive. This is used to construct the time predictor for the derivative.
descent_crit_q (float, optional) – Critical quantile of rates of descent below which descent is deemed to have ended.
ascent_crit_q (float, optional) – Critical quantile of rates of ascent above which ascent is deemed to have started.

Notes

1. Unimodal method: in this default model, the spline is constrained to be unimodal [2], assuming the diver must return to the surface to breathe. The model is fitted using R’s uniReg package. This model and constraint are consistent with the definition of dives in air-breathers, so is appropriate for this group of divers. A major advantage of this approach over the next one is that the degree of smoothing is determined via restricted maximum likelihood, and has no influence on identifying the transition between descent and ascent. Therefore, unimodal regression splines make the latter transition clearer compared to using smoothing splines. Note that dives with less than five samples are fit using smoothing splines regardless, as they produce the same fit as unimodal regression but much faster. Therefore, ensure that the parameters for that model are appropriate for the data, although defaults are reasonable.

2. Smooth spline: in this model, specified via dive_model="smooth.spline", a smoothing spline is used to model each dive, using the chosen smoothing parameter. Dive phases identified via this model, however, are highly sensitive to the degree of smoothing (smooth_par) used, thus making it difficult to determine what amount of smoothing is adequate.

The first derivative of the spline is evaluated at a set of knots to calculate the vertical rate throughout the dive and determine the end of descent and beginning of ascent. This set of knots is established using a regular time sequence with beginning and end equal to the extremes of the input sequence, and with length equal to \(N \times knot\_factor\). Equivalent procedures are used for detecting descent and ascent phases.

Once one of the models above has been fitted to each dive, the quantile corresponding to (descent_crit_q) of all the positive derivatives (rate of descent) at the beginning of the dive is used as threshold for determining the end of descent. Descent is deemed to have ended at the first minimum derivative, and the nearest input time observation is considered to indicate the end of descent. The sign of the comparisons is reversed for detecting the ascent. If observed depth to the left and right of the derivative defining the ascent are the same, the right takes precedence.

The particular dive phase categories are subsequently defined using simple set operations.

References

See also

TDR.detect_dives

Examples

ZOC using the “offset” method for convenience

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd("TDRPhases")
>>> tdrX.zoc("offset", offset=3)

Detect wet/dry phases and dives with 3 m threshold

>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)

Detect dive phases using the “unimodal” method and selected parameters

>>> tdrX.detect_dive_phases("unimodal", descent_crit_q=0.01,
...                         ascent_crit_q=0, knot_factor=20)

detect_dives(dive_thr)#

Identify dive events

Set the dives attribute’s row_ids dictionary element, and update the wet_act attribute’s phases dictionary element. Whenever the zero-offset corrected depth in an underwater phase is below the specified dive threshold. A new categorical variable with finer levels of activity is thus generated, including U (underwater), and D (diving) in addition to the ones described above.

Parameters:: dive_thr (float) – Threshold depth below which an underwater phase should be considered a dive.

See also

TDR.detect_dive_phases

Examples

ZOC using the offset method for convenience

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd("TDRPhases")
>>> tdrX.zoc("offset", offset=3)

Detect wet/dry phases and dives with 3 m threshold

>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)

detect_wet(dry_thr=70, wet_cond=None, wet_thr=3610, interp_wet=False)#

Detect wet/dry activity phases

A categorical variable is created with value L (dry) for rows with null depth samples and value W (wet) otherwise. This assumes that TDRs were programmed to turn off recording of depth when instrument is dry (typically by means of a salt-water switch). If this assumption cannot be made for any reason, then a boolean vector as long as the time series can be supplied to indicate which observations should be considered wet. The duration of each of these phases of activity is subsequently calculated. If the duration of a dry phase (L) is less than a threshold (configuration variable dry_thr), then the values in the factor for that phase are changed to W (wet). The duration of phases is then recalculated, and if the duration of a phase of wet activity is less than another threshold (variable wet_thr), then the corresponding value for the factor is changed to Z (trivial wet). The durations of all phases are recalculated a third time to provide final phase durations.

Some instruments produce a peculiar pattern of missing data near the surface, at the beginning and/or end of dives. The argument interp_wet may help to rectify this problem by using an interpolating spline function to impute the missing data, constraining the result to a minimum depth of zero. Please note that this optional step is performed after ZOC and before identifying dives, so that interpolation is performed through dry phases coded as wet because their duration was briefer than dry_thr. Therefore, dry_thr must be chosen carefully to avoid interpolation through legitimate dry periods.

Parameters:

dry_thr (float, optional) – Dry error threshold in seconds. Dry phases shorter than this threshold will be considered as wet.
wet_cond (bool mask, optional) – A Pandas.Series bool mask indexed as depth. It indicates which observations should be considered wet. If it is not provided, records with non-missing depth are assumed to correspond to wet conditions. Default is generated from testing for non-missing depth.
wet_thr (float, optional) – Wet threshold in seconds. At-sea phases shorter than this threshold will be considered as trivial wet.
interp_wet (bool, optional) – If True, then an interpolating spline function is used to impute NA depths in wet periods (after ZOC). Use with caution: it may only be useful in cases where the missing data pattern in wet periods is restricted to shallow depths near the beginning and end of dives. This pattern is common in some satellite-linked TDRs.

Notes

Unlike diveMove, the beginning/ending times for each phase are not stored with the class instance, as this information can be retrieved via the time_budget() method.

Examples

ZOC using the “offset” method for convenience

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd("TDRPhases")
>>> tdrX.zoc("offset", offset=3)

Detect wet/dry phases

>>> tdrX.detect_wet()

Access the “phases” and “dry_thr” attributes

>>> tdrX.wet_dry  
                     phase_id phase_label
date_time
2002-01-05 ...              1           L
...

dive_stats(depth_deriv=True)[source]#

Calculate dive statistics in TDR records

Parameters:

depth_deriv (bool, optional) – Whether to compute depth derivative statistics.

Returns:

DataFrame indexed by dive number, having the following columns:

begdesc: time stamp for the start of each dive;

enddesc: time stamp for the descent’s end;

begasc: time stamp for the beginning of the ascent;

desctime: duration of descent;

botttim: duration of the bottom phase;

asctim: duration of ascent;

divetim: dive duration;

descdist: last descent depth;

bottdist: sum of the absolute depth differences while at the bottom of the dive; a measure of the amount of “wiggling” while at the bottom;

ascdist: first ascent depth;

bottdep_mean: mean bottom depth;

bottdep_median: median bottom depth;

bottdep_sd: standard deviation of bottom depths;

maxdep: maximum depth;

desc_tdist: descent total distance, estimated from speed;

desc_mean_speed: descent mean speed;

desc_angle: descent mean speed;

bott_tdist: total distance at the bottom, estimated from speed;

bott_mean_speed: mean speed at the bottom;

asc_tdist: ascent total distance, estimated from speed;

asc_mean_speed: ascent mean speed;

asc_angle: ascent angle, relative to bottom plane;

postdive_dur: postdive duration;

postdive_tdist: postdive total distance, estimated from speed;

postdive_mean_speed: postdive mean speed.

If depth_deriv=True (default), 21 additional columns with the minimum, first quartile, median, mean, third quartile, maximum, and standard deviation of the depth derivative for each phase of the dive are included.

Return type:

pandas.DataFrame

Notes

This method is homologous to diveMove’s diveStats function.

Examples

ZOC using the “filter” method

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd(has_speed=True)

>>> # Window lengths and probabilities
>>> DB = [-2, 5]
>>> K = [3, 5760]
>>> P = [0.5, 0.02]
>>> tdrX.zoc("offset", offset=3)
>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)
>>> tdrX.detect_dive_phases("unimodal", descent_crit_q=0.01,
...                         ascent_crit_q=0, knot_factor=20)
>>> tdrX.dive_stats()  
                begdesc  ... postdive_mean_speed
1   2002-01-05 ...                      1.398859
2   ...

extract_dives(diveNo, **kwargs)[source]#

Extract TDR data corresponding to a particular set of dives

Parameters:

diveNo (array_like, optional) – List of dive numbers (1-based) to plot.
**kwargs – Optional keyword arguments passed to get_tdr()

Return type:

xarray.Dataset

See also

TDR.get_tdr

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.zoc("offset", offset=3)
>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)
>>> tdrX.detect_dive_phases("unimodal", descent_crit_q=0.01,
...                         ascent_crit_q=0, knot_factor=20)
>>> tdrX.extract_dives(diveNo=20)  
<xarray.Dataset> ...
Dimensions: ...

get_depth(kind='measured')[source]#

Retrieve depth records

Parameters:: kind ({"measured", "zoc"}) – Which depth to retrieve.
Return type:: xarray.DataArray

See also

TDR.get_tdr, TDR.get_speed

get_dive_deriv(diveNo, phase=None)#

Retrieve depth spline derivative for a given dive

Parameters:

diveNo (int) – Dive number to retrieve derivative for.
phase ({"descent", "bottom", "ascent"}) – If provided, the dive phase to retrieve data for.

Returns:

out

Return type:

pandas.DataFrame

get_dives_details(key, columns=None)#

Accessor for the dives attribute

Parameters:

key ({"row_ids", "model", "splines", "spline_derivs", crit_vals}) – Name of the key to retrieve.
columns (array_like, optional) – Names of the columns of the dataframe in key, when applicable.

get_phases_params(key)#

Return parameters used for identifying wet/dry or diving phases.

Parameters:: key ({'wet_dry', 'dives'})
Returns:: out
Return type:: dict

get_speed(kind='measured')[source]#

Retrieve speed records

Parameters:: kind ({"measured", "calibrated"}) – Type of speed to retrieve.
Return type:: xarray.DataArray

See also

TDR.get_tdr, TDR.get_depth

get_tdr(calib_depth=True, calib_speed=True)[source]#

Return a copy of TDR Dataset

Parameters:

calib_depth (bool, optional) – Whether to return calibrated depth measurements.
calib_speed (bool, optional) – Whether to return calibrated speed measurements.

Return type:

xarray.Dataset

See also

TDR.get_depth, TDR.get_speed

plot(concur_vars=None, concur_var_titles=None, **kwargs)[source]#

Plot TDR object

Parameters:

concur_vars (str or list, optional) – String or list of strings with names of columns in input to select additional data to plot.
concur_var_titles (str or list, optional) – String or list of strings with y-axis labels for concur_vars.
**kwargs – Optional keyword arguments passed to plotting function, including those listed below. Additional arguments are passed to underlying plotting method.
xlim (tuple of (float, float)) – Minimum and maximum limits for x axis. Ignored when concur_vars=None.
ylim (tuple of (float, float)) – Minimum and maximum limits for y axis for data other than depth.
depth_lim (array_like of (float, float)) – Minimum and maximum limits for depth to plot.
xlab (str) – Label for x axis.
ylab_depth (str) – Label for y axis for depth.
xlab_format (str) – Format string for formatting the x axis.
sunrise_time (str) – Time of sunrise, in 24 hr format. This is used for shading night time.
sunset_time (str) – Time of sunset, in 24 hr format. This is used for shading night time.
night_col (str) – Color for shading night time.
dry_time (pandas.DataFrame) – Two-column DataFrame with beginning and ending times corresponding to periods considered to be dry.
phase_cat (pandas.Series) – Categorical series dividing rows into sections.

Returns:

Figure, Axes instances.

Return type:

tuple

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.plot(xlim=["2002-01-05 21:00:00", "2002-01-06 04:10:00"],
...           depth_lim=[95, -1])  
(<Figure ... with 1 Axes>, <Axes: ...'>)

plot_dive_model(diveNo=None, **kwargs)[source]#

Plot dive model for selected dive

Diagnostic double-panel plot of dive models for selected dives. The top panel shows depth against time, the cubic spline smoother, the identified descent and ascent phases (which form the basis for identifying the rest of the dive phases), while the bottom panel shows the first derivative of the smooth trace.

Parameters:

diveNo (array_like, optional) – List of dive numbers (1-based) to plot.
**kwargs – Optional keyword arguments passed to subplots().

Returns:

Figure, Axes instances.

Return type:

tuple

See also

TDR.detect_dive_phases

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.zoc("offset", offset=3)
>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)
>>> tdrX.detect_dive_phases("unimodal", descent_crit_q=0.01,
...                         ascent_crit_q=0, knot_factor=20)
>>> tdrX.plot_dive_model(diveNo=20,
...                      figsize=(10, 10))  
(<Figure ... with 2 Axes>, (<Axes: ...>, <Axes: ...>))

plot_phases(diveNo=None, concur_vars=None, concur_var_titles=None, surface=False, **kwargs)[source]#

Plot major phases found on TDR object

Parameters:

diveNo (array_like, optional) – List of dive numbers (1-based) to plot.
concur_vars (str or list, optional) – String or list of strings with names of columns in input to select additional data to plot.
concur_var_titles (str or list, optional) – String or list of strings with y-axis labels for concur_vars.
surface (bool, optional) – Whether to plot surface readings.
**kwargs – Optional keyword arguments passed to plotting function (see plot())

Returns:

Figure, Axes instances.

Return type:

tuple

See also

TDR.detect_wet

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.zoc("offset", offset=3)
>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)
>>> tdrX.detect_dive_phases("unimodal", descent_crit_q=0.01,
...                         ascent_crit_q=0, knot_factor=20)
>>> tdrX.plot_phases(list(range(250, 300)),
...                  surface=True)  
(<Figure ... with 1 Axes>, <Axes: ...>)

plot_zoc(xlim=None, ylim=None, **kwargs)[source]#

Plot zero-offset correction filters

Compare the zero-offset corrected depth with the uncorrected signal, or the progress attained in each of the filters during recursive filtering for zero-offset correction, as illustrated in Luque and Fried (2011) [3].

Parameters:

xlim (array_like, optional) – array_like with minimum and maximum limits for x- and y-axis, respectively.
ylim (array_like, optional) – array_like with minimum and maximum limits for x- and y-axis, respectively.
**kwargs – Optional keyword arguments passed to subplots().

Returns:

Figure, Axes instances.

Return type:

tuple

See also

TDR.zoc

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> # Window lengths and probabilities
>>> DB = [-2, 5]
>>> K = [3, 5760]
>>> P = [0.5, 0.02]
>>> tdrX.zoc("filter", k=K, probs=P, depth_bounds=DB)
>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)
>>> tdrX.detect_dive_phases("unimodal", descent_crit_q=0.01,
...                         ascent_crit_q=0, knot_factor=20)
>>> tdrX.plot_zoc()  
(<Figure ... with 3 Axes>, array([<Axes: ...'>,
    <Axes: ...'>, <Axes: ...>], dtype=object))

classmethod read_netcdf(tdr_file, depth_name='depth', time_name='timestamp', subsample=None, has_speed=False, **kwargs)#

Instantiate object by loading Dataset from NetCDF file

Parameters:

tdr_file (str) – As first argument for xarray.load_dataset().
depth_name (str, optional) – Name of data variable with depth measurements. Default: “depth”.
time_name (str, optional) – Name of the time dimension in the dataset.
subsample (str, optional) – Subsample dataset at given frequency specification. See pandas offset aliases.
has_speed (bool, optional) – Weather data includes speed measurements. Column name must be one of [“velocity”, “speed”]. Default: False.
**kwargs – Optional keyword arguments passed to xarray.load_dataset().

See also

xarray.Dataset, xarray.load_dataset

Returns:: obj – Class matches the caller.
Return type:: TDRSource, ZOC, TDRPhases, or TDR

stamp_dives(ignore_z=True)#

Identify the wet activity phase corresponding to each dive

Parameters:: ignore_z (bool, optional) – Whether to ignore trivial aquatic periods.
Returns:: out – DataFrame indexed by dive ID, and three columns identifying which phase thy are in, and the beginning and ending time stamps.
Return type:: pandas.DataFrame

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd("TDRPhases")
>>> tdrX.zoc("offset", offset=3)
>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)
>>> tdrX.detect_dive_phases("unimodal", descent_crit_q=0.01,
...                         ascent_crit_q=0, knot_factor=20)
>>> tdrX.stamp_dives(ignore_z=True)  
         phase_id                 beg                 end
dive_id
1               2 2002-01-05      ... 2002-01-06      ...

time_budget(ignore_z=True, ignore_du=True)#

Summary of wet/dry activities at the broadest time scale

Parameters:

ignore_z (bool, optional) – Whether to ignore trivial aquatic periods.
ignore_du (bool, optional) – Whether to ignore diving and underwater periods.

Returns:

out – DataFrame indexed by phase id, with categorical activity label for each phase, and beginning and ending times.

Return type:

pandas.DataFrame

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd("TDRPhases")
>>> tdrX.zoc("offset", offset=3)
>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)
>>> tdrX.detect_dive_phases("unimodal", descent_crit_q=0.01,
...                         ascent_crit_q=0, knot_factor=20)
>>> tdrX.time_budget(ignore_z=True,
...                  ignore_du=True)  
                         beg phase_label                 end
phase_id
1        2002-01-05      ...           L 2002-01-05      ...
...

zoc(method='filter', **kwargs)#

Apply zero offset correction to depth measurements

This procedure is required to correct drifts in the pressure transducer of TDR records and noise in depth measurements. Three methods are available to perform this correction.

Method offset can be used when the offset is known in advance, and this value is used to correct the entire time series. Therefore, offset=0 specifies no correction.

Method filter implements a smoothing/filtering mechanism where running quantiles can be applied to depth measurements in a recursive manner [3]. The method calculates the first running quantile defined by the first probability in a given sequence on a moving window of size specified by the first integer supplied in a second sequence. The next running quantile, defined by the second supplied probability and moving window size, is applied to the smoothed/filtered depth measurements from the previous step, and so on. The corrected depth measurements (d) are calculated as:

\[d = d_{0} - d_{n}\]

where \(d_{0}\) is original depth and \(d_{n}\) is the last smoothed/filtered depth. This method is under development, but reasonable results can be achieved by applying two filters (see Examples). The default na_rm=True works well when there are no level shifts between non-NA phases in the data, but na_rm=False is better in the presence of such shifts. In other words, there is no reason to pollute the moving window with null values when non-null phases can be regarded as a continuum, so splicing non-null phases makes sense. Conversely, if there are level shifts between non-null phases, then it is better to retain null phases to help the algorithm recognize the shifts while sliding the window(s). The search for the surface can be limited to specified bounds during smoothing/filtering, so that observations outside these bounds are interpolated using the bounded smoothed/filtered series.

Once the entire record has been zero-offset corrected, remaining depths below zero, are set to zero, as these are assumed to indicate values at the surface.

Parameters:

method ({"filter", "offset"}) – Name of method to use for zero offset correction.
**kwargs – Optional keyword arguments passed to the chosen method (_offset_depth(), _filter_depth())

References

Examples

ZOC using the “offset” method

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.zoc("offset", offset=3)

Using the “filter” method

>>> # Window lengths and probabilities
>>> DB = [-2, 5]
>>> K = [3, 5760]
>>> P = [0.5, 0.02]
>>> tdrX.zoc(k=K, probs=P, depth_bounds=DB)

Plot the filters that were applied

>>> tdrX.plot_zoc(ylim=[-1, 10])  
(<Figure ... with 3 Axes>, array([<Axes: ...>,
    <Axes: ...>, <Axes: ...>], dtype=object))

property depth#

property depth_zoc#

property speed#

property wet_dry#

property zoc_params#

skdiveMove.calibrate(tdr_file, config_file=None)[source]#

Perform all major TDR calibration operations

Detect periods of major activities in a TDR object, calibrate depth readings, and speed if appropriate, in preparation for subsequent summaries of diving behaviour.

This function is a convenience wrapper around detect_wet(), detect_dives(), detect_dive_phases(), zoc(), and calibrate_speed(). It performs wet/dry phase detection, zero-offset correction of depth, detection of dives, as well as proper labelling of the latter, and calibrates speed data if appropriate.

Due to the complexity of this procedure, and the number of settings required for it, a calibration configuration file (JSON) is used to guide the operations.

Parameters:

tdr_file (str, Path or xarray.backends.*DataStore) – As first argument for xarray.load_dataset().
config_file (str) – A valid string path for TDR calibration configuration file.

Returns:

out

Return type:

TDR

See also

dump_config_template: configuration template

skdiveMove.dump_config_template(fname)[source]#

Dump configuration template file

Dump a json configuration template file to set up TDR calibration.

Parameters:: fname (str or file-like) – A valid string path, or file-like object, for output file.

Examples

>>> dump_config_template("tdr_config.json")  

Edit the file to your specifications.