Interpolation

Interpolation#

The Skyborn interpolation module provides data interpolation and regridding capabilities for atmospheric and climate data.

Regridding Classes#

class Grid(lon, lat)[source]#

Bases: object

Representation of a rectilinear grid.

Parameters:
lon: ndarray#
lat: ndarray#
classmethod from_degrees(lon, lat)[source]#
Parameters:
Return type:

Grid

classmethod from_dataset(dataset)[source]#

Create a Grid from an xarray Dataset by auto-detecting coordinates.

Parameters:

dataset (Dataset)

Return type:

Grid

property shape: tuple[int, int]#
__init__(lon, lat)#
Parameters:
Return type:

None

class Regridder(source, target)[source]#

Bases: object

Base class for regridding.

Parameters:
source: Grid#
target: Grid#
regrid_array(field)[source]#

Regrid an array with dimensions (…, lon, lat) from source to target.

Parameters:

field (ndarray)

Return type:

ndarray

regrid_dataset(dataset, lon_dim=None, lat_dim=None)[source]#

Regrid an xarray.Dataset from source to target.

Parameters:

  • dataset (Dataset) – Input xarray Dataset

  • lon_dim (str | None) – Name of longitude dimension (auto-detected if None)

  • lat_dim (str | None) – Name of latitude dimension (auto-detected if None)

Returns:

Regridded xarray Dataset with preserved dimension order

Return type:

Dataset

__init__(source, target)#
Parameters:
Return type:

None

class NearestRegridder(source, target)[source]#

Bases: Regridder

Regrid with nearest neighbor interpolation.

Parameters:
__init__(source, target)[source]#
Parameters:
property indices#

The interpolation indices associated with source_grid.

regrid_array(field)[source]#

Regrid an array with dimensions (…, lon, lat) from source to target.

Parameters:

field (ndarray)

Return type:

ndarray

class BilinearRegridder(source, target)[source]#

Bases: Regridder

Regrid with bilinear interpolation.

Parameters:
regrid_array(field)[source]#

Regrid an array with dimensions (…, lon, lat) from source to target.

Parameters:

field (ndarray)

Return type:

ndarray

class ConservativeRegridder(source, target)[source]#

Bases: Regridder

Regrid with linear conservative regridding.

Parameters:
__init__(source, target)[source]#
Parameters:
property lon_weights#

Cached longitude weights for performance.

property lat_weights#

Cached latitude weights for performance.

regrid_array(field)[source]#

Regrid an array with dimensions (…, lon, lat) from source to target.

Parameters:

field (ndarray)

Return type:

ndarray

Regridding Functions#

regrid_dataset(dataset, target_grid, method='bilinear', lon_dim=None, lat_dim=None)[source]#

Convenience function to regrid a dataset with optimized performance.

Parameters:

  • dataset (Dataset) – Input xarray Dataset

  • target_grid (Grid) – Target grid for regridding

  • method (str) – Interpolation method (‘nearest’, ‘bilinear’, ‘conservative’)

  • lon_dim (str | None) – Name of longitude dimension (auto-detected if None)

  • lat_dim (str | None) – Name of latitude dimension (auto-detected if None)

Returns:

Regridded xarray Dataset with preserved dimension order

Return type:

Dataset

nearest_neighbor_indices(source_grid, target_grid)[source]#

Returns Haversine nearest neighbor indices from source_grid to target_grid.

Parameters:
Return type:

ndarray

Interpolation Functions#

Skyborn’s model-level interpolation utilities support hybrid-sigma to pressure remapping, sigma-to-hybrid remapping, and multidimensional spatial interpolation for atmospheric fields. The hybrid-level workflow now exposes helper functions for diagnosing hybrid pressures and layer thicknesses and uses a more flexible execution path for interp_hybrid_to_pressure:

  • direct in-memory interpolation for ordinary NumPy-backed xarray inputs

  • xarray.map_blocks when Dask chunking is favorable

  • Dask map_blocks fallback for chunked inputs that still need the older workaround path

Pressure-Coordinate Profiles#

interp_pressure_1d(data=None, source_pressure=None, target_pressure=None, *, method='log', extrapolate=False, missing_value=np.nan, **legacy_kwargs)[source]#

Interpolate a one-dimensional profile between pressure coordinates.

