downscale: Downscaling of Land-Use (Change) Data

In tkrisztin/downscalr: Downscaling land-use change projections

Downscaling of Land-Use (Change) Data

Description

Performs downscaling of land-use data over specified time steps using a range of inputs, including targets, areas, explanatory variables, and priors. It supports both bias correction and non-targeted downscaling methods.

Usage

downscale(
  targets,
  start.areas,
  times = NULL,
  xmat = NULL,
  betas = NULL,
  areas.update.fun = areas.sum_to,
  xmat.coltypes = NULL,
  xmat.proj = NULL,
  xmat.dyn.fun = xmat.sum_to,
  priors = NULL,
  restrictions = NULL,
  options = downscale_control()
)

Arguments

targets	A dataframe with mandatory columns: times (character), lu.to (character), and value (numeric, all values >= 0). Optional column: lu.from (character). Represents the downscaling targets for each time step and land-use change.
start.areas	A dataframe with starting areas. Includes mandatory columns: ns (character, representing grid IDs for downscaling) and value (numeric, all areas >= 0 and sum of areas >= sum of targets). Optional column: lu.from (character).
times	A character vector of time steps for downscaling. The first time step must be present in targets. If NULL, times are derived from unique values in targets. Default is NULL.
xmat	A dataframe with explanatory variables for econometric priors. Includes columns: ns (character), ks (character), and value (numeric). If NULL, a placeholder is used. Default is NULL.
betas	A dataframe of coefficients for econometric priors. Includes columns: ks (character), lu.to (character), and value (numeric). Optional column: lu.from (character). If NULL, a placeholder is used. Default is NULL.
areas.update.fun	A function providing an update for dynamic xmat columns. Takes as arguments res, curr.areas, priors, xmat.proj and must return a dataframe with columns ns, ks, and value. Defaults to areas.sum_to(), which sums over lu.to.
xmat.coltypes	A vector ks, with each element being either "static", "dynamic", or "projected". Determines how different columns in xmat are treated during the downscaling process.
xmat.proj	A dataframe with projections. Includes columns: times (character), ns (character), ks (character), and value (numeric). Required for each xmat.coltype specified as projected.
xmat.dyn.fun	A function providing updates for dynamic xmat columns. Takes as arguments res, curr.areas, priors, xmat.proj and must return a dataframe with ⁠ns x ks(dynamic)⁠ columns.
priors	A dataframe with exogenous priors. Includes columns: times (character, optional), ns (character), lu.from (character, optional), lu.to (character), and value (numeric, >= 0). An optional weight column (numeric, 0 <= weight <= 1) can be supplied to adjust the influence of exogenous priors.
restrictions	A dataframe with restrictions. Includes columns: ns (character), lu.from (character, optional), lu.to (character), and value (numeric). Values must be either zero or one, indicating whether the MNL function should be set to zero for certain combinations.
options	A list of solver options. Use ⁠\link{downscale_control}⁠ to obtain default options and for more detailed information.

Details

The function integrates various data inputs to match p targets using either projections from an MNL-type model or exogenous priors. Appropriate input validation and preprocessing are performed before downscaling.

Value

A list containing three elements:

• out.res: A dataframe with columns times, ns, lu.from, lu.to, and value (area allocation).

• out.solver: A list detailing the solver output.

• ds.inputs: A list documenting all the inputs used in the downscaling function.

Examples

require(dplyr)
require(tidyr)
require(tibble)
betas = NULL
for (jj in unique(argentina_luc$lu.from)) {
 Y = dplyr::filter(argentina_luc,lu.from == jj & Ts == 2000) %>%
   pivot_wider(names_from = lu.to)
 X = argentina_df$xmat %>% tidyr::pivot_wider(names_from = "ks") %>%
   dplyr::arrange(match(ns,Y$ns))
 Y = Y %>% dplyr::select(-c(lu.from,Ts,ns))
 X = X %>% dplyr::select(-c(ns))
 res1 <- mnlogit(as.matrix(X), as.matrix(Y),baseline = which(colnames(Y) == jj),
          niter = 3,nburn = 2)
 betas = betas %>% dplyr::bind_rows(
  apply(res1$postb, c(1, 2), mean) %>%
  as.data.frame() %>% tibble::rownames_to_column("ks") %>%
  pivot_longer(cols = -c(1),names_to = "lu.to") %>%
  dplyr::mutate(lu.from = jj,.before="lu.to")
 )
}
ns = unique(argentina_df$lu_levels$ns)
priors = data.frame(ns = as.character(ns),lu.from="Cropland",
            lu.to="Forest",value = as.numeric(runif(length(ns))))
res1 = downscale(targets = argentina_FABLE %>% dplyr::filter(times == "2010"),
         start.areas = argentina_df$lu_levels,
         xmat = argentina_df$xmat,
         betas = betas %>% dplyr::filter(lu.from!="Cropland" | lu.to!="Forest"),
         priors = priors)

 dgp1 = sim_luc(1000,tt = 3)
 res1 = downscale(targets = dgp1$targets,start.area = dgp1$start.areas,
        xmat = dgp1$xmat,betas = dgp1$betas,times = c(1:3))

tkrisztin/downscalr documentation built on June 2, 2025, 1:16 a.m.