- x
data frame; observations to sample, including at least the columns
defining the location in space and time. Additional columns can be included
such as features that will later be used in model training.
- coords
character; names of the spatial and temporal coordinates. By
default the spatial spatial coordinates should be longitude and
latitude, and temporal coordinate should be day_of_year.
- is_lonlat
logical; if the points are in unprojected, lon-lat
coordinates. In this case, the points will be projected to an equal area
Eckert IV CRS prior to grid assignment.
- res
numeric; resolution of the spatiotemporal grid in the x, y, and
time dimensions. Unprojected locations are projected to an equal area
coordinate system prior to sampling, and resolution should therefore be
provided in units of meters. The temporal resolution should be in the
native units of the time coordinate in the input data frame, typically it
will be a number of days.
- jitter_grid
logical; whether to jitter the location of the origin of
the grid to introduce some randomness.
- sample_size_per_cell
integer; number of observations to sample from
each grid cell.
- cell_sample_prop
proportion (0-1]; if less than 1, only this
proportion of cells will be randomly selected for sampling.
- keep_cell_id
logical; whether to retain a unique cell identifier,
stored in column named .cell_id.
- grid_definition
list defining the spatiotemporal sampling grid as
returned by assign_to_grid() in the form of an attribute of the returned
data frame.
- unified_grid
logical; whether a single, unified spatiotemporal
sampling grid should be defined and used for all observations in x or a
different grid should be used for each stratum.
- by_year
logical; whether the sampling should be done stratified by
year (TRUE) or ignoring year (FALSE). If sampling by year is turned on, N
observations will be sampled from each grid cell for each year, while if it
is turned off, N observations will be sampled per grid cell across all
years. If using sampling by year, the input data frame x must have a
year column.
- case_control
logical; whether to apply case control sampling whereby
presence and absence are sampled independently.
- obs_column
character; if case_control = TRUE, this is the name of
the column in x that defines detection (obs_column > 0) and
non-detection (obs_column == 0).
- sample_by
character; additional columns in x to stratify sampling
by. For example, if a landscape has many small islands (defined by an
island variable) and we wish to sample from each independently, use
sample_by = "island".
- min_detection_probability
proportion [0-1); the minimum detection
probability in the final dataset. If case_control = TRUE, and the
proportion of detections in the grid sampled dataset is below this level,
then additional detections will be added via grid sampling the detections
from the input dataset until at least this proportion of detections appears
in the final dataset. This will typically result in duplication of some
observations in the final dataset. To turn this off this feature use
min_detection_probability = 0.
- maximum_ss
integer; the maximum sample size in the final dataset. If
the grid sampling yields more than this number of observations,
maximum_ss observations will be selected randomly from the full set. Note
that this subsampling will be performed in such a way that all levels of
each strata will have at least one observation within the final dataset,
and therefore it is not truly randomly sampling.
- jitter_columns
character; if detections are oversampled to achieve the
minimum detection probability, some observations will be duplicated, and it
can be desirable to slightly "jitter" the values of model training features
for these duplicated observations. This argument defines the column names
in x that will be jittered.
- jitter_sd
numeric; strength of the jittering in units of standard
deviations, see jitter_columns.
- cell_quantile_cap
proportion (0, 1] or NULL; if provided, limits
how many observations any single spatial grid cell can contribute to the
grid-sampled data, reducing the influence of chronically over-sampled sites
(e.g. bird feeders). For each observation class, the per-cell observation
count is capped at this quantile of the distribution of per-cell counts:
cells above the quantile are randomly reduced down to it, while cells at or
below it are left unchanged. Because the threshold is taken from the data
itself, it adapts to each dataset. Detections and non-detections are capped
independently by the same rule. NULL (the default) or a value of 1
applies no cap.
- ...
additional arguments defining the spatiotemporal grid; passed to
grid_sample().