Help for package gbm.auto

Title:

Automated Boosted Regression Tree Modelling and Mapping Suite

Version:

2024.10.01

Description:

Automates delta log-normal boosted regression tree abundance prediction. Loops through parameters provided (LR (learning rate), TC (tree complexity), BF (bag fraction)), chooses best, simplifies, & generates line, dot & bar plots, & outputs these & predictions & a report, makes predicted abundance maps, and Unrepresentativeness surfaces. Package core built around 'gbm' (gradient boosting machine) functions in 'dismo' (Hijmans, Phillips, Leathwick & Jane Elith, 2020 & ongoing), itself built around 'gbm' (Greenwell, Boehmke, Cunningham & Metcalfe, 2020 & ongoing, originally by Ridgeway). Indebted to Elith/Leathwick/Hastie 2008 'Working Guide' <doi:10.1111/j.1365-2656.2008.01390.x>; workflow follows Appendix S3. See https://www.simondedman.com/ for published guides and papers using this package.

License:

MIT + file LICENSE

Depends:

R (≥ 3.5.0)

Imports:

beepr (≥ 1.2), dismo (≥ 1.3-14), dplyr (≥ 1.0.9), gbm (≥ 2.1.1), ggmap (≥ 3.0.2), ggplot2 (≥ 3.4.2), ggspatial (≥ 1.1.9), lifecycle, lubridate (≥ 1.9.2), mapplots (≥ 1.5), Metrics (≥ 0.1.4), readr (≥ 2.1.4), sf (≥ 0.9-7), stars (≥ 0.6-3), starsExtra (≥ 0.2.7), stats (≥ 3.3.1), stringi (≥ 1.6.1), tidyselect (≥ 1.2.0), viridis (≥ 0.6.4)

Encoding:

UTF-8

Language:

en-GB

LazyData:

true

RoxygenNote:

7.3.2

NeedsCompilation:

Packaged:

2024-10-01 18:29:28 UTC; simon

Author:

Simon Dedman

[aut, cre]

Maintainer:

Simon Dedman <simondedman@gmail.com>

Repository:

CRAN

Date/Publication:

2024-10-01 21:30:02 UTC

gbm.auto: Automated Boosted Regression Tree Modelling and Mapping Suite

Description

Automates delta log-normal boosted regression tree abundance prediction. Loops through parameters provided (LR (learning rate), TC (tree complexity), BF (bag fraction)), chooses best, simplifies, & generates line, dot & bar plots, & outputs these & predictions & a report, makes predicted abundance maps, and Unrepresentativeness surfaces. Package core built around 'gbm' (gradient boosting machine) functions in 'dismo' (Hijmans, Phillips, Leathwick & Jane Elith, 2020 & ongoing), itself built around 'gbm' (Greenwell, Boehmke, Cunningham & Metcalfe, 2020 & ongoing, originally by Ridgeway). Indebted to Elith/Leathwick/Hastie 2008 'Working Guide' doi:10.1111/j.1365-2656.2008.01390.x; workflow follows Appendix S3. See https://www.simondedman.com/ for published guides and papers using this package.

Author(s)

Maintainer: Simon Dedman simondedman@gmail.com (ORCID)

Data: Numbers of 4 adult female rays caught in 2137 Irish Sea trawls, 1994 to 2014

Description

2137 capture events of adult female cuckoo, thornback, spotted and blonde rays in the Irish Sea from 1994 to 2014 by the ICES IBTS, including explanatory variables: Length Per Unit Effort in that area by the commercial fishery, depth, temperature, distance to shore, and current speed at the bottom.

Usage

data(Adult_Females)

Format

A data frame with 2137 rows and 13 variables:

