Utility functions

RSKcreate

RSKcreate()

RSKcreate - Create rsk structure with given time series data.

Syntax:

RSK = RSKcreate(‘tstamp’,tstamp,’values’,values,…

‘channel’,channel,’unit’,unit,[OPTIONS])

RSKcreate creates rsk structure with data that could originate from other CTDs or floats, which allows users to apply RSKtools post processing and other functions to any data they prefer.

Inputs:

Required:

  • tstamp – an array of time stamps (datenum format) of size (n,1)

  • values – a matrix of data of size (n,m)

  • channel – cell array with channel names of size(1,m), or a char string for a single channel

  • unit – cell array with channel units of size(1,m), or a char string for a single unit

Optional:

  • filename – filename to give a general description of the data, default is ‘sample.rsk’

  • model – instrument model from which data was collected, default is ‘unknown’

  • serialID – serial ID of the instrument from which data was collected, default is 0

Outputs:

  • RSK – created RSK structure with given time series data

Example:

tstamp = [735722.625196759;
735722.625198692;
735722.625200613];
values =  [39.9973,   16.2695,   10.1034;
39.9873,   16.2648,   10.1266;
39.9887,   16.2553,   10.1247];
channel = {'Conductivity','Temperature','Pressure'};
unit = {'mS/cm','°C','dbar'};
rsk = RSKcreate('tstamp',tstamp,'values',values,...
'channel',channel,'unit',unit);

RSKaddchannel

RSKaddchannel(RSK)

RSKaddchannel - Add a new channel with defined channel name and unit. If the new channel already exists in the RSK structure, it will overwrite the old one.

Syntax:

[RSK] = RSKaddchannel(RSK,’data’,data,[OPTIONS])

Inputs:

Required:

  • RSK – Structure containing the logger metadata and data.

  • data – Structure containing the data to be added. The data for the new channel must be stored in a field called “values” (i.e., data.values). If the data is arranged as profiles in the RSK structure, then data must be a 1xN array of structures of where N = length(RSK.data).

Optional:

  • channel – name of the added channel, default is ‘unknown’

  • unit – unit of the added channel, default is ‘unknown’

  • unitPlainText – unit of the added channel in plain text, default is ‘unknown’

  • schedule – schedule to work on. Default is ‘default’, which is the reserved generic default selector (not a literal schedule label): it resolves to the schedule with the most non-NaN Conductivity samples, then Temperature, then schedule 1. Can also be a label string. This function requires an explicit schedule on multi-schedule files.

Outputs:

  • RSK – Updated structure containing the new channel.

RSKaddstationdata

RSKaddstationdata(RSK)

RSKaddstationdata - Add station data information for specified profile(s).

Syntax:

[RSK] = RSKaddstationdata(RSK, [OPTIONS])

Append station data to data structure with profiles, including latitude, longitude, station, cruise, vessel, depth, date, weather, crew, comment and description. The function is vectorized, which allows multiple station data inputs for multiple profiles. But when there is only one station data input for multiple profiles, all profiles will be assigned with the same value.

Inputs:

Required:

  • RSK – Structure containing data.

Optional:

One or more of the following:

  • profile – Profile number(s) to which station data should be assigned. Defaults to all profiles

  • latitude – must be of data type numerical

  • longitude – must be of data type numerical

  • station – Nx1 character array or cell array of strings with length equal to the number of profiles

  • cruise – character array or cell array of strings

  • vessel – character array or cell array of strings

  • depth – must be of data type numerical

  • date – character array or cell array of strings

  • weather – character array or cell array of strings

  • crew – character array or cell array of strings

  • comment – character array or cell array of strings

  • description – character array or cell array of strings

Outputs:

  • RSK – Updated structure containing station data for specified profile(s).

Example:

rsk = RSKaddstationdata(rsk,'latitude',45,'longitude',-25,...
'station',{'SK1'},'vessel',{'R/V RBR'},...
'cruise',{'Skootamatta Lake 1'})

-OR-

rsk = RSKaddstationdata(rsk,'profile',4:6,'latitude',[45,44,46],...
'longitude',[-25,-24,-23],'comment',{'Comment1','Comment2','Comment3'});

