oce (version 1.8-4)

read.netcdf: Read a NetCDF File

Description

Read the contents of a NetCDF file, saving the information in a basic oce object. Since NetCDF files can hold any manner of data, read.netcdf() might be used as a first step in the construction of another object of a specialized class, perhaps ctd, topo, etc. As explained in “Details”, the renamer argument can facilitate this work. More work is required to move flags from the data slot of the result to the metadata slot, and this is illustrated in Example 3.

Usage

read.netcdf(
  file,
  ...,
  encoding = NA,
  renamer = NULL,
  debug = getOption("oceDebug")
)

Value

An oce object with var elements from the NetCDF file stored in the data slot. See the “Examples” for hints on renaming the elements, and moving some of them to the metadata slot.

Arguments

file

character value specifying the name of a NetCDF file.

...

ignored

encoding

ignored.

renamer

function used to rename variables that are read from the file, or NULL (which is the default) to avoid such renaming. See “Details”.

debug

an integer specifying whether debugging information is to be printed during the processing. This is a general parameter that is used by many oce functions. Generally, setting debug=0 turns off the printing, while higher values suggest that more information be printed. If one function calls another, it usually reduces the value of debug first, so that a user can often obtain deeper debugging by specifying higher debug values.

Author

Dan Kelley

Details

By default, the names of the data variables are not changed from those in the data file. This can be confusing to users who are unfamiliar with the naming scheme used in a particular file, and so read.netcdf() has a parameter named renamer with which the user can provide a translation key to go from names in the NetCDF file to more standard oce names (like salinity). See “Examples” to see how this works, for a particular file that follows the NERC/BODC convention for naming variables.

Unlike more specialized functions such as read.ctd.sbe(), read.netcdf() does not try to associate data-quality flags with the corresponding data items. This is because, in the files examined by the author, there is no clear pattern in the names. For example, the test file referred to in the “Examples” section (which is not supplied with this package) has three variables that relate to temperature, namely "TEMPS901", "TEMPP901", and "TEMPPR01". Given common naming conventions, a quality flag variable is normally constructed by prepending the letter "Q" to the name of another variable. Although there are no such names in this dataset, it does have something called "QTEMP_01" that one might guess to be a temperature-quality flag. Based on this (and similar) assumptions, Example 3 shows how to move data-quality variables from the data slot of the returned object to the metadata slot, which is where oce expects to find it, for further processing of data-quality flags.

In this same example file, there are some data fields that contain strings that evidently provide calibration and other information on some of the sensors. Example 3 shows how to move these things from the data slot to the metadata slot.

Readers might wonder why the renaming and moving of material from the data slot to the metadata slot is not done by read.netcdf() itself. The answer is that these things apply only to files of the type being dealt with in this example. The NetCDF format can hold a very wide variety of information, and so the basic behaviour of read.netcdf() is just to read the data items (things called var by functions in the ncdf4 package, which read.netcdf() uses to read the file) and store them in the data slot. In most cases, it is simply up to the user to decide what to do with the information.

Finally, it should be noted that read.netcdf() tries to get some common metadata elements from global attributes in the NetCDF file. These include Longitude, Latitude, Ship and Cruise, all of which are renamed in lower-case and stored in the metadata slot, in accordance with oce convention.

References

1. Data variable vocabulary used by NERC/BODC. http://vocab.nerc.ac.uk/collection/P01/current/

2. CIOOS Atlantic ERDDAP server entry for Bedford Institute measurements in the waters of Maritime Canada. https://cioosatlantic.ca/erddap/files/bio_maritimes_region_ecosystem_survey_ctd/ (Link tested 2024-09-21.)

Examples

if (FALSE) {
# Download the file.  (This may break if the server changes.)
file <- tempfile(fileext = ".nc")
url <- paste0(
    "https://cioosatlantic.ca/erddap/files/",
    "bio_maritimes_region_ecosystem_survey_ctd/",
    "Maritimes%20Region%20Ecosystem%20Survey%20Summer/",
    "2023/CTD_CAR2023011_001_496780_DN.ODF.nc"
)
download.file(url, file)

# Example 1: read without translating names
d <- read.netcdf(file)
summary(d)

# Example 2: as Example 1, but translate (some) names
d <- read.netcdf(file, renamer = bodcNames2oceNames)
summary(d)

# Example 3: as Example 2, but handle some flags that were
# noticed in this particular file.  See Details for more
# notes on variable names.  Note that the following code
# only deals with the first instance of a variable, e.g.
# temperature, and not temperature2 or temperature3.
# (This is of little consequence, since all 3 of the temperatures
# are identical.)
d <- read.netcdf(file, renamer = bodcNames2oceNames)
# Looking within the NetCDF file indicates that the built-in
# scheme for DFO files is appropriate here.
d <- initializeFlagScheme(d, name = "DFO")
# Move some data elements to the `metadata@flags` list,
# so they can be used for flag-handling operations. Some
# guesses had to be made on the name mapping (see Details).
flags <- list(
    QALTB_01 = "heightAboveBottom",
    QCPHLPR01 = "cholorophyll-a",
    QCNDC_01 = "conductivity",
    QDOXY_01 = "oxygen",
    QOXYV_01 = "oxygenVoltage",
    QPOTM_01 = "theta",
    QPRES_01 = "pressure",
    QPSAL_01 = "salinity",
    QPSAR_01 = "downwellingIrradiance",
    QSIGP_01 = "sigmaTheta",
    QTEMP_01 = "temperature"
)
for (i in seq_along(flags)) {
    varName <- flags[[i]]
    flagName <- names(flags)[i]
    # cat("fileName=", varName, ", flagName=", flagName, "\n", sep="")
    d@metadata$flags[[varName]] <- d[[flagName]] # move
    d@data[[flagName]] <- NULL # delete original
}
# For this group of files, it appears that sensor metadata are
# stored with particular names, e.g. "TemperatureSensor". The
# following moves these from the data slot to the metadata slot.
dataNames <- names(d@data)
for (sensorName in dataNames[grep("Sensor$", dataNames)]) {
    d@metadata[[sensorName]] <- d@data[[sensorName]]
    d@data[[sensorName]] <- NULL
}
summary(d)
# Display information about the temperator sensor
cat("Temperature Sensor\n")
if (require("jsonlite")) {
    str(jsonlite::fromJSON(d[["TemperatureSensor"]]))
}

# Finally, remove the downloaded file, according to CRAN
# policy regarding downloads in documentation examples.
file.remove(file)
}