Parameters:

  • data (xarray.DataArray, numpy.ndarray) – One-dimensional field values defined on source_pressure.

  • source_pressure (xarray.DataArray, numpy.ndarray) – One-dimensional source pressure levels. Values must be strictly monotonic after missing levels are removed.

  • target_pressure (xarray.DataArray, numpy.ndarray) – One-dimensional target pressure levels. Values may be increasing or decreasing.

  • method ({"linear", "log"}, optional) – Interpolate linearly in pressure or in log-pressure. Defaults to "log".

  • extrapolate (bool, optional) – If True, use the end slopes to extrapolate outside the valid source pressure range. Defaults to False.

  • missing_value (scalar, optional) – Public missing-value marker. Defaults to np.nan.

  • legacy_kwargs (DataArray | ndarray)

Returns:

Interpolated values on target_pressure. Xarray inputs return a one-dimensional DataArray with the target pressure coordinate.

Return type:

xarray.DataArray, numpy.ndarray

Notes

The legacy keyword aliases values, x, p_in, and p_out are still accepted for backward compatibility, but the preferred public parameter names are now data, source_pressure, and target_pressure.

Note

The public interp_pressure_1d signature now uses the descriptive parameter names data, source_pressure, and target_pressure. The historical aliases values, x, p_in, and p_out are still accepted for backward compatibility.

Hybrid-Level Diagnostics#

pressure_at_hybrid_levels(psfc, hya, hyb, p0=100000.0, lev_dim='lev', output_dims=('time', 'lev', 'lat', 'lon'))[source]#

Calculate pressure at hybrid levels.

Parameters:

  • psfc (xarray.DataArray, numpy.ndarray) – Surface pressure in Pascals.

  • hya (xarray.DataArray, numpy.ndarray) – One-dimensional hybrid coefficients.

  • hyb (xarray.DataArray, numpy.ndarray) – One-dimensional hybrid coefficients.

  • p0 (float, optional) – Reference pressure in Pascals.

  • lev_dim (str, optional) – Output vertical dimension name for xarray inputs. Defaults to "lev".

  • output_dims (sequence of str, optional) – Preferred output dimension order for xarray inputs. Defaults to ("time", "lev", "lat", "lon"); any names not present in the output are ignored, and remaining dimensions keep their relative order.

Returns:

Pressure at hybrid levels in Pascals. The output shape is (len(hya), *psfc.shape) for eager NumPy inputs, or (lev, *psfc.dims) for eager xarray inputs.

Return type:

xarray.DataArray, numpy.ndarray

delta_pressure_hybrid(ps, hya, hyb, p0=100000.0, lev_dim='lev', output_dims=('time', 'lev', 'lat', 'lon'))[source]#

Calculate pressure layer thickness for hybrid coordinates.

Parameters:

  • ps (xarray.DataArray, numpy.ndarray) – Surface pressure in Pascals.

  • hya (xarray.DataArray, numpy.ndarray) – One-dimensional hybrid coefficients defined at layer interfaces. If hya and hyb have length nlev + 1, the result contains nlev layer-thickness values.

  • hyb (xarray.DataArray, numpy.ndarray) – One-dimensional hybrid coefficients defined at layer interfaces. If hya and hyb have length nlev + 1, the result contains nlev layer-thickness values.

  • p0 (float, optional) – Reference pressure in Pascals. Use p0=1 when hya already has pressure units, for example ERA5 hyai / hyam coefficients.

  • lev_dim (str, optional) – Output vertical dimension name for xarray inputs. Defaults to "lev".

  • output_dims (sequence of str, optional) – Preferred output dimension order for xarray inputs. Defaults to ("time", "lev", "lat", "lon"); any names not present in the output are ignored, and remaining dimensions keep their relative order.

Returns:

Pressure layer thickness in Pascals for each hybrid layer. The output shape is (len(hya) - 1, *ps.shape) for eager NumPy inputs, or (lev, *ps.dims) for eager xarray inputs.

Return type:

xarray.DataArray, numpy.ndarray

Notes

This function expects hybrid coefficients defined at layer interfaces, not layer midpoints. For datasets such as ERA5, use hyai / hybi to compute layer-thickness values. If you need pressure at the layer midpoints instead, use pressure_at_hybrid_levels() with hyam / hybm.

For CESM-family data it is often convenient to keep using hyai / hybi for the calculation while leaving the default lev_dim="lev" and output_dims=("time", "lev", "lat", "lon") so the result lines up naturally with variables on model midpoints such as V(time, lev, lat, lon).

With xarray inputs, the default behavior is therefore to expose the output vertical dimension as "lev" and to prefer the common ("time", "lev", "lat", "lon") ordering. If one or more of these dimension names are not present in the output, they are ignored and the remaining dimensions keep their relative order.

Model-Level Remapping#

interp_hybrid_to_pressure(data, ps, hyam, hybm, p0=100000.0, new_levels=__pres_lev_mandatory__, lev_dim=None, method='linear', extrapolate=False, variable=None, t_bot=None, phi_sfc=None)[source]#

Interpolate and extrapolate data from hybrid-sigma levels to isobaric levels.

This function interpolates atmospheric data from hybrid-sigma coordinate levels to constant pressure levels, with optional extrapolation below ground using ECMWF formulations. Preserves all metadata from the input data.

Notes

Atmosphere hybrid-sigma pressure coordinates are commonly defined in two different ways as described below and in CF Conventions. This particular function expects the first formulation. However, with some minor adjustments on the user side it can support datasets leveraging the second formulation as well. In this case, you can set the input parameters p0=1 and hyam=ap to adapt the function to meet your needs.

Formulation 1: p(n,k,j,i) = a(k)*p0 + b(k)*ps(n,j,i) Formulation 2: p(n,k,j,i) = ap(k) + b(k)*ps(n,j,i)

Parameters:

  • data (xarray.DataArray) – Multidimensional data array with hybrid-sigma levels and a lev_dim coordinate.

  • ps (xarray.DataArray) – A multi-dimensional array of surface pressures (Pa), same time/space shape as data.

  • hyam (xarray.DataArray) – One-dimensional arrays containing the hybrid A and B coefficients. Must have the same dimension size as the lev_dim dimension of data.

  • hybm (xarray.DataArray) – One-dimensional arrays containing the hybrid A and B coefficients. Must have the same dimension size as the lev_dim dimension of data.

  • p0 (float, optional) – Scalar numeric value equal to surface reference pressure (Pa). Defaults to 100000 Pa.

  • new_levels (ndarray, optional) – A one-dimensional array of output pressure levels (Pa). If not given, the mandatory list of 21 pressure levels is used.

  • lev_dim (str, optional) – String that is the name of level dimension in data. If None, attempts to detect automatically using CF conventions.

  • method (str, optional) – Interpolation method passed to the compiled vinth2p kernels. Supported values are "linear", "log", and "log-log" (or "loglog"). Defaults to "linear".

  • extrapolate (bool, optional) – If True, below ground extrapolation for variable will be done using an ECMWF formulation. Defaults to False.

  • variable (str, optional) – String representing what variable is extrapolated below surface level. Temperature extrapolation = “temperature”. Geopotential height extrapolation = “geopotential”. All other variables = “other”. If “other”, the value of data at the lowest model level will be used as the below ground fill value. Required if extrapolate is True.

  • t_bot (xarray.DataArray, optional) – Temperature in Kelvin at the lowest layer of the model. Not necessarily the same as surface temperature. Required if extrapolate is True and variable is not 'other'

  • phi_sfc (xarray.DataArray, optional) – Geopotential in J/kg at the lowest layer of the model. Not necessarily the same as surface geopotential. Required if extrapolate is True and variable is not 'other'.

Returns:

output – Interpolated data with isobaric levels as the new vertical coordinate

Return type:

xarray.DataArray

Examples

Basic interpolation from hybrid-sigma to pressure levels:

>>> import skyborn.interp as si
>>> import xarray as xr
>>> import numpy as np
>>>
>>> # Interpolate temperature to standard pressure levels
>>> temp_p = si.interp_hybrid_to_pressure(
...     data=temperature,
...     ps=surface_pressure,
...     hyam=hybrid_a,
...     hybm=hybrid_b,
...     new_levels=np.array([100000, 85000, 70000])  # Pa
... )

See also

interp_sigma_to_hybrid : Interpolate from sigma to hybrid coordinates

Related NCL Functions: vinth2p, vinth2p_ecmwf

interp_sigma_to_hybrid(data, sig_coords, ps, hyam, hybm, p0=100000.0, lev_dim=None, method='linear')[source]#

Interpolate data from sigma to hybrid coordinates.

This function interpolates atmospheric data from sigma coordinate levels to hybrid-sigma coordinate levels. Preserves all metadata from the input data.

Parameters:

  • data (xarray.DataArray) – Multidimensional data array with sigma levels and a lev_dim coordinate.

  • sig_coords (xarray.DataArray) – A one-dimensional array of sigma coordinates corresponding to the lev_dim dimension of data.

  • ps (xarray.DataArray) – A multi-dimensional array of surface pressures (Pa), same time/space shape as data.

  • hyam (xarray.DataArray) – One-dimensional arrays containing the hybrid A and B coefficients. Must have the same dimension as the desired output hybrid levels.

  • hybm (xarray.DataArray) – One-dimensional arrays containing the hybrid A and B coefficients. Must have the same dimension as the desired output hybrid levels.

  • p0 (float, optional) – Scalar numeric value equal to surface reference pressure (Pa). Defaults to 100000 Pa.

  • lev_dim (str, optional) – String that is the name of level dimension in data. If None, attempts to detect automatically using CF conventions.

  • method (str, optional) – Interpolation method passed to the compiled sigma2hybrid kernels. Supported values are "linear", "log", and "log-log" (or "loglog"). Defaults to "linear".

Returns:

output – Interpolated data with hybrid levels as the new vertical coordinate

Return type:

xarray.DataArray

Examples

Basic interpolation from sigma to hybrid coordinates:

>>> import skyborn.interp as si
>>> import xarray as xr
>>> import numpy as np
>>>
>>> # Interpolate data from sigma to hybrid levels
>>> data_hybrid = si.interp_sigma_to_hybrid(
...     data=sigma_data,
...     sig_coords=sigma_levels,
...     ps=surface_pressure,
...     hyam=hybrid_a,
...     hybm=hybrid_b
... )

See also

interp_hybrid_to_pressure : Interpolate from hybrid to pressure coordinates

Related NCL Function: sigma2hybrid

interp_multidim(data_in, lat_out, lon_out, lat_in=None, lon_in=None, cyclic=False, missing_val=None, method='linear', fill_value=np.nan)[source]#

Multidimensional interpolation of variables. Uses xarray.interp to perform interpolation. Will not perform extrapolation by default, returns missing values if any surrounding points contain missing values.

Warning

The output data type may be promoted to that of the coordinate data.

Parameters:

  • data_in (xarray.DataArray, ndarray) – Data array with data to be interpolated and associated coords. If it is a np array, then lat_in and lon_in must be provided. Length must be coordinated with given coordinates.

  • lat_out (ndarray) – List of latitude coordinates to be interpolated to.

  • lon_out (ndarray) – List of longitude coordinates to be interpolated to.

  • lat_in (ndarray) – List of latitude coordinates corresponding to data_in. Must be given if data_in is not an xarray.

  • lon_in (ndarray) – List of longitude coordinates corresponding to data_in. Must be given if data_in is not an xarray.

  • cyclic (bool, optional) – Set as true if lon values are cyclical but do not fully wrap around the globe (0, 1.5, 3, …, 354, 355.5) Default is false

  • missing_val (np.number, optional) – Provide a number to represent missing data. Alternative to using np.nan

  • method (str, optional) – Provide specific method of interpolation. Default is “linear” “linear” or “nearest” for multidimensional array

  • fill_value (str, optional) – Set as ‘extrapolate’ to allow extrapolation of data. Default is no extrapolation.

Returns:

data_out – Returns the same type of object as input data_in. However, the type of the data in the array may be promoted to that of the coordinates. Shape will be the same as input array except for last two dimensions which will be equal to the coordinates given in data_out.

Return type:

ndarray, xarray.DataArray

Examples

Basic multidimensional interpolation:

