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 arrays, if desired.)
Download
| Download |
Date last modified |
Tested with MATLAB Version |
| readsb.m |
2023-03-23
|
R2016a
|
The last update added a minor number of known text fields to help read files containing R2R_Event, etc.
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);
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.