Longitude: Decimal longitudes in the Irish Sea
Latitude: Decimal latitudes in the Irish Sea
Haul_Index: ICES IBTS area, survey, station, and year
F_LPUE: Commercial fishery LPUE in Kg/Hr
Depth: Metres, decimal
Temperature: Degrees, decimal
Salinity: PPM
Distance_to_Shore: Metres, decimal
Current_Speed: Metres per second at the seabed
Cuckoo: Numbers of cuckoo rays caught, standardised to 1 hour
Thornback: Numbers of thornback rays caught, standardised to 1 hour
Blonde: Numbers of blonde rays caught, standardised to 1 hour
Spotted: Numbers of spotted rays caught, standardised to 1 hour

Author(s)

Simon Dedman, simondedman@gmail.com

Source

http://datras.ices.dk

Data: Predicted abundances of 4 ray species generated using gbm.auto

Description

Predicted abundances of 4 ray species generated using gbm.auto, and Irish commercial beam trawler effort 2012.

Usage

data(AllPreds_E)

Format

A data frame with 378570 rows and 7 variables:

Latitude: Decimal latitudes in the Irish Sea
Longitude: Decimal longitudes in the Irish Sea
Cuckoo: Predicted abundances of cuckoo rays in the Irish Sea, generated using gbm.auto
Thornback: Predicted abundances of thornback rays in the Irish Sea, generated using gbm.auto
Blonde: Predicted abundances of blonde rays in the Irish Sea, generated using gbm.auto
Spotted: Predicted abundances of spotted rays in the Irish Sea, generated using gbm.auto
Effort: Irish commercial beam trawler effort 2012

Author(s)

Simon Dedman, simondedman@gmail.com

Data: Scaled abundance data for 2 subsets of 4 rays in the Irish Sea, by gbm.cons

Description

A dataset containing the output of the gbm.cons example run, conservation priority areas within the Irish Sea for juvenile and adult female cuckoo, blonde, thornback and spotted rays.

Usage

data(AllScaledData)

Format

A data frame with 378570 rows and 3 variables:

Longitude: Decimal longitudes in the Irish Sea
Latitude: Decimal latitudes in the Irish Sea
allscaled: Relative abundance. Each juvenile and adult female cuckoo, blonde, thornback and spotted ray scaled to 1 and added together

Author(s)

Simon Dedman, simondedman@gmail.com

Data: Explanatory and response variables for 4 juvenile rays in the Irish Sea

Description

A dataset containing explanatory variables for environment, fishery and predators of juvenile rays in the Irish Sea, and the response variables, abundance CPUEs of cuckoo, thornback, blonde and spotted rays.

Usage

data(Juveniles)

Format

A data frame with 2136 rows and 46 variables:

Survey_StNo_HaulNo_Year: Index column of combined Survey number, station number, haul number, and year
Latitude: Decimal latitudes in the Irish Sea
Longitude: Decimal longitudes in the Irish Sea
Depth: Metres, decimal
Temperature: Degrees, decimal
Salinity: PPM
Current_Speed: Metres per second at the seabed
Distance_to_Shore: Metres, decimal
F_LPUE: Commercial fishery LPUE in Kg/Hr
Scallop: Average KwH Scallop effort from logbooks, Marine Institute and MMO combined
MI_Av_E_Hr: Average effort hours, Marine Institute Scallop VMS, 0.03 x 0.02 rectangles, all Irish Sea, 2006-14
MI_Av_LPUE: Average scallop CPUE, Marine Institute Scallop VMS, 0.03 x 0.02 rectangles, all Irish Sea, 2006-14
MI_Sum_Liv: Sum of live weight. Average scallop CPUE, Marine Institute Scallop VMS, 0.03 x 0.02 rectangles, all Irish Sea, 2006-14
Whelk: MMO Whelk LPUE 2009-12, pivot, polygons to points
MmoAvScKwh: MMO Scallop Effort 2009-12, pivot, polygons to points. ICES rectangles
Cod_C: ICES IBTS CPUE of cod caught between 1994 - 2014 large enough to predate upon <= year 1 cuckoo rays
Cod_T: As Cod_C for yr1 thornback rays
Cod_B: As Cod_C for yr1 blonde rays
Cod_S: As Cod_C for yr1 spotted rays
Haddock_C: As Cod_C, haddock predating upon cuckoo rays
Haddock_T: As Cod_C, haddock predating upon thornback rays
Haddock_B: As Cod_C, haddock predating upon blonde rays
Haddock_S: As Cod_C, haddock predating upon spotted rays
Plaice_C: As Cod_C, plaice predating upon cuckoo rays
Plaice_T: As Cod_C, plaice predating upon thornback rays
Plaice_B: As Cod_C, plaice predating upon blonde rays
Plaice_S: As Cod_C, plaice predating upon spotted rays
Whiting_C: As Cod_C, whiting predating upon cuckoo rays
Whiting_T: As Cod_C, whiting predating upon thornback rays
Whiting_B: As Cod_C, whiting predating upon blonde rays
Whiting_S: As Cod_C, whiting predating upon spotted rays
ComSkt_C: As Cod_C, common skate predating upon cuckoo rays
ComSkt_T: As Cod_C, common skate predating upon thornback rays
ComSkt_B: As Cod_C, common skate predating upon blonde rays
ComSkt_S: As Cod_C, common skate predating upon spotted rays
Blonde_C: As Cod_C, blonde ray predating upon cuckoo rays
Blonde_T: As Cod_C, blonde ray predating upon thornback rays
Blonde_S: As Cod_C, blonde ray predating upon spotted rays
C_Preds: All predator CPUEs combined for cuckoo rays
T_Preds: All predator CPUEs combined for thornback rays
B_Preds: All predator CPUEs combined for blonde rays
S_Preds: All predator CPUEs combined for spotted rays
Cuckoo: Numbers of juvenile cuckoo rays caught, standardised to 1 hour
Thornback: Numbers of juvenile thornback rays caught, standardised to 1 hour
Blonde: Numbers of juvenile blonde rays caught, standardised to 1 hour
Spotted: Numbers of juvenile spotted rays caught, standardised to 1 hour

Author(s)

Simon Dedman, simondedman@gmail.com

Defines breakpoints for draw.grid and legend.grid; mapplots fork

Description

Defines breakpoints from values in grd with options to exclude outliers, set number of bins, and include a dedicated zero column. Forked by SD 05/01/2019 to add 'lo', else bins always begin at 0, killing plotting when all data are in a tight range at high values e.g. 600:610

Usage

breaks.grid(grd, quantile = 0.975, ncol = 12, zero = TRUE)

Arguments

grd

An array produced by make.grid or a list produced by make.multigrid or a vector of positive values.

quantile

The maximum value of the breaks will be determined by the quantile given here. This can be used to deal with outlying values in grd. If quantile = 1 then the maximum value of the breaks will be the same as the maximum value in grd.

ncol

Number of colours to be used, always one more than the number of breakpoints. Defaults to 12.

zero

Logical, should zero be included as a separate category? Defaults to TRUE.

Value

A vector of breakpoints for draw.grid in mapplots

Author(s)

Simon Dedman, simondedman@gmail.com

Hans Gerritsen

Examples

breaks.grid(100,ncol=6)
breaks.grid(100,ncol=5,zero=FALSE)

# create breaks on the log scale
exp(breaks.grid(log(10000),ncol=4,zero=FALSE))

calibration

Description

Internal use only. Jane Elith/John Leathwick 17th March 2005. Calculates calibration statistics for either binomial or count data but the family argument must be specified for the latter a conditional test for the latter will catch most failures to specify the family.

Usage

calibration(obs, preds, family = c("binomial", "bernoulli", "poisson"))

Arguments

obs

Observed data.

preds

Predicted data.

family

Statistical distribution family. Choose one.

Value

roc & calibration stats internally within gbm runs e.g. in gbm.auto.

Author(s)

