Merge 20-create-transition-rate-table into main

Author: mmyrte

AGENTS.md

@@ -0,0 +1,66 @@
+# How to interact with the evoland-plus codebase
+
+_Naturally, this is also handy for human devs._
+
+This is the codebase for evoland-plus, or evoland for short.
+It is an R package that is used for land use / land cover change analyses and simulations.
+The main concept that differentiates this package from e.g. <https://github.com/simonmoulds/lulcc> is that the data are processed in tabular form.
+This enables the storage and processing of sparse domains.
+
+Storage is done in parquet files written and read via duckdb, with the domain-agnostic DB implementation in `R/parquet_duckdb.R`. 
+Using a normal duckdb file is very inefficient in terms of storage/compression; the parquet files have the advantage of being writable by other software, so they should be considered part of the interface and schema changes should be avoided as much as possible.
+The domain specific elements are in the `R/evoland_db*.R` files.
+When working on in-memory tables, S3 objects inheriting from data.tables are used for efficiency.
+Regular data.frame-like objects can be coerced to these classes using `as_` functions, e.g. `as_lulc_data_t()`.
+Classes of source data or "materialized" expensive calculation results are suffixed with `_t` to differentiate them from cheap `_v` views on the database.
+
+## Environment setup
+
+If there is no renv environment set up (check if "renv.lock" exists) ask the user if you can set up an renv development environment.
+You can efficiently initialize an renv like so from the project root directory:
+
+```sh
+R -e "install.packages('renv', repos = 'https://cloud.r-project.org'); renv::init(bare = TRUE); install.packages('pak'); pak::local_install_dev_deps(); pak::pkg_install('devtools')"
+```
+
+There may be issues where .Rprofile already contains a source("renv/activate.R") line, or where renv.lock or the renv folder exist.
+These need to be deleted before installation can be successful.
+
+## Dependencies
+
+You are allowed to suggest new dependencies, but make sure the user knows why they are needed.
+Avoid packages from the tidyverse, as their APIs tend to shift around over the years.
+Avoid niche packages that are seldom maintained; if the functionality is simple, rather implement it as a non-exported utility function.
+
+## Code Style
+
+We use the tidyverse style in general.
+This repo uses air as its principal formatter. Config in `air.toml`.
+The user may have the languageserver R package installed, meaning `.lintr` directives should also be picked up.
+Pay attention to linter warnings, but only once the main functionality is implemented.
+
+Don't add comments where the code's purpose is self-explanatory.
+Don't check for missingness or nullness to avoid errors: only catch errors early if the emitted error would be hard to understand for the user.
+Generally, use the `stopifnot("error message" = condition)` pattern if something could fail in a hard to understand manner.
+
+## Documentation
+
+The package uses roxygen, so you can use `R -e "roxygen2::roxygenize()"` to make sure the Rd documentation is up to date.
+Tutorials are written as quarto files in `vignettes/*.qmd`.
+A pkgdown github action transforms all of this into a webpage, see `.github/workflows/pkgdown.yaml`.
+
+## Testing
+
+This repo uses tinytest (not testthat) for conducting tests not only during development (i.e. when the full package namespace is attached via `pkgload::load_all()`), but also after installation.
+This means that non-exported functions need to be tested as `evoland:::private_function`.
+You can test the full package using `R -e "tinytest::build_test_install()"`.
+You can test individual files using `R -e "pkgload::load_all(); tinytest::run_test_file('inst/tinytest/somefile.R')"`
+
+While tests should be comprehensive, the full test suite should remain small enough to test often.
+Don't overwhelm the user, add 10 tests at a time, then ask for feedback before continuing.
+
+## Rcpp components
+
+C++ code is in the `src/` folder.
+This code interfaces with R using Rcpp; you can make sure the binaries are built using `pkbuild::build()` and clean dlls using `pkgbuild::clean_dll()`
+If there is no low-hanging use case for writing a standalone C++ program/header, prefer to use the Rcpp namespace and take advantage of the data types that affords.

DESCRIPTION

@@ -62,6 +62,7 @@ Collate:
     'trans_models_rf.R'
     'trans_models_t.R'
     'trans_preds_t.R'
+    'trans_rates_t.R'
     'util.R'
     'util_dinamica.r'
     'util_download.R'

NAMESPACE

@@ -15,6 +15,7 @@ S3method(print,pred_meta_t)
 S3method(print,trans_meta_t)
 S3method(print,trans_models_t)
 S3method(print,trans_preds_t)
+S3method(print,trans_rates_t)
 S3method(validate,alloc_params_t)
 S3method(validate,coords_t)
 S3method(validate,default)
@@ -34,6 +35,7 @@ S3method(validate,reporting_t)
 S3method(validate,trans_meta_t)
 S3method(validate,trans_models_t)
 S3method(validate,trans_preds_t)
+S3method(validate,trans_rates_t)
 export(as_alloc_params_t)
 export(as_coords_t)
 export(as_intrv_masks_t)
@@ -48,12 +50,15 @@ export(as_reporting_t)
 export(as_trans_meta_t)
 export(as_trans_models_t)
 export(as_trans_preds_t)
