Skip to contents

evoland_db - R6 Class for lulc data management

Source: R/evoland_db.R
evoland_db.Rd

An R6 class that provides an interface to a folder-based data storage system for the evoland package. This class uses DuckDB for in-memory SQL operations while persisting data to a DuckLake catalog on disk.

Inherits from ducklake_db for generic database operations.

See also

Additional methods and active bindings are added to this class in separate files:

Super class

ducklake_db -> evoland_db

Active bindings

coords_t

Get or upsert coords_t

periods_t

Get or upsert periods_t

lulc_meta_t

Get or upsert lulc_meta_t

lulc_data_t

Get or upsert lulc_data_t

pred_data_t

Get or upsert pred_data_t

pred_meta_t

Get or upsert pred_meta_t

trans_meta_t

Get or upsert trans_meta_t

trans_preds_t

Get or upsert trans_preds_t

trans_rates_t

Get or upsert trans_rates_t

intrv_meta_t

Get or upsert intrv_meta_t

intrv_masks_t

Get or upsert intrv_masks_t

trans_models_t

Get or upsert trans_models_t

alloc_params_t

Get or upsert alloc_params_t

trans_pot_t

Get or upsert raw transition potentials trans_pot_t. These are per-transition model probabilities stored by predict_trans_pot(). Use adjusted_trans_pot_v() for allocation-ready values.

neighbors_t

Get or upsert neighbors_t

reporting_t

Get or upsert reporting_t

runs_t

Get or upsert runs_t

id_run

Get or set active id_run, see runs_t

run_lineage

Get id_run, see runs_t

Methods

Public methods

Inherited methods

evoland_db$new()

Initialize a new evoland_db object

Usage

evoland_db$new(
  path = NULL,
  id_run = 0L,
  read_only = FALSE,
  catalog = NULL,
  data_path = NULL,
  sqlite_journal_mode = "wal",
  expire_older_than = NULL,
  delete_older_than = NULL,
  ...
)

Arguments

path

Character. Path to the data folder; may be omitted when both catalog and data_path are given, see ducklake_db.

id_run

Atomic integer run ID, defaults to 0. Can be set to NULL

read_only

Logical. Whether to update the reporting table upon initialization; if TRUE, the catalog is attached read-only.

catalog

Character. DuckLake catalog connection, see ducklake_db.

data_path

Character. DuckLake data files location, see ducklake_db.

sqlite_journal_mode

Character. Journal mode for a SQLite catalog, see ducklake_db.

expire_older_than, delete_older_than

Retention for $checkpoint(), see ducklake_db.

...

passed on to set_report

Returns

A new evoland_db object

evoland_db$get_read_expr()

Get SQL expression to read a table, respecting active run hierarchy. For each data slice, returns data from the closest ancestor run that has it.

Usage

evoland_db$get_read_expr(table_name, id_run = self$id_run)

Arguments

table_name

Character string table name

id_run

Integer, the run whose lineage is read; defaults to the active run. Another run can be read without changing the active one.

Returns

Character string SQL expression (a composable subquery)

evoland_db$print()

Print method for evoland_db

Usage

evoland_db$print(...)

Arguments

...

passed to super$print

evoland_db$set_report()

Set reporting metadata, see db_set_report()

Usage

evoland_db$set_report(...)

Arguments

...

each named argument is entered into the table with the argument name as its key

evoland_db$set_neighbors()

Set the neighbors table, see set_neighbors()

Usage

evoland_db$set_neighbors(
  max_distance = 1000,
  distance_breaks = NULL,
  overwrite = FALSE,
  quiet = FALSE,
  chunksize = 1e+07
)

Arguments

max_distance

Maximum distance

distance_breaks

Numeric vector of distance breaks

overwrite

Logical, whether to overwrite existing neighbors_t table

quiet

Logical, whether to suppress messages about progress

chunksize

Integer, chunksize for writing; keeps down memory pressure

evoland_db$generate_neighbor_predictors()

Generate neighbor prediction table, i.e. "how many neighbors within distance X are of type Y", see generate_neighbor_predictors()

Usage

evoland_db$generate_neighbor_predictors()

evoland_db$upsert_new_neighbors()

