Pyotelem API documentation

dives

pyotelem.dives.finddives2(depths, min_dive_thresh=10)

Find dives in depth data below a minimum dive threshold

Parameters:

• depths (ndarray) – Datalogger depth measurements
• min_dive_thresh (float) – Minimum depth threshold for which to classify a dive

Returns:

• dives (ndarray) – Dive summary information in a numpy record array

  Columns:

  • dive_id
  • start_idx
  • stop_idx
  • dive_dur
  • depth_max
  • depth_max_i
  • depth_min
  • depth_min_i
  • depth_mean
  • comp_mean

• dive_mask (ndarray) – Boolean mask array over depth data. Cells with True are dives and cells with False are not.

pyotelem.dives.get_bottom(depths, des_mask, asc_mask)

Get boolean mask of regions in depths the animal is at the bottom

Parameters:

• des_mask (ndarray) – Boolean mask of descents in the depth data
• asc_mask (ndarray) – Boolean mask of ascents in the depth data

Returns:

BOTTOM – Indices and depths for when the animal is at the bottom

Index positions:

0. start ind
1. depth at start
2. stop ind
3. depth at stop

Return type:

ndarray (n,4)

pyotelem.dives.get_des_asc2(depths, dive_mask, pitch, cutoff, fs, order=5)

Get boolean masks of descents and ascents in the depth data

Parameters:

• dive_mask (ndarray) – Boolean mask array over depth data. Cells with True are dives and cells with False are not.
• pitch (ndarray) – Pitch angle in radians
• cutoff (float) – Cutoff frequency at which signal will be filtered
• fs (float) – Sampling frequency
• order (int) – Order of butter filter to apply

Returns:

• des_mask (ndarray) – Boolean mask of descents in the depth data
• asc_mask (ndarray) – Boolean mask of ascents in the depth data

pyotelem.dives.get_phase(n_samples, des_mask, asc_mask)

Get the directional phase sign for each sample in depths

Parameters:

• n_samples (int) – Length of output phase array
• des_mask (numpy.ndarray, shape (n,)) – Boolean mask of values where animal is descending
• asc_mask (numpy.ndarray, shape(n,)) – Boolean mask of values where animal is ascending

Returns:

phase – Signed integer array values representing animal’s dive phase

Phases:

• 0: neither ascending/descending
• 1: ascending
• -1: descending.

Return type:

numpy.ndarray, shape (n,)

pyotelem.dives.rm_incomplete_des_asc(des_mask, asc_mask)

Remove descents-ascents that have no corresponding ascent-descent

Parameters:

• des_mask (ndarray) – Boolean mask of descents in the depth data
• asc_mask (ndarray) – Boolean mask of ascents in the depth data

Returns:

• des_mask (ndarray) – Boolean mask of descents with erroneous regions removed
• asc_mask (ndarray) – Boolean mask of ascents with erroneous regions removed

dsp

pyotelem.dsp.butter_apply(b, a, data)

Apply filter with filtfilt to allign filtereted data with input

The filter is applied once forward and once backward to give it linear phase, using Gustafsson’s method to give the same length as the original signal.

Parameters:

• b (ndarray) – Numerator polynomials of the IIR butter filter
• a (ndarray) – Denominator polynomials of the IIR butter filter

Returns:

x – Filtered data with linear phase

Return type:

ndarray

Notes

This function was adapted from the following StackOverflow answer: http://stackoverflow.com/a/25192640/943773

pyotelem.dsp.butter_filter(cutoff, fs, order=5, btype='low')

Create a digital butter fileter with cutoff frequency in Hz

Parameters:

• cutoff (float) – Cutoff frequency where filter should separate signals
• fs (float) – sampling frequency
• btype (str) – Type of filter type to create. ‘low’ creates a low-frequency filter and ‘high’ creates a high-frequency filter (Default ‘low).

Returns:

• b (ndarray) – Numerator polynomials of the IIR butter filter
• a (ndarray) – Denominator polynomials of the IIR butter filter

Notes

This function was adapted from the following StackOverflow answer: http://stackoverflow.com/a/25192640/943773

pyotelem.dsp.calc_PSD_welch(x, fs, nperseg)

Caclulate power spectral density with Welch’s method

Parameters:

• x (ndarray) – sample array
• fs (float) – sampling frequency (1/dt)

Returns:

• f_welch (ndarray) – Discrete frequencies
• S_xx_welch (ndarray) – Estimated PSD at discrete frequencies f_welch
• P_welch (ndarray) – Signal power (integrated PSD)
• df_welch (ndarray) – Delta between discreet frequencies f_welch

