Skip to content

Dbd Class Examples

Jump to bottom
John Kerfoot edited this page May 15, 2018 · 9 revisions

Wiki ▸ Cookbook ▸ Creating Dbd Class Instances

Discussion and examples for creating Dbd instances using the Slocum Power Tools toolbox.

Contents

###Background### The Slocum underwater glider is a versatile autonomous underwater vehicle (AUV) that has become a key component of ocean observing systems. This versatility, however, presents significant challenges for data management as the content of the gathered data sets can vary widely from deployment to deployment and depend upon the glider's configuration, sensor payload and software configuration.

Two common issues that often arise are the selection of appropriate timestamp and depth/pressure sensors in the real-time data sets and how these choices affect the consistency of the resulting data set. I've already addressed these 2 issues here and recommend a quick review before proceeding. I've also discussed on understanding and working with the native file formats here and here.

###Overview### The Dbd class provides a representation of a native slocum glider data file. The class provides the following functionality:

  • Include only the sensors of interest or exclude non-essential sensors.
  • Access to file metadata through properties and methods to operate on the instance.
  • Ability to add new, derived sensor data while preserving the original data content.
  • Protected lists of available timestamp and depth/pressure sensors with the ability to easily switch between sensor pair combinations when defining the yo time-series.
  • Indexes the yo (time-depth time series) and identifies individual downcasts and upcasts.
  • Provides methods for visualizing sensor data and file sampling frequency.
  • Provides a base class for building more complex classes and data structures.

###Examples & Discussion###

Let's create and instance of the Dbd class to represent a single glider data file. First, we need a listing of the files we'll be working with, which we can get using the toolbox's listDbds.m function:

>> pwd

ans =

/tmp/deployments/2013/ru29-374/ascii/sbd

>> dbds = listDbds('ext', 'dat')

dbds = 

    '/tmp/deployments/2013/ru29-374/ascii/sbd/ru29_2013_270_3_0_sbd.dat'
    '/tmp/deployments/2013/ru29-374/ascii/sbd/ru29_2013_270_3_1_sbd.dat'
    '/tmp/deployments/2013/ru29-374/ascii/sbd/ru29_2013_270_3_4_sbd.dat'
    '/tmp/deployments/2013/ru29-374/ascii/sbd/ru29_2013_270_3_5_sbd.dat'
    '/tmp/deployments/2013/ru29-374/ascii/sbd/ru29_2013_270_3_6_sbd.dat'
    '/tmp/deployments/2013/ru29-374/ascii/sbd/ru29_2013_270_3_7_sbd.dat'
    '/tmp/deployments/2013/ru29-374/ascii/sbd/ru29_2013_270_3_8_sbd.dat'
    '/tmp/deployments/2013/ru29-374/ascii/sbd/ru29_2013_270_3_9_sbd.dat'

>>

Now, create an instance:

>> dbd = Dbd(dbds{1})

dbd = 

  Properties:
                  glider: 'ru29'
                segment: 'ru29_2013_270_3_0'
             sourceFile: '/tmp/deployments/2013/ru29-374/ascii/sbd/ru29_2013_270_3_0_sbd.dat'
         the8x3filename: '01210000'
               filetype: 'sbd'
                  bytes: 440221
                   rows: 1408
                sensors: {76x1 cell}
            sensorUnits: [1x1 struct]
           startDatenum: 735505.38911296
             endDatenum: 735505.545664734
              startTime: '2013-09-28 09:20:19'
                endTime: '2013-09-28 13:05:45'
        timestampSensor: 'drv_m_present_time_datenum'
            depthSensor: 'drv_m_pressure'
    dbdTimestampSensors: {4x1 cell}
        dbdDepthSensors: {4x1 cell}
            profileInds: [2x2 double]
            numProfiles: 2
              fillTimes: 'none'
         proMinTimeSpan: 8
        proMinNumPoints: 2
             fillDepths: 'none'
            proMinDepth: 1
        proMinDepthSpan: 2
                fillGps: 'none'
         hasBoundingGps: 1
                scratch: []

>>

####Dbd Class Properties####

