Processing functions¶
RSKalignchannel¶
- RSKalignchannel(RSK)¶
RSKalignchannel - Align a channel using a specified lag.
Syntax:
[RSK] = RSKalignchannel(RSK,’channel’,’channelName’,’lag’,lag,[OPTIONS])
Applies a sample lag to a specified channel. Typically used for conductivity to minimise salinity spiking from C/T mismatches when the sensors are moving through strong gradients.
Inputs:
Required:
RSK – Input RSK structure
channel – Longname of channel to align (e.g. temperature)
lag – The lag (in samples or seconds) to apply to the channel. A negative lag shifts the channel backwards in time (earlier), while a positive lag shifts the channel forward in time (later). To apply a different lag to each data element, specify the lags in a vector.
Optional:
profile – Profile number. Default is to operate on all of data’s elements.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Defaults to all directions available.
shiftfill – Values that will fill the void left at the beginning or end of the time series. ‘nan’, fills the removed samples of the shifted channel with NaN, ‘zeroorderhold’ fills the removed samples of the shifted channels with the first or last value, ‘mirror’ fills the removed values with the reflection of the original end point, and ‘union’ removes the values of the OTHER channels that do not align with the shifted channel (note: this will reduce the size of values array by “lag” samples).
lagunits – Units of the lag entry. Can be samples (default) or seconds
visualize – To give a diagnostic plot on specified profile number(s). Original and processed data will be plotted to show users how the algorithm works. Default is 0.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is the reserved generic default selector, not a literal label: it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1.
Outputs:
RSK – Structure with aligned channel values.
Example:
rsk = RSKopen('file.rsk'); rsk = RSKreadprofiles(rsk, 'profile', 1:10, 'direction', 'down'); 1. Shift temperature channel of first four profiles with the same lag value. rsk = RSKalignchannel(rsk,'channel','temperature','lag',2,'profile',1:4); 2. Shift oxygen channel of first 4 profiles with profile-specific lags. rsk = RSKalignchannel(rsk,'channel','Dissolved O2','lag',[2 1 -1 0],'profile',1:4); 3. Shift conductivity channel from all downcasts with optimal lag calculated with RSKcalculateCTlag.m. lag = RSKcalculateCTlag(rsk); rsk = RSKalignchannel(rsk,'channel','Conductivity','lag',lag);
See also:
RSKsmooth¶
- RSKsmooth(RSK)¶
RSKsmooth - Apply a low pass filter on specified channel.
Syntax:
[RSK] = RSKsmooth(RSK, ‘channel’, ‘channelName’, [OPTIONS])
Low-pass filter a specified channel or multiple channels with a running average or median. The sample being evaluated is always in the centre of the filtering window to avoid phase distortion. Edge effects are handled by mirroring the original time series.
Inputs:
Required:
RSK – Structure containing the logger data.
Optional:
channel – Longname of channel to filter. Can be a single channel, or a cell array for multiple channels. Defaults to empty; if omitted, the function warns and returns without filtering.
filter – The weighting function, ‘boxcar’ or ‘triangle’. Use ‘median’ to compute the running median. Defaults to ‘boxcar.’
profile – Profile number. Defaults to operate on all available profiles.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Defaults to all directions available.
windowLength – The total size of the filter window. Must be odd. Default is 3.
visualize – To give a diagnostic plot on specified profile number(s). Original and processed data will be plotted to show users how the algorithm works. Default is 0.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is the reserved generic default selector, not a literal label: it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1.
Outputs:
RSK – Structure with filtered values.
Example:
rsk = RSKopen('file.rsk'); rsk = RSKreadprofiles(rsk, 'profile', 1:10); rsk = RSKsmooth(rsk, 'channel', {'Temperature', 'Salinity'}, 'windowLength', 17);
RSKdespike¶
- RSKdespike(RSK)¶
RSKdespike - Despike a time series on a specified channel.
Syntax:
[RSK, spike] = RSKdespike(RSK,’channel’,’channelName’,[OPTIONS])
Identifies and treats spikes using a median filtering algorithm. A reference time series is created by filtering the input channel with a median filter of length ‘windowLength’. A residual (“high-pass”) series is formed by subtracting the reference series from the original signal. Data in the reference series lying outside of ‘threshold’ standard deviations are defined as spikes. Spikes are then treated by one of three methods (see below).
Inputs:
Required:
RSK – Structure containing logger data.
channel – Longname of channel to despike (e.g., temperature, salinity, etc)
Optional:
profile – Profile number. Default is all available profiles.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Default is all directions available.
threshold – Amount of standard deviations to use for the spike criterion. Default value is 2.
windowLength – Total size of the filter window. Must be odd. Default is 3.
action – Action to perform on a spike. The default is ‘nan’, whereby spikes are replaced with NaN. Other options are ‘replace’, whereby spikes are replaced with the corresponding reference value, and ‘interp’ whereby spikes are replaced with values calculated by linearly interpolating from the neighbouring points.
visualize – To give a diagnostic plot on specified profile number(s). Original, processed data and flagged data will be plotted to show users how the algorithm works. Default is 0.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is the reserved generic default selector, not a literal label: it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1.
Outputs:
RSK – Structure with de-spiked series.
spike – Structure containing the index of the spikes; if more than one channel was despiked, spike is a structure with a field for each profile.
Example:
[rsk, spike] = RSKdespike(rsk,'channel','Turbidity')
OR
[rsk, spike] = RSKdespike(rsk,'channel','Temperature','profile',3:5,... 'direction','down','threshold',4,'windowLength',11,... 'action','nan','visualize',4);
See also:
RSKtrim¶
- RSKtrim(RSK)¶
RSKtrim - Remove or replace values that fall in a certain range.
Syntax:
- [RSK, trimidx] = RSKtrim(RSK, ‘reference’, ‘referenceChannelName’, …
‘range’, [x1 x2], [OPTIONS])
Flags values that fall within the range of the specified reference channel, time, or index. Flagged samples can be replaced with NaN or removed or interpolated by neighbouring points.
Inputs:
Required:
RSK – Input RSK structure
reference – Channel that determines which samples will be in the range and trimmed. To trim according to time, use ‘time’, or, to trim by index, choose ‘index’.
range – A 2 element vector of minimum and maximum values. The samples in ‘reference’ that fall within the range (including the edges) will be trimmed. If ‘reference’ is ‘time’, then range must be in Matlab datenum format.
Optional:
channel – Apply the flag to specified channels. Default is all channels. When action is set to ‘remove`, specifying channel will not work.
profile – Profile number. Default is to operate on all profiles.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Defaults to all directions available.
action – Action to apply to the flagged values. Can be ‘nan’ (default) or ‘remove’ or ‘interp’.
visualize – To give a diagnostic plot on specified profile number(s). Original, processed data and flagged data will be plotted to show users how the algorithm works. Default is 0.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is the reserved generic default selector, not a literal label: it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1.
Outputs:
RSK – Structure with trimmed channel values.
trimidx – Index of trimmed samples.
Example:
Replace data acquired during a shallow surface soak with NaN: rsk = RSKtrim(rsk, 'reference', 'sea pressure', 'range', [-1 1]);
RSKcorrecthold¶
- RSKcorrecthold(RSK)¶
- RSKcorrecthold - Replace zero-order hold points with interpolated
value or NaN.
Syntax:
[RSK, holdpts] = RSKcorrecthold(RSK, [OPTIONS])
The analogue-to-digital (A2D) converter on RBR instruments must recalibrate periodically. In the time it takes for the calibration to finish, one or more samples are missed. The onboard firmware fills the missed sample with the same data measured during the previous sample, a simple technique called a zero-order hold.
The function identifies zero-hold points by looking for where consecutive differences for each channel are equal to zero, and replaces them with an interpolated value or a NaN.
An example of where zero-order holds are important is when computing the vertical profiling rate from pressure. Zero-order hold points produce spikes in the profiling rate at regular intervals, which can cause the points to be flagged by RSKremoveloops.
Inputs:
Required:
RSK – Structure containing logger data.
Optional:
channel – Longname of channel to correct the zero-order hold (e.g., temperature, salinity, etc)
profile – Profile number. Default is all available profiles.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Default is all directions available.
action – Action to perform on a hold point. The default is ‘nan’, whereby hold points are replaced with NaN. Another option is ‘interp’, whereby hold points are replaced with values calculated by linearly interpolating from the neighbouring points.
visualize – To give a diagnostic plot on specified profile number(s). Original, processed data and flagged data will be plotted to show users how the algorithm works. Default is 0.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is the reserved generic default selector, not a literal label: it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1.
Outputs:
RSK – Structure with zero-order hold corrected values.
holdpts – Struct array indexed by cast containing the indices of the corrected hold points. Each element has a single field, .index, which is a cell array indexed by channel column; .index{c} holds the indices corrected for channel column c.
Example:
[rsk, holdpts] = RSKcorrecthold(rsk)
OR
[rsk, holdpts] = RSKcorrecthold(rsk, 'channel', 'Temperature', 'action', 'interp','visualize',1);
See also:
RSKremoveloops¶
- RSKremoveloops(RSK)¶
RSKremoveloops - Remove data exceeding a threshold profiling rate and with reversed pressure (loops).
Syntax:
[RSK, flagidx] = RSKremoveloops(RSK, [OPTIONS])
Identifies and flags data obtained when the logger vertical profiling speed falls below a threshold value or when the logger reversed the desired cast direction (forming a loop). The flagged data is replaced with NaNs. All logger channels except depth are affected.
Profiling speed is estimated by differentiating depth. The depth channel is first smoothed with a 3-point running average to reduce noise.
Inputs:
Required:
RSK – RSK structure with logger data and metadata
Optional:
profile – Profile number. Defaults to all profiles.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Defaults to all directions available.
threshold – Minimum speed at which the profile must be taken. Defaults to 0.25 m/s.
accelerationThreshold – Minimum acceleration magnitude below which samples are also flagged. Used in combination with the speed threshold. Defaults to -Inf (disabled).
visualize – To give a diagnostic plot on specified profile number(s). Original, processed data and flagged data will be plotted to show users how the algorithm works. Default is 0.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is the reserved generic default selector, not a literal label: it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1.
Outputs:
RSK – Structure with data filtered by threshold profiling speed and removal of loops.
flagidx – Index of the samples that are filtered.
Example:
rsk = RSKopen('file.rsk'); rsk = RSKreadprofiles(rsk); rsk = RSKremoveloops(rsk);
OR
rsk = RSKremoveloops(rsk,'profile',7:9,'direction','down','threshold',0.3,'visualize',8);
RSKremovecasts¶
- RSKremovecasts(RSK)¶
RSKremovecasts - Remove the data elements with either an increasing or decreasing pressure.
Syntax:
RSK = RSKremovecasts(RSK,[OPTIONS])
Note: When there are only downcasts in current RSK structure, request to remove downcasts will not take effect. The same for upcasts.
Inputs:
Required:
RSK – Structure containing logger data in profile structure.
Optional:
direction – ‘up’ for upcast, ‘down’ for downcast. Default is ‘up’.
Outputs:
RSK – Structure only containing downcast or upcast data.
Example:
rsk = RSKremovecasts(rsk,'direction','up');
RSKcorrecttau¶
- RSKcorrecttau(RSK)¶
RSKcorrecttau - Apply tau correction and smoothing (optional) algorithm from Fozdar et al. (1985)
Syntax:
RSK = RSKcorrecttau(RSK,’channel’,’channelName’,’tauResponse’,tauRespone,[OPTIONS])
Sensors require a finite time to reach equilibrium with the ambient environment under variable conditions. The adjustment process alters both the magnitude and phase of the true signal. The time to reach 63.2% of the true value is defined as time constant (tau). This function applies Fozdar et al. (1985) recursive filter in the time domain to correct the phase and response of the measured signal to more accurately represent the true signal. The Fozdar algorithm reduces to the standard expression when tauSmooth = 0, which is the default.
Fozdar, F.M., G.J. Parkar, and J. Imberger, 1985: Matching Temperature and Conductivity Sensor Response Characteristics. J. Phys. Oceanogr., 15, 1557-1569, https://doi.org/10.1175/1520-0485(1985)015<1557:MTACSR>2.0.CO;2
Inputs:
Required:
RSK – Structure containing logger data.
channel – Longname of channel to apply tau correction (e.g., Temperature, Dissolved O2).
tauResponse – sensor time constant of the channel in seconds.
Optional:
tauSmooth – smoothing time scale in seconds. Default is 0.
profile – Profile number. Default is all available profiles.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Default is all directions available.
visualize – To give a diagnostic plot on specified profile number(s). Original and processed data will be plotted to show users how the algorithm works. Default is 0.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is the reserved generic default selector, not a literal label: it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1.
Outputs:
RSK – Structure with corrected channel in place of measured channel.
Example:
rsk = RSKcorrecttau(rsk,'channel','Dissolved O2','tauResponse',1)
OR
rsk = RSKcorrecttau(rsk,'channel','Temperature','tauResponse',1,'tauSmooth',0.2,'direction','down','profile',1);
See also:
RSKcorrectTM¶
- RSKcorrectTM(RSK)¶
- RSKcorrectTM - Apply a thermal mass correction to conductivity using
the model of Lueck and Picklo (1990).
Syntax:
[RSK] = RSKcorrectTM(RSK,’alpha’,alpha,’beta’,beta,[OPTIONS])
RSKcorrectTM applies the algorithm developed by Lueck and Picklo (1990) to minimise the effect of conductivity cell thermal mass on measured conductivity. Conductivity cells exchange heat with the water as they travel through temperature gradients. The heat transfer changes the water temperature and hence the measured conductivity. This effect will impact the derived salinity and density in the form of sharp spikes and even a bias under certain conditions.
References:
- Lueck, R. G., 1990: Thermal inertia of conductivity cells: Theory.
J. Atmos. Oceanic Technol., 7, pp. 741 - 755. https://doi.org/10.1175/1520-0426(1990)007<0741:TIOCCT>2.0.CO;2
- Lueck, R. G. and J. J. Picklo, 1990: Thermal inertia of conductivity
cells: Observations with a Sea-Bird cell. J. Atmos. Oceanic Technol., 7, pp. 756 - 768. https://doi.org/10.1175/1520-0426(1990)007<0756:TIOCCO>2.0.CO;2
Inputs:
Required:
RSK – Structure containing the logger data.
alpha – Volume-weighted magnitude of the initial fluid thermal anomaly.
beta – Inverse relaxation time of the adjustment.
Optional:
gamma – Temperature coefficient of conductivity (dC/dT). Default is 1, which is suitable for waters with “oceanographic” temperature and salinity and when conductivity is measured in mS/cm.
profile – Profile number. Default is all available profiles.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Default is all directions available.
visualize – To give a diagnostic plot on specified profile number(s). Original and processed data will be plotted to illustrate the correction. Default is 0.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is the reserved generic default selector, not a literal label: it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1.
Outputs:
RSK – Structure with processed values.
Example:
rsk = RSKcorrectTM(rsk,'alpha',0.04,'beta',0.1)
correcttau60¶
- correcttau60(RSK)
- correcttau60 - Apply SCI-22 algorithm to correct conductivity for
the “tau60” thermal dynamic error.
Syntax:
RSK = correcttau60(RSK,’CTcoef’,CTcoef,[OPTIONS])
Inputs:
Required:
RSK – Structure containing logger data.
CTcoef – Conductivity-temperature coefficient for the long-term thermal dynamic correction, applied as Ccor = C ./ (1 + CTcoef*(CT - T)) (e.g. 2.4e-4). Required; no default.
Optional:
profile – Profile number. Default is all available profiles.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Default is all directions available.
visualize – To give a diagnostic plot on specified profile number(s). Original and processed data will be plotted to show users how the algorithm works. Default is 0.
schedule – Schedule to work on. Can be a schedule name (string). Default is ‘default’, the reserved generic selector which resolves to the schedule with the most non-NaN Conductivity data (then Temperature), falling back to schedule 1.
Outputs:
RSK – Structure with corrected conductivity
Example:
rsk = correcttau60(rsk,'CTcoef',2.4e-4)
See also:
RSKcalculateCTlag¶
- RSKcalculateCTlag(RSK)¶
RSKcalculateCTlag - Calculate a conductivity lag.
Syntax:
[lag] = RSKcalculateCTlag(RSK, [OPTIONS])
Calculates the optimal conductivity time shift relative to temperature to minimise salinity spiking. Determines the optimal lag by smoothing the calculated salinity by running it through a boxcar filter, then comparing the standard deviations of the residuals for a range of lags, from -20 to +20 samples. A sea pressure range can be determined to align over a certain range of values (used to avoid large effects from surface anomalies).
Note: Requires the TEOS-10 GSW toolbox to compute salinity.
Inputs:
Required:
RSK – Structure, with profiles as read using RSKreadprofiles.
Optional:
seapressureRange – Limits of the sea pressure range used to obtain the lag. Specify as a two-element vector, [seapressureMin, seapressureMax]. Default is [0, max(seapressure)].
profile – Profile number. Default is all available profiles.
direction – ‘up’ for upcast, ‘down’ for downcast, or ‘both’ for all. Default all directions available.
windowLength – Length of the filter window used for the reference salinity. Default is 21 samples.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is a reserved selector, not a literal label: it uses resolvedefaultschedulect to find the schedule with both conductivity and temperature channels.
Outputs:
lag – Optimal lag of conductivity for each profile. These can serve as inputs into RSKalignchannel.m.
Example:
rsk = RSKopen('file.rsk'); rsk = RSKreadprofiles(rsk, 'profile', 1:10, 'direction', 'down'); % read first 10 downcasts 1. All downcast profiles with default smoothing lag = RSKcalculateCTlag(rsk); 2. Specified profiles (first 4), reference salinity found with 13 pt boxcar. lag = RSKcalculateCTlag(rsk, 'profile',1:4, 'windowLength',13);
See also:
RSKcentrebursttimestamp¶
- RSKcentrebursttimestamp(RSK)¶
RSKcentrebursttimestamp - Modify wave/BPR file time stamp in data field from beginning to middle of the burst.
Syntax:
[RSK] = RSKcentrebursttimestamp(RSK)
For wave or BPR loggers, Ruskin stores the raw high frequency values in the burstData field. The data field is composed of one sample for each burst with time stamp set to be the first value of each burst period; the sample is the average of the values during the corresponding burst. For users’ convenience, this function modifies the time stamp from beginning of each burst to be the middle of it.
Inputs:
Required:
RSK – Structure containing the logger metadata and data.
Outputs:
RSK – Structure containing the logger metadata, and data with corrected time stamp.
Example:
rsk = RSKcentrebursttimestamp(rsk);
See also:
RSKcorrecttempADCcal¶
- RSKcorrecttempADCcal(RSK)¶
RSKcorrecttempADCcal - Add a Temperature Corrected channel with periodic A2D self-calibration outliers removed.
Syntax:
RSK = RSKcorrecttempADCcal(RSK, [OPTIONS])
Reads the temperature channel and the sample timestamps from RSK, calls the routines.correcttempADCcal routine to remove the once-per-minute A2D self-calibration outliers, and adds the cleaned series as a new ‘Temperature Corrected’ channel. The original channel is left unchanged. The numerical work lives in the standalone routine; this function is the RSK-aware wrapper that pulls the arrays out per cast, calls the routine, and writes the result back.
If the periodic self-calibration signature cannot be confirmed (the instrument does not perform it, or the record is too short to verify), the function makes no change, so the ‘Temperature Corrected’ channel is added identical to the source (no error, no warning).
Inputs:
Required:
RSK – Structure containing logger data.
Optional:
channel – Longname of the temperature channel to clean. Default is ‘Temperature’.
schedule – Schedule to work on. Can be a schedule name (string) or ‘default’. Here ‘default’ is the reserved generic default selector, not a literal label: it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1.
Outputs:
RSK – Structure with an added ‘Temperature Corrected’ channel.
Example:
rsk = RSKopen('deployment.rsk'); rsk = RSKreaddata(rsk); rsk = RSKcorrecttempADCcal(rsk); % Or batch a folder of files: if ~isfolder('corrected'); mkdir('corrected'); end files = dir(fullfile('deployment', '*.rsk')); for k = 1:numel(files) rsk = RSKopen(fullfile('deployment', files(k).name)); rsk = RSKreaddata(rsk); rsk = RSKcorrecttempADCcal(rsk); % adds Temperature Corrected RSK2RSK(rsk, 'outputdir', 'corrected'); % writes the corrected copy end
See also: