add file naming conventions to the documentation

[rachela-sfei]

There are some conventions being applied by stglib regarding file naming, but I don't truly understand them. I think we should add some documentation that specify what they are, but it might be worth talking through that first!

Specifically, stglib reports -a.nc files, -s.nc files, s-a.nc files, b-cal.nc files, along with -cal.cdf. Maybe others?

Based on this document, https://pubs.usgs.gov/of/2007/1194/append1.html (table 1-2), "-a" means the best basic version (BBV). "-cal" means "Calibrated, or translated into scientific units, implies provisional status".

That document implies that "s" (before the -) means statistics, and that "b" (before the -) means burst, though I don't think it's spelled out.

I infer that "-s" means statistics, but it does not seem to be in the document.

In use in stglib, "-s" seems to contain things like burst mean and burst standard deviation, while "s-a" contains wave statistics.

If these are all and they are correct, I will add to stglib documentation, including a link to the usgs publication. But I bet I'm missing something!

[rachela-sfei]

Oh, I was re-reading the documentation ( https://pubs.usgs.gov/of/2007/1194/append1.html), and it looks like .nc also means best basic version: "The suffix ".nc" is typically used for files that have passed BBV review. Older netCDF files translated from data that were originally stored in Buoy Format often have ".cdf" extensions, but have been reviewed. In some cases, ".cdf" may be used to indicate provisional status." So, is -a redundant?

[dnowacki-usgs]

.cdf is deprecated in the wider community as far as I understand it. For example, Panoply won't open a file with a .cdf extension. We've been keeping it to differentiate raw vs processed, but at some point we may want everything to end with .nc, in which case we'd want to keep "-raw", "-a", etc.

Here's a snipped from Unidata at https://docs.unidata.ucar.edu/netcdf-c/current/faq.html :

NetCDF files should have the file name extension ".nc". The recommended extension for netCDF files was changed from ".cdf" to ".nc" in 1994 in order to avoid a clash with the NASA CDF file extension, and now it also avoids confusion with "Channel Definition Format" files.

Maybe after 30 years it's time to stop using .cdf 😃