Simon Dedman, simondedman@gmail.com

Automated Boosted Regression Tree modelling and mapping suite

Description

Automates delta log normal boosted regression trees abundance prediction. Loops through all permutations of parameters provided (learning rate, tree complexity, bag fraction), chooses the best, then simplifies it. Generates line, dot and bar plots, and outputs these and the predictions and a report of all variables used, statistics for tests, variable interactions, predictors used and dropped, etc. If selected, generates predicted abundance maps, and Unrepresentativeness surfaces. See www.GitHub.com/SimonDedman/gbm.auto for issues, feedback, and development suggestions. See SimonDedman.com for links to walkthrough paper, and papers and thesis published using this package.

Usage

gbm.auto(
  grids = NULL,
  samples,
  expvar,
  resvar,
  randomvar = FALSE,
  tc = c(2),
  lr = c(0.01, 0.005),
  bf = 0.5,
  offset = NULL,
  n.trees = 50,
  ZI = "CHECK",
  fam1 = c("bernoulli", "binomial", "poisson", "laplace", "gaussian"),
  fam2 = c("gaussian", "bernoulli", "binomial", "poisson", "laplace"),
  simp = TRUE,
  gridslat = 2,
  gridslon = 1,
  samplesGridsAreaScaleFactor = 1,
  multiplot = TRUE,
  cols = grey.colors(1, 1, 1),
  linesfiles = TRUE,
  smooth = FALSE,
  savedir = tempdir(),
  savegbm = TRUE,
  loadgbm = NULL,
  varint = TRUE,
  map = TRUE,
  shape = NULL,
  RSB = TRUE,
  BnW = TRUE,
  alerts = TRUE,
  pngtype = c("cairo-png", "quartz", "Xlib"),
  gaus = TRUE,
  MLEvaluate = TRUE,
  brv = NULL,
  grv = NULL,
  Bin_Preds = NULL,
  Gaus_Preds = NULL,
  ...
)

Arguments

grids

