improver.regrid.bilinear module
Bilinear Regridding with Land-sea Mask Awareness
This subpackage provides a fast and unified implementation of bilinear regridding with land-sea mask awareness. It is assumed that the source grid is evenly-spaced in a rectilinear latitude/longitude system. The target grid could be rectilinear or curvilinear. Regridding a field with land-sea mask awareness means that only land-surface source points are used for regridding at the land-surface target points, and vice versa at the sea-surface target points.
Calculation Steps of Regridding
Given a target point, determine its four source points according to regular grid point ordering.
Identify surface type of source/target points from land sea mask input files.
Identify if source points have the same surface type as the target point. The matched source points are called “True”, and unmatched source points are called “False”.
Calculate weights of four source points with normal bilinear formulation.
Adjust source points & weights if unmatched source points exist.
Apply weights at values of source points for interpolated value in a unified way so that vectorisation of the Numpy computation can be fully achieved.
Weight Calculation and Adjustment
2 .----------. 3
| | target point x(lon,lat)
lat | x | four source points 1,2,3 and 4
| |
1 .----------. 4
lon
For the target points with four matched surrounding source points, their source point weights can be calculated using the Finite-Element based interpolation shape function (please see R.D.Cook et al., 2001 on how to derive the finite element shape function). The formulations are as below (var is the physical variable to be interpolated).
\[ \begin{align}\begin{aligned}var &= \sum \limits_{i=1}^4 weight_i \cdot var_i\\weight_1 &= (lat_2-lat)*(lon_3-lon)/area\\weight_2 &= (lat-lat_1)*(lon_3-lon)/area\\weight_3 &= (lat-lat_1)*(lon-lon_1)/area\\weight_4 &= (lat_2-lat)*(lon-lon_1)/area\\area &= (lat_2-lat_1)*(lon_3-lon_1)\end{aligned}\end{align} \]
For the target points with three matched source points plus one unmatached source point, and the target point inside the triangle formed with three matched source points, three matched source points is used to construct linear field for interpolation. The Finite-Element based interpolation shape functions are given for the weight calculation.
if source point 1 is unmatched:
\[ \begin{align}\begin{aligned}weight_1 &= 0.0\\weight_2 &= (lat_2-lat_1)*(lon_3-lon)/area\\weight_3 &= (lat_2-lat)*(lon_3-lon_1)/area\\weight_4 &= 1.0-weight_2-weight_3\end{aligned}\end{align} \]if source point 2 is unmatched:
\[ \begin{align}\begin{aligned}weight_1 &= (lat_2-lat_1)*(lon_3-lon)/area\\weight_2 &= 0.0\\weight_3 &= (lat-lat_1)*(lon_3-lon_1)/area\\weight_4 &= 1.0-weight_1-weight_3\end{aligned}\end{align} \]if source point 3 is unmatched:
\[ \begin{align}\begin{aligned}weight_2 &= (lat-lat_1)*(lon_3-lon_1)/area\\weight_4 &= (lat_2-lat_1)*(lon-lon_1)/area\\weight_3 &= 0.0\\weight_1 &= 1.0-weight_2-weight_4\end{aligned}\end{align} \]if source point 4 is unmatched:
\[ \begin{align}\begin{aligned}weight_1 &= (lat_2-lat)*(lon_3-lon_1)/area\\weight_3 &= (lat_2-lat_1)*(lon-lon_1)/area\\weight_2 &= 1.0-weight_1-weight_3\\weight_4 &= 0.0\end{aligned}\end{align} \]
The inverse distance weighting(IDW) method is used for the target points with the following:
One unmatched source points, three matched source points but the target point is outside the triangle formed with three matched source points.
Two unmatched source points, two matched source points.
Three unmatched source points, one matched source point
The source points of inverse distance weighting are obtained by searching for the nearest k (default: 4) source points for each target point using the K-D tree method, and then are identified as unmatched-surface-type and matched-surface-type. If there is no matched source points, these target points will be added into the target point list with “four unmatched source points”. The latitude and longitude coordinates are transformed to the earth-centric earth-fixed(ECEF) Cartesian XYZ coordinates for the K-D tree calculation so that the distances are calculated in the ECEF coordinate system.
If there are matched surface points, the weights of inverse distance weighting are calculated:
where p is a positive number, called the power parameter. The optimum value =1.80 is used.
For the target points with four unmatched source points and zero matched source point, re-locating their source points by looking up eight nearest source points with specified distance limit using the K-D tree method and then check if there are any same-type source points:
if yes, use the matched source for the interpolation of inverse distance weighting
if no, just ignore the surface type and do normal bilinear interpolation
- adjust_boundary_indexes(in_lons_size, lat_max_equal, lon_max_equal, lat_max_in, lon_max_in, out_latlons, indexes)[source]
Adjust surrounding source point indexes for boundary target points. it is required when maximum latitude and logitude are identical between source and target grids.
- Parameters:
in_lons_size (
int) – Source grid’s longitude dimension.lat_max_equal (
bool) – Whether maximum latitude is identical between source/targin grids.lon_max_equal (
bool) – Whether maximum longitude is identical between source/targin grids.lat_max_in (
float) – Input grid’s maximum latitude.lon_max_in (
float) – Input grid’s maximum longtitude.out_latlons (
ndarray) – Target points’s latitude-longitudes.indexes (
ndarray) – Updated array of source grid point number for all target grid points.
- Return type:
- Returns:
Updated array of source grid point number for all target grid points. Array shape is (total number of target points, 4).
- adjust_for_surface_mismatch(in_latlons, out_latlons, in_classified, out_classified, weights, indexes, surface_type_mask, in_lons_size, vicinity, lat_spacing, lon_spacing)[source]
Updating source points and weighting for mismatched-source-point cases.
Triangle interpolation function is used for only one mismatched source point and target point is within the triangle formed with three matched sourced point.
In one of 3 cases (a)one false source points, three true source points but the target point is outside triangle (b)Two false source points, two true source points (c) three false source points, one true source pointfor, find four surrounding source points using KDtree, and regridding with inverse distance weighting(IDW) if matched source point is available.
In case of four mismatched source points(zero matched source point), Look up 8 points with specified distance limit (input) using KD tree, and then check if there are any same-type source points. If yes, pick up the points of the same type, and do IDW interpolation. If no, ignore surface type and just do normal bilinear interpolation.
- Parameters:
in_latlons (
ndarray) – Source points’s latitude-longitudes.out_latlons (
ndarray) – Target points’s latitude-longitudes.in_classified (
ndarray) – Land_sea type for source grid points (land ->True).out_classified (
ndarray) – Land_sea type for terget grid points (land ->True).weights (
ndarray) – Array of source grid point weighting for all target grid points.indexes (
ndarray) – Array of source grid point number for all target grid points.surface_type_mask (
ndarray) – Numpy ndarray of bool, true if source point type matches target point type.in_lons_size (
int) – Longitude dimension in cube_in.vicinity (
float) – Radius of specified searching domain, in meter.lat_spacing (
float) – Input grid latitude spacing, in degree.lon_spacing (
float) – Input grid longitude spacing, in degree.
- Return type:
- Returns:
Updated array of source grid point weights for all target grid points.
Updated array of source grid point index for all target grid points.
- apply_weights(indexes, in_values, weights)[source]
Apply bilinear weight of source points for target value.
- Parameters:
- Return type:
- Returns:
Regridded values for target points.
- basic_indexes(out_latlons, in_latlons, in_lons_size, lat_spacing, lon_spacing)[source]
Locating source points for each target point.
- Parameters:
in_latlons (
ndarray) – Source points’s latitude-longitudes.out_latlons (
ndarray) – Target points’s latitude-longitudes.in_lons_size (
int) – Source grid’s longitude dimension.lat_spacing (
float) – Input grid latitude spacing, in degree.lon_spacing (
float) – Input grid longitude spacing, in degree.
- Return type:
- Returns:
Updated array of source grid point number for all target grid points. Array shape is (total number of target points, 4).
- basic_weights(index_range, indexes, out_latlons, in_latlons, lat_spacing, lon_spacing)[source]
Calculate weighting for selecting target points using standard bilinear function.
- Parameters:
index_range (
ndarray) – A list of target points.indexes (
ndarray) – Array of source grid point number for all target grid points.in_latlons (
ndarray) – Source points’s latitude-longitudes.out_latlons (
ndarray) – Target points’s latitude-longitudes.lat_spacing (
float) – Input grid latitude spacing, in degree.lon_spacing (
float) – Input grid longitude spacing, in degree.
- Return type:
- Returns:
Weighting array of source grid point number for target grid points.
- lakes_islands(lake_island_indexes, weights, indexes, surface_type_mask, in_latlons, out_latlons, in_classified, out_classified, in_lons_size, vicinity, lat_spacing, lon_spacing)[source]
Updating source points and weighting for 4-false-source-point cases. These are lakes (water surrounded by land) and islands (land surrounded by water). Note that a similar function can be found in nearest.py for nearest neighbour regridding rather than bilinear regridding.
- Parameters:
lake_island_indexes (
ndarray) – Selected target points which have 4 false source points.in_latlons (
ndarray) – Source points’s latitude-longitudes.out_latlons (
ndarray) – Target points’s latitude-longitudes.surface_type_mask (
ndarray) – Numpy ndarray of bool, true if source point type matches target point type.indexes (
ndarray) – Array of source grid point number for all target grid points.weights (
ndarray) – Array of source grid point weighting for all target grid points.in_classified (
ndarray) – Land_sea type for source grid points (land ->True).out_classified (
ndarray) – Land_sea type for terget grid points (land ->True).in_lons_size (
int) – Source grid’s longitude dimension.vicinity (
float) – Radius of specified searching domain, in meter.lat_spacing (
float) – Input grid latitude spacing, in degree.lon_spacing (
float) – Input grid longitude spacing, in degree.
- Return type:
- Returns:
Updated weights - source point weighting for all target grid points.
Updated indexes - source grid point number for all target grid points.
Updated surface_type_mask - matching info between source/target point types.
- one_mismatched_input_point(one_mismatch_indexes, surface_type_mask, indexes, weights, out_latlons, in_latlons, lat_spacing, lon_spacing)[source]
Updating source points and weighting for one mismatched source-point cases. If target is not within the triangle formed by 3 matched-sourced-points, updating of weights is deferred to inverse-distance-weight method.
- Parameters:
one_mismatch_indexes (
ndarray) – Selected target points which have 1 false source point.surface_type_mask (
ndarray) – Numpy ndarray of bool, true if source point type matches target point type.indexes (
ndarray) – Array of source grid point number for all target grid points.weights (
ndarray) – Array of source grid point weighting for all target grid points.in_latlons (
ndarray) – Source points’s latitude-longitudes.out_latlons (
ndarray) – Target points’s latitude-longitudes.in_lons_size – Source grid’s longitude dimension.
lat_spacing (
float) – Input grid latitude spacing, in degree.lon_spacing (
float) – Input grid longitude spacing, in degree.
- Return type:
- Returns:
Updated weights - array of source grid point weighting for target grid points.
Excluded indexes - target points which are not handled in this function.