diff --git a/NEWS.md b/NEWS.md index de88af4..d4e9acd 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,6 +2,8 @@ * Added `table_initializeExisting()` for fast conversion of an existing table of spatial metadata into a standardized "known location" table. +* Added `table_findOverlappingLocations()` to help choose an appropriate radius +when initializing frorm an existing metadata table. * Added `addressService` argument to `table_addLocation()`, `table_addSingleLocation() and `location_initialize()` to skip the address step that requires web services. diff --git a/docs/articles/MazamaLocationUtils.html b/docs/articles/MazamaLocationUtils.html index ecdad50..451b22e 100644 --- a/docs/articles/MazamaLocationUtils.html +++ b/docs/articles/MazamaLocationUtils.html @@ -213,7 +213,9 @@

latitude = lats, radius = 50 ) %>% dplyr::pull(city) -
##  [1] NA NA NA NA NA NA NA NA NA NA NA NA NA
+
##  [1] "Chelan"    NA          NA          NA          NA          "Wellpinit"
+##  [7] NA          NA          NA          NA          NA          NA         
+## [13] NA
# Any known locations within 500 meters
 table_getNearestLocation(
   wa_monitors_500,
@@ -221,10 +223,11 @@ 

   latitude = lats,
   radius = 500
 ) %>% dplyr::pull(city)
-
##  [1] NA                 NA                 NA                 "Sunnyside"       
-##  [5] "Inchelium"        "Wellpinit"        "Lake Forest Park" "Okanogan County" 
-##  [9] NA                 "Okanogan County"  "Ritzville"        "Darrington"      
-## [13] "Tukwila"
+
##  [1] "Chelan"             "La Crosse"          NA                  
+##  [4] NA                   "Inchelium"          "Wellpinit"         
+##  [7] NA                   NA                   "Limestone Junction"
+## [10] NA                   NA                   NA                  
+## [13] NA
# How about 5000 meters?
 table_getNearestLocation(
   wa_monitors_500,
diff --git a/docs/news/index.html b/docs/news/index.html
index 71c48f0..1baa3f2 100644
--- a/docs/news/index.html
+++ b/docs/news/index.html
@@ -119,6 +119,7 @@ 

 

 
    
 
  • Added table_initializeExisting() for fast conversion of an existing table of spatial metadata into a standardized “known location” table.
    • 
+
  • Added table_findOverlappingLocations() to help choose an appropriate radius when initializing frorm an existing metadata table.
    • 
 
  • Added addressService argument to table_addLocation(), table_addSingleLocation() andlocation_initialize()` to skip the address step that requires web services.
    •
diff --git a/docs/reference/index.html b/docs/reference/index.html index 6da0503..66d31eb 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -255,6 +255,12 @@

table_findOverlappingLocations()

+ +

Finds overlapping locations in a known locations table.

+ +

table_getLocationID()

diff --git a/docs/reference/location_initialize.html b/docs/reference/location_initialize.html index 59737c2..f110135 100644 --- a/docs/reference/location_initialize.html +++ b/docs/reference/location_initialize.html @@ -156,6 +156,7 @@

Create known location record with core metadata

longitude = NULL, latitude = NULL, stateDataset = "NaturalEarthAdm1", + elevationService = NULL, addressService = NULL, verbose = TRUE ) @@ -175,10 +176,15 @@

Arg stateDataset

Name of spatial dataset to use for determining state

+ + elevationService +

Name of the elevation service to use for determining +the elevation. Default: NULL. Accepted values: "usgs".

+ addressService

Name of the address service to use for determining -the street address. Default: NA. Accepted values: "photon".

+the street address. Default: NULL Accepted values: "photon".

verbose diff --git a/docs/reference/table_addLocation.html b/docs/reference/table_addLocation.html index d6431fa..d5bcd29 100644 --- a/docs/reference/table_addLocation.html +++ b/docs/reference/table_addLocation.html @@ -132,6 +132,7 @@

Add new known location records to a table

latitude = NULL, radius = NULL, stateDataset = "NaturalEarthAdm1", + elevationService = NULL, addressService = NULL, verbose = TRUE ) @@ -159,11 +160,16 @@

Arg stateDataset

Name of spatial dataset to use for determining state codes, Default: 'NaturalEarthAdm1'

+ + + elevationService +

Name of the elevation service to use for determining +the elevation. Default: NULL. Accepted values: "usgs".

addressService

Name of the address service to use for determining -the street address. Default: NA. Accepted values: "photon".

+the street address. Default: NULL. Accepted values: "photon".

verbose diff --git a/docs/reference/table_addSingleLocation.html b/docs/reference/table_addSingleLocation.html index 32c2d36..a1b4bb9 100644 --- a/docs/reference/table_addSingleLocation.html +++ b/docs/reference/table_addSingleLocation.html @@ -132,6 +132,7 @@

