Read functions

RSKopen

RSKopen(fname)

RSKopen - Open an RBR RSK file and read metadata and downsample, if exists.

Syntax:

RSK = RSKopen(fname, [OPTIONS])

Makes a connection to an RSK (SQLite format) database as obtained from an RBR logger and reads in the instrument metadata as well as downsample of the stored data. RSKopen assumes only a single instrument deployment is in the RSK file. The downsample table will not exist when the data contains less than 40960 samples per channel. It is a downsample of the full range of data, for a quick review of the original data.

Requires a working mksqlite library. We have included a couple of versions here for Windows (32/64 bit), Linux (64 bit) and Mac (64 bit), but you might need to compile another version. The mksqlite-src directory contains everything you need and some instructions from the original author. You can also find the source through Google.

Please note that the hidden-channel data is accessible only when it is available in the RSK table. For the RSK with the type of EPdesktop, hidden- channel data is not stored in RSK file, thus, not readable even with readHiddenChannels = true.

Inputs:

Required:

  • fname – Filename of the RSK database.

Optional:

  • readHiddenChannels – Read hidden channel when set as true, default is false.

Outputs:

  • RSK – Structure containing the logger metadata.

Example:

rsk = RSKopen('sample.rsk');

See also:

RSKreaddata(), RSKreadprofiles().

RSKreaddata

RSKreaddata(RSK)

RSKreaddata - Read the data tables from an RBR RSK SQLite file.

Syntax:

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

Reads the actual data tables from the RSK file previously opened with RSKopen(). Will either read the entire data structure, or a subset specified by the ‘t1’ and ‘t2’ arguments.

Note: If the file type is ‘skinny’ the file has to be opened with Ruskin before RSKtools can read the data because the data is in a raw bin file.

Inputs:

Required:

  • RSK – Structure containing the logger metadata returned by RSKopen. If provided as the only argument the data for the entire file is read. Depending on the amount of data in your dataset, and the amount of memory on your computer, you can read bigger or smaller chunks before Matlab complains and runs out of memory.

Optional:

  • t1 – Start time for range of data to be read, specified using the MATLAB datenum format.

  • t2 – End time for range of data to be read, specified using the MATLAB datenum format.

Outputs:

  • RSK – Structure containing the logger metadata, along with the added ‘data’ fields. Note: This function replaces all entries and elements in the data field.

Example:

rsk = RSKopen('sample.rsk');
% Read 1/2 day of data since logger started.
rsk = RSKreaddata(rsk, 't2', RSK.epochs.startTime+0.5);

See also:

RSKopen(), RSKreadburstdata().

RSKreadprofiles

RSKreadprofiles(RSK)

RSKreadprofiles - Read individual casts from RSK SQLite database.

Syntax:

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

Reads profile, including upcasts, downcasts, or both from the events contained in a .rsk file. Each cast is an element in the data field matrix. The cast direction is indicated as ‘up’ or ‘down’ in RSK.data.direction. The function will parse annotations (GPS, comment) and profile description/detail field available into the data structure.

Note: RSKreadprofiles reads profiles directly from the RSK file (i.e. from disk). If one wishes to organise existing time series data in RSK structure into profiles (i.e. from memory). Use RSKreaddata followed by RSKtimeseries2profiles.

Inputs:

Required:

  • RSK – Structure containing metadata read from the RSK file.

Optional:

  • profile – Vector identifying the profile numbers to read. Can be used to read only a subset of all the profiles. Default is to read all the profiles.

  • direction – ‘up’ for upcast, ‘down’ for downcast, or both for all. Default is ‘both’.

Outputs:

  • RSK – RSK structure containing individual casts as each element in the data field.

Example:

rsk = RSKopen('profiles.rsk');

% read all profiles
rsk = RSKreadprofiles(rsk);

-OR-

% read selective upcasts
rsk = RSKreadprofiles(rsk, 'profile', [1 3 10], 'direction', 'up');

See also:

RSKfindprofiles(), RSKtimeseries2profiles(), RSKplotprofiles().