RSKappendtolog

RSKappendtolog(RSK, logentry)

RSKappendtolog - Append the entry and current time to the log field.

Syntax:

[RSK] = RSKappendtolog(RSK, logentry)

Adds the current time and log entry to the log field in the RSK structure. Creates the log field if it does not exist. It only ever appends entries to the end.

Inputs:

Required:

  • RSK – Structure containing the logger metadata

  • logentry – Comment that will be added to the log. Must be a string.

Outputs:

  • RSK – Input structure with updated log field.

See also:

RSKopen(), RSKalignchannel(), RSKbinaverage().

RSKsettings

RSKsettings(rsksettings)

RSKsettings - View and change RSKtools parameters.

Syntax:

rsksettings = RSKsettings([OPTIONS])

The function returns current RSKtools parameters when there is no input argument. It updates RSKtools parameters when a structure of input parameters is specified.

Inputs:

Optional:

  • rsksettings – structure that contains specified RSKtools parameters, for instance:

rsksettings.latitude = 45; rsksettings.seawaterLibrary = ‘TEOS-10’;

Outputs:

  • rsksettings – Structure containing current or updated RSKtools parameters

Example:

rsksettings = RSKsettings; % get current setting parameters
rsksettings.seawaterLibrary = 'seawater'; % set default to CSIRO seawater
RSKsettings(rsksettings); % set parameters

See also:

RSKdefaultsettings()

RSKdefaultsettings

RSKdefaultsettings()

RSKdefaultsettings - Set RSKtools parameters to default values.

Syntax:

rsksettings = RSKdefaultsettings

See also:

RSKsettings()

getchannelindex

getchannelindex(RSK, channel)

getchannelindex - Return index of channels.

Syntax:

[channelIdx1,channelIdx2,…] = getchannelindex(RSK, channel)

Finds the channel index in the RSK of the channel longNames given. If the channel(s) is not in the RSK, it returns an error.

Inputs:

  • RSK – RSK structure

  • channel – LongName as written in RSK.channels.

Outputs:

channelIdx(n) - Index of channels, note that the index must be in the same sequence as the input, when there are multiple inputs.

See also:

getdataindex(), getcastdirection().

getdataindex

getdataindex(RSK)

getdataindex - Return the index of data elements requested.

Syntax:

[castidx] = getdataindex(RSK, [OPTIONS])

Selects the data elements that fulfill the requirements described by the profile number and direction arguments.

Inputs:

Required:

  • RSK – Structure containing the logger data

Optional:

  • profile – Profile number. Default is to use all profiles available.

  • direction – Cast direction. Default is to use all directions available.

  • scheduleId – Schedule number selecting which schedule’s dataArrays to index (RSK.dataArrays{scheduleId}). Default is 1.

Outputs:

  • castidx – Array containing the index of data’s elements.

See also:

RSKplotprofile, RSKsmooth(), RSKdespike().

channelallnan

channelallnan(RSK, channel)

channelallnan - Test whether a channel is all-NaN (or absent) everywhere.

Syntax:

tf = channelallnan(RSK, channel)

Returns true if and only if the named channel contains no non-NaN value in ANY schedule (and any cast/profile element within a schedule). A channel that is absent from the file, or absent from a particular schedule’s data matrix, is treated as all-NaN for that schedule. Returns false as soon as a single non-NaN value is found anywhere.

This mirrors the pyRSKtools RSK.channelallnan helper. It is used by the dependency guards (e.g. getseapressure, requiresalinity) to distinguish “channel present and populated” from “channel present but entirely NaN” - the latter being a data problem rather than a missing channel.

Note on data layout: RSK.dataArrays{scheduleId} is an array of structs (one element per cast/profile after RSKreadprofiles, or a single element after RSKreaddata); each element carries its own .values matrix whose columns follow the global RSK.channels order. A schedule (or element) may have fewer columns than numel(RSK.channels) when a derived channel has not yet been written (see appendnanchannel), so the column index is bounds-checked per element.

Inputs:

  • RSK – Structure containing the logger metadata and data.

  • channel – Channel longName (char) as written in RSK.channels.

