Core Functions for Custom Reporting

These functions load pre-processed data and calculate intactness and sector effects for custom regions and sets of species.

load_common_data(path=NULL, version=NULL)
is_loaded()
clear_common_data()
subset_common_data(id=NULL, species="all")
clear_subset_data()

load_species_data(species, boot=NULL, path=NULL, version=NULL)
calculate_results(y, level=0.9)
rasterize_results(y)

report_all(boot=NULL, path=NULL, version=NULL, level=0.9, cores=NULL)
flatten(x, ...)
# S3 method for c4iraw
flatten(x, raw_boot=FALSE, limit=NULL, ...)

custom_report(id=NULL, species="all",
    path=NULL, version=NULL, address=NULL,
    boot=NULL, level=0.9, cores=NULL,
    raw_boot=FALSE, limit=NULL)
custom_predict(species, xy, veg, soil,
    path=NULL, version=NULL, ...)

set_options(...)
overlay_polygon(ply)
get_all_id(mregion="both", nr=NULL, nsr=NULL, luf=NULL)
get_all_species(taxon = "all", mregion="both", habitat, status)
get_id_locations()
get_id_table(mregion="both", nr=NULL, nsr=NULL, luf=NULL)
get_species_table(taxon = "all", mregion="both", habitat, status)
get_version_info()
get_all_qsid()
qs2km(qsid)
make_subset_map()
get_subset_info()
get_subset_id()
get_subset_species()

dowload_data(dir, species="all", version=NULL, ...)

load_spclim_data(species, path=NULL, version=NULL)
get_levels()
# S3 method for c4ispclim
predict(object, xy, veg, soil,
    method="simple", ...)
predict_mat(object, ...)
# S3 method for c4ispclim
predict_mat(object, xy, veg, soil,
    method="simple",  ...)
combine_veg_soil(xy, veg, soil, method="simple")
make_multispecies_map(type=c("richness", "intactness"),
    path=NULL, version=NULL, clip=TRUE, limit=NULL,
    area="ha", pair_adj=2)

Arguments