Instances of the Dbd class have the following properties (properties in bold face may be changed by the user):

  • glider : glider name
  • segment : segment name of the source file
  • sourceFile : fully-qualified path the source file
  • filetype : file type
  • bytes : size of the file in bytes
  • rows : number of rows in the segment data set
  • sensors : cell array containing the names of the sensors in the file. Sensors with the drv prefix are derived sensors, meaning that they were created from the raw sensor data with some conversion applied.
  • sensorUnits : structured array mapping sensor names to the default sensor units, taken from masterdata. These units are only available if the source file created without using dba2_orig_matlab to create an m-file.
  • startDatenum : first valid timestamp for the currently selected timestamp sensor ( Dbd.timestampSensor ).
  • endDatenum : last valid timestamp for the currently select timestamp sensor ( Dbd.timestampSensor ).
  • timestampSensor : currently selected timestamp sensor. This value is selected from the list of available sensors ( Dbd.dbdTimestampSensors ). All native glider timestamp sensors are in unix time units (seconds since 1970-01-01 00:00:00 UTC). Any timestamp sensor with a drv prefix has been converted to Matlab datenum units.
  • depthSensor : currently selected depth sensor. This value is selected from the list of available sensors ( Dbd.dbdDepthSensors ). All native pressure sensors are specified in bars. Any sensor with a drv prefix has been converted to decibars.
  • profileInds : 2 column array containing the start and stop row indices for each indexed profile.
  • numProfiles : number of indexed profiles. The indexed yo (time-depth) is constructed from the Dbd.timestampSensor and Dbd.depthSensor .
  • fillTimes : string specifying the interpolation method to be used when dumping time-series data. Default is none, meaning that no interpolation is performed on missing timestamps. Method must be a valid interp1.m method.
  • proMinTimeSpan : minimum number of seconds a profile must span to be considered valid. Default is 8 seconds.
  • proMinNumPoints : minimum number of points a profile must contain to be considered valid. Default is 2.
  • fillDepths : string specifying the interpolation method to be used when dumping time-series data. Default is none, meaning that no interpolation is performed on missing pressures/depths. Method must be a valid interp1.m method.
  • proMinDepth : number specifying the depths to exclude when indexing profiles. Default is to exclude depths shallower than 1 meter.
  • proMinDepthSpan : minimum depth range a profile must span to be considered value. Default is 2 meters.
  • fillGps : string specifying the interpolation method to be used when interpolating measured GPS positions. Default is none, meaning that no interpolation is performed on missing pressures/depths. Method must be a valid interp1.m method. The data set must contain at least one indexed profile bounded by measured GPS positions in order to perform the interpolation.
  • hasBoundingGps : logical scalar specifying whether the data set contains at least one indexed profile bounded by measured GPS positions. If this value is false, GPS positions will not be interpolated.
  • scratch : empty array that can be used to store external data, state, etc,.

####Dbd Class Methods for Modifying the Instance####

Instances of the Dbd class have the following methods that may be used to modify the properties of the instance or the underlying dataset:

  • addSensor : add new sensor data, under the specified sensor name and specify (optional) the units.
  • deleteSensor : remove the sensor(s) contained the specified sensor_list from the Dbd instance. Optionally, you may replace the sensor_list with the 'regexp' option and a cell array of regular expressions to match against.

Type 'help Dbd.method' to get a detailed description of the arguments passed to each method and the resulting behavior.

####Dbd Class Methods for Exporting Sensor Data####

Instances of the Dbd class have the following methods that may be used to export sensor data:

  • averageProfiles : Calculate the downcast, upcast and total means and standard deviations for the specified sensor. The profiles are binned to 1 meter depth prior to performing the statistical analysis.
  • toArray : export sensor data to an MxN array.
  • toDbdStruct : export the dataset to a structured array with associated metadata.
  • toGrid2d : export sensor data to a 2-D array suitable for contour or surface plotting.
  • toGrid3d : export sensor data to a 3-D array suitable for contour or surface plotting.
  • toProfiles : export the dataset to a structured array containing individual profiles.
  • toStruct : export the dataset to a structured array mapping sensor names to sensor data.

Type 'help Dbd.method' to get a detailed description of the arguments passed to each method, options and return values.

####Dbd Class Visualization Methods####

Instances of the Dbd class have the following methods that may be used to visualize the underlying dataset:

  • plotProfiles : display a clickable image of indexed sensor profile data.
  • plotSampleMap : display a map of the raw glider sensor sampling frequency independent of the selected timestamp.
  • plotSensorMap : display a map of the raw glider sensor sampling frequency that has been timestamped with the Dbd.timestampSensor . This routine is handy for visualizing the time dependence/sensor alignment.
  • plotXY : display a plot of sensor X vs sensor Y.
  • plotYo : display a plot of the yo (time-depth series) using Dbd.timestampSensor and Dbd.depthSensor .

Type 'help Dbd.method' to get a detailed description of the arguments passed to each method, options and return values.

Clone this wiki locally