...
If applied to a multi-field fieldset, then all fields are modified.
vector or list values ( fieldset number gribsetbits ( number )
This function returns the grid point values as a vector. If the fieldset contains more than one field it returns a list of vectors. Each of these vectors contains as many elements as grid points in each field. Missing values are included in the results as vector_missing_value.
...
number gribsetbits ( number )
...
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.
fieldset indexes ( fieldset, vector )
Given a fieldset and a vector of target values, this function finds for each gridpoint the indexes of the nearest values in the target. Indexes are zero-based and will always have a minimum value of zero and a maximum value equal to the index of the last element of the target vector. A value lying between two values in the vector will use the index of the nearest value; if equidistant, then the higher value is used. The input vector MUST be sorted in ascending order. Example: if these are our inputs:
GRIB: 10,20,30,40 15,25,35,45 8, 4,20,11
VECTOR: | 5,10,15,20,25,30 |
then our output would be a new GRIB, with values equal to the input values' positions in the input vector:
GRIB: 1,3,5,5
2,4,5,5
1,0,3,1
number or list integrate ( fieldset )
number or list integrate ( fieldset,list )
number or list integrate ( fieldset,fieldset )
...
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 )
These two functions build an output fieldset using the values in the first input fieldset as indices in a look-up action on a second input fieldset or input list :
- Takes the grid values in the first fieldset and uses them as index in the second fieldset. E.g. a grid value of n in the first fieldset, retrieves the corresponding grid point value of the (n-1)th field of the second fieldset (indexing is 0 based). The output fieldset is built from these values and has as many fields as the second fieldset.
- Takes the grid values in the first fieldset and uses them as index in the list - real numbers are truncated, not rounded. E.g. a grid value of n in the first fieldset, retrieves the (n-1)th list element (indexing is 0 based). The output fieldset is built from these values and has as many fields as the first fieldset.
Any missing values in the first fieldset will cause the function to fail with a `value out of range' error message.
fieldset mask ( fieldset,list )
For each field of the input fieldset, this function creates a field containing grid point values of 0 or 1 according to whether they are outside or inside a defined geographical area.
The list parameter must contain exactly four numbers representing a geographical area. These numbers should be in the order north, west, south and east (negative values for western and southern coordinates). Non-rectangular masks, and even convex masks can be created by using the operators and , or and not . To create the following mask :
First decompose into basic rectangles :
Then create a mask for each of them and use and and or to compose the desired mask. This is the corresponding macro :
...
The resulting mask field can be used in the integrate() function.
fieldset max ( fieldset )
fieldset min ( fieldset )
Returns the fieldset of maximum (minimum) value of the input fieldset at each grid point or spectral coefficient. A missing value in either input fieldset will result in a missing value in the corresponding place in the output fieldset.
fieldset max ( fieldset,fieldset )
fieldset min ( fieldset,fieldset )
Returns the fieldset of maximum (minimum) value of the two input fieldsets at each grid point or spectral coefficient. A missing value in either input fieldset will result in a missing value in the corresponding place in the output fieldset.
fieldset max ( fieldset,number )
fieldset min ( fieldset,number )
Returns the fieldset of the maximum (minimum) of the number and the fieldset value at each grid point or spectral coefficient. Missing values in the input fieldset are transferred to the output fieldset.
geopoints max ( fieldset,geopoints )
geopoints min ( fieldset,geopoints )
Returns geopoints of maximum (minimum) of the fieldset value and the geopoint value at each grid point or spectral coefficient. Missing values, either in the fieldset or in the original geopoints variable, result in a value of geo_missing_value .
number maxvalue ( fieldset )
number maxvalue ( fieldset,list )
number minvalue ( fieldset )
number minvalue ( 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 nil.
matrix or list matrix ( fieldset )
Generates a matrix containing the values of the input field, or a list of matrices if there are more than one field in the fieldset. Only works with regular lat/long grids.
fieldset mean ( fieldset )
Computes the mean field 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 :
fieldset mean_ew ( fieldset )
Takes a fieldset as its parameter and computes the mean for each line of constant latitude. The result is a fieldset where the value at each point is the mean of all the points at that latitude. Missing values are excluded; if there are no valid values, then the grib missing value indicator will be returned for those points.
fieldset merge ( fieldset,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.
fieldset mod ( fieldset,fieldset )
Returns a fieldset with as many fields as the input fieldsets; the grid point values of the output fieldset are the remainder of the division of the first fieldset by the second fieldset (the function operating field by field). Where the gridpoint values of the second fieldset are larger than those of the first, the output gridpoint value is set to the integer part of the first input gridpoint value. A missing value in either input fieldset will result in a missing value in the corresponding place in the output fieldset. Note that only the integer parts of the inputs are considered in the calculation, meaning that a second parameter of 0.5 would cause a division by zero.
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 )
...
value or removed with the function remove_missing_values).
vector or list latitudes ( fieldset )
This function returns the grid point latitudes as a vector. If the fieldset contains more than one field it returns a list of vectors. Each of these vectors contains as many elements as grid points in each field.
vector or list longitudes ( fieldset )
This function returns the grid point longitudes as a vector. If the fieldset contains more than one field it returns a list of vectors. Each of these vectors contains as many elements as grid points in each field.
fieldset lookup ( fieldset,fieldset )
fieldset lookup ( fieldset,list )
These two functions build an output fieldset using the values in the first input fieldset as indices in a look-up action on a second input fieldset or input list :
- Takes the grid values in the first fieldset and uses them as index in the second fieldset. E.g. a grid value of n in the first fieldset, retrieves the corresponding grid point value of the (n-1)th field of the second fieldset (indexing is 0 based). The output fieldset is built from these values and has as many fields as the second fieldset.
- Takes the grid values in the first fieldset and uses them as index in the list - real numbers are truncated, not rounded. E.g. a grid value of n in the first fieldset, retrieves the (n-1)th list element (indexing is 0 based). The output fieldset is built from these values and has as many fields as the first fieldset.
Any missing values in the first fieldset will cause the function to fail with a `value out of range' error message.
fieldset mask ( fieldset,list )
For each field of the input fieldset, this function creates a field containing grid point values of 0 or 1 according to whether they are outside or inside a defined geographical area.
The list parameter must contain exactly four numbers representing a geographical area. These numbers should be in the order north, west, south and east (negative values for western and southern coordinates). Non-rectangular masks, and even convex masks can be created by using the operators and , or and not . To create the following mask :
First decompose into basic rectangles :
Then create a mask for each of them and use and and or to compose the desired mask. This is the corresponding macro :
# Define basic rectangles
a = [50,-120,10,-30]
b = [20,20,50,10]
c = [50,50,40,100]
d = [35,-60,-40,100]
# The field is used to get the grid information
f = retrieve(...)
# First compute the union of a,c and d
m = mask(f,a) or mask(f,d) or mask(f,c)
# Then remove b
m = m and not mask(f,b)
The resulting mask field can be used in the integrate() function.
fieldset max ( fieldset )
fieldset min ( fieldset )
Returns the fieldset of maximum (minimum) value of the input fieldset at each grid point or spectral coefficient. A missing value in either input fieldset will result in a missing value in the corresponding place in the output fieldset.
fieldset max ( fieldset,fieldset )
fieldset min ( fieldset,fieldset )
Returns the fieldset of maximum (minimum) value of the two input fieldsets at each grid point or spectral coefficient. A missing value in either input fieldset will result in a missing value in the corresponding place in the output fieldset.
fieldset max ( fieldset,number )
fieldset min ( fieldset,number )
Returns the fieldset of the maximum (minimum) of the number and the fieldset value at each grid point or spectral coefficient. Missing values in the input fieldset are transferred to the output fieldset.
geopoints max ( fieldset,geopoints )
geopoints min ( fieldset,geopoints )
Returns geopoints of maximum (minimum) of the fieldset value and the geopoint value at each grid point or spectral coefficient. Missing values, either in the fieldset or in the original geopoints variable, result in a value of geo_missing_value .
number maxvalue ( fieldset )
number maxvalue ( fieldset,list )
number minvalue ( fieldset )
number minvalue ( 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 nil.
matrix or list matrix ( fieldset )
Generates a matrix containing the values of the input field, or a list of matrices if there are more than one field in the fieldset. Only works with regular lat/long grids.
fieldset mean ( fieldset )
Computes the mean field 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 :
fieldset mean_ew ( fieldset )
Takes a fieldset as its parameter and computes the mean for each line of constant latitude. The result is a fieldset where the value at each point is the mean of all the points at that latitude. Missing values are excluded; if there are no valid values, then the grib missing value indicator will be returned for those points.
fieldset merge ( fieldset,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.
fieldset mod ( fieldset,fieldset )
Returns a fieldset with as many fields as the input fieldsets; the grid point values of the output fieldset are the remainder of the division of the first fieldset by the second fieldset (the function operating field by field). Where the gridpoint values of the second fieldset are larger than those of the first, the output gridpoint value is set to the integer part of the first input gridpoint value. A missing value in either input fieldset will result in a missing value in the corresponding place in the output fieldset. Note that only the integer parts of the inputs are considered in the calculation, meaning that a second parameter of 0.5 would cause a division by zero.
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, nil is returned.
The following example illustrates how to use the function.
fs = read (strGribFile)
listdef = nearest_gridpoint_info(fs, 51.46, -1.33)
loop ngp in listdef
print ("Value : ", ngp.value)
print ("Latitude : ", ngp.latitude)
print ("Longitude : ", ngp.longitude)
end loop
fieldset nobitmap ( fieldset,number )
Returns a copy of the input fieldset (first argument) with all of its missing values replaced with the number specified by the second argument. See also bitmap .
fieldset pressure ( fieldset )
fieldset pressure ( fieldset,number )
fieldset pressure ( fieldset,list )
fieldset pressure ( fieldset,fieldset )
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 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.
Missing values in the lnsp field are retained in the output fieldset.
fieldset rmask ( fieldset,number,number,number )
fieldset rmask ( fieldset,list )
Similar to mask , except that a round mask is computed with a given radius around a geographical centre point. These can be given by either:
- three numbers : latitude, longitude (in degrees), radius (in meters)
- a list containing the above three numbers
The name of this function is derived from the fact that it creates a "round mask" or a "radius mask".
fieldset rms ( 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 :
y = rms(x)
y = sqrt(mean(x*x))
fieldset set_values ( fieldset,vector )fieldset set_values ( fieldset,list )fieldset set_values ( fieldset,vector,string )
fieldset set_values ( fieldset,list,string )
Creates a new fieldset with all the fields' values replaced by those supplied. If supplied as a single vector, the values are set in all fields; if a list of vectors is supplied then there must be the same number of vectors as there are fields in the fieldset. The default behaviour is to produce an error if the input fieldset and vector have different numbers of values. If, however, a third parameter (set to the string 'resize') is passed to the function, the resulting fieldset will instead be resized to have the same number of values as the input vector - this can be useful when creating a new fieldset from a template. Missing values in the vector(s) are retained as missing values in the fieldset.
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, nil is returned.
The following example illustrates how to use the function.
fs = read (strGribFile)
listdef = nearest_gridpoint_info(fs, 51.46, -1.33)
loop ngp in listdef
print ("Value : ", ngp.value)
print ("Latitude : ", ngp.latitude)
print ("Longitude : ", ngp.longitude)
end loop
fieldset nobitmap ( fieldset,number )
Returns a copy of the input fieldset (first argument) with all of its missing values replaced with the number specified by the second argument. See also bitmap .
fieldset pressure ( fieldset )
fieldset pressure ( fieldset,number )
fieldset pressure ( fieldset,list )
fieldset pressure ( fieldset,fieldset )
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 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.
Missing values in the lnsp field are retained in the output fieldset.
fieldset rmask ( fieldset,number,number,number )
fieldset rmask ( fieldset,list )
Similar to mask , except that a round mask is computed with a given radius around a geographical centre point. These can be given by either:
- three numbers : latitude, longitude (in degrees), radius (in meters)
- a list containing the above three numbers
The name of this function is derived from the fact that it creates a "round mask" or a "radius mask".
fieldset rms ( 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 :
...
fieldset sinlat ( fieldset )
...
This function performs a vertical integration of the input fieldset. If just one fieldset is given, it must also contain the logarithm of the surface pressure (lnsp). If the function is called with two fieldsets, the first one is a fieldset containing an lnsp field, the second one is the multi-level fieldset. A number may optionally be given as the last parameter in order to specify the lnsp code used in the fieldset that contains the lnsp data; its default value is 152. If a list with two elements [top, bottom] is given as the third parameter, then the integration is performed between (and including) these layers.
A missing value in any field will result in a missing value in the corresponding place in the output fieldset.
The function computes :
Where f is the fieldset, p is the pressure and g the acceleration of gravity.
...
these layers.
A missing value in any field will result in a missing value in the corresponding place in the output fieldset.
The function computes :
Where f is the fieldset, p is the pressure and g the acceleration of gravity.
vector or list values ( fieldset )
This function returns the grid point values as a vector. If the fieldset contains more than one field it returns a list of vectors. Each of these 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 = values(x)
field1_values = xgrid[1]
gridpoint1 = field1_values[1]
# or equivalently
gridpoint1 = xgrid[1][1]
fieldset var ( fieldset )
Computes the variance 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 :
...
# Retrieve clwc
clwc = retrieve(
levtype : "ml",
levelist : [1,"to",31],
param : "clwc",
date : -1,
grid : [2.5,2.5]
)
# Retrieve lnsp
lnsp = retrieve(
levtype : "ml",
levelist : 1,
param : "lnsp",
date : -1,
grid : [2.5,2.5]
)
# Integrate the field
x = vertint(lnsp,clwc)
plot(x)