Reading and Loading Data

Contains high level routines for reading in instrument binary data, and saving and loading xarray datasets. DOLfYN will automatically search through and select a binary reader based on the input data’s file extension.

`read`	Read a binary Nortek (e.g., .VEC, .wpr, .ad2cp, etc.) or RDI (.000, .PD0, .ENX, etc.) data file.
`read_example`	Read an ADCP or ADV datafile from the examples directory.
`save`	Save xarray dataset as netCDF (.nc).
`load`	Load xarray dataset from netCDF (.nc)
`save_mat`	Save xarray dataset as a MATLAB (.mat) file
`load_mat`	Load xarray dataset from MATLAB (.mat) file, complimentary to save_mat()

I/O functions can be accessed directly from DOLfYN’s main import:

>> import dolfyn
>> dat = dolfyn.read(<path/to/my_data_file>)
>> dolfyn.save(dat, <path/to/save_file.nc>)

dolfyn.io.api.read(fname, userdata=True, nens=None, **kwargs)[source]

Read a binary Nortek (e.g., .VEC, .wpr, .ad2cp, etc.) or RDI (.000, .PD0, .ENX, etc.) data file.

Parameters:

filename (string) – Filename of instrument file to read.
userdata (bool, or string of userdata.json filename (default True)) – Whether to read the ‘<base-filename>.userdata.json’ file.
nens (None, int or 2-element tuple (start, stop)) – Number of pings or ensembles to read from the file. Default is None, read entire file
**kwargs (dict) – Passed to instrument-specific parser.

Returns:

ds (xarray.Dataset) – An xarray dataset from instrument datafile.

dolfyn.io.api.read_example(name, **kwargs)[source]

Read an ADCP or ADV datafile from the examples directory.

Parameters:

name (str) –

A few available files:

AWAC_test01.wpr BenchFile01.ad2cp RDI_test01.000 vector_burst_mode01.VEC vector_data01.VEC vector_data_imu01.VEC winriver01.PD0 winriver02.PD0

Returns:

ds (xarray.Dataset) – An xarray dataset from the binary instrument data.

dolfyn.io.api.save(ds, filename, format='NETCDF4', engine='netcdf4', compression=False, **kwargs)[source]

Save xarray dataset as netCDF (.nc).

Parameters:

ds (xarray.Dataset) – Dataset to save
filename (str) – Filename and/or path with the ‘.nc’ extension
compression (bool (default: False)) – When true, compress all variables with zlib complevel=1.
**kwargs (dict) – These are passed directly to xarray.Dataset.to_netcdf()

Notes

Drops ‘config’ lines.

Rewrites variable encoding dict

More detailed compression options can be specified by specifying ‘encoding’ in kwargs. The values in encoding will take precedence over whatever is set according to the compression option above. See the xarray.to_netcdf documentation for more details.

dolfyn.io.api.load(filename)[source]

Load xarray dataset from netCDF (.nc)

Parameters:: filename (str) – Filename and/or path with the ‘.nc’ extension
Returns:: ds (xarray.Dataset) – An xarray dataset from the binary instrument data.

dolfyn.io.api.save_mat(ds, filename, datenum=True)[source]

Save xarray dataset as a MATLAB (.mat) file

Parameters:

ds (xarray.Dataset) – Dataset to save
filename (str) – Filename and/or path with the ‘.mat’ extension
datenum (bool) – If true, converts time to datenum. If false, time will be saved in “epoch time”.

Notes

The xarray data format is saved as a MATLAB structure with the fields ‘vars, coords, config, units’. Converts time to datenum