Vertical interpolation and re-mapping vertical_interpolation/std

Vertical interpolation and re-mapping vertical_interpolation/std#

Description#

vertical_interpolation transform: map model fields to observation vertical levels.

Interpolates or samples a gridded model field along the vertical axis to produce values at the pressure or height levels of the observations or the succeeding transform.

Five interpolation methods are available (set via method):

  • ``static-levels`` — reads a station level file (file_statlev) that maps each station name to its model level index. No pressure calculation needed; the level index is used directly.

  • ``linear`` — linear interpolation between the model level mid-points bracketing the target pressure/height coordinate (coord_out).

  • ``closest`` — selects the model level whose centre pressure/height is nearest to the target coordinate.

  • ``match-layer`` — assigns the observation to the model layer whose boundaries contain the target coordinate.

  • ``layer-weighted`` — distributes the observation over all model layers that overlap the observation’s vertical extent, weighting by the fractional thickness within each layer.

Two data paths are implemented:

  • Array data — gridded xarray fields; the interpolation is applied to the full (time, lev, lat, lon) array.

  • Sparse / sampled data — observation-indexed DataFrames; the level index is looked up per observation row.

The adjoint scatters observation sensitivities back to the model level(s) with the same weights used in the forward pass.

YAML arguments#

The following arguments are used to configure the plugin. pyCIF will return an exception at the initialization if mandatory arguments are not specified, or if any argument does not fit accepted values or type:

Mandatory arguments#

method : “static-levels” or “linear” or “closest” or “match-layer” or “layer-weighted”, mandatory
Method used for the interpolation

  • static-levels:

  • linear: a linear interpolation. Uses the coordinate specified in coord_out

  • closest: gets closest levels

  • “static-levels”: determines levels from pre-determined levels as specified in the argument file_statlev

  • “linear”: a linear interpolation. Uses the coordinate specified in coord_out

  • “closest”: gets closest levels

  • “match-layer”: finds the layer matching outputs.

  • “layer-weighted”: finds the layers matching outputs, and weights according to the thickness in each input layers

Optional arguments#

parameter : str, optional

Parameter name on which the transform works on

component : str, optional

Component name on which the transform works on

orig_parameter_plg : Plugin, optional

Plugin object on which the transform works on

orig_component_plg : Plugin, optional

Corresponding component object on which the transform works on

successor : str, optional

Name of the successor transform

precursor : str, optional

Name of the precursor transform

coord_in : str, optional, default “pres”

Vertical coordinate of the input model field: 'pres' for pressure (Pa or hPa) or 'height' for altitude (m).

file_statlev : str, optional, default “”

File with model levels in which stations are. The expected format is:

#STAT LAT     LON     LEV  alt(m)
ALT   82.45   -62.52  1        210
JFJ   46.548  7.987   10       3580
MHD   53.33   -9.9    1        8

The first line is ignored. The important informations are the first columns with the station ID (should be consistent with the station name in your monitor file, and the fourth column specifying the level in the model (in python index starting from 0)

ignore_level : bool, optional, default False

Don’t do any vertical interpolation for sparse data and just propagate levels from inputs and outputs

coord_out : str, optional, default “pres”

Vertical coordinate of the target (output) levels: 'pres' (Pa or hPa) or 'height' (m). Used by the linear and closest methods.

psurf : float, optional, default 1013.25

Reference surface pressure (hPa) used when converting sigma/hybrid coordinates (α, β) to absolute pressure. Only needed for models that use hybrid sigma-pressure levels.

fill_nans : bool, optional, default False

Use in combination with method = linear. Fill values outside the convex hull of inputs by using the closest valid (above or below) value

target_top : bool, optional, default False

Interpolate to the top of a domain

sparse_in : bool, optional, default False

Set to True when the input is an observation-indexed pandas DataFrame rather than a gridded xarray DataArray.

sparse_out : bool, optional, default False

Set to True when the output should be an observation-indexed pandas DataFrame.

sampled_in : bool, optional, default False

Set to True when the input has already been sampled at observation locations by a preceding transform.

sampled_out : bool, optional, default False

Set to True when the output should be sampled at observation locations.

YAML template#

Please find below a template for a YAML configuration:

 1transform:
 2  plugin:
 3    name: vertical_interpolation
 4    version: std
 5    type: transform
 6
 7  # Mandatory arguments
 8  method: XXXXX  # static-levels|linear|closest|match-layer|layer-weighted
 9
10  # Optional arguments
11  parameter: XXXXX  # str
12  component: XXXXX  # str
13  orig_parameter_plg: XXXXX  # Plugin
14  orig_component_plg: XXXXX  # Plugin
15  successor: XXXXX  # str
16  precursor: XXXXX  # str
17  coord_in: XXXXX  # str
18  file_statlev: XXXXX  # str
19  ignore_level: XXXXX  # bool
20  coord_out: XXXXX  # str
21  psurf: XXXXX  # float
22  fill_nans: XXXXX  # bool
23  target_top: XXXXX  # bool
24  sparse_in: XXXXX  # bool
25  sparse_out: XXXXX  # bool
26  sampled_in: XXXXX  # bool
27  sampled_out: XXXXX  # bool

See also

API reference (functions & code)