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¶
|
Base class encapsulating TDR objects and processing |
|
Zero offset correction |
|
Detect wet/dry activity phases |
|
Identify dive events |
|
Detect dive phases |
|
Calibrate TDR object |
|
Calibrate speed measurements |
Analyses¶
|
Calculate dive statistics in TDR records |
|
Summary of wet/dry activities at the broadest scale |
|
Identify the wet/dry activity phase corresponding to each dive |
Plotting¶
|
Plot TDR object |
|
Plot zero offset correction filters |
|
Plot major phases found on the object |
|
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
-
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 thewet_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
*args (arguments) – Passed to
get_dive_deriv()
**kwargs (keyword arguments) – Passed to
get_dive_deriv()
-
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
-
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
- andy
-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])
-