Append new neighbors to predictor for a given period; depends on generate_neighbor_predictors() having been run.

Usage

evoland_db$upsert_new_neighbors(id_period)

Arguments

id_period

Period to calculate predictors for

evoland_db$add_predictor()

Add a predictor using the currently active id_run, see add_predictor()

Usage

evoland_db$add_predictor(
  pred_data_raw,
  name,
  fill_value,
  pretty_name = name,
  description = NA_character_,
  orig_format = NA_character_,
  sources = data.frame(url = character(0), md5sum = character(0)),
  unit = NA_character_
)

Arguments

pred_data_raw

Data frame with columns id_coord, id_period, and value

name

Unique short name

fill_value

Value to substitute if a coordinate point in coords_t does not have an explicit associated value

pretty_name

char, Friendly name for use in reporting

description

char, For use in reporting.

orig_format

char, Format description of the underlying data (raster, vector…)

sources

data.frame with url/md5sum columns, used for keeping track of underlying raw data, see download_and_verify()

unit

char, SI unit for physical predictors, or descriptions like "bed nights/year" as a proxy for touristic activity

evoland_db$pred_wide_train_v()

Get transitions along with their predictor data in a wide data.table, see pred_wide_train_v()

Usage

evoland_db$pred_wide_train_v(id_trans, id_pred)

Arguments

id_trans

Integer transition ID, see trans_meta_t

id_pred

Optional integer vector of predictor IDs to include

evoland_db$pred_wide_predict_v()

Retrieve a wide view of the predictor data, see pred_wide_predict_v()

Usage

evoland_db$pred_wide_predict_v(id_trans, id_period_anterior)

Arguments

id_trans

Integer transition ID, see trans_meta_t

id_period_anterior

Integer ID of period to retrieve data for

evoland_db$figure_of_merit_v()

Pontius' figure of merit of simulated against observed change, see figure_of_merit_v()

Usage

evoland_db$figure_of_merit_v(
  id_period_anterior,
  id_period_post,
  id_run_reference,
  id_run_simulated = self$id_run,
  by_transition = FALSE,
  exclude_id_lulc = integer(0)
)

Arguments

id_period_anterior

Integer, period of the initial map

id_period_post

Integer, period of the observed and simulated maps

id_run_reference

Integer, run holding the initial and observed maps

id_run_simulated

Integer vector, runs holding the simulated maps; defaults to the active run

by_transition

Logical; if TRUE, report per transition instead of overall.

exclude_id_lulc

Integer vector of classes; cells whose class in the reference run, at id_period_anterior or id_period_post, is one of them are ignored. Default none.

evoland_db$lulc_crosstab_v()

Cross-tabulation of land use between two periods, see lulc_crosstab_v()

Usage

evoland_db$lulc_crosstab_v(
  id_period_anterior,
  id_period_post,
  id_run_anterior = self$id_run,
  id_run_post = id_run_anterior
)

Arguments

id_period_anterior, id_period_post

Integer, the two periods to compare

id_run_anterior

Integer, run to read id_period_anterior from; defaults to the active run

id_run_post

Integer, run to read id_period_post from; defaults to id_run_anterior

evoland_db$alloc_dinamica()

Runs a path-dependent Monte Carlo simulation using Dinamica EGO, see alloc_dinamica()

Usage

evoland_db$alloc_dinamica(
  id_periods,
  select_score,
  select_maximize,
  work_dir = NULL,
  keep_intermediate = FALSE,
  use_parent_trans_pot = FALSE,
  force_predict_trans_pot = FALSE,
  update_neighbors = TRUE
)

Arguments

id_periods

Integer vector of period IDs to include in the simulation.

select_score

Character string; mlr3 measure ID (e.g. "classif.auc") used to select model for extrapolation

select_maximize

Logical; maximize (TRUE) or minimize (FALSE) the score.

work_dir

Character path for Dinamica working directory; NULL (default) uses a temporary directory.

keep_intermediate

Logical, keep intermediate Dinamica files? Default FALSE.

use_parent_trans_pot

Logical; use the direct parent run's transition potentials

force_predict_trans_pot

Logical; re-run prediction for trans_pot_t even if those values already exist

update_neighbors

Logical; recompute neighbour predictors after the last requested period. Intermediate periods are always updated.

