Class DBD : reading single files

DBD API

The DBD class is designed to be used with a single file, either a dbd (sbd) or ebd (tbd) file. The actual reading of the binary files if offloaded to a C-extension.

There is a small issue with the way the glider creates a new file. When opening a new file, all sensors are reported as updated, even though most sensors are not, and report whatever value is stored in memory. As a result all sensors that update regularly will be reported with old values. Therefore the default behaviour is to disregard the first data entry for each sensor. There are, however, some sensors that are set once, and never update. Dropping the first data entry, also drops this information. Therefore, for specific or debugging purposes, the default behaviour can be altered to also include the first data entries of all sensors, by setting the optional keyword skip_initial_line to False, when calling the constructor.

class dbdreader.DBD(filename, cacheDir=None, skip_initial_line=True)

Class to read a single DBD type file

Parameters:

  • filename (str) – dbd filename

  • cachedDir (str or None, optional) – path to CAC file cache directory. If None, the default path is used.

  • skip_initial_line (bool, default: True) – controls the behaviour of the binary reader: if set to True, all first lines of data in the binary files are skipped otherwise they are read. Default value is True, as the data in the initial file have usually no scienitific merit (random value or arbitrarily old); only for debugging purposes one may want to have the initial data line read.

close()

Closes a DBD file

get(*parameters, decimalLatLon=True, discardBadLatLon=True, return_nans=False, max_values_to_read=-1)

Returns time and parameter data for requested parameter

This method reads the requested parameter, and convert it optionally to decimal format if the parameter is latitude-like or longitude-like

Parameters:

  • *parameters (variable length list of str) – parameter name

  • decimalLatLon (bool, optional) – If True (default), latitiude and longitude related parameters are converted to decimal format, as opposed to nmea format.

  • discardBadLatLon (bool, optional) – If True (default), bogus latitiude and longitude values are ignored.

  • return_nans (bool, optional) – if True, nans are returned for timestamps the variable was not updated or changed.

  • max_values_to_read (int, optional) – if > 0, reading is stopped after this many values have been read.

Returns:

time vector (in seconds) and value vector

Return type:

tuple of (ndarray, ndarray) for each parameter requested.

Raises:

DbdError when the requested parameter(s) cannot be read. –

Changed in version 0.4.0: Multi parameters can be passed, giving a time,value tuple for each parameter.

Changed in version 0.5.5: For a single parameter request, the number of values to be read can be limited.

get_fileopen_time()

Returns the time stamp of opening the file in UTC

get_list(*parameters, decimalLatLon=True, discardBadLatLon=True, return_nans=False)

Returns time and value tuples for a list of requested parameters

This method returns time and values tuples for a list of parameters. It is basically a short-hand for a looped get() method.

Note that each parameter comes with its own time base. No interpolation is done. Use get_sync() for that in stead.

Parameters:

  • *parameters (list of str) – list of parameter names

  • decimalLatLon (bool, optional) – If True (default), latitiude and longitude related parameters are converted to decimal format, as opposed to nmea format.

  • discardBadLatLon (bool, optional) – If True (default), bogus latitiude and longitude values are ignored.

  • return_nans (bool) – If True, nan’s are returned for those timestamps where no new value is available. Default value: False

Returns:

  • list of (ndarray, ndarray) – list of tuples of time and value vectors for each parameter requested.

  • .. deprecated:: 0.4.0

  • .. note:: – This function will be removed in a future version. Use .get() instead.

get_mission_name()

Returns the mission name such as micro.mi

get_sync(*sync_parameters, decimalLatLon=True, discardBadLatLon=True)
Returns a list of values from parameters, all interpolated to the

time base of the first paremeter

This method is used if a number of parameters should be interpolated onto the same time base.

Parameters:

  • *sync_parameters (variable length list of str) – parameter names. Minimal length is 2. The time base of the first parameter is used to interpolate all other parameters onto.

  • decimalLatLon (bool, optional) – If True (default), latitiude and longitude related parameters are converted to decimal format, as opposed to nmea format.

  • discardBadLatLon (bool, optional) – If True (default), bogus latitiude and longitude values are ignored.

Returns:

  • (ndarray, ndarray, …) – Time vector (of first parameter), values of first parmaeter, and interpolated values of subsequent parameters.

  • Example – get_sync(‘m_water_pressure’,’m_water_cond’,’m_water_temp’)

Notes

Changed in version 0.4.0: Calling signature has changed from the sync parameters passed on as a list, to passed on as parameters.

get_xy(parameter_x, parameter_y, decimalLatLon=True, discardBadLatLon=True)

Returns values of parameter_x and paramter_y

For parameters parameter_x and parameter_y this method returns a tuple with the values of both parameters. If necessary, the time base of parameter_y is interpolated onto the one of parameter_x.

Parameters:

  • parameter_x (str) – parameter name of x-parameter

  • parameter_y (str) – parameter name of y-parameter

  • decimalLatLon (bool, optional) – If True (default), latitiude and longitude related parameters are converted to decimal format, as opposed to nmea format.

  • discardBadLatLon (bool, optional) – If True (default), bogus latitiude and longitude values are ignored.

Returns:

tuple of value vectors

Return type:

(ndarray, ndarray)

has_parameter(parameter)

Check wheter this file contains parameter

Parameters:

parameter (str) – parameter to check

Returns:

True if parameter is in the list, or False if not

Return type:

bool

DBD Example

import numpy as np
import dbdreader

# open a given file
dbd=dbdreader.DBD("data/amadeus-2014-204-05-000.sbd")

# print what parameters are available:
for i,p in enumerate(dbd.parameterNames):
    print("%2d: %s"%(i,p))

# get the measured depth
tm,depth=dbd.get("m_depth")

# print maximum depth
max_depth=depth.max()
print("\nmax depth %f m"%(max_depth))

# get lat lon
lat,lon=dbd.get_xy("m_lat","m_lon")

# interpolate roll speed on depth time
tm,depth,roll,speed=dbd.get_sync("m_depth","m_roll","m_speed")
print("\nmax speed %f m/s"%(np.nanmax(speed)))