>>> import skyborn.interp as si
>>> import xarray as xr
>>> import numpy as np
>>>
>>> # Create sample data
>>> data = np.asarray([[1, 2, 3, 4, 5, 99],
...                   [2, 4, 6, 8, 10, 12]])
>>> lat_in = [0, 1]
>>> lon_in = [0, 50, 100, 250, 300, 350]
>>> data_in = xr.DataArray(data,
...                        dims=['lat', 'lon'],
...                        coords={'lat':lat_in,
...                                'lon': lon_in})
>>>
>>> # Interpolate to new coordinates with cyclic boundary
>>> do = si.interp_multidim(data_in,
...                         [0, 1],
...                         [0, 50, 360],
...                         cyclic=True,
...                         missing_val=99)
>>> print(do)
<xarray.DataArray (lat: 2, lon: 3)>
array([[ 1.,  2., 99.],
   [ 2.,  4., 99.]])
Coordinates:
  * lat      (lat) int64 0 1
  * lon      (lon) int64 0 50 360

See also

Related External Functions: xarray.DataArray.interp, cartopy.util.add_cyclic_point

Related NCL Function: NCL linint2

Curvilinear and Unstructured Interpolation#

rcm2points(lat2d, lon2d, fi, lat1d, lon1d, opt=0, msg=None, meta=False)[source]#

Interpolates data on a curvilinear grid (i.e. RCM, WRF, NARR) to an unstructured grid.

Interpolates data on a curvilinear grid, such as those used by the RCM (Regional Climate Model), WRF (Weather Research and Forecasting) and NARR (North American Regional Reanalysis) models/datasets to an unstructured grid. All of these have latitudes that are oriented south-to-north. An inverse distance squared algorithm is used to perform the interpolation. Missing values are allowed and no extrapolation is performed.

Parameters:

  • lat2d (xarray.DataArray, numpy.ndarray) – A two-dimensional array that specifies the latitudes locations of fi. The latitude order must be south-to-north. Because this array is two-dimensional it is not an associated coordinate variable of fi, so it should always be explicitly provided.

  • lon2d (xarray.DataArray, numpy.ndarray) – A two-dimensional array that specifies the longitude locations of fi. The longitude order must be west-to-east. Because this array is two-dimensional it is not an associated coordinate variable of fi, so it should always be explicitly provided.

  • fi (xarray.DataArray, numpy.ndarray) – A multi-dimensional array to be interpolated. The rightmost two dimensions (latitude, longitude) are the dimensions to be interpolated.

  • lat1d (xarray.DataArray, numpy.ndarray) – A one-dimensional array that specifies the latitude coordinates of the output locations.

  • lon1d (xarray.DataArray, numpy.ndarray) – A one-dimensional array that specifies the longitude coordinates of the output locations.

  • opt (numpy.number) – opt=0 or 1 means use an inverse distance weight interpolation. opt=2 means use a bilinear interpolation.

  • msg (numpy.number) – A numpy scalar value that represent a missing value in fi. This argument allows a user to use a missing value scheme other than NaN or masked arrays, similar to what NCL allows.

  • meta (bool) – If set to True and the input array is an Xarray, the metadata from the input array will be copied to the output array; default is False. Warning: This option is not currently supported.

Returns:

fo – The interpolated grid. A multi-dimensional array of the same size as fi except that the rightmost dimension sizes have been replaced by the number of coordinate pairs (lat1d, lon1d).

Return type:

xarray.DataArray, numpy.ndarray

rcm2rgrid(lat2d, lon2d, fi, lat1d, lon1d, msg=None, meta=False)[source]#

Interpolates data on a curvilinear grid (i.e. RCM, WRF, NARR) to a rectilinear grid.

Interpolates RCM (Regional Climate Model), WRF (Weather Research and Forecasting) and NARR (North American Regional Reanalysis) grids to a rectilinear grid. Actually, this function will interpolate most grids that use curvilinear latitude/longitude grids. No extrapolation is performed beyond the range of the input coordinates. Missing values are allowed but ignored.

The weighting method used is simple inverse distance squared. Missing values are allowed but ignored.

The code searches the input curvilinear grid latitudes and longitudes for the four grid points that surround a specified output grid coordinate. Because one or more of these input points could contain missing values, fewer than four points could be used in the interpolation.

Curvilinear grids which have two-dimensional latitude and longitude coordinate axes present some issues because the coordinates are not necessarily monotonically increasing. The simple search algorithm used by rcm2rgrid is not capable of handling all cases. The result is that, sometimes, there are small gaps in the interpolated grids. Any interior points not interpolated in the initial interpolation pass will be filled using linear interpolation.

