TDR class

TDR objects homologous to R package diveMove’s main classes

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

This module instantiates an R session to interact with low-level functions and methods of package diveMove.

Class & Main Methods Summary

See API section for details on minor methods.

Calibration and phase detection

TDR(*args, **kwargs)

Base class encapsulating TDR objects and processing

TDR.zoc([method])

Zero offset correction

TDR.detect_wet(**kwargs)

Detect wet/dry activity phases

TDR.detect_dives(dive_thr)

Identify dive events

TDR.detect_dive_phases(**kwargs)

Detect dive phases

TDR.calibrate([zoc_method, dry_thr, …])

Calibrate TDR object

TDR.calibrate_speed([tau, contour_level, z, …])

Calibrate speed measurements

Analyses

TDR.dive_stats([depth_deriv])

Calculate dive statistics in TDR records

TDR.time_budget(**kwargs)

Summary of wet/dry activities at the broadest scale

TDR.stamp_dives(**kwargs)

Identify the wet/dry 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 the object

TDR.plot_dive_model([diveNo])

Plot dive model for selected dive

API

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

Base class encapsulating TDR objects and processing

TDR subclasses TDRSource to provide comprehensive TDR processing capabilities.

tdr_file

String indicating the file where data comes from.

Type

str

tdr

Dataset with input data.

Type

xarray.Dataset

depth_name

Name of Dataset variable with depth measurements.

Type

str

has_speed

Whether input data include speed measurements.

Type

bool

speed_name

Name of Dataset variable with the speed measurements.

Type

str

zoc_depth

Instance to perform and store zero offset correction operations for depth.

Type

ZOC

phases

Instance for performing wet/dry and dive phase detection.

Type

TDRPhases

speed_calib_fit

Model object fit by quantile regression for speed calibration.

Type

quantreg model fit

Examples

Construct an instance from diveMove example dataset

>>> rstr = ('system.file(file.path("data", "dives.csv"), '
...         'package="diveMove", mustWork=TRUE)')
>>> data_path = robjs.r(rstr)[0]
>>> tdrX = TDR(data_path, sep=";", compression="bz2")

For convenience, the above operation is wrapped in the function get_diveMove_sample_data.

Plot the TDR object

>>> tdrX.plot()
calibrate(zoc_method='filter', dry_thr=70, wet_cond=None, wet_thr=3610, interp_wet=False, dive_thr=4, dive_model='unimodal', smooth_par=0.1, knot_factor=3, descent_crit_q=0, ascent_crit_q=0, **kwargs)[source]

Calibrate TDR object

Convenience method to set all instance attributes.

Parameters
  • zoc_method ({"filter", "offset"}, optional) – Name of method to use for zero offset correction.

  • dry_thr (float, optional) –

  • wet_cond (bool mask, optional) –

  • wet_thr (float, optional) –

  • dive_thr (float, optional) –

  • dive_model ({"unimodal", "smooth.spline"}, optional) –

  • smooth_par (float, optional) –

  • knot_factor (int, optional) –

  • ascent_crit_q (descent_crit_q,) –

  • **kwargs (optional keyword arguments) –

    Passed to TDR.zoc() method:

    • method ‘filter’: (‘k’, ‘probs’, ‘depth_bounds’ (defaults to range), ‘na_rm’ (defaults to True)).

    • method ‘offset’: (‘offset’).

Notes

This method is homologous to diveMove’s calibrateDepth function.

Examples

ZOC using the “filter” method

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> # Window lengths and probabilities
>>> DB = [-2, 5]
>>> K = [3, 5760]
>>> P = [0.5, 0.02]
>>> tdrX.calibrate(dive_thr=3, zoc_method="filter",
... k=K, probs=P, depth_bounds=DB, descent_crit_q=0.01,
... knot_factor=20)

Plot dive phases

>>> tdrX.plot_phases()

Plot dive model for a dive

>>> tdrX.plot_dive_model(40)
calibrate_speed(tau=0.1, contour_level=0.1, z=0, bad=[0, 0], save_fig=False, fname=None, **kwargs)[source]

Calibrate speed measurements

Set the speed_calib_fit attribute

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 value should be used for calibration, respectively.

  • save_fig (bool, optional) – Whether to save the plot.

  • fname (str, optional) – A path to save plot. Ignored if save_fig=False.

  • **kwargs (optional keyword arguments) – Passed to calibrate_speed.calibrate()

Returns

out – The quantile regression fit object, matplotlib.pyplot Axes and Figures instances.

Return type

3-tuple

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.zoc("offset", offset=3)
>>> tdrX.calibrate_speed(z=2)
detect_dive_phases(**kwargs)[source]

Detect dive phases

Complete filling the dives attribute.

Parameters

**kwargs (optional keyword arguments) – Passed to detect_dive_phases()

Notes

See details for arguments in diveMove’s calibrateDepth.

Examples

ZOC using the “offset” method for convenience

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> 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)[source]

Identify dive events

Set the dives attribute’s “row_ids” dictionary element, and update the wet_act attribute’s “phases” dictionary element.

Parameters

dry_thr (float) – Passed to detect_dives().

Notes

See details for arguments in diveMove’s calibrateDepth.

Examples

ZOC using the “offset” method for convenience

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

Detect wet/dry phases and dives with 3 m threshold

>>> tdrX.detect_wet()
>>> tdrX.detect_dives(3)
detect_wet(**kwargs)[source]

