match_coord {epwshiftr}

Match coordinates of input EPW in the CMIP6 output file database

Description

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.

Usage

match_coord(epw, threshold = list(lon = 1, lat = 1), max_num = NULL)

Arguments

epw

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

threshold

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)

max_num

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.

Details

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.

Value

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

Geographical distance calculation

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

Examples

## Not run: 
# 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))

## End(Not run)