The whole preparation in one node

Parts 2 and 3 prepared the sloth's records one node at a time: cleaning, one record per cell, thinning, the accessible area, the predictors, the background, the folds. In practice you will often do all of it in one node, sdm.prepare, which runs the same steps in the same order with one setting each, and reports what every step did. In this part you will see every setting of that node, read its two outputs that document a model (report and settings), and measure how much each choice of the preparation changes the scores of the same model: more than the choice of algorithm did in part 4.

The idea#

A species distribution model is a chain of decisions before any model is fitted. Each one is defensible on its own, and together they decide what the model can learn and how it will be judged (Araújo et al., 2019, list them among the standards of a good model). Bundling them in one node has three advantages:

• every choice is in one place, so a model can be read, changed and rerun at a glance;
• one seed drives every random step (thinning, background, folds), so the same settings give the same records on any computer;
• a report counts the records each step removed, and a settings output lists every setting actually used, defaults included: the methods section of a paper, ready to copy.

The node runs these steps, in this order:

When to use it#

• Almost always, once you know what each step does (parts 2 and 3). It is what the template Species distribution model uses.
• Use the separate nodes when you need to look at a step's own outputs (CoordinateCleaner's counts per test, the variograms of the autocorrelation range, the VIF table), to put your own step in between (a target-group bias for the background, part 2), or to teach the steps one by one.

What you need#

• The records: points, or a table with coordinate columns. Columns named x/y, lon/lat, longitude/latitude or GBIF's decimalLongitude/decimalLatitude are found by themselves; x and y name others. A species setting keeps only the rows of one species of a table that holds several.
• The predictors: a stack (by name) or a map.
• Optionally: an area (polygons) or background points of your own, in place of those steps; regions (polygons such as ecoregions, for area = { method = "regions" }); within (polygons the area is cut to: the land of a country, a continent).

Build the model#

format = "terraflux/1"

[[nodes]]
id = "records"
op = "vector.read"
params = { path = "bradypus.csv" }

[[nodes]]
id = "climate"
op = "raster.read"
params = { path = "bioclim.tif" }

[[nodes]]
id = "data"
op = "sdm.prepare"
inputs = { occurrences = "records.vector", env = "climate.raster" }
params = { clean = true, one_per_cell = true, thin = 50000, area = 500000, predictors = 10, background = 2000, folds = { size = 500000, k = 5 }, seed = 1 }

[[nodes]]
id = "fit"
op = "sdm.fit"
inputs = { records = "data.records" }
params = { regmult = 2, classes = "lqh" }

[[nodes]]
id = "predict"
op = "sdm.maxnet_predict"
inputs = { model = "fit.model", env = "data.env" }

[outputs.report]
from = "data.report"

[outputs.settings]
from = "data.settings"

The settings of node 3, one per step:

Its outputs:

• records: the table for sdm.fit: x, y, presence, the predictors kept and fold;
• env: the predictors kept, to map the model;
• area: the accessible area (or the extent of the predictors);
• presences and background_points: the records left and the background, to draw or to evaluate (part 5);
• report and settings, below.

Read the results#

The report#

The report output, a row per step:

Enlarge

Read the report as the record of what your data went through. Losing 28 % of the records is normal for GBIF data at 0.5°; losing most of them would ask whether the resolution, the thinning distance or a test is too strict.

The settings#

The settings output (JSON) lists every setting used, the defaults filled in, and what was kept:

{
 "area": { "distance": 500000 },
 "background": { "n": 2000, "seed": 1 },
 "clean": {},
 "folds": { "k": 5, "method": "blocks", "seed": 1, "size": 500000 },
 "n_background": 2000,
 "n_presences": 83,
 "predictors": { "seed": 1, "vif": 10.0 },
 "predictors_used": ["bio5", "bio7", "bio16", "bio17"],
 "seed": 1,
 "thin": { "distance": 50000, "seed": 1 }
}

