integrate

integrate(fs[, area_or_mask])

Computes the average of each field in fs over an area.

Parameters

  • fs (Fieldset) – input fieldset

  • area_or_mask (list or Fieldset) – list defining an area as [North, West, South, East] or fieldset defining a mask

Return type

number or ndarray or None

If fs contains only one field a number is returned. If there is more than one field a numpy array is returned. Missing values in the input fieldset are bypassed in this calculation. For each field for which there are no valid values None is returned.

  • If fs is the only argument the integration is done on all grid points.

  • If area_or_mask is a list it defines an area as [North, West, South, East] for the integration:

    import metview as mv
europe = [75,-12.5,35,42.5]
x = mv.integrate(field, europe)

  • If area_or_mask is a fieldset it is used as a mask and the integration is performed only on the grid points where the mask values are non zero. area_or_mask should contain either one or as many fields as there are in fs. If it has a single field then the mask is applied to all fields in fs. If it has the same number of fields as fs, then a different mask is applied to each input field. The example below shows how to use integrate() with a land-sea mask retrieved from MARS:

    import metview as mv

# read grib data on a 1 degree by 1 degree grid
f = mv.read("my_fs.grib")

# retrieve land-sea mask from MARS on the same grid
lsm = mv.retrieve(
   type="an",
   date=-1,
   param="lsm",
   grid=[1,1],
   levtype="sfc"
)

# make sure values are either 0 or 1
lsm = lsm > 0.5

# compute the average value on land and on sea
land = mv.integrate(f, lsm)
sea = mv.integrate(f, not lsm)

Note

The computations are based on the following approximation of the grid cell areas:

\[A_{i} = 2 R^{2} cos\phi_{i} sin(\frac{\Delta\phi_{i}}{2}) \Delta\lambda_{i}\]

where:

  • R is the radius of the Earth

  • \(\phi_{i}\) is the latitude of the i-th grid cell

  • \(\Delta\phi_{i}\) is the size of the grid cells in latitude

  • \(\Delta\lambda_{i}\) is the size of the i-th grid cell in longitude.

Assuming that \(\Delta\phi_{i}\) is small enough using \(sin(x) \approx x\) we can rewrite the formula as:

\[A_{i} = R^{2} cos\phi_{i} \Delta\phi_{i} \Delta\lambda_{i}\]

The next assumption is that \(\Delta\phi_{i}\) is constant yielding the following formula for the average used by integrate():

\[\frac {\sum_{i}f_{i} A_{i}}{\sum_{i}A_{i}} = \frac {\sum_{i}f_{i}cos\phi_{i}\Delta\lambda_{i}}{\sum_{i}cos\phi_{i}\Delta\lambda_{i}}\]

Please note that for Gaussian grids though \(\Delta\phi_{i}\) is not constant this formula is still used in the computations.

Warning

The formula above is only used for the following grids:

  • regular and reduced latitude-longitude grids

  • regular and reduced Gaussian grids

For all the other grid types integrate() simply returns the mathematical average of the values (just like average() does).