RSKreadburstdata

RSKreadburstdata(RSK)

RSKreadburstdata - Read the burst data tables from events.

Syntax:

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

Reads the burst data tables from the RSK file previously opened with RSKopen(). Will either read the entire burst data structure, or a subset specified by ‘t1’ and ‘t2’. Use in conjunction with readevents to separate bursts.

The function probes the SQLite schema and reads from the appropriate burst-data table for the file’s version. v3.2.0 uses dataWave, v3.0.0 transitional uses dataBurst, and v2 (EPdesktop/full) uses burstData. For v3.0.0+ multi-schedule files only schedule 1 is read into RSK.burstData; per-schedule burst access is a future extension.

Inputs:

Required:

  • RSK – Structure containing the logger metadata returned by RSKopen.

Optional:

  • t1 – Start time for range of data to be read, specified using the MATLAB datenum format.

  • t2 – End time for range of data to be read, specified using the MATLAB datenum format.

Outputs:

  • RSK – Structure containing the logger metadata, along with the added burstData fields. Note: any data previously in the burstData field is replaced.

Example:

rsk = RSKreadburstdata(rsk);

See also:

RSKopen(), RSKplotburstdata(), readevents().

RSKreadcalibrations

RSKreadcalibrations(RSK)

RSKreadcalibrations - Read the calibrations table of a .rsk file.

Syntax:

RSK = RSKreadcalibrations(RSK)

Adds the calibrations field and coefficients to the RSK structure. In version 1.13.4 of the RSK schema, the coefficients table is separate from the calibrations table. Here, we combine them into one table or simply open the calibrations table and adjust the timestamps.

Inputs:

Required:

  • RSK – Structure containing the logger metadata returned by RSKopen.

Outputs:

  • RSK – Structure containing previously present logger metadata as well as calibrations including coefficients.

See also:

RSKopen().

RSKreadwavetxt

RSKreadwavetxt(file)

RSKreadwavetxt - Reads wave data from a Ruskin txt export.

Syntax:

RSK = RSKreadwavetxt(file)

DISCLAIMER: This script is meant as a temporary solution to a bug in Ruskin that prevents export of large RSK files to Matlab format, specifically for files obtained from “wave”-type loggers. This function may disappear in the future.

Reads the Ruskin exported text data for a “wave” instrument into a Matlab structure comparable to what would have been obtained using the Ruskin Matlab export.

Inputs:

Required:

  • file – Filename of the text export archive directory to be read. Note that Ruskin exports a zip file of the folder containing the metadata and all the data tables, with each data type (data, burst, events, wave, etc) stored as separately named csv files.

Outputs:

  • RBR – Structure containing the data.

Example:

system('unzip 099999_20160517_1200.zip') % not necessary if already unzipped
RBR = RSKreadwavetxt('099999_20160517_1200');

readsamplingperiod

readsamplingperiod(RSK, scheduleNumber)

readsamplingperiod - Returns the sampling period information.

Syntax1: samplingperiod = readsamplingperiod(RSK)

To return the sampling period of continuous mode or fast sampling period of DD (directional dependent) mode

Syntax2: [samplingperiod, samplingperiodSlow] = readsamplingperiod(RSK)

To return the fast and slow sampling period of DD mode

Inputs:

Required:

  • RSK – Structure containing the logger metadata.

Optional:

  • scheduleNumber – the index of the schedule to be read, default the first schedule

Outputs:

  • samplingperiod – In seconds.

samplingperiodSlow [optional] - In seconds.

See also:

readfirmwarever(), returnversion().

RSKfindprofiles

RSKfindprofiles(RSK)
RSKfindprofiles - Find profiles in a time series using pressure

and conductivity data (if it exists).

Syntax:

[RSK,hasProfile] = RSKfindprofiles(RSK, [OPTIONS])

Implements the algorithm used by the logger and Ruskin to find upcasts or downcasts by looking for pressure reversals. The algorithm distinguishes between upcasts and downcasts, and stores the start and end time for each as ‘tstart’ and ‘tend’ in the profile field of the RSK structure. If profiles are detected when RSK.profiles already exists, it will be removed and replaced.

