[fix] Use spheroid formula for grid distance calculation

[hongyuanjia]

Pull request overview

• Fixes #39
• Fixes #29
• match_coord() has been refactored to correct the calculation method of geographical distance. Previously, epwshiftr assumes that distance on longitude and latitude is the same which is not true. Now it uses a spheroid formula to calculate the tunnel distance. For details, please see Tunnel Distance . The structure of the returned epw_cmip6_coord object has also changed. The coord column in the coord data.table is also a data.table which contains 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

Besides, the usage of the input threshold and max_num has been changed a little bit:

• threshold: Due to the change in distance calculation, the meaning of the threshold input has been changed. Instead of directly being used to get the 'closest' grid points in NetCDF, the longitude and latitude threshold is only used to help exclude grid points that are definitely too far away from the target location. The default threshold, which is 1 degree for both longitude and latitude, is still reasonable for common use cases and is kept unchanged. Also threshold now can be set to NULL. In this case, the distances between the target location and all grid points will be calculated. But this may be only useful for rare cases.

• max_num: Now the value max_num is the key input to control how many grid points are to be matched. The points will always be ordered in descending order in terms of the distances.

• The data in the returned value of extract_data() has been updated to include a new column dist which gives the spherical distance in km between EPW location and grid coordinates.

• The document on the return value structure for extract_data() and morphing_epw() has been fixed (#29). And the column order for all metadata in the returned data.table from extract_data() and morphing_epw() are not consistent. The columns will always be in the order below:

  • activity_drs
  • institution_id
  • source_id
  • experiment_id
  • member_id
  • table_id
  • lon
  • lat
  • dist

[codecov-commenter]

Codecov Report

Merging #45 (44fadff) into master (76ff383) will increase coverage by 0.00%. The diff coverage is 100.00%.

:exclamation: Current head 44fadff differs from pull request most recent head e940a4f. Consider uploading reports for the commit e940a4f to get more accurate results

@@           Coverage Diff           @@
##           master      #45   +/-   ##
=======================================
  Coverage   99.81%   99.81%           
=======================================
  Files           5        5           
  Lines        1063     1084   +21     
=======================================
+ Hits         1061     1082   +21     
  Misses          2        2           

Impacted Files	Coverage Δ
R/utils.R	100.00% <ø> (ø)
R/coord.R	100.00% <100.00%> (ø)
R/morph.R	100.00% <100.00%> (ø)
R/netcdf.R	99.33% <100.00%> (+<0.01%)	:arrow_up:

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 76ff383...e940a4f. Read the comment docs.