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)

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.

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 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)

...

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.

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

...

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

...

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
  • φ 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.

...

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

...

This function accepts a fieldset as input and returns it sorted according to keys and rules specified in the other input arguments.

Specified with only the fieldset as its single argument, sort() sorts in ascending order the fieldset according to the following MARS keys: date, time, step, number (ensemle member), levelist and param (integer ID).

The second argument allows you to modify the precedence of the sorting keys - e.g. if the second argument is a string "param", then the sorting is done according to the param key. If the second argument is a list you specify a list of sorting keys - e.g. ["param", "date"] sorts on parameter and then date.

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.

...

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 :

Image Removed

Note that the following lines are equivalent :

y = stdev(x)
y = sqrt(mean(x*x)-mean(x)*mean(x))
y = sqrt(var(x))

...

Computes the standard deviation over a weighted area. The area, if specified, is a list of numbers representing North, West, South, East. If the area is not specified, the whole field will be used in the calculation. The result is a number for a single field, or a list for a multi-field fieldset.

...

Computes the sum of a fieldset. The result is a single-field 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 x_i ^k is the ith i^th value of the kth k^th input field and yi y_i is the ith 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))

Returns the indexes of the four gridpoints surrounding the given location, ordered by increasing distance from the target 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 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, nil is returned.

...

For each field in the input fieldset, this function creates a field where each grid point has the value of the tangent of its latitude. The resulting fields contain missing values on the poles.

...

This function creates fields of thickness from the logarithm of the surface pressure (lnsp ) and a list of model levels. Note that this function only works with lat/long grids and assumes that the parameter for lnsp is 152. A newer, more flexible version of this function exists - see unithickness () .

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

...

This function creates fields of pressure from the logarithm of the surface pressure (lnsp) and a list of model levels. Unlike pressure() , this function works with all grid types known to Metview (not just lat/long); it also allows the user to override the parameter number for lnsp (default 152).

• • The first argument is always a fieldset containing an lnsp field. If no other parameter is given, then pressure is computed for all model levels that are described in the GRIB header of fieldset .
  • If number is given (always the last parameter) it is the lnsp parameter code (default is 152).
  • list should contain model levels for which pressure is to be computed. Note that also for a single model level one has to use a list (this is a signature difference compared to the old function pressure() ).
  • If fieldset is given as the second parameter then pressure is computed for those model levels found in the second fieldset.

Missing values in the lnsp field are retained in the output fieldset.

...

This function creates fields of thickness from the logarithm of the surface pressure (lnsp) and a list of model levels. Unlike thickness() , this function works with all grid types known to Metview (not just lat/long); it also allows the user to override the parameter number for lnsp (default 152).

• • The first argument is always a fieldset containing an lnsp field. If no other parameter is given, then thickness is computed for all model levels that are described in the GRIB header of fieldset .
  • If number is given (always the last parameter) it is the lnsp parameter code (default is 152).
  • list should contain model levels for which thickness is to be computed. Note that also for a single model level one has to use a list (this is a signature difference compared to the old function thickness() ).
  • If fieldset is given as the second parameter then thickness is computed for those model levels found in the second fieldset.

Missing values in the lnsp field are retained in the output fieldset.

...

Universal vertical integration. This function is similar to vertint() , except that univertint() also works with sparse levels whereas vertint() is restricted to continuous levels.

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:

\int_{bottom}^{top} f \frac{dp}{g}

where

• • f is the fieldset
  • p is the pressure
  • g is the acceleration of gravity (9.81 m/s²).

...

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

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.

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

This function accepts a fieldset as input and returns it sorted according to keys and rules specified in the other input arguments.

Specified with only the fieldset as its single argument, sort() sorts in ascending order the fieldset according to the following MARS keys: date, time, step, number (ensemble member), levelist and param (integer ID).

The second argument allows you to modify the precedence of the sorting keys - e.g. if the second argument is a string "param", then the sorting is done according to the param key. If the second argument is a list you specify a list of sorting keys - e.g. ["param", "date"] sorts on parameter and then date.

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.

Computes the standard deviation

...

Returns the valid dates (including the time components) of the given fields. If the fieldset has only one field, a date is returned; otherwise a list of dates is returned.

...

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.

