match_coord() takes an EPW and uses its longitude and latitude to calculate
the distance between the EPW location and the global grid points in NetCDF
files.
match_coord(epw, threshold = list(lon = 1, lat = 1), max_num = NULL)Possible values:
A file path of EPW file
An eplusr::Epw object
A regular expression used to search locations in EnergyPlus Weather
Database, e.g. "los angeles.*tmy3". You will be asked to select a matched
EPW to download and read. It will be saved into tempdir(). Note that the
search is case-insensitive
A list of 2 elements lon and lat specifying the
absolute distance threshold used for subsetting longitude and
latitude value for calculating distances. If NULL, no subsetting is
performed and the distances between the target location and all grid
points are calculated. This is useful set the threshold value to
exclude some points that are absolute too far away from the target
location. Default: list(lon = 1.0, lat = 1.0)
The maximum number of grid points to be matched. Default is
NULL, which means no number limit and the total matched grid points
are determined by the threshold input.
An epw_cmip6_coord object, which is basically a list of 3 elements:
epw: An eplusr::Epw object parsed from input epw argument
meta: A list containing basic meta data of input EPW, including city,
state_province, country, latitute and longitude.
coord: A data.table::data.table() which is basically CMIP6 index
database with an appending new list column coord that contains
matched latitudes and longitudes in each NetCDF file. Each element
in coord is a data.table::data.table() of 6 columns describing
the matched coordinates.
index: the indices of matched coordinates
ind_lon, ind_lat: The value indices of longitude or latitude in the
NetCDF coordinate grids. These values are used to extract the
corresponding variable values
lon, lat: the actual longitude or latitude in the NetCDF coordinate
grids
dist: the distance in km between the coordinate values in NetCDF and
input EPW
match_coord() uses future.apply
underneath. You can use your preferable future backend to
speed up data extraction in parallel. By default, match_coord() uses
future::sequential backend, which runs things in sequential.
match_coord() calculates the geographical distances based formulas of
spherical trigonometry:
$$ \Delta{X}=\cos(\phi_2)\cos(\lambda_2) - \cos(\phi_1)\cos(\lambda_1) $$
$$ \Delta{Y}=\cos(\phi_2)\sin(\lambda_2) - \cos(\phi_1)\sin(\lambda_1) $$
$$ \Delta{Z}=\sin(\phi_2) - \sin(\phi_1) $$
$$ C_h=\sqrt{(\Delta{X})^2 + (\Delta{Y})^2 + (\Delta{Z})^2} $$
where \(phi\) is the latitude and \(lambda\) is the longitude. This formula treats the Earth as a sphere. The geographical distance between points on the surface of a spherical Earth is \(D = RC_h\).
For more details, please see this Wikipedia
if (FALSE) {
# download an EPW from EnergyPlus website
epw <- eplusr::download_weather("los angeles.*TMY3", dir = tempdir(),
type = "EPW", ask = FALSE)
match_coord(epw, threshold = list(lon = 1.0, lat = 1.0))
}