Inputs:

Required:

  • RSK – Structure containing logger metadata and data

Optional:

  • pressureThreshold – Minimum pressure difference required to detect a profile. The default is 3 dbar, which is the same as the logger. Consider reducing the pressure difference for very shallow profiles.

  • conductivityThreshold – Threshold value that indicates whether the sensor is out of water. Default is 0.05 mS/cm. In very fresh water it may help to reduce this value.

  • schedule – schedule to use pressure and conductivity data from. Default is ‘default’, which is a reserved selector, not a literal label. It auto-resolves to the schedule with the most non-NaN Pressure samples, then Sea Pressure, then the generic default schedule (most Conductivity, then Temperature, then schedule 1). Can also be a schedule name (char).

Outputs:

  • RSK – Structure containing profiles field with the profile metadata. Use RSKreadprofiles to parse and organise the time series into profiles by applying the start and end times.

  • hasProfile – logical value to check if given RSK data has profiles or not. (true or false)

Example:

rsk = RSKopen(fname);
rsk = RSKreaddata(rsk);
rsk = RSKfindprofiles(rsk, 'pressureThreshold', 1);

See also:

RSKreadprofiles(), getprofiles().

RSKtimeseries2profiles

RSKtimeseries2profiles(RSK)

RSKtimeseries2profiles - Detect profiles in existing time series data in RSK structure (RSK.data) and organise it into profiles.

Syntax:

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

Call RSKfindprofiles to detect up and down casts using the same algorithm that logger/Ruskin uses. Reorganise the time series data based on the redetected profile information. Must be used for time series data only.

Note: By contrast, RSKreadprofiles directly read profile data from the RSK file (i.e. from disk), while RSKtimeseries2profiles convert current RSK structure time series data (i.e. from memory) into profiles.

Inputs:

Required:

  • RSK – Structure containing the logger time series data read from the RSK file.

Optional:

  • pressureThreshold – Minimum pressure difference required to detect a profile. The default is 3 dbar, which is the same as the logger. Consider reducing the pressure difference for very shallow profiles.

  • conductivityThreshold – Threshold value that indicates whether the sensor is out of water. Default is 0.05 mS/cm. In very fresh water it may help to reduce this value.

  • schedule – schedule to use for profile detection. Default is ‘default’, which is passed through to RSKfindprofiles. Here ‘default’ is a reserved selector, not a literal label: it resolves to the schedule with the most non-NaN Pressure samples, then Sea Pressure, then the generic default schedule (most Conductivity, then Temperature, then schedule 1). Can also be a schedule name (char).

Outputs:

  • RSK – RSK structure containing individual casts as each element in the data field.

Example:

rsk = RSKopen('profiles.rsk');
rsk = RSKreaddata(rsk);
rsk = RSKtimeseries2profiles(rsk,'pressureThreshold',5);

See also:

RSKreadprofiles(), RSKfindprofiles().

CSV2RSK

CSV2RSK(fname)

CSV2RSK - Convert a csv file into a rsk structure.

Syntax:

RSK = CSV2RSK(fname, [OPTIONS])

Inputs:

Required:

  • fname – filename of the csv file

Optional:

  • 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

  • DDmode – indicate if the data is from DD (directional dependent) mode, default is false

Outputs:

  • RSK – RSK structure containing data from the csv file

Note: The header of the csv file must follow exactly the format below to make this function work: “Time (ms)”,”Conductivity (mS/cm)”,”Temperature (°C)”,”Pressure (dbar)” 1564099200000,49.5392,21.8148,95.387 1564099200167,49.5725,21.8453,95.311 1564099200333,49.5948,21.8752,95.237 … where the first column represents time stamp, which is milliseconds elapsed since January 1 1970 (i.e. unix time or POSIX time). Header for each column is comprised with channel name followed by space and unit (with parentheses) with double quotes.