Page History

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:

Image Added

Computes geopotential on model levels.

All fields must be gridpoint data - no spherical harmonics, and they must all be on the same grid, with the same number of points. mvl_geopotential_on_ml() assumes that there are no other dimensions contained in the data, e.g. all fields should have the same date and time.

The return value is a fieldset of geopotential defined on the model levels present in the input data sorted by ascending numeric level order.

The required levels and their ordering in t and q depend on the Metview version used:

• • from Metview version 5.14.0: t and q must contain the same levels in the same order but there is no restriction on the actual level ordering. The model level range must be contiguous and must include the bottom-most level. E.g. if the current vertical coordinate system has 137 model levels using only a subset of levels between e.g. 137-96 is allowed.
  • in previous Metview versions: t and q must contain the full model level range in ascending numeric order. E.g. if the current vertical coordinate system has 137 model levels t and q must contain all the levels ordered as 1,..., 137.

The code below illustrates how to use this function:

# retrieves analysis data on model levels

r = (date: -1, time: 12, levtype: "ml", grid: [1.5,1.5]

...

)

...


t    = retrieve(r,levelist: [1,"to",137],param: "t")
q    = retrieve(r,levelist: [1,"to",137],param: "q")
zs   = retrieve(r,levelist: 1,param: "z")
lnsp = retrieve(r,levelist: 1,param: "lnsp")


# computes the geopotential


z_ml = mvl_geopotential_on_ml(t,

...

q,

...

lnsp,

...

zs)

...

...

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:

Image Removed

...

fieldset mvl_ml2hPa(lnsp: fieldset, mfld: fieldset, plist: list)

Interpolates a fieldset currently on model levels onto pressure levels (in hPa). Locations where interpolation is not possible are returned as missing.

Parameter lnsp is a field of logarithm of surface pressure; mfld is the fieldset to be interpolated and should be on model levels; plist is a list of pressure levels in hPa - the result will be the mfld fieldset interpolated onto these levels. Neither mfld nor plist need to be sorted.

The following code shows a simple example:

# retrieve the data in model levels

common_retrieve_params = ( type : "fc", levtype : "ml", step : 12, grid : [1.5,1.5] )

tmod = retrieve param : "t", levelist : [1, 'to', 91], common_retrieve_params)

lnsp = retrieve( param : "lnsp", levelist : 1, common_retrieve_params)

# interpolate onto a list of pressure levels

plevels = [1000, 900, 850, 500, 300, 100, 10, 1, 0.1]

tpres = mvl_ml2hPa (lnsp, tmod, plevels)

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, 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.

By default, when the nearest gridpoint value is a missing value or the location is out of the grid area, nil is returned in the case of a single coordinate, or vector_missing_value in the case of a vector. If an extra parameter 'valid' is added to the function call, then of the surrounding points, the nearest valid one is returned; nil will still be returned if all the surrounding points are missing.

Note that a similar function, interpolate(), also exists.

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). Note that a similar function, interpolate() , also exists.

...

fieldset mvl_geopotential_on_ml(t:fieldset, q:fieldset, lnsp:fieldset, zs:fieldset)

Computes geopotential on model levels.

Parameter t should be a fieldset of temperature on model levels in ascending numeric order (e.g. 1-137), q a fieldset of specific humidity on model levels in ascending numeric order, lnsp a field of log of surface pressure on model level 1, zs a field of geopotential on model level 1 (available from MARS). All fields must be GRIDDED data - no spherical harmonics, and they must all be on the same grid, with the same number of points. The function assumes that there are no other dimensions contained in the data, e.g. all fields should have the same date and time. The return value is a fieldset of geopotential on model levels.

The code below illustrates how to use this function:

# retrieves analysis data on model levels

r = (date: -1, time: 12, levtype: "ml", grid: [1.5,1.5])
t    = retrieve(r,levelist: [1,"to",137],param: "t")
q    = retrieve(r,levelist: [1,"to",137],param: "q")
zs   = retrieve(r,levelist: 1,param: "z")
lnsp = retrieve(r,levelist: 1,param: "lnsp")


# computes the geopotential


z_ml = mvl_geopotential_on_ml(t, q, lnsp, zs)