path	path to a local copy of results or NULL (default, the value of getOption("cure4insect")$baseurl).
version	version of the results or NULL NULL (default, the value of getOption("cure4insect")$version).
id	character, IDs of the 1km x 1km spatial pixel units to be used for the custom summaries. The Row_Col field defines the IDs and links the raster cells in the geodatabase (http://sc-dev.abmi.ca/reports/2017/grids/Grid1km_working.gdb.zip) or CSV (http://sc-dev.abmi.ca/reports/2017/grids/Grid1km_working.csv.zip; with latitude/longitude in NAD_1983_10TM_AEP_Forest projection http://spatialreference.org/ref/epsg/3402/). If id is a matrix-like object, values of the 1st column are taken. id can be of class 'SpatialPolygons' defined by the 'sp' package. The supplied values are turned into character internally. Use get_all_id to see all possible values.
qsid	character, quarter section (QS) IDs in the "MER-RGE-TWP-SEC-QS" format, e.g. "4-12-1-2-SE". The CSV file http://sc-dev.abmi.ca/reports/2017/grids/Grid1km_working.csv.zip has the corresponding coordinates in NAD_1983_10TM_AEP_Forest projection http://spatialreference.org/ref/epsg/3402/).
species	A list of species defined by the field SpeciesID in the table http://sc-dev.abmi.ca/reports/2017/data/species-info.csv. If species is a matrix-like object, values of the 1st column are taken. The following values are also accepted to define groups of species: "all" (all groups/species), or one of the taxonomic ("birds", "lichens", "mammals", "mites", "mosses", "vplants") or other ("upland", "lowland", "native", "nonnative") groups. For a combination of filters, see get_all_species.
boot	logical or NULL, if confidence intervals for abundance and intactness are desired. Defaults to getOption("cure4insect")$boot when NULL.
level	numeric, level for confidence interval, defaults to 90%.
cores	integer, number of cores used in forking (used on Unix/Linux OS) or number of cluster workers (on Windows). Defaults to getOption("cure4insect")$cores when NULL.
y	and input object from call to load_species_data.
x	and input object from call to calculate_results.
raw_boot	logical, if raw bootstrap abundance results should be returned.
limit	numeric (0-1), species with mean abundance less than 100 * limit percent of the maximum abundance (current and reference combined) are flagged and should not be used when calculating multi-species metrics because the species is not effectively present in the region. Defaults to getOption("cure4insect")$limit when NULL.
address	character, optional email address to send finished results to in the format "name@domain.org". The default (NULL) is not to send an email.
object	and input object from call to load_spclim_data.
xy	a 'SpatialPoints' object defined by the 'sp' package with geographic coordinates corresponding to veg and soil (i.e. centroids of polygons).
veg, soil	factor, vegetation/soil classes. One of the two or both must be provided. Can be NULL or missing.
method	character, the method argument for raster value extraction. "simple": values for the cell a point falls in, "bilinear": interpolated from the values of the four nearest raster cells.
taxon	character, return "all" species, or a subset (one or more of "birds", "lichens", "mammals", "mites", "mosses", "vplants").
habitat	character, one of "upland" or "lowland" to indicate expert based habitat associations in Alberta.
status	character, one of "native" or "nonnative" to indicate expert based status in Alberta.
mregion	character, modeling region ("both", "north", or "south").
nr, nsr, luf	character vector, narural regions (nr), natural subregions (nsr), and land use framework regions (luf) of Alberta.
ply	an object of class 'SpatialPolygons' defined by the 'sp' package.
clip	logical, if the multi-species map needs to be clipped to the region bounds defined by the spatial subset.
type	character, the type of multi-species map to produce. "intactness" is the raster cell level average intactness across species, "richness" is probability of >0 observation in a 1 ha plot summed across species (expected species richness).
area, pair_adj	spatial scale ("ha" or "km") and pair adjustment factor to turn bird densities into probability of observing non-zero count before calculating richness (sum of these probabilities).
dir	Character, a directory name to download the data to.
...	Arguments in tag = value form, or a list of tagged values. The tags are configuration settings as described below. For the dowload_data function, these arguments are passed to download.file

Details

Configuration is stored in the file system.file("config/defaults.conf", package="cure4insect"). Current options are: path (path to results), version (version of results), verbose (default is 1, value 0 suppresses the messages), cores (number of cores to use in parallel calculations, uses forking on Linux/Unix/Mac and socket clusters on Windows, default is 1), limit (abundance threshold for regional intactness calculations), boot (bootstrap based uncertainties used or not), trunc (quantile for truncating rasterized maps to avoid outliers), sender (email of sender), subject (subject of the email), and body (body of the email).

The multicore processing performance (not on Windows, where shared memory forked processes are not available) might be limited by memory and network speed/bandwidth. Local copy of the data is the surest way to boost performance.

Value

load_common_data loads common data to memory of the R session. is_loaded check if common data has been loaded previously.

subset_common_data subsets the common data and makes the information available in the R session. make_subset_map makes a raster map of the spatial selection, get_subset_info counts the number of species and 1 square km spatial pixel units in the selection. get_subset_id and get_subset_species returns the species and spatial IDs, respectively, based on the selection.

load_species_data load data of a single species and returns it.

clear_common_data, and clear_subset_data clears the respective environments.

calculate_results calculates intactness and sector effects results based on spatial subset definitions and single species data. The output is a list of class 'c4iraw'. The flatten method arranges the results from calculate_results into a 1-liner data frame.

report_all calculate results based on sequential calls to load_species_data for all species defined in the subset. Returns a list (class 'c4ilist') output from calculate_results.

custom_report wrapper function to load common data, subset spatial units and species list, calculate results for all species, and optionally send results as attachment of a email. Returns an object of class 'c4idf' (inheriting from data frame), rows representing species (flattened results, the Comment field flagging possible issues).

overlay_polygon selects spatial IDs based on a 'SpatialPolygons' object.

rasterize_results takes the single species data without any spatial subset. The output is a raster stack object with the following layers: NC (current abundance), NR (reference abundance), SI (intactness), SI2 (two-sided intactness), SE, and CV (bootstrap based standard error and coefficient of variation estimates for current abundance).

make_multispecies_map calculated multi-species maps of richness (1-ha based probability of occurrence summed across species) or intactness (mean pixel level intactness of species whose mean abundance in the subset region is at least 100 * limit percent of the provincial maximum abundance).

set_options sets the options and return previous values invisibly. dowload_data downloads the data to the hard drive so that it can be used later. Set the path in the file system.file("config/defaults.conf", package="cure4insect") to have permanent effect, or in each session using set_options.

get_all_id gets all possible spatial IDs. get_all_species gets "all" possible species IDs, or a subset of those IDs for a selected taxon. get_id_locations gets the 'SpatialPoints' object with geographic coordinates of the spatial IDs, get_species_table gets the lookup table for species, or a group of species as defined by the taxon argument. get_all_qsid gets all possible quarter section (QS) IDs, qs2km finds the 1 square km units corresponding to the quarter section IDs. QS IDs are composed as "MER-RGE-TWP-SEC-QS" (Meridian [4-6], Range[1-30], Township[1-127], Section[1-36], and Quarter Section [NE, NW, SE, SW]), e.g. "4-12-1-2-SE". All these require to run load_common_data() first.

load_spclim_data is used to load raster data for spatially explicit predictions by predict.c4ispclim. predict.c4ispclim returns a data frame with columns 'veg', 'soil', and 'comb' (combines 'veg' and 'soil' using combine_veg_soil as a weighted average). Note: for some species, either the 'veg' or 'soil' based estimates are unavailable. predict.c4ispclim returns NA for these and the combined results will be NA as well.

get_version_info returns detailed version info for each taxa, depending on the version set through options or load_common_data, including the following variables: taxon, version (year of production), 1st and last year of field sampling (yr_first, yr_last), field methodology, base year and version of human footprint inventory (hf), version of the backfilled vegetation layer (veg), the type of model used (model), and the number of species by taxon. load_common_data prints these info upon successfully loading common data objects.

get_levels returns a list with elements 'veg' for vegetation and 'soil' for soil class levels expected by predict.c4ispclim. The predict_clim method is similar, but expects veg and soil to be a composition matrix with rows corresponding to points in space (e.g. grid cell centroids) and columns to correspond to vegetation/soil classes, with cell values as areas or proportions (row standardized). The return value is a list with elements veg and soil, each containing either a matrix with same dimensions as the corresponding input, or NULL when the input is missing.

See also

plot_sector and plot_abundance for plots.

Examples

if (FALSE) {
## workflow with 1 species --------------------
## ID is a vector of Row_Col IDs of 1km pixels
## species is a vector if species IDs
load_common_data()
is_loaded()
get_version_info() # important details about versions
## here is how to inspect all possible spatial and species IDs
str(get_all_id())
str(get_all_species())
plot(xy <- get_id_locations(), pch=".")
summary(xy)
str(get_species_table())
## define spatial and species IDs
Spp <- "Ovenbird"
ID <- c("182_362", "182_363", "182_364", "182_365", "182_366", "182_367",
    "182_368", "182_369", "182_370", "182_371", "182_372")
subset_common_data(id=ID, species=Spp)
y <- load_species_data("Ovenbird")
x <- calculate_results(y)
x
flatten(x)

## using quarter sections
Spp <- "Ovenbird"
QSID <- c("4-12-1-2-SE", "4-12-1-2-SW", "4-12-1-3-SE", "4-12-1-3-SW")
qs2km(QSID) # corresponding Row_Col IDs
subset_common_data(id=QSID, species=Spp)
y <- load_species_data(Spp)
flatten(calculate_results(y))

## using pre-defined planning/management regions
#ID <- get_all_id(nr=c("Boreal", "Foothills"))
ID <- get_all_id(luf="North Saskatchewan")
subset_common_data(id=ID)
plot(make_subset_map())

## workflow with multiple species ----------------
load_common_data() # use as before
## id and species can be defined using text files
Spp <- read.table(system.file("extdata/species.txt", package="cure4insect"))
ID <- read.table(system.file("extdata/pixels.txt", package="cure4insect"))
subset_common_data(id=ID, species=Spp)
xx <- report_all()
str(xx)
do.call(rbind, lapply(xx, flatten))

## ID can also be a SpatialPolygons object based on GeoJSON for example
#library(rgdal)
#dsn <- system.file("extdata/polygon.geojson", package="cure4insect")
#ply <- readOGR(dsn=dsn)
#subset_common_data(id=ply, species=Spp)
#xx2 <- report_all()

## wrapper function ----------------------
## species="all" runs all species
## species="mites" runs all mite species
## sender="you@example.org" will send an email with the results attached
## increase cores to allow parallel processing
z <- custom_report(id=ID,
    species=c("AlderFlycatcher", "Achillea.millefolium"),
    address=NULL, cores=1)
z

## making of the file raw_all.rda
opar <- set_options(path = "w:/reports")
getOption("cure4insect")
load_common_data()
SPP <- get_all_species()
subset_common_data(id=get_all_id(), species=SPP)
res <- list()
for (i in 1:length(SPP)) {
    cat("processing species:", SPP[i], i, "/", length(SPP), "\n")
    flush.console()
    y <- load_species_data(SPP[i])
    res[[i]] <- calculate_results(y)
}
names(res) <- SPP

## spatial maps
y <- load_species_data("Ovenbird")
r <- rasterize_results(y)
plot(r, "NC") # current abundance map
plot(r, "SE") # standadr errors for current abundance

## making multi-species richness and intactness maps for birds
subset_common_data(species=get_all_species(taxon="birds"))
r1 <- make_multispecies_map("richness")
r2 <- make_multispecies_map("intactness")
}

## working with a local copy of the results is much faster
## set path via function arguments or the options:
getOption("cure4insect")
#> $path
#> [1] "http://sc-dev.abmi.ca/reports"
#> 
#> $version
#> [1] "2018"
#> 
#> $verbose
#> [1] "1"
#> 
#> $cores
#> [1] "2"
#> 
#> $limit
#> [1] "0.01"
#> 
#> $boot
#> [1] "TRUE"
#> 
#> $trunc
#> [1] "0.99"
#> 
#> $sender
#> [1] "noreply@science.abmi.ca"
#> 
#> $subject
#> [1] "Custom Report for Intactness and Sector Effects"
#> 
#> $body
#> [1] "Hi,\\n\\nYour custom report results are attached.\\n\\nWith regards,\\n\\nthe ABMI Science Team"
#> 
(opar <- set_options())
#> $path
#> [1] "http://sc-dev.abmi.ca/reports"
#> 
#> $version
#> [1] "2018"
#> 
#> $verbose
#> [1] "1"
#> 
#> $cores
#> [1] "2"
#> 
#> $limit
#> [1] "0.01"
#> 
#> $boot
#> [1] "TRUE"
#> 
#> $trunc
#> [1] "0.99"
#> 
#> $sender
#> [1] "noreply@science.abmi.ca"
#> 
#> $subject
#> [1] "Custom Report for Intactness and Sector Effects"
#> 
#> $body
#> [1] "Hi,\\n\\nYour custom report results are attached.\\n\\nWith regards,\\n\\nthe ABMI Science Team"
#> 
set_options(path = "/your/path/to/local/copy")
(set_options(opar)) # reset options
#> $path
#> [1] "/your/path/to/local/copy"
#> 
#> $version
#> [1] "2018"
#> 
#> $verbose
#> [1] "1"
#> 
#> $cores
#> [1] "2"
#> 
#> $limit
#> [1] "0.01"
#> 
#> $boot
#> [1] "TRUE"
#> 
#> $trunc
#> [1] "0.99"
#> 
#> $sender
#> [1] "noreply@science.abmi.ca"
#> 
#> $subject
#> [1] "Custom Report for Intactness and Sector Effects"
#> 
#> $body
#> [1] "Hi,\\n\\nYour custom report results are attached.\\n\\nWith regards,\\n\\nthe ABMI Science Team"
#> 

## change configs in this file to make it permanent for a given installation
as.list(drop(read.dcf(file=system.file("config/defaults.conf",
package="cure4insect"))))
#> $path
#> [1] "http://sc-dev.abmi.ca/reports"
#> 
#> $version
#> [1] "2018"
#> 
#> $verbose
#> [1] "1"
#> 
#> $cores
#> [1] "2"
#> 
#> $limit
#> [1] "0.01"
#> 
#> $boot
#> [1] "TRUE"
#> 
#> $trunc
#> [1] "0.99"
#> 
#> $sender
#> [1] "noreply@science.abmi.ca"
#> 
#> $subject
#> [1] "Custom Report for Intactness and Sector Effects"
#> 
#> $body
#> [1] "Hi,\\n\\nYour custom report results are attached.\\n\\nWith regards,\\n\\nthe ABMI Science Team"
#> 

if (FALSE) {
## spatially explicit prediction
load_common_data()
## see bird species codes
sptab <- get_species_table()
rownames(sptab)[sptab$taxon == "birds"]
## pick Ovenbird
species <- "Ovenbird"
object <- load_spclim_data(species)
## vegetation/disturbance classes: use as factor
## might need to make a crosswalk, use e.g. mefa4::reclass
(veg <- as.factor(get_levels()$veg))
## for each veg class value, need to have
## spatial locations (can repeat the same value,
## but avoid duplicate rownames)
## use the sp package to get SpatialPoints as here:
XY <- get_id_locations()
coords <- coordinates(XY)[10^5,,drop=FALSE]
rownames(coords) <- NULL
xy <- data.frame(coords[rep(1, length(veg)),])
coordinates(xy) <- ~ POINT_X + POINT_Y
proj4string(xy) <- proj4string(XY)
## predict
pred <- predict(object, xy=xy, veg=veg)
summary(pred)
}