Add a single new known location record to a table

latitude = NULL, radius = NULL, stateDataset = "NaturalEarthAdm1", + elevationService = NULL, addressService = NULL, verbose = TRUE ) @@ -159,11 +160,16 @@

Arg stateDataset

Name of spatial dataset to use for determining state codes, Default: 'NaturalEarthAdm1'

+ + + elevationService +

Name of the elevation service to use for determining +the elevation. Default: NULL. Accepted values: "usgs".

addressService

Name of the address service to use for determining -the street address. Default: NA. Accepted values: "photon".

+the street address. Default: NULL. Accepted values: "photon".

verbose diff --git a/docs/reference/table_findOverlappingLocations.html b/docs/reference/table_findOverlappingLocations.html new file mode 100644 index 0000000..240bf88 --- /dev/null +++ b/docs/reference/table_findOverlappingLocations.html @@ -0,0 +1,223 @@ + + + + + + + + +Finds overlapping locations in a known locations table. — table_findOverlappingLocations • MazamaLocationUtils + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+ + + + +
+ +
+
+
+

Finds overlapping locations in a known locations table.

+ Source: R/table_findOverlappingLocations.R + +
+ +
+

Calculates distances between all locations within a known +locations table and returns a tibble with the row indices and separation +distances of those records with overlapping locations.

+

It is useful when working with new metadata tables to identify overlapping +locations early on so that decisions can be made about the apporpriateness +of the specified radius.

+
+ + 
table_findOverlappingLocations(tbl = NULL, radius = NULL)
+ +

Arguments

+ + + + + + + + + + +
tbl

Tibble with longitude and latitude columns.

radius

Radius in meters.

+ +

Value

+ +

Tibble of row indices and distances for those locations which overlap.

+ +

Examples

+ 
library(MazamaLocationUtils)
+
+meta <- wa_airfire_meta
+
+# Anything locations closer than 2 km? (diameter = 2*radius)
+table_findOverlappingLocations(meta, radius = 1000)
#> # A tibble: 0 x 3
+#> # … with 3 variables: row1 <dbl>, row2 <dbl>, distance <dbl>

+# How about 4 km?
+table_findOverlappingLocations(meta, radius = 2000)
#> # A tibble: 3 x 3
+#>    row1  row2 distance
+#>   <int> <int>    <dbl>
+#> 1     2    34    2500.
+#> 2    12    34    3328.
+#> 3     2     9    3762.

+# Let's look at those locations
+
+tooCloseTbl <- table_findOverlappingLocations(meta, radius = 2000)
+
+for ( i in seq_len(nrow(tooCloseTbl)) ) {
+  rows <- as.numeric(tooCloseTbl[i, 1:2])
+  cat(sprintf("\n%5.1f meters apart:\n", tooCloseTbl$distance[i]))
+  print(meta[rows, c('longitude', 'latitude', 'siteName')])
+}
#> 
+#> 2500.2 meters apart:
+#>              longitude latitude            siteName
+#> 530330057_01 -122.3405 47.56200    Seattle-Duwamish
+#> 530330080_01 -122.3086 47.56824 Seattle-Beacon Hill
+#> 
+#> 3328.1 meters apart:
+#>              longitude latitude              siteName
+#> 530330030_01 -122.3197 47.59722 Seattle-10th & Weller
+#> 530330080_01 -122.3086 47.56824   Seattle-Beacon Hill
+#> 
+#> 3761.7 meters apart:
+#>              longitude latitude           siteName
+#> 530330057_01 -122.3405  47.5620   Seattle-Duwamish
+#> 530331011_01 -122.3208  47.5309 Seattle-South Park

+
+
+
+ +
+ + + +
+ + + + + + + + diff --git a/docs/reference/table_initializeExisting.html b/docs/reference/table_initializeExisting.html index bb48752..971da9e 100644 --- a/docs/reference/table_initializeExisting.html +++ b/docs/reference/table_initializeExisting.html @@ -182,6 +182,7 @@

Converts an existing table into a known location table

tbl = NULL, stateDataset = "NaturalEarthAdm1", countryCodes = NULL, + radius = NULL, verbose = TRUE ) @@ -203,6 +204,10 @@

Arg

Vector of country codes used to optimize spatial searching. (See ?MazamaSpatialUtils::getStateCode())

+ + radius +

Radius in meters, Default: NULL

+ verbose

Logical controlling the generation of progress messages.

@@ -211,7 +216,15 @@

Arg

Value

-

Known location tibble with the specified metadata columns.

+

Known location tibble with the specified metadata columns. Any +locations whose circles (as defined by radius) overlap will generate +warning messages.

+

It is incumbent upon the user to address these issue by one of:

+
    +

  1. reduce the radius until no overlaps occur

    2. +

  2. assign one of the overlapping locations to the other location

    3. +
+