In some cases, edge points may not be filled.

Parameters:

  • lat2d (xarray.DataArray, numpy.ndarray) – A two-dimensional array that specifies the latitudes locations of the input (fi). Because this array is two-dimensional, it is not an associated coordinate variable of fi; therefore, it always needs to be explicitly provided. The latitude order must be south-to-north.

  • lon2d (xarray.DataArray, numpy.ndarray) – A two-dimensional array that specifies the longitudes locations of the input (fi). Because this array is two-dimensional, it is not an associated coordinate variable of fi; therefore, it always needs to be explicitly provided. The latitude order must be west-to-east.

  • fi (xarray.DataArray, numpy.ndarray) – A multi-dimensional array to be interpolated. The rightmost two dimensions (latitude, longitude) are the dimensions to be interpolated.

  • lat1d (xarray.DataArray, numpy.ndarray) – A one-dimensional array that specifies the latitude coordinates of the regular grid. Must be monotonically increasing.

  • lon1d (xarray.DataArray, numpy.ndarray) – A one-dimensional array that specifies the longitude coordinates of the regular grid. Must be monotonically increasing.

  • msg (numpy.number) – A numpy scalar value that represent a missing value in fi. This argument allows a user to use a missing value scheme other than NaN or masked arrays, similar to what NCL allows.

  • meta (bool) – If set to True and the input array is an Xarray, the metadata from the input array will be copied to the output array; default is False. Warning: This option is not currently supported.

Returns:

fo – The interpolated grid. A multi-dimensional array of the same size as fi except that the rightmost dimension sizes have been replaced by the sizes of lat1d and lon1d, respectively.

Return type:

xarray.DataArray, numpy.ndarray

Examples

Example 1: Using rcm2rgrid with xarray.DataArray input

import numpy as np import xarray as xr from skyborn.interp import rcm2rgrid

# Open a netCDF data file using xarray default engine and load the data stream ds = xr.open_dataset(“./ruc.nc”)

# [INPUT] Grid & data info on the source curvilinear ht_curv=ds.DIST_236_CBL[:] lat2D_curv=ds.gridlat_236[:] lon2D_curv=ds.gridlon_236[:]

# [OUTPUT] Grid on destination rectilinear grid (or read the 1D lat and lon from # an other .nc file. newlat1D_rect=np.linspace(lat2D_curv.min(), lat2D_curv.max(), 100) newlon1D_rect=np.linspace(lon2D_curv.min(), lon2D_curv.max(), 100)

ht_rect = rcm2rgrid(lat2D_curv, lon2D_curv, ht_curv, newlat1D_rect, newlon1D_rect)

rgrid2rcm(lat1d, lon1d, fi, lat2d, lon2d, msg=None, meta=False)[source]#

Interpolates data on a rectilinear lat/lon grid to a curvilinear grid like those used by the RCM, WRF and NARR models/datasets.

Interpolates data on a rectilinear lat/lon grid to a curvilinear grid, such as those used by the RCM (Regional Climate Model), WRF (Weather Research and Forecasting) and NARR (North American Regional Reanalysis) models/datasets. No extrapolation is performed beyond the range of the input coordinates. The method used is simple inverse distance weighting. Missing values are allowed but ignored.

Parameters:

  • lat1d (xarray.DataArray, numpy.ndarray) –

    A one-dimensional array that specifies the latitude coordinates of the regular grid. Must be monotonically increasing.

    Note: It should only be explicitly provided when the input (fi) is numpy.ndarray; otherwise, it should come from fi.coords.

  • lon1d (xarray.DataArray, numpy.ndarray) –

    A one-dimensional array that specifies the longitude coordinates of the regular grid. Must be monotonically increasing.

    Note: It should only be explicitly provided when the input (fi) is numpy.ndarray; otherwise, it should come from fi.coords.

  • fi (xarray.DataArray, numpy.ndarray) – A multi-dimensional array to be interpolated. The rightmost two dimensions (latitude, longitude) are the dimensions to be interpolated.

  • lat2d (xarray.DataArray, numpy.ndarray) – A two-dimensional array that specifies the latitude locations of the input (fi). Because this array is two-dimensional it is not an associated coordinate variable of fi.

  • lon2d (xarray.DataArray, numpy.ndarray) – A two-dimensional array that specifies the longitude locations of the input (fi). Because this array is two-dimensional it is not an associated coordinate variable of fi.

  • msg (numpy.number) – A numpy scalar value that represents a missing value in fi. This argument allows a user to use a missing value scheme other than NaN or masked arrays, similar to what NCL allows.

  • meta (bool) – If set to True and the input array is an Xarray, the metadata from the input array will be copied to the output array; default is False. Warning: this option is not currently supported.

