readsb (MATLAB)

readsb.m is a MATLAB function designed to open and read data files that are in a SeaBASS format. Some SeaBASS files can be opened using MATLAB's various built-in import functions, however many of the built-in methods are unsuited to efficiently open SeaBASS files without errors or significant manual intervention. Using this function, data outputs can simply be returned as either a cell array or as a structure where the names of the data field headers from the SeaBASS file are array field names (e.g. dataStructure.DEPTH, dataStructure.CHL, dataStructure.LW412). File metadata information is also returned in a separate structure and array.


Table of Contents


Download

Download Date last modified Matlab Version Supported
readsb.m
2018-04-02
R2016b
readsb_2012b.m
2016-02-10
R2012b and older (does not support all features)
 
The last update added a minor feature to include "station" as one of the "FillAncillaryData" fields. Also, all header output now includes 2 new additions containing extra information (fields_list and wavelength_lists; the latter was originally added to the data matrix but it has been relocated to the header where it is a better fit).

Software Usage Policy

NASA Goddard Space Flight Center (GSFC) Software distribution policy for Public Domain Software
 
The readsb code is in the public domain, available without fee for educational, research, non-commercial and commercial purposes. Users may distribute this code to third parties provided that this statement appears on all copies and that no charge is made for such copies.
 
NASA GSFC MAKES NO REPRESENTATION ABOUT THE SUITABILITY OF THE SOFTWARE  FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY. NEITHER NASA GSFC NOR THE U.S. GOVERNMENT SHALL BE LIABLE FOR  ANY DAMAGE SUFFERED BY THE USER OF THIS SOFTWARE.
 

Important Notes

  • This script is designed to work with files that have been properly formatted according to SeaBASS guidelines (i.e. files that passed FCHECK). Some error checking is performed, but improperly formatted input files could cause this script to error or behave unexpectedly. Files downloaded from the SeaBASS database should already be properly formatted; however, please email seabass@seabass.gsfc.nasa dot gov and/or the contact listed in the file's metadata header if you identify problems with specific files.
  • It is always HIGHLY recommended that before performing calculations with data sets you also check for and read any metadata header comments and/or any documentation accompanying the data files. Special notes and metadata information might impact your analysis.
  • readsb was tested primarily with MATLAB R2016.
  • refer to the script's header or "help readsb" for the most up-to-date usage information

 

How to Use

Refer to "help readsb" for the most up-to-date and thorough information.
 
This function always requires as input a FILENAME from the current working directory (or full filepath). A few of the optional argument pairings are described below on the page, but there are many more. For the most detailed and up-to-date information, read the header of the function (or within MATLAB use "help readsb").
 
syntax: [data, sbHeader, headerArray, dataArray] = readsb(fileName, <optional arguments paired with values>)

Example:

[data, header] = readsb('myfile.csv', 'MakeStructure', 1, 'SetBDLValue',NaN);
 
 

Input Arguments

 

FILENAME (required)

Syntax: readsb(FILENAME)
FILENAME must be the first argument. It is the name of the single SeaBASS formatted file you wish to load into MATLAB.
 

SetBDLValue (optional)

SetBDLValue 
Example: readsb(FILENAME, 'SetBDLValue', NaN)
           or readsb(FILENAME, 'SetBDLValue', -8888);
 
Use SetBDLValue to mask any below detection limit values in the file to a NaN or number of your choice. Setting them to a NaN is a common choice, to mimic the default value of how this function treats /missing values (if appropriate to your own analysis). If this optional argument isn't specified, the BDL values remain whatever fill value was specified in the metadata header /below_detection_limit. A very similar argument, SetADLValue, is available for modifying any /above_detection_limit values.
 

MakeStructure (optional)

MakeStructure  (0 by default if this argument is not used)
Example: readsb(FILENAME, 'MakeStructure', true)
 
By default readsb outputs all values in a cell array. Include MakeStructure with value true if you instead want a structure. The structure will contain a field named for each data field (e.g. data.chl, data.phaeo, data.LU410, etc.)
 

Outputs

[data, sbHeader, headerArray, dataArray] = readsb(FILENAME)

data is by default a cell matrix, but will be a structure if the 'MakeStructure' argument is used and set to true.

sbHeader is a structure of the SeaBASS file's header where the fields are based on metadata header names (e.g. sbHeader.missing)

headerArray is a cell array containing the verbatim contents of the SeaBASS header. It is typically only useful if you are planning to modify the data and then re-write a SeaBASS file keeping the original header format mostly intact.

dataArray is a cell array containing the verbatim contents of the SeaBASS data block. It is typically only useful if you are planning to re-write a SeaBASS file.
Last edited by Joel Scott on 2018-04-02
Created by Chris Proctor on 2013-03-20