Removes out or flags records that are outliers in geographic space according to the method
defined via the method argument. Geographic outliers often represent
erroneous coordinates, for example due to data entry errors, imprecise
geo-references, individuals in horticulture/captivity.
Usage
cc_outl(
x,
lon = "decimallongitude",
lat = "decimallatitude",
species = "species",
method = "quantile",
mltpl = 5,
tdi = 1000,
value = "clean",
sampling_thresh = 0,
verbose = TRUE,
min_occs = 7,
thinning = FALSE,
thinning_res = 0.5
)Arguments
- x
data.frame. Containing geographical coordinates and species names.
- lon
character string. The column with the longitude coordinates. Default = “decimallongitude”.
- lat
character string. The column with the latitude coordinates. Default = “decimallatitude”.
- species
character string. The column with the species name. Default = “species”.
- method
character string. Defining the method for outlier selection. See details. One of “distance”, “quantile”, “mad”. Default = “quantile”.
- mltpl
numeric. The multiplier of the interquartile range (
method == 'quantile') or median absolute deviation (method == 'mad')to identify outliers. See details. Default = 5.- tdi
numeric. The minimum absolute distance (
method == 'distance') of a record to all other records of a species to be identified as outlier, in km. See details. Default = 1000.- value
character string. Defining the output value. See value.
- sampling_thresh
numeric. Cut off threshold for the sampling correction. Indicates the quantile of sampling in which outliers should be ignored. For instance, if
sampling_thresh== 0.25, records in the 25 not be flagged as outliers. Default = 0 (no sampling correction).- verbose
logical. If TRUE reports the name of the test and the number of records flagged.
- min_occs
Minimum number of geographically unique datapoints needed for a species to be tested. This is necessary for reliable outlier estimation. Species with fewer than min_occs records will not be tested and the output value will be 'TRUE'. Default is to 7. If
method == 'distance', consider a lower threshold.- thinning
forces a raster approximation for the distance calculation. This is routinely used for species with more than 10,000 records for computational reasons, but can be enforced for smaller datasets, which is recommended when sampling is very uneven.
- thinning_res
The resolution for the spatial thinning in decimal degrees. Default = 0.5.
Value
Depending on the ‘value’ argument, either a data.frame
containing the records considered correct by the test (“clean”) or a logical vector (“flagged”), with TRUE = test passed and FALSE = test failed/potentially problematic . Default = “clean”.
Details
The method for outlier identification depends on the method argument.
If “outlier”: a boxplot method is used and records are flagged as
outliers if their mean distance to all other records of the same
species is larger than mltpl * the interquartile range of the mean distance
of all records of this species. If “mad”: the median absolute
deviation is used. In this case a record is flagged as outlier, if the
mean distance to all other records of the same species is larger than
the median of the mean distance of all points plus/minus the mad of the mean
distances of all records of the species * mltpl. If “distance”:
records are flagged as outliers, if the minimum distance to the next
record of the species is > tdi. For species with records from > 10000
unique locations a random sample of 1000 records is used for
the distance matrix calculation. The test skips species with fewer than min_occs,
geographically unique records.
The likelihood of occurrence records being erroneous outliers is linked to the sampling effort in any given location. To account for this, the sampling_cor option fetches the number of occurrence records available from www.gbif.org, per country as a proxy of sampling effort. The outlier test (the mean distance) for each records is than weighted by the log transformed number of records per square kilometre in this country. See for https://besjournals.onlinelibrary.wiley.com/doi/full/10.1111/2041-210X.13152 an example and further explanation of the outlier test.
Note
See https://ropensci.github.io/CoordinateCleaner/ for more details and tutorials.
Examples
x <- data.frame(species = letters[1:10],
decimallongitude = runif(100, -180, 180),
decimallatitude = runif(100, -90,90))
cc_outl(x)
#> Testing geographic outliers
#> Removed 0 records.
#> species decimallongitude decimallatitude
#> 1 a -87.407862 -36.713884
#> 2 b -155.587914 44.513173
#> 3 c -36.652208 86.716247
#> 4 d 164.612983 -23.968896
#> 5 e -147.523974 -50.763917
#> 6 f 136.839823 -50.715290
#> 7 g 16.269704 -82.192640
#> 8 h -48.390515 21.728698
#> 9 i -177.532386 -42.546705
#> 10 j -148.280092 -40.333333
#> 11 a 142.585470 -67.576278
#> 12 b -65.612254 69.833100
#> 13 c 158.476841 -51.710305
#> 14 d -68.131455 48.425544
#> 15 e -174.337536 28.660911
#> 16 f -49.056956 -16.814006
#> 17 g -77.766152 -25.884368
#> 18 h 162.518062 29.454416
#> 19 i 173.528997 20.272774
#> 20 j -53.351441 5.777590
#> 21 a 103.808701 -47.901447
#> 22 b -171.105852 -63.319709
#> 23 c 52.033926 -33.507519
#> 24 d -40.762746 -6.930392
#> 25 e -10.173972 50.901966
#> 26 f -106.931763 -33.119829
#> 27 g 119.329632 31.148209
#> 28 h 29.996639 89.020909
#> 29 i 146.017661 -3.687713
#> 30 j 120.878918 -46.888357
#> 31 a -14.999815 71.968294
#> 32 b 25.878644 -42.604127
#> 33 c 170.842693 37.070038
#> 34 d 156.677683 -38.153296
#> 35 e -69.314226 -21.191386
#> 36 f 67.262937 8.151315
#> 37 g -94.353850 -6.720805
#> 38 h 111.262269 -48.710282
#> 39 i 57.221787 20.068861
#> 40 j 68.237536 -87.079752
#> 41 a -71.871749 36.160388
#> 42 b 98.933072 34.123346
#> 43 c 77.532220 -47.735925
#> 44 d 125.696092 -67.147252
#> 45 e -145.812823 28.425241
#> 46 f -93.606062 -53.906347
#> 47 g -82.985870 4.419120
#> 48 h -41.277291 80.330436
#> 49 i -43.536914 -48.887050
#> 50 j -17.978858 84.290884
#> 51 a 165.940428 37.902116
#> 52 b 99.707370 43.632996
#> 53 c -117.107720 38.909567
#> 54 d -101.994700 67.770435
#> 55 e 23.355434 18.630251
#> 56 f -46.464742 -65.966103
#> 57 g 145.895680 69.195080
#> 58 h -49.692696 78.366364
#> 59 i -67.479733 -48.241918
#> 60 j -41.835389 41.302893
#> 61 a -26.203778 -48.638077
#> 62 b -98.216526 -62.493131
#> 63 c -59.440694 -41.785465
#> 64 d -99.246206 -20.329263
#> 65 e -62.781823 89.716023
#> 66 f 157.140853 -77.975497
#> 67 g -76.161404 22.171943
#> 68 h -86.669290 -40.270749
#> 69 i -148.093733 47.703233
#> 70 j 41.386105 53.162070
#> 71 a -73.845213 -74.115801
#> 72 b -123.933291 -80.459925
#> 73 c 72.099551 75.523175
#> 74 d -108.173817 85.762885
#> 75 e 108.923092 66.762459
#> 76 f -130.790167 3.836314
#> 77 g 103.680859 77.100332
#> 78 h -129.841453 -28.545053
#> 79 i 4.046163 42.888928
#> 80 j 154.247977 -45.401568
#> 81 a 113.057824 -68.141027
#> 82 b -112.373360 41.330494
#> 83 c 69.038851 6.063339
#> 84 d -56.216490 -89.107026
#> 85 e -116.505858 19.607741
#> 86 f 7.691193 -85.762648
#> 87 g 15.507339 -56.727331
#> 88 h -10.681759 -74.453374
#> 89 i 76.996377 48.868731
#> 90 j -92.176833 27.510738
#> 91 a -92.081271 -47.447226
#> 92 b 105.530247 -80.904021
#> 93 c -43.506961 -1.589615
#> 94 d -81.166091 89.910818
#> 95 e 137.517209 -3.177786
#> 96 f -110.217443 -14.814367
#> 97 g 56.348358 -73.511428
#> 98 h 69.549146 -50.029731
#> 99 i 29.191610 -37.203041
#> 100 j -29.783253 56.719528
cc_outl(x, method = "quantile", value = "flagged")
#> Testing geographic outliers
#> Flagged 0 records.
#> [1] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [16] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [31] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [46] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [61] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [76] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [91] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
cc_outl(x, method = "distance", value = "flagged", tdi = 10000)
#> Testing geographic outliers
#> Flagged 0 records.
#> [1] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [16] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [31] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [46] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [61] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [76] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
#> [91] TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE
cc_outl(x, method = "distance", value = "flagged", tdi = 1000)
#> Testing geographic outliers
#> Flagged 96 records.
#> [1] FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
#> [13] FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
#> [25] FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
#> [37] FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE TRUE
#> [49] FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE TRUE FALSE FALSE
#> [61] FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
#> [73] FALSE TRUE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
#> [85] FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE TRUE FALSE FALSE
#> [97] FALSE FALSE FALSE FALSE