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 (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 “quantile”: 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 42.9098292 -48.546942
#> 2 b 15.0041098 -35.774224
#> 3 c -5.4608398 39.684002
#> 4 d 95.1461710 -42.947025
#> 5 e 165.9696972 -70.614657
#> 6 f -82.5895680 -42.763912
#> 7 g 83.0160795 -56.392887
#> 8 h -131.7004034 7.639502
#> 9 i -162.5766380 -78.206675
#> 10 j 73.2985453 68.469325
#> 11 a -127.0030341 -39.741743
#> 12 b 96.8959199 31.086661
#> 13 c -116.5139604 -79.176443
#> 14 d -140.1267602 87.927399
#> 15 e 157.8032670 -39.190422
#> 16 f 124.7296105 9.740226
#> 17 g 25.6116894 70.215121
#> 18 h 64.4736263 -85.895630
#> 19 i -147.8439923 31.983922
#> 20 j 102.7346850 -29.329237
#> 21 a -98.2953187 -64.584703
#> 22 b -18.6557526 -26.538482
#> 23 c -121.9580506 -17.739926
#> 24 d -116.5997917 70.004583
#> 25 e -108.6378755 -33.729446
#> 26 f -51.2599270 -78.902153
#> 27 g -114.7200466 32.307528
#> 28 h 22.0121495 -21.930738
#> 29 i 57.2698835 15.906663
#> 30 j 57.6912273 -1.443864
#> 31 a -179.1357165 -38.560150
#> 32 b 177.6405723 -88.484473
#> 33 c 45.8961231 9.139373
#> 34 d -174.7330791 56.381563
#> 35 e -106.1358417 25.843425
#> 36 f 58.7075991 -77.568839
#> 37 g -13.0521491 41.168929
#> 38 h -50.2746632 30.980016
#> 39 i 68.1719009 57.564178
#> 40 j -86.8101162 74.631880
#> 41 a 126.4338116 34.194723
#> 42 b -7.1983112 -1.443996
#> 43 c 13.4159005 26.447157
#> 44 d 58.1903631 -7.827308
#> 45 e -71.6923763 -67.419608
#> 46 f -85.1394544 18.785695
#> 47 g -70.1833933 58.828812
#> 48 h 134.9849756 21.488085
#> 49 i 78.6373981 61.389668
#> 50 j -33.5089101 -13.095611
#> 51 a -173.0305897 48.471607
#> 52 b -161.9350708 38.185342
#> 53 c 72.8103715 -78.593902
#> 54 d -156.1067030 -13.319058
#> 55 e -166.9923474 -74.110024
#> 56 f -172.7446695 -52.502973
#> 57 g -45.7988051 -48.913043
#> 58 h -98.7604546 -80.920414
#> 59 i -2.9094840 11.127825
#> 60 j -19.2077436 34.964306
#> 61 a 68.4737637 -48.970322
#> 62 b 123.3863927 82.856449
#> 63 c -44.6998798 -1.289306
#> 64 d 174.5602878 40.177563
#> 65 e 162.8734787 -1.554645
#> 66 f 176.3634633 62.163915
#> 67 g -20.4737924 -85.480261
#> 68 h -124.6450134 8.712044
#> 69 i 160.1018361 81.981867
#> 70 j 7.0079089 -64.709664
#> 71 a -15.9715425 37.849252
#> 72 b -100.7675281 -67.247660
#> 73 c -129.8943416 60.418130
#> 74 d -102.1831628 -36.327689
#> 75 e -33.9556777 -21.360825
#> 76 f -95.8555471 -45.387120
#> 77 g -170.9761105 -27.903303
#> 78 h 90.8431053 -14.438983
#> 79 i 83.5461156 28.639798
#> 80 j -32.7215611 81.712269
#> 81 a 47.1088100 -5.419142
#> 82 b -156.4398061 -62.888203
#> 83 c -126.4708254 72.454112
#> 84 d -79.3073646 -11.155374
#> 85 e 126.2364513 55.216005
#> 86 f -172.2453191 -3.330816
#> 87 g -88.9812432 -43.553122
#> 88 h 56.4161404 -59.375554
#> 89 i 104.0937875 -61.090076
#> 90 j 75.1844331 29.050274
#> 91 a -156.7465229 -5.660618
#> 92 b 4.0720838 8.170711
#> 93 c -107.6657941 40.517686
#> 94 d 113.0816133 4.586857
#> 95 e 55.3608273 21.408560
#> 96 f -52.8292865 -57.787036
#> 97 g 34.7741625 48.189821
#> 98 h 81.9735744 56.933094
#> 99 i 178.4046741 -54.975172
#> 100 j -0.7001022 -51.747463
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 94 records.
#> [1] FALSE FALSE FALSE FALSE TRUE FALSE FALSE TRUE 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 TRUE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
#> [49] TRUE FALSE FALSE FALSE FALSE FALSE TRUE FALSE FALSE FALSE FALSE FALSE
#> [61] FALSE FALSE FALSE FALSE FALSE FALSE FALSE TRUE FALSE FALSE FALSE FALSE
#> [73] FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
#> [85] FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE FALSE
#> [97] FALSE FALSE FALSE FALSE