evoland_db$alloc_clumpy()

Runs CLUMPY-style LULC allocation, see alloc_clumpy(). The method (uSAM vs uPAM) is selected automatically from the patch parameters: mono-pixel patches (area_mean == 1, area_var == 0) use uSAM, otherwise uPAM.

Usage

evoland_db$alloc_clumpy(
  id_periods,
  select_score,
  select_maximize,
  area_dist = "lognormal",
  avoid_aggregation = TRUE,
  batch_size = 0L,
  use_parent_trans_pot = FALSE,
  force_predict_trans_pot = FALSE,
  update_neighbors = TRUE
)

Arguments

id_periods

Integer vector of period IDs to include in the simulation.

select_score

Character string; mlr3 measure ID (e.g. "classif.auc") used to select model for extrapolation.

select_maximize

Logical; maximize (TRUE) or minimize (FALSE) the score.

area_dist

Character; patch-area distribution, "lognormal" (default) or "normal". See alloc_clumpy().

avoid_aggregation

Logical; if TRUE (default) uPAM patches that would merge fail and allocate nothing. Ignored for uSAM.

batch_size

Integer; uPAM pivots attempted per MuST re-draw. 0 (default) auto-scales with the source pool; > 0 is an explicit cap (1 = strict uPAM); < 0 = all candidates in one pass. Ignored for uSAM.

use_parent_trans_pot

Logical; use the direct parent run's transition potentials (useful for repeated allocation)

force_predict_trans_pot

Logical; re-run prediction for trans_pot_t even if those values already exist

update_neighbors

Logical; recompute neighbour predictors after the last requested period. Intermediate periods are always updated.

evoland_db$alloc_greedy()

Runs deterministic greedy (rank-and-fill) allocation, see alloc_greedy(): each transition's demand goes to the cells of highest adjusted potential, every cell changes at most once.

Usage

evoland_db$alloc_greedy(
  id_periods,
  select_score,
  select_maximize,
  arbitration = c("joint", "ordered"),
  order = NULL,
  use_parent_trans_pot = FALSE,
  force_predict_trans_pot = FALSE,
  update_neighbors = TRUE
)

Arguments

id_periods

Integer vector of period IDs to include in the simulation.

select_score

Character string; mlr3 measure ID (e.g. "classif.auc") used to select model for extrapolation.

select_maximize

Logical; maximize (TRUE) or minimize (FALSE) the score.

arbitration

Character; "joint" (default) ranks all transitions together, "ordered" lets transitions claim cells in the priority given by order.

order

Integer vector of id_trans, the priority for "ordered".

use_parent_trans_pot

Logical; use the direct parent run's transition potentials

force_predict_trans_pot

Logical; re-run prediction for trans_pot_t even if those values already exist

update_neighbors

Logical; recompute neighbour predictors after the last requested period. Intermediate periods are always updated.

evoland_db$eval_alloc_params_t()

Evaluates allocation parameters in dinamica, see eval_alloc_params_t()

Usage

evoland_db$eval_alloc_params_t(
  select_score,
  select_maximize,
  work_dir = NULL,
  keep_intermediate = FALSE
)

Arguments

select_score

Character string; mlr3 measure ID (e.g. "classif.auc") used to select model for extrapolation

select_maximize

Logical; maximize (TRUE) or minimize (FALSE) the score.

work_dir

Character path for Dinamica working directory; NULL (default) uses a temporary directory.

keep_intermediate

Logical, keep intermediate Dinamica files? Default FALSE.

evoland_db$create_alloc_params_t()

Estimates allocation parameters for all viable transitions under the active id_run, see create_alloc_params_t()

Usage

evoland_db$create_alloc_params_t()

evoland_db$lulc_data_as_rast()

Retrieve LULC data as a SpatRaster object for a given period. See lulc_data_as_rast()

Usage

evoland_db$lulc_data_as_rast(id_period = NULL)

Arguments

id_period

Optional integer vector of period IDs to include. If NULL (default), all periods are included.

evoland_db$fit_full_models()

Fit full models (trained on the complete dataset) for each viable transition, see fit_full_models(). Two mutually exclusive modes: pass learner to train directly, or pass select_score to pick the best partial model by score.