+export(as_trans_rates_t)
 export(covariance_filter)
 export(create_coords_t_square)
+export(create_extr_trans_rates_t)
 export(create_intrv_meta_t)
 export(create_intrv_meta_t_row)
 export(create_lulc_meta_t)
 export(create_neighbors_t)
+export(create_obs_trans_rates_t)
 export(create_periods_t)
 export(create_pred_meta_t)
 export(create_trans_meta_t)

R/evoland_db_tables.R

@@ -16,6 +16,7 @@
 #' - `pred_meta_t` - Predictor metadata. See [as_pred_meta_t()]
 #' - `trans_meta_t` - Transition metadata. See [as_trans_meta_t()]
 #' - `trans_preds_t` - Transition-predictor relationships. See [as_trans_preds_t()]
+#' - `trans_rates_t` - Transition rates by period. See [as_trans_rates_t()]
 #' - `intrv_meta_t` - Intervention metadata. See [as_intrv_meta_t()]
 #' - `intrv_masks_t` - Intervention masks. See [as_intrv_masks_t()]
 #' - `trans_models_t` - Transition models. See [as_trans_models_t()]
@@ -155,6 +156,15 @@ evoland_db$set("active", "trans_preds_t", function(x) {
   )(x)
 })
 
+evoland_db$set("active", "trans_rates_t", function(x) {
+  create_table_binding(
+    self,
+    "trans_rates_t",
+    as_trans_rates_t,
+    key_cols = c("id_period", "id_trans")
+  )(x)
+})
+
 evoland_db$set("active", "intrv_meta_t", function(x) {
   create_table_binding(
     self,

R/evoland_db_views.R

@@ -8,13 +8,14 @@
 #'
 #' - `lulc_meta_long_v` - Unrolled LULC metadata with one row per source class
 #' - `pred_sources_v` - Distinct predictor URLs and their MD5 checksums
-#' - `transitions_v` - Land use transitions derived from lulc_data_t
+#' - `trans_v` - Land use transitions derived from lulc_data_t
 #' - `extent` - Spatial extent of coords_t as terra::SpatExtent
 #' - `coords_minimal` - Minimal coordinate representation (id_coord, lon, lat)
 #'
 #' @section Methods Added:
 #'
 #' - `trans_pred_data_v(id_trans)` - Returns wide table of transition results and predictor data for a specific transition. Used as input to covariance filtering.
+#' - `trans_rates_dinamica_v(id_period)` - Returns transition rates formatted for Dinamica export for a specific period.
 #'
 #' @name evoland_db_views
 #' @include evoland_db.R
@@ -49,7 +50,7 @@ evoland_db$set("active", "pred_sources_v", function() {
   })
 })
 
-evoland_db$set("active", "transitions_v", function() {
+evoland_db$set("active", "trans_v", function() {
   self$with_tables("lulc_data_t", function() {
     self$get_query(glue::glue(
       r"{
@@ -137,8 +138,8 @@ evoland_db$set(
           stop(glue::glue("Transition id_trans = {id_trans} not found in trans_meta_t"))
         }
 
-        id_lulc_ant <- trans_info$id_lulc_anterior
-        id_lulc_post <- trans_info$id_lulc_posterior
+        id_lulc_ant <- trans_info[["id_lulc_anterior"]]
+        id_lulc_post <- trans_info[["id_lulc_posterior"]]
 
         ctes <- list()
 
@@ -304,3 +305,37 @@ evoland_db$set(
     )
   }
 )
+
+# get transition rates formatted for Dinamica export
+# id_period - integer period ID for which to export rates
+evoland_db$set(
+  "public",
+  "trans_rates_dinamica_v",
+  function(id_period) {
+    stopifnot(
+      "id_period must be a single integer" = {
+        length(id_period) == 1L && id_period == as.integer(id_period)
+      }
+    )
+
+    self$with_tables(
+      c("trans_rates_t", "trans_meta_t"),
+      function() {
+        result <- self$get_query(glue::glue(
+          "SELECT
+            m.id_lulc_anterior as \"From*\",
+            m.id_lulc_posterior as \"To*\",
+            r.rate as \"Rate\"
+          FROM
+            trans_rates_t r,
+            trans_meta_t m
+          WHERE
+            r.id_trans = m.id_trans
+            AND r.id_period = {id_period}"
+        ))
+
+        result
+      }
+    )
+  }
+)

R/trans_meta_t.R

@@ -6,7 +6,7 @@
 #'
 #' @name trans_meta_t
 #'
-#' @param transitions A transitions_v table, with columns id_coord, id_lulc_anterior,
+#' @param transitions A trans_v table, with columns id_coord, id_lulc_anterior,
 #' id_lulc_posterior, id_period
 #' @param min_cardinality_abs Minimum absolute number of transitions for viability (optional)
 #' @param min_frequency_rel Minimum relative frequency of transitions for viability (optional)
@@ -62,6 +62,7 @@ create_trans_meta_t <- function(
   # Aggregate transitions by type and calculate frequencies
   trans_summary <-
     transitions[
+      # excludes non-transitions
       id_lulc_anterior != id_lulc_posterior
     ][,
       .(cardinality = .N),