...

fieldset mvl_ml2hPa(lnsp: fieldset, mfld: fieldset, plist: list)

Interpolates a fieldset currently on model levels onto pressure levels (in hPa). Locations where interpolation is not possible are returned as missing.

Parameter lnsp is a field of logarithm of surface pressure; mfld is the fieldset to be interpolated and should be on model levels; plist is a list of pressure levels in hPa - the result will be the mfld fieldset interpolated onto these levels. Neither mfld nor plist need to be sorted.

The following code shows a simple example:

# retrieve the data in model levels

common_retrieve_params = ( type : "fc", levtype : "ml", step : 12, grid : [1.5,1.5] )

tmod = retrieve param : "t", levelist : [1, 'to', 91], common_retrieve_params)

lnsp = retrieve( param : "lnsp", levelist : 1, common_retrieve_params)

# interpolate onto a list of pressure levels

plevels = [1000, 900, 850, 500, 300, 100, 10, 1, 0.1]

tpres = mvl_ml2hPa (lnsp, tmod, plevels)

Anchornearest_gridpointnearest_gridpointnumber or list nearest_gridpoint ( fieldset,list[,string] )
number or list nearest_gridpoint_info ( fieldset,number,number[,string] ) vector or list nearest_gridpoint ( fieldset,vector,vector[,string] )

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. If an extra parameter 'valid' is added to the function call, then of the surrounding points, the nearest valid one is returned; nil will still be

...

Note that a similar function, interpolate(), also exists.

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). Note that a similar function, interpolate() , also exists.

...

returned if all the surrounding points are missing.

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

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 percentile(...)

Computes the specified percentiles for a given fieldset. This is a Metview icon function, for detailed documentation please see Percentile.

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.

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".

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 x_i ^k is the i^th value of the k^th input field and y_i is the i^th value of the resulting field, the formula can be written :

Image Added

Note that the following lines are equivalent :

y = rms(x)
y = sqrt(mean(x*x))

Computes the second zonal (from West to East) partial derivative of each field in the fieldset. The computations for a field f are based on the following formula:

\frac {\partial^2 f}{\partial x^2} = \frac{1}{R^2 \ cos^2\phi}\frac{\partial^2 f}{\partial \lambda^2} 

where

• • R is the radius of the Earth
  • φ is the latitude
  • λ is the longitude.

The derivatives are computed with a second order finite-difference approximation. The resulting fields contain missing values on the poles. Please note that this function is only implemented for regular latitude-longitude grids.

Computes the second meridional (from South to North) partial derivative of each field in the fieldset. The computations for a field f are based on the following formula:

\frac {\partial^2 f}{\partial y^2} = \frac{1}{R^2}\frac{\partial^2 f}{\partial \phi^2} 

where

• • R is the radius of the Earth
  • φ is the latitude.

The derivatives are computed with a second order finite-difference approximation. The resulting fields contain missing values on the poles. Please note that this function is only implemented for regular latitude-longitude grids.

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.

New in Metview version 5.13.0.

Computes the shear deformation of 2-dimensional vector fields. The computations for a vector field f=(fx,fy) are based on the following formula:

d(f) = \frac{1}{R \ cos\phi}\frac{\partial f_y}{\partial \lambda} + \frac{1}{R}\frac{\partial f_x}{\partial \phi} + \frac{f_x}{R}tan\phi

...

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. If an extra parameter 'valid' is added to the function call, then of the surrounding points, the nearest valid one is returned; nil will still be returned if all the surrounding points are missing.

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

...

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 percentile(...)

Computes the specified percentiles for a given fieldset. This is a Metview icon function, for detailed documentation please see Percentile.

...

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.

...

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".

...

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 x_i ^k is the i^th value of the k^th input field and y_i is the i^th value of the resulting field, the formula can be written :

Image Removed

Note that the following lines are equivalent :

y = rms(x)
y = sqrt(mean(x*x))

...

Computes the second zonal (from West to East) partial derivative of each field in the fieldset. The computations for a field f are based on the following formula:

\frac {\partial^2 f}{\partial x^2} = \frac{1}{R^2 \ cos^2\phi}\frac{\partial^2 f}{\partial \lambda^2} 