Usage

evoland_db$fit_full_models(
  learner = NULL,
  select_score = NULL,
  select_maximize = TRUE,
  cluster = NULL,
  trans_preds = NULL,
  trans_meta = NULL
)

Arguments

learner

An mlr3 Learner or AutoTuner for direct-learner mode (NULL when select_score is used).

select_score

Measure ID string for score-select mode, e.g. "classif.auc" (NULL when learner is used).

select_maximize

Logical; maximize (TRUE) or minimize (FALSE) the score.

cluster

Optional cluster object for parallel processing

trans_preds

Optional trans_preds_t; bypasses the database read in direct-learner mode. Ignored in score-select mode.

trans_meta

Optional trans_meta_t; bypasses the database read in direct-learner mode. Ignored in score-select mode.

evoland_db$fit_partial_models()

Fit partial models for each viable transition using stratified sampling. Models are trained on a subsample and evaluated on held-out data, see fit_partial_models() for details.

Usage

evoland_db$fit_partial_models(
  learner,
  measures,
  sample_frac = 0.7,
  seed = NULL,
  cluster = NULL,
  trans_preds = NULL,
  trans_meta = NULL
)

Arguments

learner

An mlr3 Learner or AutoTuner R6 object.

measures

A vector of Measure names passed to mlr3::msr or a list of Measure objects for scoring the held-out split.

sample_frac

Fraction in \(0, 1\) for stratified sampling.

seed

Random seed for reproducible sampling

cluster

Optional cluster object for parallel processing

trans_preds

Optional trans_preds_t; bypasses the trans_preds_t database read.

trans_meta

Optional trans_meta_t; bypasses the trans_meta_t database read.

evoland_db$get_crossval_plots()

Get cross-validation plots for stored predictions, see get_crossval_plots()

Usage

evoland_db$get_crossval_plots(id_run = NULL, id_trans = NULL, ...)

Arguments

id_run

Optional integer; filter by run ID.

id_trans

Optional integer; filter by transition ID.

...

Passed to mlr3viz::autoplot.PredictionClassif()

evoland_db$set_full_trans_preds()

Set an initial full set of transition / predictor relations, see set_full_trans_preds()

Usage

evoland_db$set_full_trans_preds(overwrite = FALSE)

Arguments

overwrite

Logical, whether to overwrite existing trans_preds_t table. Default FALSE.

evoland_db$get_pred_filter_score()

Add filter scores to predictors for each id_run, id_trans. See get_pred_filter_score().

Usage

evoland_db$get_pred_filter_score(
  filter = "correlation",
  trans_preds = NULL,
  cluster = NULL,
  ...
)

Arguments

filter

Character passed to mlr3filters::flt or mlr3filters::Filter object specifying the filter method to use for feature selection.

trans_preds

Optional trans_preds_t; when supplied, it is used directly instead of reading from the database.

cluster

Optional cluster object for parallel processing

...

Additional arguments passed to flt.

evoland_db$predict_trans_pot()

Predict the raw transition potential for a given period and store in trans_pot_t, see predict_trans_pot(). Raw potentials are per-transition model probabilities (not yet allocation-ready); use adjusted_trans_pot_v() to obtain column-scaled, row-closed values.

Usage

evoland_db$predict_trans_pot(
  id_period_post,
  select_score,
  select_maximize,
  force = FALSE
)

Arguments

id_period_post

Integerish, posterior period of the transition potential interval

select_score

Character string; mlr3 measure ID (e.g. "classif.auc") used to select model for extrapolation

select_maximize

Logical; maximize (TRUE) or minimize (FALSE) the score.

evoland_db$get_obs_trans_rates()

Get the transition rates that were observed, see trans_rates_t

Usage

evoland_db$get_obs_trans_rates()

evoland_db$trans_rates_dinamica_v()

Usage

evoland_db$trans_rates_dinamica_v(id_period)

evoland_db$adjusted_trans_pot_v()

Usage

evoland_db$adjusted_trans_pot_v(id_period_post)

evoland_db$alloc_params_clumpy_v()

Usage

evoland_db$alloc_params_clumpy_v()

evoland_db$clone()

The objects of this class are cloneable with this method.

Usage

evoland_db$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.