Explanatory data to predict to. Import with (e.g.) read.csv and specify object name. Defaults to NULL (won't predict to grids).

samples

Explanatory and response variables to predict from. Keep col names short (~17 characters max), no odd characters, spaces, starting numerals or terminal periods. Spaces may be converted to periods in directory names, underscores won't. Can be a subset of a large dataset.

expvar

Vector of names or column numbers of explanatory variables in 'samples': c(1,3,6) or c("Temp","Sal"). No default.

resvar

Name or column number(s) of response variable in samples: 12, c(1,4), "Rockfish". No default. Column name is ideally species name.

randomvar

Add a random variable (uniform distribution, 0-1) to the expvars, to see whether other expvars perform better or worse than random.

tc

Permutations of tree complexity allowed, can be vector with the largest sized number no larger than the number of explanatory variables e.g. c(2,7), or a list of 2 single numbers or vectors, the first to be passed to the binary BRT, the second to the Gaussian, e.g. tc = list(c(2,6), 2) or list(6, c(2,6)).

lr

Permutations of learning rate allowed. Can be a vector or a list of 2 single numbers or vectors, the first to be passed to the binary BRT, the second to the Gaussian, e.g. lr = list(c(0.01,0.02),0.0001) or list(0.01,c(0.001, 0.0005)).

bf

Permutations of bag fraction allowed, can be single number, vector or list, per tc and lr. Defaults to 0.5.

offset

Column number or quoted name in samples, containing offset values relating to the samples. A numeric vector of length equal to the number of cases. Similar to weighting, see https://towardsdatascience.com/offsetting-the-model-logic-to-implementation-7e333bc25798 .

n.trees

From gbm.step, number of initial trees to fit. Can be single or list but not vector i.e. list(fam1,fam2).

ZI

Are data zero-inflated? TRUE FALSE "CHECK". Choose one. TRUE: delta BRT, log-normalised Gaus, reverse log-norm and bias corrected. FALSE: do Gaussian only, no log-normalisation. "CHECK": Tests data for you. Default is "CHECK". TRUE and FALSE aren't in quotes, "CHECK" is.

fam1

Probability distribution family for 1st part of delta process, defaults to "bernoulli". Choose one.

fam2

Probability distribution family for 2nd part of delta process, defaults to "gaussian". Choose one.

simp

Try simplifying best BRTs?

gridslat

Column number for latitude in 'grids'.

gridslon

Column number for longitude in 'grids'.

samplesGridsAreaScaleFactor

Scale up or down factor so values in the predict-to pixels of 'grids' match the spatial scale sampled by rows in 'samples'. Default 1 means no change.

multiplot

Create matrix plot of all line files? Default true. turn off if big n of exp vars causes an error due to margin size problems.

cols

Barplot colour vector. Assignment in order of explanatory variables. Default 1white: white bars black borders. '1' repeats.

linesfiles

Save individual line plots' data as csv's? Default TRUE.

smooth

Apply a smoother to the line plots? Default FALSE.

savedir

Save outputs to a temporary directory (default) else change to current directory e.g. "/home/me/folder". Do not use getwd() here.

savegbm

Save gbm objects and make available in environment after running? Open with load("Bin_Best_Model") Default TRUE.

loadgbm

Relative or (very much preferably) absolute location of folder containing Bin_Best_Model and Gaus_Best_Model. If set will skip BRT calculations and do predicted maps and csvs. Avoids re-running BRT models again (the slow bit), can run normally once with savegbm=T then multiple times with new grids & loadgbm to predict to multiple grids e.g. different seasons, areas, etc. Default NULL, character vector, "./" for working directory.

varint

Calculate variable interactions? Default:TRUE, FALSE for error: "contrasts can be applied only to factors with 2 or more levels".

map

Save abundance map png files?

shape

Enter the full path to downloaded map e.g. coastline shapefile, possibly from gbm.basemap, typically Crop_Map.shp, including the .shp. Can also name an existing object in the environment, read in with sf::st_read. Default NULL, in which case bounds calculated by gbm.mapsf which then calls gbm.basemap to download and auto-generate the base map.

RSB

Run Unrepresentativeness surface builder? Default TRUE.

BnW

Repeat maps in black and white e.g. for print journals. Default TRUE.

alerts

Play sounds to mark progress steps. Default TRUE but running multiple small BRTs in a row (e.g. gbm.loop) can cause RStudio to crash.

pngtype

Filetype for png files, alternatively try "quartz" on Mac. Choose one.

gaus

Do family2 (typically Gaussian) runs as well as family1 (typically Bin)? Default TRUE.

MLEvaluate

do machine learning evaluation metrics & plots? Default TRUE.

brv

Dummy param for package testing for CRAN, ignore.

grv

Dummy param for package testing for CRAN, ignore.

Bin_Preds

Dummy param for package testing for CRAN, ignore.

Gaus_Preds

Dummy param for package testing for CRAN, ignore.

...

Optional arguments for gbm.step (dismo package) arguments n.trees and max.trees, both of which can be added in list(1,2) format to pass to fam1 and 2; for gbm.mapsf colourscale, heatcolours, colournumber, and others.

Details

Errors and their origins:

install ERROR: dependencies ‘rgdal’, ‘rgeos’ are not available for package ‘gbm.auto’. For Linux/*buntu systems, in terminal, type: 'sudo apt install libgeos-dev', 'sudo apt install libproj-dev', 'sudo apt install libgdal-dev'.
Error in FUN(X[[i]], ...) : only defined on a data frame with all numeric variables. Check your variable types are correct, e.g. numerics haven't been imported as factors because there's an errant first row of text information before the data. Remove NA rows from the response variable if present: convert blank cells to NA on import with read.csv(x, na.strings = "") then samples2 <- samples[-which(is.na(samples[,resvar_column_number])),]
At BF=0.5, if nrows <= 42, gbm.step will crash. Use gbm.bfcheck to determine optimal viable BF size.
Maps/plots don't work/output. If on a Mac, try changing pngtype to "quartz".
Error in while (delta.deviance > tolerance.test & n.fitted < max.trees): missing value where TRUE/FALSE needed. If running a zero-inflated delta model (bernoulli/bin & gaussian/gaus), Data are expected to contain zeroes (lots of them in zero- inflated cases), have you already filtered them out, i.e. are only testing the positive cases? Or do you only have positive cases? If so only run (e.g.) Gaussian: set ZI to FALSE.
Error in round(gbm.object$cv.statistics$deviance.mean, 4) : non-numeric argument to mathematical function. LR or BF probably too low in earlier BRT (normally Gaus run with highest TC).
Error in if (n.trees > x$n.trees) argument is of length zero. LR or BF probably too low in earlier BRT (normally Gaus run with highest TC).
Error in gbm.fit(x, y, offset = offset, distribution = distribution, w = w): The dataset size is too small or subsampling rate is too large: nTrain*bag.fraction <= n.minobsinnode. LR or BF probably too low in earlier BRT (normally Gaus run with highest TC). It may be that you don't have enough positive samples to run BRT modelling. Run gbm.bfcheck to check recommended minimum BF size.
Warning message: In cor(y_i, u_i) : the standard deviation is zero. LR or BF probably too low in earlier BRT (normally Gaus run with highest TC). It may be that you don't have enough positive samples to run BRT modelling. Run gbm.bfcheck to check recommended minimum BF size. Similarly: glm.fit: fitted probabilities numerically 0 or 1 occurred, and glm.fit: algorithm did not converge. Similarly: Error in if (get(paste0("Gaus_BRT", ".tc", j, ".lr", k, ".bf", l))$self.statistics$correlation[[1]]: argument is of length zero. See also: Error 15.
Anomalous values can obfuscate clarity in line plots e.g. salinity range 32:35ppm but dataset has errant 0 value: plot axis will be 0:35, and 99.99% of the data will be in the tiny bit at the right. Clean your data beforehand.
Error in plot.new() : figure margins too large: In RStudio, adjust plot pane (usually bottom right) to increase its size. Still fails? Set multiplot=FALSE.
Error in dev.print(file = paste0("./", names(samples[i]), "/pred_dev_bin.jpeg"): can only print from a screen device. An earlier failed run (e.g. LR/BF too low) left a plotting device open. Close it with: 'dev.off()'.
RStudio crashed: set alerts=F and pause cloud sync programs if outputting to a synced folder.
Error in grDevices::dev.copy(device = function (filename = "Rplot%03d.jpeg", could not open file './resvar/pred_dev_bin.jpeg' (or similar). Your resvar column name contains an illegal character e.g. /&'_. Fix with colnames(samples)[n] <- "BetterName".
Error in gbm.fit: Poisson requires the response to be a positive integer. If running Poisson distributions, ensure the response variables are positive integers, but if they are, try a smaller LR.
If lineplots of factorial variables include empty columns be sure to remove unused levels with samples %<>% droplevels() before the gbm.auto run.
Error in seq.default(from = min(x$var.levels[[i.var[i]]]), to = max(x$var.levels[[i.var[i]]]):'from' must be a finite number. If you logged any expvars with log() and they has zeroes in them, those zeroes became imaginary numbers. Use log1p() instead.
Error in loadNamespace...'dismo' 1.3-9 is being loaded, but >= 1.3.10 is required: first do remotes::install_github("rspatial/dismo") then library(dismo).
Error in if (scope >= 160) res <- "c" : missing value where TRUE/FALSE needed. Check gridslat and gridslon are indexing the correct columns in grids.

ALSO: check this section in the other functions run by gbm.auto e.g. gbm.mapsf, gbm.basemap. Use traceback() to find the source of errors.

I strongly recommend that you download papers 1 to 5 (or just the doctoral thesis) on http://www.simondedman.com, with emphasis on P4 (the guide) and P1 (statistical background). Elith et al 2008 (https://besjournals.onlinelibrary.wiley.com/doi/10.1111/j.1365-2656.2008.01390.x) is also strongly recommended. Just because you CAN try every conceivable combination of tc, lr, bf, all, at once doesn't mean you should. Try a range of lr in shrinking orders of magnitude from 0.1 to 0.000001, find the best, THEN try tc c(2, n.expvars), find the best THEN bf c(0.5, 0.75, 0.9) and then in between if either outperform 0.5.

Value

Line, dot and bar plots, a report of all variables used, statistics for tests, variable interactions, predictors used and dropped, etc. If selected, generates predicted abundance maps, and Unrepresentativeness surface. Biggest Interactions in the report csv: see ?dismo::gbm.interactions .

Author(s)

Simon Dedman, simondedman@gmail.com

Examples


# Not run. Note: grids file was heavily cropped for CRAN upload so output map
# predictions only cover patchy chunks of the Irish Sea, not the whole area.
# Full versions of these files:
# https://drive.google.com/file/d/1WHYpftP3roozVKwi_R_IpW7tlZIhZA7r
# /view?usp=sharing
library(gbm.auto)
data(grids)
data(samples)
# Set your working directory
gbm.auto(grids = grids, samples = samples, expvar = c(4:8, 10), resvar = 11,
tc = c(2,7), lr = c(0.005, 0.001), ZI = TRUE, savegbm = FALSE)

Creates Basemaps for Gbm.auto mapping from your data range

Description

Downloads unzips crops & saves NOAAs global coastline shapefiles to user-set box. Use for 'shape' in gbm.map. If downloading in RStudio uncheck "Use secure download method for HTTP" in Tools > Global Options > Packages. Simon Dedman, 2015/6 simondedman@gmail.com GitHub.com/SimonDedman/gbm.auto

Usage

gbm.basemap(
  bounds = NULL,
  grids = NULL,
  gridslat = NULL,
  gridslon = NULL,
  getzip = TRUE,
  zipvers = "2.3.7",
  savedir = tempdir(),
  savename = "Crop_Map",
  res = "CALC",
  extrabounds = FALSE
)

Arguments

bounds

Region to crop to: c(xmin,xmax,ymin,ymax).

grids

If bounds unspecified, name your grids database here.

gridslat

If bounds unspecified, specify which column in grids is latitude.

gridslon

If bounds unspecified, specify which column in grids is longitude.

getzip

Download & unpack GSHHS data to WD? "TRUE" else absolute/relative reference to GSHHS_shp folder, including that folder.

zipvers

GSHHS version, in case it updates. Please email developer (SD) if this is incorrect.

savedir

Save outputs to a temporary directory (default) else change to current directory e.g. "/home/me/folder". Do not use getwd() here.

savename

Shapefile save-name, no shp extension, default is "Crop_Map"

res

Resolution, 1:5 (low:high) OR c,l,i,h,f (coarse, low, intermediate, high, full) or "CALC" to calculate based on bounds. Choose one.

extrabounds

Grow bounds 16pct each direction to expand rectangular datasets basemaps over the entire square area created by basemap in mapplots.

Details

errors and their origins:

Error in setwd(getzip) : cannot change working directory If you've specified the location of the local GSHHS_shp folder, ensure you're in the correct directory relative to it. This error means it looked for the folder and couldn't find it.
subscript out of bounds: can't crop world map to your bounds. Check lat/lon are the right way around: check gridslat and gridslon point to the correct columns for lat and lon in grids, and those columns named (something like) lat and lon, ARE ACTUALLY the latitudes and longitudes, and not the wrong way around.
If your download is timing out use options(timeout = 240).
Error in if (scope >= 160) res <- "c" : missing value where TRUE/FALSE needed. Check gridslat and gridslon are indexing the correct columns in grids.

Value

basemap coastline file for gbm.map in gbm.auto. "cropshp" SpatialPolygonsDataFrame in in local environment & user-named files in "CroppedMap" folder. Load later with maptools function: MyMap <- sf::st_read(dsn = "./CroppedMap/Crop_Map.shp", layer = "Crop_Map, quiet = TRUE)

Author(s)

Simon Dedman, simondedman@gmail.com

Examples


# Not run: downloads and saves external data.
data(samples)
mybounds <- c(range(samples[,3]),range(samples[,2]))
gbm.basemap(bounds = mybounds, getzip = "./GSHHS_shp/",
savename = "My_Crop_Map", res = "f")
# In this example GSHHS folder already downloaded to the working directory
# hence I pointed getzip at that rather than having it download the zip again

Calculates minimum Bag Fraction size for gbm.auto

Description

Provides minimum bag fractions for gbm.auto, preventing failure due to bf & samples rows limit. Simon Dedman, 2016, simondedman@gmail.com, GitHub.com/SimonDedman/gbm.auto

Usage

gbm.bfcheck(samples, resvar, ZI = "CHECK", grv = NULL)

Arguments

samples

Samples dataset, same as gbm.auto.

resvar

Response variable column in samples.

ZI

Are samples zero-inflated? TRUE/FALSE/"CHECK".

grv

Dummy param for package testing for CRAN, ignore.

Value

Prints minimum Bag Fraction size for gbm.auto.

Author(s)

Simon Dedman, simondedman@gmail.com

Examples

data(samples)
gbm.bfcheck(samples = samples, resvar = "Cuckoo")

Conservation Area Mapping

Description

Runs gbm.auto for multiple subsets of the same overall dataset and scales the combined results, leading to maps which highlight areas of high conservation importance for multiple species in the same study area e.g. using juvenile and adult female subsets to locate candidate nursery grounds and spawning areas respectively.

Usage

gbm.cons(
  mygrids,
  subsets,
  alerts = TRUE,
  map = TRUE,
  BnW = TRUE,
  resvars,
  gbmautos = TRUE,
  savedir = tempdir(),
  expvars,
  tcs = NULL,
  lrs = rep(list(c(0.01, 0.005)), length(resvars)),
  bfs = rep(0.5, length(resvars)),
  ZIs = rep("CHECK", length(resvars)),
  colss = rep(list(grey.colors(1, 1, 1)), length(resvars)),
  linesfiless = rep(FALSE, length(resvars)),
  savegbms = rep(TRUE, length(resvars)),
  varints = rep(TRUE, length(resvars)),
  maps = rep(TRUE, length(resvars)),
  RSBs = rep(TRUE, length(resvars)),
  BnWs = rep(TRUE, length(resvars)),
  zeroes = rep(TRUE, length(resvars)),
  shape = NULL,
  pngtype = c("cairo-png", "quartz", "Xlib"),
  gridslat = 2,
  gridslon = 1,
  grids = NULL
)

Arguments

mygrids

Gridded lat+long+data object to predict to.

subsets

Subset name(s): character; single or vector, corresponding to matching-named dataset objects e.g. read in by read.csv().

alerts

Play sounds to mark progress steps.

map

Produce maps.

BnW

Also produce B&W maps?

resvars

Vector of resvars cols from dataset objects for gbm.autos, length(subsets)*species, no default.

gbmautos

Do gbm.auto runs for species? Default TRUE, set FALSE if already run and output files in expected directories.

savedir

Save outputs to a temporary directory (default) else change to current directory e.g. "/home/me/folder". Do not use getwd() here.

expvars

List object of expvar vectors for gbm.autos, length = no. of subsets * no. of species. No default.

tcs

Gbm.auto parameters, auto-calculated below if not provided by user.

lrs