Detect wet/dry activity phases

Set the wet_dry attribute.

Parameters

**kwargs (Keyword arguments) – Passed to detect_wet()

Notes

See details for arguments in diveMove’s calibrateDepth. 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()
>>> tdrX.zoc("offset", offset=3)

Detect wet/dry phases

>>> tdrX.detect_wet()

Access the “phases” and “dry_thr” attributes

>>> tdrX.get_wet_activity("phases")
>>> tdrX.get_wet_activity("dry_thr")
dive_stats(depth_deriv=True)[source]

Calculate dive statistics in TDR records

Parameters

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

Returns

Return type

pandas.DataFrame

Notes

This method homologous to diveMove’s diveStats function.

Examples

ZOC using the “filter” method

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> # Window lengths and probabilities
>>> DB = [-2, 5]
>>> K = [3, 5760]
>>> P = [0.5, 0.02]
>>> tdrX.calibrate(dive_thr=3, zoc_method="filter",
...                k=K, probs=P, depth_bounds=DB,
...                descent_crit_q=0.01, knot_factor=20)
>>> tdrX.dive_stats()
extract_dive(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()

Returns

Return type

xarray.Dataset

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.calibrate(dive_thr=3, zoc_method="offset",
...                offset=3, descent_crit_q=0.01, knot_factor=20)
>>> tdrX.extract_dive(diveNo=20)
get_depth(kind='measured')[source]

Retrieve depth records

Parameters

kind ({"measured", "zoc"}) – Which depth to retrieve.

Returns

Return type

xarray.DataArray

get_dive_deriv(*args, **kwargs)[source]

Retrieve depth spline derivative for a given dive

Parameters
get_dives_details(*args, **kwargs)[source]

Retrieve wet/dry activity DataFrame

Returns

*args, **kwargs – Passed to get_dives_details()

Return type

arguments and keyword arguments

get_phases_params(key)[source]

Retrieve parameters used for identification of phases

Parameters

key ({'wet_dry', 'dives'}) – Name of type of parameters to retrieve.

Returns

out

Return type

dict

get_speed(kind='measured')[source]

Retrieve speed records

Parameters

kind ({"measured", "calibrated"}) – Which speed to retrieve.

Returns

Return type

xarray.DataArray

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.

Returns

Return type

xarray.Dataset

get_wet_activity()[source]

Retrieve wet/dry activity DataFrame

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) – Arguments passed to plotting function.

Returns

matplotlib.pyplot Figure and 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])
plot_dive_model(diveNo=None, **kwargs)[source]

Plot dive model for selected dive

Parameters
  • diveNo (array_like, optional) – List of dive numbers (1-based) to plot.

  • **kwargs (optional keyword arguments) – Arguments passed to plotting function.

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.calibrate(dive_thr=3, zoc_method="offset",
...                offset=3, descent_crit_q=0.01, knot_factor=20)
>>> tdrX.plot_dive_model(diveNo=20, figsize=(10, 10))
plot_phases(diveNo=None, concur_vars=None, concur_var_titles=None, surface=False, **kwargs)[source]

Plot major phases found on the 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.

  • **kwargs (optional keyword arguments) – Arguments passed to plotting function.

Returns

matplotlib.pyplot Figure and Axes instances.

Return type

tuple

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.calibrate(dive_thr=3, zoc_method="offset",
...                offset=3, descent_crit_q=0.01, knot_factor=20)
>>> tdrX.plot_phases(list(range(250, 300)), surface=True)
plot_zoc(xlim=None, ylim=None, **kwargs)[source]

Plot zero offset correction filters

Parameters
  • ylim (xlim,) – Minimum and maximum limits for x- and y-axis, respectively.

  • **kwargs (optional keyword arguments) – Passed to matplotlib.pyplot.subplots.

Returns

matplotlib.pyplot Figure and Axes instances.

Return type

tuple

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.zoc("offset", offset=3)
>>> tdrX.plot_zoc()
stamp_dives(**kwargs)[source]

Identify the wet/dry activity phase corresponding to each dive

Parameters

**kwargs (optional keyword arguments) – Passed to stamp_dives()

Returns

out

Return type

pandas.DataFrame

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.calibrate(dive_thr=3, zoc_method="offset",
...                offset=3, descent_crit_q=0.01, knot_factor=20)
>>> tdrX.stamp_dives(ignore_z=True)
time_budget(**kwargs)[source]

Summary of wet/dry activities at the broadest scale

Parameters

**kwargs (optional keyword arguments) – Passed to time_budget()

Returns

out

Return type

pandas.DataFrame

Examples

>>> from skdiveMove.tests import diveMove2skd
>>> tdrX = diveMove2skd()
>>> tdrX.calibrate(dive_thr=3, zoc_method="offset",
...                offset=3, descent_crit_q=0.01, knot_factor=20)
>>> tdrX.time_budget(ignore_z=True, ignore_du=True)
zoc(method='filter', **kwargs)[source]

Zero offset correction

Set the zoc_depth attribute.

Parameters
  • method ({"filter", "offset"}) – Name of method to use for zero offset correction.

  • **kwargs (optional keyword arguments) –

    • methods ‘filter’: (‘k’, ‘probs’, ‘depth_bounds’ (defaults to range), ‘na_rm’ (defaults to True)).

    • method ‘offset’: (‘offset’).

Notes

More details in diveMove’s calibrateDepth function.

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])