NetCDF object

class NetCDF

Metview includes some functionality on NetCDF data. In addition to taking NetCDF as input, Metview generates NetCDF data in some contexts, notably when data slices are generated by modules such as mcross_sect() and mhovmoeller_area().

Construction

A NetCDF file can be read from disk using read():

import metview as mv

nc = mv.read("mydata.nc")

Examining NetCDF contents

If Metview has been built with its graphical user interface, the contents of a NetCDF file can be inspected with the NetCdf Examiner, which can be started up from the user interface (right-click examine on the icon).

Visualisation

Direct visualisation of NetCDF is not available in Metview but it is implemented via the NetCDF Visualiser icon (netcdf_visualiser()). With this we can specify the view type, the variable and the dimensions (with slicing) to generate the actual plot. Visualisation is supported both on maps and xy-charts for scalar and vector data, as well.

Processing NetCDF data

How operators and functions work on NetCDF

NetCDF files can contain a wide variety of data. They can contain a number of data units, e.g. a set of cross section plots, a set of 2D geographical grids, a set of time series or vertical profiles, etc. Each component of a set is stored in the netCDF file as a separate netcdf variable. The handling of and computations with netCDF files are based on the concept of current variable.

Out of the N variables contained in a netCDF file, one is always set to be the current variable. Functions and operators acting upon the netcdf file will act only upon the current variable .

In general, users set the current variable (which by default is the first variable in the file) to one of those contained in the file and can then apply a number of functions and operators to them:

setcurrent(netcdf1, "rh") # use the variable called "rh" in this netCDF file
setcurrent(netcdf2, 2) # use the 2nd variable in this netCDF file
netcdf3 = netcdf1 op netcdf2
out = function(netcdf1, ...)

However, because functions and operators work only on the current variable, when the netCDF contains more than one variable (a multi-variable netCDF), special care must be taken when you need the operator/function to apply to all variables - this is detailed later in this page.

When two netCDF variables are involved, both files have to have the same number of data points in each current variable, as an operation between two netCDFs is carried out between each pair of corresponding data values. Alternatively, an operation can be between a NetCDF variable and a constant, or a function can work entirely on a single NetCDF variable. Examples of these are shown here:

nc3 = nc1 + nc2   # current variables of nc1 and nc2 are used
nc2 = nc1 + 10.8  # current variable of nc1 is used
nc2 = nc1.sqrt()  # current variable of nc1 is used

NOTE : Like fieldsets, a netCDF resulting from an operation on two other netCDFs, will take the metadata (e.g. date, time, parameter, levels, …) from the first netCDF.

Scaled values

By default, Metview will apply any scale_factor and add_offset attributes for the current variable. This behaviour can be toggled using the function netcdf_auto_scale_values().

Missing values

By default, Metview will check the _FillValue attribute of the current variable and will not include any such values in its calculations. This behaviour can be toggled using the function netcdf_preserve_missing_values().

Working with multi-variable NetCDF files

Functions and operators working on netCDF files apply only to the current variable. When the netCDF file contains several variables, you need to address each variable separately and explicitly, and apply the function /operator to each in turn. For this purpose, Metview provides functions to query the contents of a netCDF file and to set one of its variables to be the current variable.

Users can list the variables held in a netcdf variable by means of the function variables():

var_list = nc.variables()

This returns a list of strings, each holding a variable name. Counting the number of elements in the output list gives the number of variables.

To set one of the existing variables to be the current variable, use function setcurrent(), which takes the index (starting at 1) of the desired variable:

nc.setcurrent(n)

Extracting NetCDF values

If you need to have access to the data values of a netcdf current variable, you can use function values():

val_list = nc.values()

which returns a numpy array with all the values for the current variable.

An alternative method for accessing individual values is to the use the function value():

val = nc.value(n)

which returns the nth value from the current netcdf variable.

Time variables

Variables which are detected to be of ‘time’ type (e.g. attribute standard_name=’time’, plus other checks) are, by default, retrieved by the value() and values() functions as a date or a list of dates. This behaviour can be toggled calling the function netcdf_auto_translate_times() with an argument of 1 or 0 to activate/deactivate the translation to dates. If deactivated, the value() and values() functions will instead return a number or a vector of raw numbers as they are encoded in the variable.

Automatic rescaling of values

If Metview performs a computation on a variable which results in its values overflowing the data type used to pack the values in the netCDF variable (e.g. adding 3000 to the values of a Byte variable), and the variable has scale_factor and add_offset attributes, Metview will compute new scale_factor and add_offset attributes so that the values can be packed within the data type, making best use of its data range. In this case, the _FillValue may be modified too.

This rescaling will not be performed if these attributes are not defined for the current variable, or if Metview has been instructed to ignore them (via the netcdf_auto_scale_values() function). The automatic rescaling behaviour can be toggled on or off via the netcdf_auto_rescale_values_to_fit_packed_type() function. If disabled, and the computed values overflow the data type, the macro will fail.