pyotelem.dsp.findzc(x, thresh, t_max=None)

Find cues to each zero-crossing in vector x.

To be accepted as a zero-crossing, the signal must pass from below -thresh to above thresh, or vice versa, in no more than t_max samples.

Parameters:

• thresh ((float)) – magnitude threshold for detecting a zero-crossing.
• t_max ((int)) – maximum duration in samples between threshold crossings.

Returns:

zc – Array containing the start zc_s, finish zc_f and direction S of zero crossings

where:

• zc_s: the cue of the first threshold-crossing in samples
• zc_f: the cue of the second threshold-crossing in samples
• S: the sign of each zero-crossing (1 = positive-going, -1 = negative-going).

Return type:

ndarray

Notes

This routine is a reimplementation of Mark Johnson’s Dtag toolbox method and tested against the Matlab version to be sure it has the same result.

pyotelem.dsp.normalized(a, axis=-1, order=2)

Return normalized vector for arbitrary axis

Parameters:

• a (ndarray (n,3)) – Tri-axial vector data
• axis (int) – Axis index to overwhich to normalize
• order (int) – Order of nomalization to calculate

Notes

This function was adapted from the following StackOverflow answer: http://stackoverflow.com/a/21032099/943773

pyotelem.dsp.simple_peakfinder(x, y, delta)

Detect local maxima and minima in a vector

A point is considered a maximum peak if it has the maximal value, and was preceded (to the left) by a value lower by delta.

Parameters:

• y (ndarray) – array of values to find local maxima and minima in
• delta (float) – minimum change in y since previous peak to be considered new peak. It should be positive and it’s absolute value taken to ensure this.
• x (ndarray) – corresponding x-axis positions to y array

Returns:

• max_ind (ndarray) – Indices of local maxima
• min_ind (ndarray) – Indices of local minima

Example

max_ind, min_ind = simple_peakfinder(x, y, delta)

# get values of y at local maxima local_max = y[max_ind]

Notes

Matlab Author: Eli Billauer http://billauer.co.il/peakdet.html Python translation: Chris Muktar https://gist.github.com/endolith/250860 Python cleanup: Ryan J. Dillon

glides

pyotelem.glides.calc_glide_des_asc(depths, pitch_lf, roll_lf, heading_lf, swim_speed, dives, SGL, pitch_lf_deg, temperature, Dsw)

Calculate glide ascent and descent summary data

Parameters:SGL (numpy.ndarray, shape (n,2)) – start and end index positions for sub-glides Returns:sgls – Sub-glide summary information defined by SGL start/stop indices

Columns:

• dive_phase
• dive_id
• dive_min_depth
• dive_max_depth
• dive_duration
• start_idx
• stop_idx
• duration
• mean_depth
• total_depth_change
• abs_depth_change
• mean_speed
• total_speed_change
• mean_pitch
• mean_sin_pitch
• SD_pitch
• mean_temp
• mean_swdensity
• mean_a
• R2_speed_vs_time
• SE_speed_vs_time
• mean_pitch_circ
• pitch_concentration
• mean_roll_circ
• roll_concentration
• mean_heading_circ
• heading_concentration

Return type:pandas.DataFrame

pyotelem.glides.calc_glide_ratios(dives, des, asc, glide_mask, depths, pitch_lf)

Calculate summary information on glides during dive ascent/descents

Parameters:

• dives ((n,10)) – Numpy record array with summary information of dives in sensor data
• des (ndarray) – Boolean mask of descents over sensor data
• asc (ndarray) – Boolean mask of descents over sensor data
• glid_mask (ndarray) – Boolean mask of glides over sensor data
• depths (ndarray) – Depth values at each sensor sampling
• pitch_lf (ndarray) – Pitch in radians over the low frequency signals of acceleration

Returns:

gl_ratio – Dataframe of summary information of glides during dive descent/ascents

Columns:

• des_duration
• des_gl_duration
• des_gl_ratio
• des_mean_pitch
• des_rate
• asc_duration
• asc_gl_duration
• asc_gl_ratio
• asc_mean_pitch
• asc_rate

Return type:

pandas.DataFrame

pyotelem.glides.get_stroke_freq(Ax, Az, fs_a, nperseg, peak_thresh, stroke_ratio=None)

Determine stroke frequency to use as a cutoff for filtering

Parameters:

• Ax (numpy.ndarray, shape (n,)) – x-axis accelermeter data (longitudinal)
• Ay (numpy.ndarray, shape (n,)) – x-axis accelermeter data (lateral)
• Az (numpy.ndarray, shape (n,)) – z-axis accelermeter data (dorso-ventral)
• fs_a (float) – sampling frequency (i.e. number of samples per second)
• nperseg (int) – length of each segment (i.e. number of samples per frq. band in PSD calculation. Default to 512 (scipy.signal.welch() default is 256)
• peak_thresh (float) – PSD power level threshold. Only peaks over this threshold are returned.

Returns:

• cutoff_frq (float) – cutoff frequency of signal (Hz) to be used for low/high-pass filtering
• stroke_frq (float) – frequency of dominant wavelength in signal
• stroke_ratio (float)

Notes

During all descents and ascents phases where mainly steady swimming occurs. When calculated for the whole dive it may be difficult to differentiate the peak at which stroking rate occurs as there are movements than only steady swimming

Here the power spectra is calculated of the longitudinal and dorso-ventral accelerometer signals during descents and ascents to determine the dominant stroke frequency for each animal in each phase

This numpy samples per f segment 512 and a sampling rate of fs_a.

Output: S is the amount of power in each particular frequency (f)

pyotelem.glides.get_stroke_glide_indices(A_g_hf, fs_a, J, t_max)

Get stroke and glide indices from high-pass accelerometer data

Parameters:

• A_g_hf (1-D ndarray) – Animal frame triaxial accelerometer matrix at sampling rate fs_a.
• fs_a (int) – Number of accelerometer samples per second
• J (float) – Frequency threshold for detecting a fluke stroke in m/s^2. If J is not given, fluke strokes will not be located but the rotations signal (pry) will be computed.
• t_max (int) – Maximum duration allowable for a fluke stroke in seconds. A fluke stroke is counted whenever there is a cyclic variation in the pitch deviation with peak-to-peak magnitude greater than +/-J and consistent with a fluke stroke duration of less than t_max seconds, e.g., for Mesoplodon choose t_max=4.

Returns:

GL – Matrix containing the start time (first column) and end time (2nd column) of any glides (i.e., no zero crossings in t_max or more seconds). Times are in seconds.

Return type:

1-D ndarray

Note

If no J or t_max is given, J=[], or t_max=[], GL returned as None

pyotelem.glides.split_glides(n_samples, dur, fs_a, GL, min_dur=None)

Get start/stop indices of each dur length sub-glide for glides in GL

Parameters:

• dur (int) – Desired duration of glides
• GL (ndarray, (n, 2)) – Matrix containing the start time (first column) and end time (2nd column) of any glides.Times are in seconds.
• min_dur (int, default (bool False)) – Minimum number of seconds for sub-glide. Default value is False, which makes min_dur equal to dur, ignoring sub-glides smaller than dur.

pyotelem.glides.gl_ind_diff

GL, with additional column of difference between the first two columns

Type:ndarray, (n,3)

Returns:SGL – Matrix containing the start time (first column) and end time (2nd column) of the generated sub-glides. All glides must have duration equal to the given dur value.Times are in seconds. Return type:ndarray, (n, 2)

physio_seal

pyotelem.physio_seal.bodycomp(mass, tbw, method='reilly', simulate=False, n_rand=1000)

Create dataframe with derived body composition values

Parameters:

• mass (ndarray) – Mass of the seal (kg)
• tbw (ndarray) – Total body water (kg)
• method (str) – name of method used to derive composition values
• simulate (bool) – switch for generating values with random noise
• n_rand (int) – number of density values to simulate

Returns:

field – dataframe containing columns for each body composition value

Return type:

pandas.Dataframe

References

Reilly, J.J., Fedak, M.A., 1990. Measurement of the body composition of living gray seals by hydrogen isotope dilution. Journal of Applied Physiology 69, 885–891.

Gales, R., Renouf, D., Noseworthy, E., 1994. Body composition of harp seals. Canadian journal of zoology 72, 545–551.

pyotelem.physio_seal.buoyant_force(dens_gcm3, vol, sw_dens=1.028)

Cacluate the buoyant force of an object in seawater

Parameters:

• dens_gcm3 (float) – Density of the animal (g/cm^3)
• vol – Volume of the animal (cm^3)
• sw_dens (float) – Density of seawater (Default 1.028 g/cm^3)

Returns:

Fb – Buoyant force of animal

Return type:

float

pyotelem.physio_seal.calc_CdAm(frontal_area, mass)

Calculate drag term

Parameters:

• frontal_area (float) – Frontal area of animal
• mass (float) – Total animal mass

Returns:

CdAm – Friction term of hydrodynamic equation

Return type:

float

References

Miller, P.J.O., Johnson, M.P., Tyack, P.L., Terray, E.A., 2004. Swimming gaits, passive drag and buoyancy of diving sperm whales Physeter macrocephalus. Journal of Experimental Biology 207, 1953–1967. doi:10.1242/jeb.00993

pyotelem.physio_seal.calc_seal_volume(mass_kg, dens_kgm3, length=None, girth=None)

Calculate an animal’s volume from mass and density or length and girth

Parameters:

• mass_kg (float or ndarray) – Mass of animal (kg)
• dens_kgm3 (float or ndarray) – Density of animal (kg/m^3)
• length (float or None) – Length of animal. Default None (m)
• girth (float or None) – Girth of animal. Default None (m)

Returns:

vol_kgm3 – Volume of animal (m^3)

Return type:

float or ndarray

pyotelem.physio_seal.dens2lip(dens_gcm3, dens_lipid=0.9007, dens_prot=1.34, dens_water=0.994, dens_ash=2.3)

Get percent composition of animal from body density

The equation calculating animal density is from Biuw et al. (2003), and default values for component densities are from human studies collected in the book by Moore et al. (1963).

Parameters:

• dens_gcm3 (float or ndarray) – An array of seal densities (g/cm^3). The calculations only yield valid percents with densities between 0.888-1.123 with other parameters left as defaults.
• dens_lipid (float) – Density of lipid content in the animal (g/cm^3)
• dens_prot (float) – Density of protein content in the animal (g/cm^3)
• dens_water (float) – Density of water content in the animal (g/cm^3)
• dens_ash (float) – Density of ash content in the animal (g/cm^3)

Returns:

perc_all – Dataframe of components of body composition

Return type:

pandas.DataFrame

References

Biuw, M., 2003. Blubber and buoyancy: monitoring the body condition of free-ranging seals using simple dive characteristics. Journal of Experimental Biology 206, 3405–3423. doi:10.1242/jeb.00583

Moore FD, Oleson KH, McMurrery JD, Parker HV, Ball MR, Boyden CM. The Body Cell Mass and Its Supporting Environment - The Composition in Health and Disease. Philadelphia: W.B. Saunders Company; 1963. 535 p. ISBN:0-7216-6480-6

pyotelem.physio_seal.diff_speed(sw_dens=1.028, dens_gcm3=1.053, seal_length=300, seal_girth=200, Cd=0.09)

Calculate terminal velocity of animal with a body size

Parameters:

• sw_dens (float) – Density of seawater (g/cm^3)
• dens_gcm3 (float) – Density of animal (g/cm^3)
• seal_length (float) – Length of animal (cm)
• seal_girth (float) – Girth of animal (cm)
• Cd (float) – Drag coefficient of object in fluid, unitless

Returns:

Vt – Terminal velocity of animal with given body dimensions (m/s).

Return type:

float

References

Biuw, M., 2003. Blubber and buoyancy: monitoring the body condition of free-ranging seals using simple dive characteristics. Journal of Experimental Biology 206, 3405–3423. doi:10.1242/jeb.00583

Vogel, S., 1994. Life in Moving Fluids: The Physical Biology of Flow. Princeton University Press.

pyotelem.physio_seal.lip2dens(perc_lipid, dens_lipid=0.9007, dens_prot=1.34, dens_water=0.994, dens_ash=2.3)

Derive tissue density from lipids

The equation calculating animal density is from Biuw et al. (2003), and default values for component densities are from human studies collected in the book by Moore et al. (1963).

Parameters:

• perc_lipid (float or ndarray) – Percent lipid of body composition
• dens_lipid (float) – Density of lipid in animal (Default 0.9007 g/cm^3)
• dens_prot (float) – Density of protein in animal (Default 1.34 g/cm^3)
• dens_water (float) – Density of water in animal (Default 0.994 g/cm^3)
• dens_ash (float) – Density of ash in animal (Default 2.3 g/cm^3)

Returns:

dens_gcm3 – Density of seal calculated from percent compositions and densities of components from Moore et al. (1963)

Return type:

float or ndarray

References

Biuw, M., 2003. Blubber and buoyancy: monitoring the body condition of free-ranging seals using simple dive characteristics. Journal of Experimental Biology 206, 3405–3423. doi:10.1242/jeb.00583

Moore FD, Oleson KH, McMurrery JD, Parker HV, Ball MR, Boyden CM. The Body Cell Mass and Its Supporting Environment - The Composition in Health and Disease. Philadelphia: W.B. Saunders Company; 1963. 535 p. ISBN:0-7216-6480-6

pyotelem.physio_seal.lip2en(BM, perc_lipid)

Percent lipid composition to percent energy stores

Parameters:

• BM (float or ndarray) – Body mass of animal
• perc_lipid (float or ndarray) – Percent lipids of animal’s body composition

Returns:

en – Total energy stores

Return type:

float or ndarray

pyotelem.physio_seal.lung_capacity(mass)

Caclulate lung capacity

Parameters:mass (float) – Mass of animal Returns:volume – Lung volume of animal Return type:float

References

Kooyman, G.L., Sinnett, E.E., 1979. Mechanical properties of the harbor porpoise lung, Phocoena phocoena. Respir Physiol 36, 287–300.

pyotelem.physio_seal.perc_bc_from_lipid(perc_lipid, perc_water=None)

Calculate body composition component percentages based on % lipid

Calculation of percent protein and percent ash are based on those presented in Reilly and Fedak (1990).

Parameters:

• perc_lipid (float or ndarray) – 1D array of percent lipid values from which to calculate body composition
• perc_water (float or ndarray) – 1D array of percent water values from which to calculate body composition (Default None). If no values are passed, calculations are performed with values from Biuw et al. (2003).

Returns:

• perc_water (float or ndarray) – 1D array of percent water values
• perc_protein (float or ndarray) – 1D array of percent protein values
• perc_ash (float or ndarray) – 1D array of percent ash values

References

Biuw, M., 2003. Blubber and buoyancy: monitoring the body condition of free-ranging seals using simple dive characteristics. Journal of Experimental Biology 206, 3405–3423. doi:10.1242/jeb.00583

Reilly, J.J., Fedak, M.A., 1990. Measurement of the body composition of living gray seals by hydrogen isotope dilution. Journal of Applied Physiology 69, 885–891.

pyotelem.physio_seal.surf_vol(length, girth)

Calculate the surface volume of an animal from its length and girth

Parameters:

• length (float or ndarray) – Length of animal (m)
• girth (float or ndarray) – Girth of animal (m)

Returns:

• surf – Surface area of animal (m^2)
• vol (float or ndarray) – Volume of animal (m^3)

pyotelem.physio_seal.water_from_lipid_protein(lipid, protein)

Calculate total body water from total lipid and protein

Parameters:

• lipid (float or ndarray) – Mass of lipid content in animal
• protein (float or ndarray) – Mass of protein content in animal

Returns:

water – Mass of water content in animal

Return type:

float or ndarray

References

Reilly, J.J., Fedak, M.A., 1990. Measurement of the body composition of living gray seals by hydrogen isotope dilution. Journal of Applied Physiology 69, 885–891.

seawater

pyotelem.seawater.SWdensityFromCTD(SA, t, p, potential=False)

Calculate seawater density at CTD depth

Parameters:

• SA (ndarray) – Absolute salinity, g/kg
• t (ndarray) – In-situ temperature (ITS-90), degrees C
• p (ndarray) – Sea pressure (absolute pressure minus 10.1325 dbar), dbar

Returns:

rho – Seawater density, in-situ or potential, kg/m^3

Return type:

ndarray

pyotelem.seawater.interp_S_t(S, t, z, z_new, p=None)

Linearly interpolate CTD S, t, and p (optional) from z to z_new.

Parameters:

• S (ndarray) – CTD salinities
• t (ndarray) – CTD temperatures
• z (ndarray) – CTD Depths, must be a strictly increasing or decreasing 1-D array, and its length must match the last dimension of S and t.
• z_new (ndarray) – Depth to interpolate S, t, and p to. May be a scalar or a sequence.
• p (ndarray (optional)) – CTD pressures

Returns:

• S_i (ndarray) – Interpolated salinities
• t_i (ndarray) – Interpolated temperatures
• p_i (ndarray) – Interpolated pressures. None returned if p not passed.

Note

It is assumed, but not checked, that S, t, and z are all plain ndarrays, not masked arrays or other sequences.

Out-of-range values of z_new, and nan in S and t, yield corresponding numpy.nan in the output.

This method is adapted from the the legacy python-gsw package, where their basic algorithm is from scipy.interpolate.

utils

pyotelem.utils.contiguous_regions(condition)

Finds contiguous True regions of the boolean array ‘condition’.

Parameters:condition (numpy.ndarray, dtype bool) – boolean mask array, but can pass the condition itself (e.g. x > 5) Returns:

• start_ind (numpy.ndarray, dtype int) – array with the start indices for each contiguous region
• stop_ind (numpy.ndarray, dtype int) – array with the stop indices for each contiguous region

Notes

This function is adpated from Joe Kington’s answer on StackOverflow: http://stackoverflow.com/a/4495197/943773

pyotelem.utils.get_dir_indices(msg, dirs)

Return path(s) indices of directory list from user input

Parameters:

• msg (str) – String with message to display before pass selection input
• dir_list (array-like) – list of paths to be displayed and selected from

Returns:

input_dir_indices – list of index positions of user selected path from input

Return type:

array-like

pyotelem.utils.nearest(items, pivot)

Find nearest value in array, including datetimes

Parameters:

• items (iterable) – List of values from which to find nearest value to pivot
• pivot (int or float) – Value to find nearest of in items

Returns:

nearest – Value in items nearest to pivot

Return type:

int or float

pyotelem.utils.recursive_input(input_label, type_class)

Recursive user input prompter with type checker

Parameters:type_class (type) – name of python type (e.g. float, no parentheses) Returns:output – value entered by user converted to type type_class Return type:str

Note

Use ctrl-c to exit input cycling

pyotelem.utils.rm_regions(a, b, a_start_ind, a_stop_ind)

Remove contiguous regions in a before region b

Boolean arrays a and b should have alternating occuances of regions of True values. This routine removes additional contiguous regions in a that occur before a complimentary region in b has occured

Parameters:

• a (ndarray) – Boolean array with regions of contiguous True values
• b (ndarray) – Boolean array with regions of contiguous True values
• a_start_ind (ndarray) – indices of start of a regions
• a_stop_ind (ndarray) – indices of stop of a regions

Returns:

a – Boolean array with regions for which began before a complimentary region in b have occured

Return type:

ndarray

plots

Dive and dive phase plotting functions

pyotelem.plots.plotdives.plot_depth_descent_ascent(depths, dive_mask, des, asc)

Plot depth data for whole deployment, descents, and ascents

Parameters:

• depths (ndarray) – Depth values at each sensor sampling
• dive_mask (ndarray) – Boolean mask slicing dives from the tag data
• des (ndarray) – boolean mask for slicing descent phases of dives from tag dta
• asc (ndarray) – boolean mask for slicing asccent phases of dives from tag dta

pyotelem.plots.plotdives.plot_dives(dv0, dv1, p, dp, t_on, t_off)

Plots depths and delta depths with dive start stop markers

Parameters:

• dv0 (int) – Index position of dive start in cue array
• dv1 (int) – Index position of dive stop in cue array
• p (ndarray) – Depth values
• dp (ndarray) – Delta depths
• t_on (ndarray) – Cue array with start index position of dives
• t_off (ndarray) – Cue array with stop index postition of dives

pyotelem.plots.plotdives.plot_dives_pitch(depths, dive_mask, des, asc, pitch, pitch_lf)

Plot dives with phase and associated pitch angle with HF signal

Parameters:

• depths (ndarray) – Depth values at each sensor sampling
• dive_mask (ndarray) – Boolean mask slicing dives from the tag data
• des (ndarray) – boolean mask for slicing descent phases of dives from tag dta
• asc (ndarray) – boolean mask for slicing asccent phases of dives from tag dta
• pitch (ndarray) – Pitch angle derived from acceleromter data
• pitch_lf (ndarray) – Low-pass filtered derived pitch angle data

pyotelem.plots.plotdives.plot_triaxial_depths_speed(tag)

Plot triaxial accelerometer data for whole deployment, descents, and ascents

Only x and z axes are ploted since these are associated with stroking

Parameters:tag (pandas.DataFrame) – Tag dataframe with acceleromter, depth, and propeller columns

pyotelem.plots.plotdives.plot_triaxial_descent_ascent(Ax, Az, des, asc)

Plot triaxial accelerometer data for whole deployment, descents, and ascents

Only x and z axes are ploted since these are associated with stroking

Parameters:

• Ax (ndarray) – X-axis acclerometer data array
• Az (ndarray) – Z-axis acclerometer data array
• des (ndarray) – boolean mask for slicing descent phases of dives from tag dta
• asc (ndarray) – boolean mask for slicing asccent phases of dives from tag dta

Signal processing plotting functions

pyotelem.plots.plotdsp.plot_acc_pry_depth(A_g_lf, A_g_hf, pry_deg, depths, glide_mask=None)

Plot the acceleration with the pitch, roll, and heading

Parameters:

• A_g_lf (ndarray) – Low-pass filtered calibration accelerometer signal
• A_g_hf (ndarray) – High-pass filtered calibration accelerometer signal
• pry_deg (ndarray) – Pitch roll and heading in degrees
• depths (ndarray) – Depth data for all samples
• glide_mask (ndarray) – Boolean array for slicing glides from tag data

pyotelem.plots.plotdsp.plot_data_filter(data, data_f, b, a, cutoff, fs)

Plot frequency response and filter overlay for butter filtered data

Parameters:

• data (ndarray) – Signal array
• data_f (float) – Signal sampling rate
• b (array_like) – Numerator of a linear filter
• a (array_like) – Denominator of a linear filter
• cutoff (float) – Cutoff frequency for the filter
• fs (float) – Sampling rate of the signal

Notes

http://stackoverflow.com/a/25192640/943773

pyotelem.plots.plotdsp.plot_fft(f, S, dt, N)

Plot fft

Parameters:

• f (ndarray) – Array of frequencies produced with PSD
• S (ndarray) – Array of powers produced with PSD
• dt (ndarray) – Sampling rate of sensor
• N (int) – Number of samples in original data?

pyotelem.plots.plotdsp.plot_lf_hf(x, xlf, xhf, title='')

Plot original signal, low-pass filtered, and high-pass filtered signals

Parameters:

• x (ndarray) – Signal data array
• xlf (ndarray) – Low-pass filtered signal
• xhf (ndarray) – High-pass filtered signal
• title (str) – Main title of plot

pyotelem.plots.plotdsp.plot_welch_peaks(f, S, peak_loc=None, title='')

Plot welch PSD with peaks as scatter points

Parameters:

• f (ndarray) – Array of frequencies produced with PSD
• S (ndarray) – Array of powers produced with PSD
• peak_loc (ndarray) – Indices of peak locations in signal
• title (str) – Main title for plot

pyotelem.plots.plotdsp.plot_welch_perdiogram(x, fs, nperseg)

Plot Welch perdiogram

Parameters:

• x (ndarray) – Signal array
• fs (float) – Sampling frequency
• nperseg (float) – Length of each data segment in PSD

Plotting functions for dynamic movement of the animal, including pitch, roll, and heading as well as speed.

pyotelem.plots.plotdynamics.plot_prh_des_asc(p, r, h, asc, des)

Plot pitch, roll, and heading during the descent and ascent dive phases

Parameters:

• p (ndarray) – Derived pitch data
• r (ndarray) – Derived roll data
• h (ndarray) – Derived heading data
• des (ndarray) – boolean mask for slicing descent phases of dives from tag dta
• asc (ndarray) – boolean mask for slicing asccent phases of dives from tag dta

pyotelem.plots.plotdynamics.plot_prh_filtered(p, r, h, p_lf, r_lf, h_lf)

Plot original and low-pass filtered PRH data

Parameters:

• p (ndarray) – Derived pitch data
• r (ndarray) – Derived roll data
• h (ndarray) – Derived heading data
• p_lf (ndarray) – Low-pass filtered pitch data
• r_lf (ndarray) – Low-pass filtered roll data
• h_lf (ndarray) – Low-pass filtered heading data

pyotelem.plots.plotdynamics.plot_swim_speed(exp_ind, swim_speed)

Plot the swim speed during experimental indices

Parameters:

• exp_ind (ndarray) – Indices of tag data where experiment is active
• swim_speed (ndarray) – Swim speed data at sensor sampling rate

Glides and subglide plotting functions

pyotelem.plots.plotglides.plot_glide_depths(depths, mask_tag_filt)

Plot depth at glides

Parameters:

• depths (ndarray) – Depth values at each sensor sampling
• mask_tag_filt (ndarray) – Boolean mask to slice filtered sub-glides from tag data

pyotelem.plots.plotglides.plot_sgls(mask_exp, depths, mask_tag_filt, sgls, mask_sgls_filt, Az_g_hf, idx_start=None, idx_end=None, path_plot=None, linewidth=0.5, leg_bbox=(1.23, 1), clip_x=False)

Plot sub-glides over depth and high-pass filtered accelerometer signal

Parameters:

• mask_exp (ndarray) – Boolean mask array to slice tag data to experimtal period
• depths (ndarray) – Depth values at each sensor sampling
• mask_tag_filt (ndarray) – Boolean mask to slice filtered sub-glides from tag data
• sgls (pandas.DataFrame) – Sub-glide summary information defined by SGL start/stop indices
• mask_sgls_filt (ndarray) – Boolean mask to slice filtered sub-glides from sgls data
• Az_g_hf (ndarray) – High-pass filtered, calibrated z-axis accelerometer data
• idx_start (int) – Sample index position where plot should begin
• idx_stop (int) – Sample index position where plot should stop
• path_plot (str) – Path and filename for figure to be saved
• linewidth (float) – Width of plot lines (Default: 0.5)
• clip_x (bool) – Swith to clip x-axis to the experimental period

Utility functions for plotting

pyotelem.plots.plotutils.add_alpha_labels(axes, xpos=0.03, ypos=0.95, suffix='', color=None, fontsize=14, fontweight='normal', boxstyle='square', facecolor='white', edgecolor='white', alpha=1.0)

Add sequential alphbet labels to subplot axes

Parameters:

• axes (list of pyplot.ax) – A list of matplotlib axes to add the label labels to
• xpos (float or array_like) – X position(s) of labels in figure coordinates
• ypos (float or array_like) – Y position(s) of labels in figure coordinates
• suffix (str) – String to append to labels (e.g. ‘.’ or ‘ name)
• color (matplotlib color) – Color of labels
• fontsize (int) – Alppa fontsize
• fontweight (matplotlib fontweight) – Alpha fontweight
• boxstyle (matplotlib boxstyle) – Alpha boxstyle
• facecolor (matplotlib facecolor) – Color of box containing label
• edgecolor (matplotlib edgecolor) – Color of box’es border containing label
• alpha (float) – Transparency of label

Returns:

axes – A list of matplotlib axes objects with alpha labels added

Return type:

list of pyplot.ax

pyotelem.plots.plotutils.hourminsec(n_seconds)

Generate a string of hours and minutes from total number of seconds

Parameters:n_seconds (int) – Total number of seconds to calculate hours, minutes, and seconds from Returns:

• hours (int) – Number of hours in n_seconds
• minutes (int) – Remaining minutes in n_seconds after number of hours
• seconds (int) – Remaining seconds in n_seconds after number of minutes

pyotelem.plots.plotutils.magnitude(x)

Determine the magnitude of a number

Parameters:x (float) – Number whose magnitude to find Returns:mag – Magnitude of passed number Return type:int

pyotelem.plots.plotutils.merge_limits(axes, xlim=True, ylim=True)

Set maximum and minimum limits from list of axis objects to each axis

Parameters:

• axes (iterable) – list of matplotlib.pyplot axis objects whose limits should be modified
• xlim (bool) – Flag to set modification of x axis limits
• ylim (bool) – Flag to set modification of y axis limits

pyotelem.plots.plotutils.nsamples_to_hourmin(x, pos)

Convert axes labels to experiment duration in hours/minutes

Notes

Matplotlib FuncFormatter function https://matplotlib.org/examples/pylab_examples/custom_ticker1.html

pyotelem.plots.plotutils.nsamples_to_hourminsec(x, pos)

Convert axes labels to experiment duration in hours/minutes/seconds

Notes

Matplotlib FuncFormatter function https://matplotlib.org/examples/pylab_examples/custom_ticker1.html

pyotelem.plots.plotutils.nsamples_to_minsec(x, pos)

Convert axes labels to experiment duration in minutes/seconds

Notes

Matplotlib FuncFormatter function https://matplotlib.org/examples/pylab_examples/custom_ticker1.html

pyotelem.plots.plotutils.plot_noncontiguous(ax, data, ind, color='black', label='', offset=0, linewidth=0.5, linestyle='-')

Plot non-contiguous slice of data

Parameters:

• data (ndarray) – The data with non continguous regions to plot
• ind (ndarray) – indices of data to be plotted
• color (matplotlib color) – Color of plotted line
• label (str) – Name to be shown in legend
• offset (int) – The number of index positions to reset start of data to zero
• linewidth (float) – The width of the plotted line
• linstyle (str) – The char representation of the plotting style for the line

Returns:

ax – Axes object with line glyph added for non-contiguous regions

Return type:

pyplot.ax

pyotelem.plots.plotutils.plot_shade_mask(ax, ind, mask, facecolor='gray', alpha=0.5)

Shade across x values where boolean mask is True

Parameters:

• ax (pyplot.ax) – Axes object to plot with a shaded region
• ind (ndarray) – The indices to use for the x-axis values of the data
• mask (ndarray) – Boolean mask array to determine which regions should be shaded
• facecolor (matplotlib color) – Color of the shaded area

Returns:

ax – Axes object with the shaded region added

Return type:

pyplot.ax

pyotelem.plots.plotutils.roundup(x, order)

Round a number to the passed order

Parameters:

• x (float) – Number to be rounded
• order (int) – Order to which x should be rounded

Returns:

x_round – The passed value rounded to the passed order

Return type:

float