readsb (Python)
SB_support.py is a Python module containing a set of classes designed to open, read, and manipulate data files that are in
SeaBASS file format. While many of Python's built-in functions may be used to read SeaBASS files, this module leverages Python libraries and tools to efficiently read, sort, mask, and return the contained data for easy use without errors or significant intervention. Using this function, data outputs will be returned as data structures containing the file's header information (metadata) as an array of strings, the file's comments as an array of strings, the file's missing data, above detection limit, and below detection limit values (if present), the file's variable and unit lists as an Ordered Dictionary indexed by variable name, and the file's data as an Ordered Dictionary indexed by variabile name. Additionally, optional arguments flags that may be toggled are mask_missing, mask_above_detection_limit, and mask_below_detection_limit (all set true by default), which remove the relevant header-defined fill values, replacing them with NaN.
Download
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 module 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.
- Compatibility: readSB in SB_support.py was developed for Python 3.
- Refer to the module's header for the most up-to-date usage information.
How to Use
Refer to SB_support.py's header for the most up-to-date information.
This function always requires as input a FILENAME from the current working directory (or full filepath). There are optional argument pairings described below that enable various features. For the most detailed and up-to-date information, read the header of the Python module or readSB function.
syntax: data = readSB(filename=fname)
Required arguments:
filename = name of SeaBASS input file (string)
Optional arguments:
mask_missing = flag to set missing values to NaN, default set to True
mask_above_detection_limit = flag to set above_detection_limit values to NaN, default set to True
mask_below_detection_limit = flag to set below_detection_limit values to NaN, default set to True
no_warn = flag to suppress warnings, default set to False
Returned data structures:
filename = name of data file
header = array of strings containing non-comment lines from the header information
comments = array of strings containing the comment lines from the header information
missing = fill value used for missing data, read from header
variables = dictionary of variable and unit for each data type
data = dictionary of variable and values for each data type
length = number of rows in the data matrix (i.e. the length of each list in data)
data_use_warning = logical indicating if the /data_use_warning= header is set
pi = primary investigator (i.e. the first investigator listed)
bdl = fill value used for below detection limit, read from header (empty if missing or N/A)
adl = fill value used for above detection limit, read from header (empty if missing or N/A)
err_suffixes = list of supported field suffixes for expressing errors in a SeaBASS file
Built-in methods:
.fd_datetime() - Converts date and time information from the file's data matrix to a Python list of datetime objects
.addDataToOutput(irow, var_name, units, var_value, overwrite)
.writeSBfile(ofile) - Writes headers, comments, and data into a SeaBASS file specified by ofile