where

• • R is the radius of the Earth
  • φ is the latitude
  • λ is the longitude.

The derivatives are computed with a second order finite-difference approximation. The resulting fields contain missing values on the poles. Please note that this function is only implemented for regular latitude-longitude grids.

...

Computes the second meridional (from South to North) partial derivative of each field in the fieldset. The computations for a field f are based on the following formula:

\frac {\partial^2 f}{\partial y^2} = \frac{1}{R^2}\frac{\partial^2 f}{\partial \phi^2} 

where

• • R is the radius of the Earth (m)
  • φ is the latitude
  • λ is the longitude.

The derivatives are computed with a second order finite-difference approximation. The resulting fields contain missing values on the poles. Please note that this function is only implemented for regular latitude-longitude grids.

...

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.

...

.  Please note that this function is only implemented for regular latitude-longitude grids.

For each field in the input fieldset, this function creates a field where each grid point has the value of the sine of its latitude. For example, the following macro adds the coriolis parameter to each grid point of a field :

# Computes absolute vorticity from vorticity
omega = 2 * pi / 86400
coriolis = 2 * omega * sinlat(vort)
absvort = vort + coriolis

New in Metview version 5.14.0.

Computes the solar zenith angle for each gridpoint by using the following positional arguments:

• • fs: input fieldset
  • to_cosine: (optional) when this argument is specified as set to "to_cosine" the cosine of the solar zenith angle is returned

The result is the solar zenith angle in degrees (unless "to_cosine" is specified when the cosine of the solar zenith angle is returned). The computations are based on the following formula:

cos\theta_{s} = sin\phi\, sin\delta + cos\phi\, cos\delta\, cosh 

where

• • θ is the solar zenith angle
  • φ is the latitude
  • δ is the declination of the Sunδ
  • h is the hour angle in local solar time

The declination of the Sun is computed as:

\delta = - arcsin\left(0.39779 cos(0.98565\unicode{xB0} (N+10) + 1.914\unicode{xB0} sin(0.98565\unicode{xB0} (N-2))\right) 

where:

• • N is the day of the year beginning with N=0 at midnight Universal Time (UT) as January 1. It is a floating point number allowing for fractional days.

A missing value in any field in fs will result in a missing value in the corresponding grid point in the output fieldset.

The dates and times used in the computations are based on the "validityDate" and "validityTime" ecCodes keys. If these are not available for a given field the result will contain missing values for all the gridpoints for that field.

When "to_cosine" is not specified and the GRIB edition of the input field is 2 the ecCodes paramId in the output field is set to 260225 (shortName="solza"). For GRIB edition 1 this parameter is not defined.

When "to_cosine" is specified the ecCodes paramId in the output is set to 214001 (shortName="uvcossza").

d(f) = \frac{1}{R \ cos\phi}\frac{\partial f_y}{\partial \lambda} + \frac{1}{R}\frac{\partial f_x}{\partial \phi} + \frac{f_x}{R}tan\phi

...

• • R is the radius of the Earth (m)
  • φ is the latitude
  • λ is the longitude.

The derivatives are computed with a second order finite-difference approximation. The resulting fields contain missing values on the poles.  Please note that this function is only implemented for regular latitude-longitude grids.

...

For each field in the input fieldset, this function creates a field where each grid point has the value of the sine of its latitude. For example, the following macro adds the coriolis parameter to each grid point of a field :

...

...

The third argument specifies a sorting direction. This can be a string (">" or "<") or a list ([">", "<", ">",...]). If it is a string, the sorting direction it specifies applies to all sorting keys specified in the second argument. If it is a list, then the second argument must also be a list with the same number of elements - the sorting directions apply to each sorting key specified.

New in Metview version 5.14.0.

Computes the wind speed from the u and v wind components.

The resulting values are speed values in the same units as the input fields. A missing value in either u or v will result in a missing value in the corresponding place in the output fieldset. The ecCodes paramId in the output is set as follows:

• • 10 (atmospheric wind speed)
  • 207 (10m wind speed)
  • 228249 (100m wind speed)
  • 228241 (200m wind speed)

In any other cases the ecCodes paramId is set to 10.

...