...
fieldset ( fieldset op fieldset )
...
a = retrieve(...) b = retrieve(...) c = a and b
creates a fieldset c with values of 1 where the corresponding values of fieldset a and fieldset b are both non zero, and 0 otherwise. For an example of the use of boolean operators, see the mask function. A missing value in either input fieldset will result in a missing value in the corresponding place in the output fieldset.
fieldset ( fieldset and number )
fieldset ( number or fieldset )
...
Merge several fieldsets. The output is a fieldset with as many fields as the total number of fields in all merged fieldsets. Merging with the value nil does nothing, and is used to initialise when building a fieldset from nothing.
...
Returns the fieldset of the integer part of the input fieldset at each grid point or spectral coefficient. This function modifies the resulting GRIB header to be of integer data type, and is intended for the conversion of satellite data so that it can be plotted correctly by the MAGICS library. Missing values are replaced with INTLONG_MAX and should therefore continue to be interpreted as missing. This function was used in Metview 3 to enable the plotting of certain types of satellite imagery.
fieldset log ( fieldset )
...
For each field in the fieldset, the accumulate() this function calculates the sum of all the values of the field. If there is only one field in the fieldset, a number is returned. Otherwise, a list of numbers is returned. Only non-missing values are considered in the calculation. If there are no valid values, the function returns the grib missing value indicator nil for that field.
number or list average ( fieldset )
For each field in the fieldset, the average() this function calculates the average of all the field values. If there is only one field in the fieldset, a number is returned. Otherwise, a list of numbers is returned. Only non-missing values are considered in the calculation. If there are no valid values, the function returns the grib missing value indicator nil for that field.
Note that the average() function does not return the physically correct average of the field but merely the average of all field values. To get the physically correct average value of a field, use the integrate() function (which employs a cosine latitude weighting)
vector or list average_ew ( fieldset,list,number )
The function average_ew() takes as parameters a fieldset, a list of four numbers that define an area ( [N,W,S,E] ) and a number that defines the output one-dimensional grid interval in degrees.
The function returns a list vector (if the input fieldset contains only one field) or a list of listsvectors. The elements of the returned listvector(s) are means computed over rows of similar latitude using those grid points that fall inside the given area. Means are computed at intervals as specified in the third parameter. The output list vector size is thus independent of the grid interval in the input fieldset.
Each grid point value is weighted by the cosine of its latitude. Missing values are ignored. If a latitude belt contains no grid point values then a the missing value indicator vector_missing_value is returned.
Example:
ave = average_ew(fs, [60,-180,-60,180], 2.5)
This function call will compute means over full latitude circles starting from 60N, stepping 2.5 degrees until 60S. If fs contains only one field the output would be a list vector of 49 E-W mean values, from North to South. If fs contains n fields then the output would be a list of n listsvectors, where each of these n sublists vectors would contain 49 means.
For the above example, each value returned (representing the mean at latitude Lat ) is the mean of non-missing values in those grid points whose latitude coordinate is between Lat-1.25 and Lat+1.25 (1.25 is 2.5/2), i.e. within a latitude belt with width of 2.5 degrees, centered around Lat.
vector or list average_ns ( fieldset,list,number )
The function average_ns() takes as parameters a fieldset, a list of four numbers that define an area ( [N,W,S,E] ) and a number that defines the output one-dimensional grid interval in degrees.
The function returns a list vector (if the input fieldset contains only one field) or a list of listsvectors. The elements of the returned list(s) are means computed over lines of similar longitude using those grid points that fall inside the given area. Means are computed at intervals as specified in the third parameter. The output list vector size is thus independent of the grid interval in the input fieldset.
Each grid point value is weighted by the cosine of its latitude. Missing values are ignored. If a longitude line contains no grid point values then a the missing value indicator vector_missing_value is returned.
Example:
ave = average_ns(fs, [30,0,-30,360], 5)
This function call will compute means over longitudes 30N...30S, in 5 degree intervals around the globe. The result for each field in fs would be a list vector of 73 values (in this case values for 0 and 360 are duplicated values).
...
abs(data-value) <= threshold
...
list grib_get
...
(fieldset,
...
list)
...
list grib_get
...
(fieldset,
...
list
...
, string)
...
For the efficient retrieval of multiple GRIB keys from a fieldset. A single call to grib_get can replace multiple calls to the other grib_get_* functions and is hence more efficient. The keys are provided as a list for the second argument; by default they will be retrieved as strings, but their type can be specified by adding a modifier to their names, following the convention used by grib_ls where the key name is followed by a colon and then one or two characters which specify the type (s=string, l=long, d=double, la=long array, da=double array). For example, the key 'centre' can be retrieved as a string with 'centre' or 'centre:s', or as a number with 'centre:l'. The result is always a list of lists; by default, or if the optional third argument is 'field', the result will be grouped by field, containing one list per field, each of these lists containing one element per key; if the optional third parameter is 'key', the result will be grouped by key, containing one list per key, each of these lists containing one element per field. Example - the following lines of Macro code on a particular 6-field fieldset:
print(grib_get(data, ['editionNumber', 'centre', 'level', 'step'], 'field'))print(grib_get(data, ['editionNumber', 'centre:l', 'level', 'step'], 'key'))
produces this output:
[[1,ecmf,1000,0],[1,ecmf,500,0],[1,ecmf,100,0],[1,ecmf,1000,48],[1,ecmf,500,48],[1,ecmf,100,48]][[1,1,1,1,1,1],[98,98,98,98,98,98],[1000,500,100,1000,500,100],[0,0,0,48,48,48]]
number or list grib_get_long ( fieldset, string )
number or list grib_get_double ( fieldset, string )
number or list grib_get_string ( fieldset, string )
vector or list grib_get_long_array ( fieldset, string )
vector or list grib_get_double_array ( fieldset, string )
These functions return information from the given fieldset'These functions return information from the given fieldset's GRIB header. Available keys (to be passed as the second parameter) can be inspected by Examining the GRIB file (right-click, Examine). Alternatively, use the GRIB API command grib_dump to see the available key names. See httphttps://wwwsoftware.ecmwf.int/publicationswiki/manualsdisplay/grib_api/keys.htmlGRIB/Grib+API+keys for more details on key names.
The first three functions return a number if the input fieldset has a single field, otherwise they return a list of numbers. The `array' functions return a list vector of numbers if the input fieldset has a single field, otherwise they return a list of lists of numbersvectors.
The following example shows the retrieval of GRIB header information, including the derived key `max'max', using the different functions:
print (grib_get_long long (data, "editionNumber"))
print (grib_get_long long (data, "max"))
print (grib_get_double (data, "max"))
print (grib_get_string (data, "max"))
print (grib_get_string (data, "typeOfGrid"))
...
a = read('/x/y/z/data_in_gg.grb')
pl = grib_get_long_array (a, 'pl')
print (count(pl))
print (pl)
As of Metview 3.11, these functions should be used in preference to the getksec and getrsec functions.
fieldset grib_set_long ( fieldset, list )
fieldset grib_set_double ( fieldset, list )
fieldset grib_set_string ( fieldset, list )
...
data = grib_set_long (data,
["centre", 99,
"level", 200])
This function does not modify the input fieldset, but returns a new fieldset with the modifications applied.
Available keys can be inspected by Examining the GRIB file (right-click, Examine). Alternatively, use the GRIB API command grib_dump to see the available key names. See httphttps://wwwsoftware.ecmwf.int/publicationswiki/manualsdisplay/grib_api/keys.htmlGRIB/Grib+API+keys for more details on key names.
If applied to a mult-field fieldset, then all fields are modified.
As of Metview 3.11, these functions should be used in preference to the putksec and putrsec functions.
.
If applied to a multi-field fieldset, then all fields are modified.
vector or list values list gridvals ( fieldset )
This function returns the GRIB section 4 (i.e. the grid point values ) as a list of numbersvector. If the fieldset contains more than one field it returns a list of listsvectors. Each of these lists vectors contains as many elements as grid points in each field. Missing values are included in the results .
...
as vector_missing_value.
# x is a fieldset of n fields
xgrid = gridvalsvalues(x)
field1_values = xgrid[1]
gridpoint1 = field1_values[1]
# or equivalently
gridpoint1 = xgrid[1][1]
...
This function sets the number of GRIB packing bits to the value given (eg 8, 10, 16), and returns the previously used internal value. This function is particularly useful when dealing with 10-bit satellite images as these require GRIB packing to be set to 10 bits.
number or list integrate ( fieldset )
number or list integrate ( fieldset,list )
number or list integrate ( fieldset,fieldset )
...
Where ϕi is the latitude and xi is the grid point value. If the input fieldset contains only one field, a number is returned. If there is more than one field, a list of numbers is returned. Missing values in the input fieldset are bypassed in this calculation. For each field for which there are no valid values, the grib missing indicator nil is returned.
- If the fieldset is the only argument, the integration is done on all grid points.
- If a list is the second argument, it must contain four numbers which are respectively the north, west, south and east boundaries of an area. The integration is done on the grid points contained inside this area :
...
Interpolate a fieldset at a given point. If a list is given, it must contain two numbers - latitude and longitude. If two numbers are given, the first is the latitude, the second the longitude. The field must be a lat-long gridded field. If the fieldset has only one field, a number is returned; otherwise a list is returned. Where it is not possible to generate a sensible value due to lack of valid data in the fieldset, the grib missing indicator nil is returned.
geopoints interpolate ( fieldset,geopoints )
Generates a set of geopoints from a field. The first field of the input fieldset is used. The field is interpolated for each position of the geopoints given as a second parameter. The output geopoints take their date, time and level from the fieldset. Where it is not possible to generate a sensible value due to lack of valid data in the fieldset, the internal geopoints missing value is used (this value can be checked for with the built-in variable geo_missing_value or removed with the function remove_missing_values).
fieldset lookup ( fieldset,fieldset )
fieldset lookup ( fieldset,list )
...
Returns the maximum (minimum) value of all the values of all the fields of the fieldset. The versions that take a list as a second parameter require a geographical area (north, west, south, east); only points within this area will be included in the calculation. Only non-missing values are considered in the calculation. If there are no valid values, the function returns the grib missing value indicator nil.
matrix or list matrix ( fieldset )
...
Merge several fieldsets. The same as the operator &. The output is a fieldset with as many fields as the total number of fields in all merged fieldsets. Merging with the value nil does nothing, and is used to initialise when building a fieldset from nothing.
...
With n fields in the input fieldsets, if xik, yik are the ith value of the kth input fieldsets and zi is the ith value of the resulting field:
...
number or list nearest_gridpoint ( fieldset,list )
number or list nearest_gridpoint ( fieldset,number,number )vector or list nearest_gridpoint ( fieldset,vector,vector )
Returns the value of the nearest point to a given location (or locations) in each field of a fieldset. The field must be a gridded field. If a list is given, it must contain two numbers - latitude and longitude. If two numbers are given, the first is the latitude, the second the longitude.
...
For batch processing of multiple locations, two vectors can be given given, the first is a vector of latitudes, the second the longitudes; this can be much more efficient than multiple calls with a single location each. If the fieldset has only one field, a number (or vector) is returned; otherwise a list of numbers (or a list of vectors) is returned. Where it is not possible to generate a sensible value due to lack of valid data in the fieldset, the
...
a nil is returned in the case of a single coordinate, or vector_missing_value in the case of a vector.
geopoints nearest_gridpoint ( fieldset,geopoints )
Generates a set of geopoints from a field. The first field of the input fieldset is used. The result is a set of geopoints whose values are those of the nearest gridpoints in the field to the geopoints given as a second parameter. Where it is not possible to generate a sensible value due to lack of valid data in the fieldset, the internal geopoints missing value is used (this value can be checked for with the built-in variable geo_missing_value or removed with the function remove_missing_values).
list nearest_gridpoint_info ( fieldset,list )
list nearest_gridpoint_info ( fieldset,number,number )
Returns the value and location of the nearest point to a given location in each field of a fieldset. If a list is given, it must contain two numbers - latitude and longitude. If two numbers are given, the first is the latitude, the second the longitude. The field must be a lat-long field. The return value is a list of definitions, one for each field, and each containing the following members: value , latitude , longitude . Where it is not possible to generate a sensible value due to lack of valid data in the fieldset, the grib missing indicator nil is returned.
The following example illustrates how to use the function.
...
This function creates fields of pressure from the logarithm of the surface pressure (lnsp) and a list of model levels. Note that this function only works with lat/long grids gridded fields and assumes that the parameter for lnsp is 152. A newer, more flexible version of this function exists - see unipressure () .
- The first argument is always a fieldset containing an lnsp field. If no other parameter is given, the list of levels will range from 1 to (number of vertical coordinates/2)-1 as coded in the GRIB header of the lnsp parameter.
- The second argument specifies the levels at which the output fields must be generated. To generate a single level, pass a number. For more than one level, either pass a list of levels or a fieldset. If a fieldset is passed as the second parameter, the level information is extracted from each field of the fieldset.
...
Computes the root mean square of a fieldset. A missing value in any field will result in a missing value in the corresponding place in the output fieldset. With n fields in the input fieldset, if xik is the ith value of the kth input field and yi is the ith value of the resulting field, the formula can be written :
...
Note that the following lines are equivalent :
...
Computes the standard deviation of a fieldset. A missing value in any field will result in a missing value in the corresponding place in the output fieldset. With n fields in the input fieldset, if xik is the ith value of the kth input field and yi is the ith value of the resulting field, the formula can be written :
...
Note that the following lines are equivalent :
...
Universal vertical integration. This function is similar to vertint() , except that univertint() also works with sparse levels whereas vertint() is restricted to continuous levels.
...