NAME
ReadNC
DESCRIPTION
This module reads netCDF files and converts them to lattices. Before
the conversion, the selected netCDF variables can be sampled, cropped,
and their dimensionality can be reduced. This allows small pieces of
large files to be brought into Explorer. The optional "missing_value"
number can also be replaced with another number in the lattice data.
ReadNC provides information about all the meta-data in the netCDF file
using scrolling lists. In addition, selected parts are output on parameter
ports for easy use in other modules. These include the global "title"
attribute, as well as the name ("long_name" attribute) of the selected
variable along with its "units" attribute and dimension names. All the
meta-data will come from the last selected variable.
ReadNC supports the selection of multiple variables using an internal
variables list. Variables are selected from the "File Variables" list,
(which always contains all the variables found in the current file) by
clicking on one variable at a time or drag-selecting adjacent variables.
The "Information" list can show all the selected variables and their
information or the global information about the netCDF file itself. There
is currently a limit of 10 selected variables and a button is provided to
empty the list. Only variables with the same datatype, the same number
of dimensions, and the same dimension sizes can be combined into
vectors.
ReadNC also supports netCDF files containing variables with "packed"
(compressed) data. It looks for the "add_offset" and "scale_factor"
attributes to unpack the data. Currently, it unpacks variables with byte
and short datatypes into floats. If missing values (as specified by the
"missing_value" attribute) are found during variable unpacking then
they are replaced with the value of the "New Special Value" widget.
ReadNC was written to make up for the lack of some necessary features
in ReadDF while simultaneously duplicating most of its functionality.
The biggest drawback with ReadDF is that all the selected variables are
sent out in their entirety. This is fine for relatively small files, but what
about those that could be dozens of megabytes? ReadDF also doesn't
provide a way to send out the essential meta-data. Although, ReadDFG
could be used, but in that case the "Grid" data type must be dealt with;
an extra step. Another problem with ReadDF is that it doesn't properly
handle the coordinates associated with netCDF's unlimited (record)
dimension. The only other significant difference between ReadDF and
ReadNC is that when selecting a variable in ReadDF, it actually scans
all of that variable's data in order to find the minimum and maximum.
ReadNC saves time by avoiding this step so the variable information can
be seen more quickly. In ReadDF's defense, it has much better control
over which variables should go to which output lattices. ReadNC,
however, is limited to one output lattice which cannot have more than
four dimensions.
WIDGETS
Filename -- Text
This is the name of the netCDF file to read.
New Special Value -- Text
This is a value which can replace values in the data specified by the
"missing_value" attribute. ReadNC first looks for a "missing_value"
attribute for the last selected variable. If it doesn't exist, then it looks
for a global "missing_value" attribute. The local one will always take
precedence over the global one.
Replace Special? -- Option Menu
This determines whether the value of "New Special Value" will be used
to replace the missing values in the output lattice's data. It is only used
if the netCDF file has a global or local "missing-value" attribute.
Sample -- Slider
This is the stride for sampling along each of the axes.
File Variables -- Scroll List
This is a list of all the variables found in the netCDF file. It doesn't
include any dimensions, although technically they are variables as well.
Information -- Scroll List
This list can contain information about the entire netCDF file or about
the selected dimensions (if any). When a netCDF file is first read or
when one or more variables are selected, the relevant information is
saved. The group of information that is displayed is based on the
setting of the "Which Info?" buttons.
Which Info? -- Radio Box
This selects whether information is displayed about the the netCDF file
in general or about the currently selected variables.
Clear Vars. -- Button
This deletes the list of all the selected variables if they are displayed
with the "Selected Var. Info" option from "Which Info?".
Mode -- Option Menu
This determines whether the output lattice will be generated. "Build"
mode allows all the widgets to be set without creating an output lattice
each time. "Run" mode uses all the settings to create the output lattice.
I Start -- Slider
This is the lower bound for cropping along the I axis.
I End -- Slider
This is the upper bound for cropping along the I axis.
J Start -- Slider
This is the lower bound for cropping along the J axis.
J End -- Slider
This is the upper bound for cropping along the J axis.
K Start -- Slider
This is the lower bound for cropping along the K axis.
K End -- Slider
This is the upper bound for cropping along the K axis.
T Start -- Slider
This is the lower bound for cropping along the T axis.
T End -- Slider
This is the upper bound for cropping along the T axis.
Fixed I? -- Option Menu
This determines whether the I axis will be fixed when cropping and/or
sampling for the output lattice. If "Yes", it will be fixed at the value of
"I Start" and "I End" will disappear and be ignored. It essentially
removes the selected variable's I axis.
Fixed J? -- Option Menu
This determines whether the J axis will be fixed when cropping and/or
sampling for the output lattice. If "Yes", it will be fixed at the value of
"J Start" and "J End" will disappear and be ignored. It essentially
removes the selected variable's J axis.
Fixed K? -- Option Menu
This determines whether the K axis will be fixed when cropping and/or
sampling for the output lattice. If "Yes", it will be fixed at the value of
"K Start" and "K End" will disappear and be ignored. It essentially
removes the selected variable's K axis.
Fixed T? -- Option Menu
This determines whether the T axis will be fixed when cropping and/or
sampling for the output lattice. If "Yes", it will be fixed at the value of
"T Start" and "T End" will disappear and be ignored. It essentially
removes the selected variable's T axis.
Automatic Max Range? -- Option Menu
This determines whether the necessary widgets will be set so as to
maximize the size of the output lattice based on the selected variable(s).
The "Start *" sliders are all set to 1. The "End *" sliders are all set to
the size of their corresponding dimensions. The "Sample" slider is set
to 1. Finally, all the "Fixed *" option menus are set to "No".
Saved List -- Text
This hidden port is used to save the selected variables with a map.
Nothing should ever be connected to it or unpredictable results might
occur!
OUTPUTS
Output -- Lattice
This is the sampled and/or cropped lattice with the selected number of
dimensions.
Global Title -- Parameter
This is the global "title" attribute of the netCDF file. If it doesn't have
this attribute then this parameter will be blank.
Missing Value -- Parameter
This is a "missing_value" attribute of either the entire netCDF file or the
selected variable. ReadNC first looks for the global one to put on this
port. If a selected variable has a "missing_value" attribute of its own
then the local one will always take precedence over the global one.
Missing Value Exist -- Parameter
This is a flag indicating whether a "missing_value" attribute was found
(0=no, 1=yes).
Variable Name -- Parameter
This is the name of the last selected variable as specified by the
"long_name" attribute. If it doesn't have this attribute then this
parameter will not change.
Variable Units -- Parameter
This is the "units" attribute of the last selected variable. If it doesn't
have this attribute then this parameter will not change.
Dimension 1 Name -- Parameter
This is the name of the first dimension of the last selected variable. If
the variable has less than one dimension (quite pointless) then this
parameter will not change.
Dimension 2 Name -- Parameter
This is the name of the second dimension of the last selected variable.
If the variable has less than two dimensions then this parameter will not
change.
Dimension 3 Name -- Parameter
This is the name of the third dimension of the last selected variable. If
the variable has less than three dimensions then this parameter will not
change.
Dimension 4 Name -- Parameter
This is the name of the fourth dimension of the last selected variable. If
the variable has less than four dimensions then this parameter will not
change.
KNOWN PROBLEMS
ReadNC is currently limited to one output lattice and four dimensions. A
packed byte or short variable cannot be combined with a float variable
since it has a different datatype before the unpacking. There are no
known bugs.
SEE ALSO
ReadDF, ReadDFG, ReadPerimCDF, WritePerimCDF
-
Hans Vahlenkamp (Hans.Vahlenkamp@noaa.gov)
Geophysical Fluid Dynamics Laboratory / NOAA
Princeton University Forrestal Campus
http://www.gfdl.noaa.gov