Outputs:

  • tf – Logical scalar. true if the channel is all-NaN/absent across all schedules, false if any schedule has a non-NaN value.

See also:

getchannelindex(), getseapressure(), requiresalinity().

Barometric correction

RSKimportbarometer(RSK, source)

RSKimportbarometer - Import a barometer source and attach it to an RSK.

Syntax:

[RSK] = RSKimportbarometer(RSK, source, [OPTIONS])

Imports an atmospheric-pressure (barometer) series from one of four source shapes and interpolates it onto the marine RSK’s sample timestamps, so that RSKderiveseapressure (called without patm) subtracts it to give a barometer- corrected sea pressure. Marine samples outside the barometer’s time range are filled with the nearest barometer reading, held constant. A source that does not overlap the marine range at all is rejected (the function errors and nothing is attached).

Only one barometer can be attached at a time – call RSKremovebarometer before importing a different one. The correction is applied to a single schedule: the first one with pressure samples (a warning names it when the file has other pressure-bearing schedules).

Eligible files are schema >=3.2.0, or 2.18.2/2.19.0 with dbType full/live/EPdesktop. The correction is attached in memory; persist it with RSK2RSKFULL, or RSK2RSK for a v2 file.

Inputs:

Required:

  • RSK – Marine RSK structure (opened + read with RSKopen / RSKreaddata).

  • source – One of: * char/string path ending in ‘.csv’ (auto-detected parsing, overridable via csvHints). * char/string path ending in ‘.rsk’ (opened via RSKopen; its first measured pressure channel is used as the barometer). * a channel longName/shortName of THIS RSK (same-RSK source): the channel must be pressure-natured (shortName starting ‘pres’) and measured, not derived. * an Nx2 numeric matrix [utc_ms, dbar].

Optional:

  • sourceSchedule – Schedule label to read from a multi-schedule source (required when a source RSK has more than one schedule, or a same-RSK channel carries finite samples in more than one schedule). Default ‘’.

  • sourceTzOffsetHours – Source UTC offset (OFFSET_FROM_UTC convention: hours east of UTC, negative west). For an RSK source, [] auto-detects the stored OFFSET_FROM_UTC; for a CSV source it sets the tz of naive timestamps ([] treats them as UTC). Timestamps with an explicit offset are unaffected. Default [].

  • csvHints – Struct of CSV parsing overrides with any of the fields hasHeader (logical), timeFormat (char), pressureUnits (char). Default empty struct.

Outputs:

  • RSK – RSK with RSK.barometer / RSK.barometerData populated and the atmospheric-pressure (pres002) channel added.

Example:

rsk = RSKopen('deployment.rsk');
rsk = RSKreaddata(rsk);
rsk = RSKimportbarometer(rsk, 'barometer.rsk');
rsk = RSKderiveseapressure(rsk);   % applies the barometer per sample

See also:

RSKremovebarometer(), RSKderiveseapressure(), RSKopen().

RSKremovebarometer(RSK)

RSKremovebarometer - Remove an imported barometer and its artefacts.

Syntax:

[RSK] = RSKremovebarometer(RSK)

Detaches the barometer attached by RSKimportbarometer (and the pres002 atmospheric-pressure channel and schedule it added), then re-derives sea pressure with the default constant atmospheric pressure (10.1325 dbar). Depth is re-derived too, but only if a Depth channel already exists, using RSKderivedepth defaults (latitude 45, TEOS-10); if you derived depth with non-default parameters, re-run RSKderivedepth afterwards.

Acts in memory only; persist the result with RSK2RSKFULL or RSK2RSK. If no barometer is attached this is a no-op. To apply a different barometer, call this first, then RSKimportbarometer again.

Inputs:

Required:

  • RSK – Structure with an imported barometer attached.

Outputs:

  • RSK – Structure with the barometer artefacts removed and sea pressure (and any pre-existing depth) re-derived with the constant atmospheric pressure.

Example:

rsk = RSKimportbarometer(rsk, 'barometer.csv');
rsk = RSKderiveseapressure(rsk);
rsk = RSKremovebarometer(rsk);   % back to the constant atmosphere

See also:

RSKimportbarometer(), RSKderiveseapressure(), RSKderivedepth().