...

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 :Image Removed

Image Added

Note that the following lines are equivalent :

y = varstdev(x)
y = sqrt(mean(x*x)-mean(x)*mean(x))
y = sqrt(var(x))

Computes the variance standard deviation over a weighted area. The area, if specified, is a list of numbers representing North, West, South, East. If the area is not specified, the whole field will be used in the calculation. The result is a number for a single field, or a list for a multi-field fieldset.

...

stretch_deformation(fx: fieldset, fy: fieldset)

...

This function performs a vertical integration of the input fieldset, which must contain a range of model levels for the same parameter. A missing value in any field will result in a missing value in the corresponding place in the output fieldset. If the function is called with the fieldset as its single argument, it must also contain the logarithm of the surface pressure (lnsp ). If the function is called with two parameters, the first one is a fieldset containing an lnsp field, the second one is the multi-level fieldset.

The function computes :

\int_{bottom}^{top} f \frac{dp}{g}

where

• • f is the fieldset
  • p is the pressure
  • g is the acceleration of gravity (9.81 m/s²).

The following example computes the total amount of liquid water in the atmosphere by integrating the cloud liquid water content (clwc ) over all levels of the model

...

New in Metview version 5.13.0.

Computes the stretch 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_x}{\partial \lambda} - \frac{1}{R}\frac{\partial f_y}{\partial \phi} - \frac{f_y}{R}tan\phi

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.

Computes the sum of a fieldset. The result is a single-field 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 :

Image Added

Returns the indexes of the four gridpoints surrounding the given location, ordered by increasing distance from the target 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 gridded field. If the fieldset has only one field, a single vector of indexes is returned; otherwise a list of vectors is returned. In the case where the field is a reduced Gaussian grid and the input location is at the North or South pole, beyond the most extreme row of points, there will be a 'circle' of surrounding points, and all of these indexes are returned.

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 single vector is returned; otherwise a list of vectors is returned.

By default, if any of the surrounding points are missing, the function will return nil. To prevent this, and to return all the points regardless, add the option 'all' as the last parameter of the function call.

For each field in the input fieldset, this function creates a field where each grid point has the value of the tangent of its latitude. The resulting fields contain missing values on the poles.

This function creates fields of thickness from the logarithm of the surface pressure (lnsp ) and a list of model levels. Note that this function only works with lat/long grids and assumes that the parameter for lnsp is 152. A newer, more flexible version of this function exists - see unithickness () .

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

This function creates fields of pressure from the logarithm of the surface pressure (lnsp) and a list of model levels. Unlike pressure() , this function works with all grid types known to Metview (not just lat/long); it also allows the user to override the parameter number for lnsp (default 152).

• • The first argument is always a fieldset containing an lnsp field. If no other parameter is given, then pressure is computed for all model levels that are described in the GRIB header of fieldset .
  • If number is given (always the last parameter) it is the lnsp parameter code (default is 152).
  • list should contain model levels for which pressure is to be computed. Note that also for a single model level one has to use a list (this is a signature difference compared to the old function pressure() ).
  • If fieldset is given as the second parameter then pressure is computed for those model levels found in the second fieldset.

Missing values in the lnsp field are retained in the output fieldset.

This function creates fields of thickness from the logarithm of the surface pressure (lnsp) and a list of model levels. Unlike thickness() , this function works with all grid types known to Metview (not just lat/long); it also allows the user to override the parameter number for lnsp (default 152).

• • The first argument is always a fieldset containing an lnsp field. If no other parameter is given, then thickness is computed for all model levels that are described in the GRIB header of fieldset .
  • If number is given (always the last parameter) it is the lnsp parameter code (default is 152).
  • list should contain model levels for which thickness is to be computed. Note that also for a single model level one has to use a list (this is a signature difference compared to the old function thickness() ).
  • If fieldset is given as the second parameter then thickness is computed for those model levels found in the second fieldset.

Missing values in the lnsp field are retained in the output fieldset.

This function performs a vertical integration for data on pressure levels or ECMWF (hybrid) model levels. This function is similar to vertint() , except that univertint() also works with sparse levels whereas vertint() is restricted to continuous levels.

• Pressure levels: the function has to be called with one argument only (the input fieldset).
• Model levels: 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:

\int_{p_{top}}^{p_{bottom}} f \frac{dp}{g}

where

• • f is the fieldset
  • p is the pressure
  • g is the acceleration of gravity (9.80665 m/s²).

Returns the valid dates (including the time components) of the given fields. If the fieldset has only one field, a date is returned; otherwise a list of dates is returned.

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]

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 :
Image Added
Note that the following lines are equivalent :

y = var(x)
y = mean(x*x)-mean(x)*mean(x)

Computes the variance over a weighted area. The area, if specified, is a list of numbers representing North, West, South, East. If the area is not specified, the whole field will be used in the calculation. The result is a number for a single field, or a list for a multi-field fieldset.

fieldset vertint ( fieldset,fieldset )

This function performs a vertical integration of the input fieldset, which must contain a range of model levels for the same parameter. A missing value in any field will result in a missing value in the corresponding place in the output fieldset. If the function is called with the fieldset as its single argument, it must also contain the logarithm of the surface pressure (lnsp ). If the function is called with two parameters, the first one is a fieldset containing an lnsp field, the second one is the multi-level fieldset.

The function computes:

\int_{p_{top}}^{p_{bottom}} f \frac{dp}{g}

where

• • f is the fieldset
  • p is the pressure
  • g is the acceleration of gravity (9.80665 m/s²).

The following example computes the total amount of liquid water in the atmosphere by integrating the cloud liquid water content (clwc ) over all levels of the model

# 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)

Computes the vertical component of the curl differential operator for 2-dimensional vector fields. For wind fields (i.e. when the input fieldsets are u and v wind components) this computes the relative vorticity (ζ). The computations for a vector field f=(f_x ,f_y ) are based on the following formula :

 \zeta =\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

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. If the input fields are horizontal wind components the GRIB paramId of the resulting field is set to 138 (relative vorticity). Please note that this function is only implemented for regular latitude-longitude grids.

number w_from_omega(omega: number,  t: number,  p: number)

vector w_from_omega(omega: vector,  t: vector,  p: vector)

fieldset w_from_omega(omega: fieldset, t: fieldset)

fieldset w_from_omega(omega: fieldset,  t: fieldset,  p: fieldset)

Computes the hydrostatic vertical velocity from  pressure velocity (omega) for a given temperature and pressure, where

• • omega: pressure velocity (Pa/s)
  • t: temperature (K)
  • p: pressure (Pa)

The result is the vertical velocity in m/s units. On error  nil is returned. The following rules are applied when omega is a fieldset:

• • if omega is a pressure level fieldset no pressure argument is needed
  • if omega is defined on ECMWF model levels (hybrid/eta) p is either a single LNSP (logarithm of surface pressure, identified by paramId=152) field or a fieldset defining the pressure on the levels of omega
  • for other level types p is a fieldset defining the pressure on the levels of omega

The computation is based on the following hydrostatic formula:

w = - \frac{\omega T R_{d}}{p g}

where

• Rd is the specific gas constant for dry air (287.058 J/(kg K)).
• g is the gravitational acceleration (9.81 m/s²)

This functions was introduced in version 5.10.0.

list of numbers xy_from_polar(magnitude: number,  dir: number)

list of vectors xy_from_polar(magnitude: vector,  dir: vector)

fieldset xy_from_polar(magnitue: fieldset, dir: fieldset)

Converts vector data from meteorological polar representation to xy representation. In polar representation the data is specified by two components:

• magnitude: represents the speed/magnitude
• dir: represents the direction of the vector in degrees. Angles measured from South in clockwise direction.

In the target xy representation the x axis points East while the y axis points North.

The type of the result depends on the type of the input data

• if the input is number the result is a list of two numbers
• if the input is vector the result is a list of two vectors, the first vector contains the x components while the second vector the y components
• if the input is fieldset the result is a fieldset where an x component field is immediately followed by the corresponding y component field.

This function was introduced in version 5.10.0

...

...

Computes the vertical component of the curl differential operator for 2-dimensional vector fields. For wind fields (i.e. when the input fieldsets are u and v wind components) this computes the relative vorticity (ζ). The computations for a vector field f=(f_x ,f_y ) are based on the following formula :

 \zeta =\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

where

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

...

.