Keep it with the model's results: with the data and Terraflux's version, it is everything needed to make the same records again. A methods section can be written from it and the report: "Of 116 records, 3 failed CoordinateCleaner's tests (capitals, seas, institutions), 21 duplicated a cell of 0.5° and 9 were removed by thinning at 50 km, leaving 83. Background points (2 000) were drawn within 500 km of the records; four predictors with VIF below 10 were kept (bio5, bio7, bio16, bio17); the records were split into five folds of spatial blocks of 500 km."

Settings that change the answer#

The same model (MaxNet, classes = "lqh", regmult = 2) after five preparations of the same records, each adding one choice:

The accessible area moves the scores most: the test AUC drops from 0.87 to 0.69 when the background is drawn near the records rather than from the whole continent. The model is not worse; its task is harder and more honest (part 3). The thinning and the folds move them less, and the folds mostly move the Boyce index, which on 14 to 20 test presences per fold is noisy. In part 4 the three algorithms differed by 0.05 in test AUC; here the preparation changes it by 0.18. Report the preparation with the scores: they mean nothing without it.

Other settings worth knowing:

• background larger than the cells available: with the default of 10 000 and the accessible area of 500 km, the node warns that only 3 230 points could be drawn and takes every cell of the area. A census of the area is fine for MaxNet, but the number of points (and the prevalence of part 5) is then not the one you asked for.
• folds = { size = "auto" } sizes the blocks by the predictors' range of autocorrelation. Read the variograms first (part 3): on a continent their ranges can run away.
• area = { method = "regions" } with polygons on regions (ecoregions, biomes) draws the background from the regions that hold records; within cuts the area to the land of a country or a continent.
• predictors = { vif = 10, keep = ["bio12"] } keeps a predictor the biology calls for whatever its VIF.
• clean = false for records that are not longitudes and latitudes (a projected grid, the template's points).

Common pitfalls#

• Default settings taken as neutral. Every default is a choice (no thinning, no accessible area, 10 000 background points); the settings output shows them, and they belong in the methods.
• A different seed, a different model. Thinning, background and folds are random; keep the seed, or report the spread over several seeds.
• Too many background points for the area: read the warnings and the report's background row.
• Comparing models prepared differently. Two models are comparable only on the same records table.
• Forgetting the report. A model of 83 records from 116 is not the same as one of 83 from 2 000; say how many each step removed.

Going further#

• The steps one by one: Part 2: Occurrence data and Part 3: Predictors and the accessible area.
• Part 4: Fitting models, Part 5: Evaluation and thresholds, Part 6: Projection and extrapolation.
• The operators: sdm.prepare, and the nodes of its steps in the operator reference.

References#

• Aiello-Lammens, M. E., Boria, R. A., Radosavljevic, A., Vilela, B., & Anderson, R. P. (2015). spThin: an R package for spatial thinning of species occurrence records for use in ecological niche models. Ecography, 38(5), 541–545. https://doi.org/10.1111/ecog.01132
• Araújo, M. B., Anderson, R. P., Barbosa, A. M., Beale, C. M., Dormann, C. F., Early, R., et al. (2019). Standards for distribution models in biodiversity assessments. Science Advances, 5(1), eaat4858. https://doi.org/10.1126/sciadv.aat4858
• Valavi, R., Elith, J., Lahoz-Monfort, J. J., & Guillera-Arroita, G. (2019). blockCV: an R package for generating spatially or environmentally separated folds for k-fold cross-validation of species distribution models. Methods in Ecology and Evolution, 10(2), 225–232. https://doi.org/10.1111/2041-210X.13107
• Zizka, A., Silvestro, D., Andermann, T., Azevedo, J., Duarte Ritter, C., Edler, D., et al. (2019). CoordinateCleaner: standardized cleaning of occurrence records from biological collection databases. Methods in Ecology and Evolution, 10(5), 744–751. https://doi.org/10.1111/2041-210X.13152