Returns:

fo – The interpolated grid. A multi-dimensional array of the same size as fi except that the rightmost dimension sizes have been replaced by the sizes of lat2d (or lon2d).

Return type:

xarray.DataArray, numpy.ndarray

Examples

Example 1: Using rgrid2rcm with xarray.DataArray input

import numpy as np import xarray as xr from skyborn.interp import rgrid2rcm

# Open a netCDF data file using xarray default engine and load the data stream # input grid and data ds_rect = xr.open_dataset(“./DATAFILE_RECT.nc”)

# [INPUT] Grid & data info on the source rectilinear ht_rect =ds_rect.SOME_FIELD[:] lat1D_rect=ds_rect.gridlat_[:] lon1D_rect=ds_rect.gridlon_[:]

# Open a netCDF data file using xarray default engine and load the data stream # for output grid ds_curv = xr.open_dataset(“./DATAFILE_CURV.nc”)

# [OUTPUT] Grid on destination curvilinear grid (or read the 2D lat and lon from # an other .nc file newlat2D_rect=ds_curv.gridlat2D_[:] newlon2D_rect=ds_curv.gridlat2D_[:]

ht_curv = rgrid2rcm(lat1D_rect, lon1D_rect, ht_rect, newlat2D_curv, newlon2D_curv)

grid_to_triple(data, x_in=None, y_in=None, msg_py=None)[source]#

Converts a two-dimensional grid with one-dimensional coordinate variables to an array where each grid value is associated with its coordinates.

Parameters:

  • data (xarray.DataArray, numpy.ndarray) – Two-dimensional input array of size ny x mx containing the data values. Missing values may be present in data, but they are ignored.

  • x_in (xarray.DataArray, numpy.ndarray) –

    A one-dimensional array that specifies the the right dimension coordinates of the input (data).

    Note: It should only be explicitly provided when the input (fi) is numpy.ndarray; otherwise, it should come from fi.coords.

  • y_in (xarray.DataArray, numpy.ndarray) –

    A one-dimensional array that specifies the the left dimension coordinates of the input (data).

    Note: It should only be explicitly provided when the input (fi) is numpy.ndarray; otherwise, it should come from fi.coords.

  • msg_py (numpy.number) – A numpy scalar value that represent a missing value in data. This argument allows a user to use a missing value scheme other than NaN or masked arrays, similar to what NCL allows.

Returns:

out – The maximum size of the returned array will be 3 x ld, where ld <= ny x mx. If no missing values are encountered in data, then ld = ny x mx. If missing values are encountered in data, they are not returned and hence ld will be equal to ny x mx minus the number of missing values found in data.

Return type:

xarray.DataArray, numpy.ndarray

Examples

Example 1: Using grid_to_triple with xarray.DataArray input

import numpy as np
import xarray as xr
from skyborn.interp import grid_to_triple

# Open a netCDF data file using xarray default engine and load the data stream
ds = xr.open_dataset("./NETCDF_FILE.nc")

# [INPUT] Grid & data info on the source curvilinear
data = ds.DIST_236_CBL[:]
x_in = ds.gridlat_236[:]
y_in = ds.gridlon_236[:]

output = grid_to_triple(data, x_in, y_in)
triple_to_grid(data, x_in, y_in, x_out, y_out, method=1, domain=1.0, distmx=None, missing_value=None, meta=False)[source]#

Places unstructured (randomly-spaced) data onto the nearest locations of a rectilinear grid.

This function puts unstructured data (randomly-spaced) onto the nearest locations of a rectilinear grid. A default value of domain option is now set to 1.0 instead of 0.0.

This function does not perform interpolation; rather, each individual data point is assigned to the nearest grid point. It is possible that upon return, grid will contain grid points set to missing value if no x_in(n), y_in(n) are nearby.

