rcaiman (version 2.0.1)

rem_outliers: Remove statistical outliers in sky points

Description

Remove sky points considered outliers relative to their local neighbors in a user-specified variable.

Usage

rem_outliers(
  sky_points,
  r,
  z,
  a,
  k = 20,
  angular_radius = 20,
  laxity = 2,
  cutoff_side = "both",
  use_window = TRUE,
  trend = NULL
)

Value

The retained points represented as a data.frame with columns row

and col, same as sky_points.

Arguments

sky_points

data.frame with columns row and col (raster coordinates).

r

terra::SpatRaster. Image from which sky_points were sampled (or any raster with identical dimensions).

z

terra::SpatRaster generated with zenith_image().

a

terra::SpatRaster generated with azimuth_image().

k

numeric vector of length one. Number of neighbors.

angular_radius

numeric vector of length one. The maximum radius for searching k-nearest neighbors (KNN) in degrees.

laxity

numeric vector of length one.

cutoff_side

character vector of length one. Options are "both" (default), "upper" or "lower". Controls which side(s) of the inequality are evaluated to detect outliers. See Details.

use_window

logical of length one. If TRUE (default), use a \(3 \times 3\) local mean around each point; if FALSE, use only the central pixel.

trend

numeric vector of length one or NULL. Zero to three. Specifies the order of the polynomial surface fitted to the neighbors to account for spatial trends. Use NULL (default) to skip detrending.

Details

Based on the Statistical Outlier Removal (SOR) filter from the PCL library. Distances are computed on a spherical surface. The number of neighbors is controlled by k, and angular_radius sets the maximum search radius (deg). If fewer than k neighbors are found within that radius, the point is retained due to insufficient evidence for removal. The decision criterion follows Leys2013;textualrcaiman:

\(M - laxity \times MAD < x_i < M + laxity \times MAD\)

where \(x_i\) is the value from r at sky point i, \(M\) and \(MAD\) are the median and median absolute deviation, respectively, computed from the the neighbors of \(x_i\), and \(laxity\) is the user-defined threshold.

cutoff_side controls which side(s) of the inequality are evaluated: "both" (default), "left" (left tail only), or "right" (right tail only).

References

Examples

if (FALSE) {
caim <- read_caim()
r <- caim$Blue
z <- zenith_image(ncol(caim), lens())
a <- azimuth_image(z)
m <- !is.na(z)
bin <- binarize_by_region(r, ring_segmentation(z, 30),
                          method = "thr_isodata")
bin <- bin & select_sky_region(z, 0, 80)
g <- sky_grid_segmentation(z, a, 5, first_ring_different = TRUE)
sky_points <- extract_sky_points(r, bin, g,
                                 dist_to_black = 3)
plot(r)
points(sky_points$col, nrow(caim) - sky_points$row, col = 2, pch = 10)

sky_points <- rem_outliers(sky_points, r, z, a,
                                 k = 5,
                                 angular_radius = 20,
                                 laxity = 2,
                                 cutoff_side = "left")
points(sky_points$col, nrow(caim) - sky_points$row, col = 3, pch = 0)
}