Creates a Quadtree
from a
SpatRaster
,
RasterLayer
or a matrix.
# S4 method for ANY
quadtree(
x,
split_threshold = NULL,
split_method = "range",
split_fun = NULL,
split_args = list(),
split_if_any_na = TRUE,
split_if_all_na = FALSE,
combine_method = "mean",
combine_fun = NULL,
combine_args = list(),
max_cell_length = NULL,
min_cell_length = NULL,
adj_type = "expand",
resample_n_side = NULL,
resample_pad_nas = TRUE,
extent = NULL,
projection = "",
proj4string = NULL,
template_quadtree = NULL
)
a RasterLayer
,
SpatRaster
, or
matrix
. If x
is a matrix
, the extent
and
projection
parameters can be used to set the extent and projection
of the quadtree. If x
is a
RasterLayer
or
SpatRaster
, the extent and
projection are derived from the raster.
numeric; the threshold value used by the split method
(specified by split_method
) to decide whether to split a quadrant.
If the value for a quadrant is greater than this value, it is split into
its four child cells. If split_method
is "custom"
, this
parameter is ignored.
character; one of "range"
(the default),
"sd"
(standard deviation), "cv"
(coefficient of variation) or
"custom"
. Determines the method used for calculating the value used
to determine whether or not to split a quadrant (this calculated value is
compared with split_threshold
to decide whether to split a cell). If
"custom"
, a function must be supplied to split_fun
. See
'Details' for more.
function; function used on each quadrant to decide whether
or not to split the quadrant. Only used when split_method
is
"custom"
. Must take two arguments, vals
(a numeric vector of
the cell values in a quadrant) and args
(a named list of arguments
used within the function), and must output TRUE
if the quadrant is
to be split and FALSE
otherwise. It must be able to handle NA
values - if NA
is ever returned, an error will occur.
list; named list that contains the arguments needed by
split_fun
. This list is given to the args
parameter of
split_fun
.
boolean; if TRUE
(the default), a quadrant is
automatically split if any of the values within the quadrant are NA
.
boolean; if FALSE
(the default), a quadrant
that contains only NA
values is not split. If TRUE
, quadrants
that contain all NA
values are split to the smallest possible cell
size.
character; one of "mean"
, "median"
,
"min"
, "max"
, or "custom"
. Determines the method used
for aggregating the values of multiple cells into a single value for a
larger, aggregated cell. Default is "mean"
. If "custom"
, a
function must be supplied to combine_fun
.
function; function used to calculate the value of a
quadrant. Only used when combine_method
is "custom"
. Must
take two arguments, vals
(a numeric vector of the cell values in a
quadrant) and args
(a named list of arguments used within the
function), and must output a single numeric value, which will be used as
the cell value.
list; named list that contains the arguments needed by
combine_fun
. This list is given to the args
parameter of
combine_fun
.
numeric; the maximum side length allowed for a
quadtree cell. Any quadrants larger than max_cell_length
will
automatically be split. If NULL
(the default) no restrictions are
placed on the maximum cell length.
numeric; the minimum side length allowed for a
quadtree cell. A quadrant will not be split if its children would be
smaller than min_cell_length
. If NULL
(the default) no
restrictions are placed on the minimum cell length.
character; one of "expand"
(the default),
"resample"
, or "none"
. Specifies the method used to adjust
x
so that its dimensions are suitable for quadtree creation (i.e.
square and with the number of cells in each direction being a power of 2).
See 'Details' for more on the two methods of adjustment.
integer; if adj_type
is 'resample'
, this
number is used to determine the dimensions to resample the raster to.
boolean; only applicable if adj_type
is
'resample'
. If TRUE
(the default), NA
s are added to
the shorter side of the raster to make it square before resampling. This
ensures that the cells of the resulting quadtree will be square. If
FALSE
, no NA
s are added - the cells in the quadtree will not
be square.
Extent
object or else a
four-element numeric vector describing the extent of the data (in this
order: xmin, xmax, ymin, ymax). Only used when x
is a matrix - this
parameter is ignored if x
is a raster since the extent is derived
directly from the raster. If no value is provided and x
is a matrix,
the extent is assumed to be c(0,ncol(x),0,nrow(x))
.
character; string describing the projection of the
data. Only used when x
is a matrix - this parameter is ignored if
x
is a raster since the proj4ection of the raster is automatically
used. If no value is provided and x
is a matrix, the projection of
the quadtree is set to NA
.
deprecated. Use projection
instead.
Quadtree
; if provided, the new
quadtree will be created so that it has the exact same structure as the
template quadtree. Thus, no split function is used because the decision
about whether to split is pre-determined by the template quadtree. The
raster used to create the template quadtree should have the exact same
extent and dimensions as x
. If template_quadtree
is
non-NULL
, all split_
* parameters are disregarded, as are
max_cell_length
and min_cell_length
.
a Quadtree
The 'quadtree-creation' vignette contains detailed explanations and
examples for all of the various creation options - run
vignette("quadtree-creation", package = "quadtree")
to view the
vignette.
If adj_type
is "expand"
, NA
cells are added to the
raster in order to create an expanded raster whose dimensions are a power
of two. The smallest number that is a power of two but greater than the
larger dimension is used as the dimensions of the expanded raster. If
adj_type
is "resample"
, the raster is resampled to a raster
with resample_n_side
rows and columns. If resample_pad_nas
is
TRUE
, NA
rows or columns are are added to the shorter
dimension before resampling to make the raster square. This ensures that
the quadtree cells will be square (assuming the original raster cells were
square).
When split_method
is "range"
, the difference between the
maximum and minimum cell values in a quadrant is calculated - if this value
is greater than split_threshold
, the quadrant is split. When
split_method
is "sd"
, the standard deviation of the cell
values in a quadrant is calculated - if this value is greater than
split_threshold
, the quadrant is split.
####### NOTE #######
# see the "quadtree-creation" vignette for more details and examples of all
# the different parameter options:
# vignette("quadtree-creation", package = "quadtree")
####################
library(quadtree)
habitat <- terra::rast(system.file("extdata", "habitat.tif", package="quadtree"))
qt <- quadtree(habitat, .15)
plot(qt)
# we can make it look nicer by customizing the plotting parameters
plot(qt, crop = TRUE, na_col = NULL, border_lwd = .3)
# try a different splitting method
qt <- quadtree(habitat, .05, "sd")
plot(qt)
# ---- using a custom split function ----
# split a cell if any of the values are below a given value
split_fun = function(vals, args) {
if (any(is.na(vals))) { # check for NAs first
return(TRUE) # if there are any NAs we'll split automatically
} else {
return(any(vals < args$threshold))
}
}
qt <- quadtree(habitat, split_method = "custom", split_fun = split_fun,
split_args = list(threshold = .8))
plot(qt)