Parameters:

  • data (xarray.DataArray, numpy.ndarray) – A multi-dimensional array, whose rightmost dimension is the same length as x_in and y_in, containing the values associated with the “x” and “y” coordinates. Missing values may be present but will be ignored.

  • x_in (xarray.DataArray, numpy.ndarray) – A one-dimensional array that specifies the x-coordinate associated with the input (data).

  • y_in (xarray.DataArray, numpy.ndarray) – A one-dimensional array that specifies the y-coordinate associated with the input (data).

  • x_out (xarray.DataArray, numpy.ndarray) – A one-dimensional array of length M containing the x-coordinates associated with the returned two-dimensional grid. The coordinate values must be monotonically increasing.

  • y_out (xarray.DataArray or numpy.ndarray) – A one-dimensional array of length N containing the y-coordinates associated with the returned two-dimensional grid. The coordinate values must be monotonically increasing.

  • method (int, optional) – An integer value that can be 0 or 1. The default value is 1. A value of 1 means to use the great circle distance formula for distance calculations. Warning: method = 0, together with domain = 1.0, could result in many of the target grid points to be set to the missing value if the number of grid points is large (ie: a high resolution grid) and the number of observations relatively small.

  • domain (float, optional) – A float value that should be set to a value >= 0. The default value is 1.0. If present, the larger this factor, the wider the spatial domain allowed to influence grid boundary points. Typically, domain is 1.0 or 2.0. If domain <= 0.0, then values located outside the grid domain specified by x_out and y_out arguments will not be used.

  • distmx (float, optional) – Setting distmx allows the user to specify a search radius (km) beyond which observations are not considered for nearest neighbor. Only applicable when method = 1. The default distmx=1e20 (km) means that every grid point will have a nearest neighbor. It is suggested that users specify a reasonable value for distmx.

  • missing_value (numpy.number, optional) – A numpy scalar value that represent a missing value in data. The default value is np.nan. If specified explicitly, this argument allows the user to use a missing value scheme other than NaN or masked arrays.

  • meta (bool, optional) – If set to True and the input array is an Xarray, the metadata from the input array will be copied to the output array; default is False. Warning: This option is not yet supported for this function.

Returns:

grid – The returned array will be K x N x M, where K represents the leftmost dimensions of data, N represent the size of y_out, and M represent the size of x_out coordinate vectors.

Return type:

xarray.DataArray, numpy.ndarray

Examples

Example 1: Using triple_to_grid with xarray.DataArray input

import numpy as np
import xarray as xr
from skyborn.interp import triple_to_grid

# Open a netCDF data file using xarray default engine and load the data stream
ds = xr.open_dataset("./ruc.nc")

# [INPUT] Grid & data info on the source curvilinear
data = ds.DIST_236_CBL[:]
x_in = ds.gridlat_236[:]
y_in = ds.gridlon_236[:]
x_out = ds.gridlat_236[:]
y_out = ds.gridlon_236[:]

# [OUTPUT] Grid on destination points grid (or read the 1D lat and lon from
# another .nc file.
newlat1D_points=np.linspace(lat2D_curv.min(), lat2D_curv.max(), 100)
newlon1D_points=np.linspace(lon2D_curv.min(), lon2D_curv.max(), 100)

output = triple_to_grid(data, x_in, y_in, x_out, y_out)

Example Usage#

import skyborn as skb
import xarray as xr

# Load data
data = xr.open_dataset('input_data.nc')

# Create regridder
regridder = skb.interp.ConservativeRegridder(
    source_grid=data,
    target_grid=target_grid
)

# Regrid data
regridded_data = regridder.regrid_array(data['temperature'])

# Convert gridded data to triples (x, y, value) and back to a rectilinear grid
from skyborn.interp import grid_to_triple, triple_to_grid
triples = grid_to_triple(data['temperature'], data['lon'], data['lat'])
# Define target 1D coordinates
x_out = xr.DataArray(np.linspace(float(data['lon'].min()), float(data['lon'].max()), 100), dims=('x',))
y_out = xr.DataArray(np.linspace(float(data['lat'].min()), float(data['lat'].max()), 80), dims=('y',))
gridded = triple_to_grid(triples[2], triples[0], triples[1], x_out, y_out, method=1, domain=1.0)