Package 'luh2impact'

Build pixel-level data frame with weights

Description

Rasterizes the IMPACT country shapefile to match the shares grid, merges all raster data into a pixel-level data frame, computes land pool areas, available land, and spatial weights for each pool.

Usage

luh2_build_pixels(
  luh,
  shares,
  crop_trend,
  natfor_trend,
  other_trend,
  cellarea,
  icwtr,
  cty_shp,
  landx0
)

Arguments

luh	A 'SpatRaster' of historical land use shares returned by [luh2_load()].
shares	A 'SpatRaster' of adjusted land use shares returned by [luh2_merge_planted()].
crop_trend	A single-layer 'SpatRaster' of crop slope returned by [luh2_pool_trend()].
natfor_trend	A single-layer 'SpatRaster' of natural forest slope returned by [luh2_pool_trend()].
other_trend	A single-layer 'SpatRaster' of other land slope returned by [luh2_pool_trend()].
cellarea	A single-layer 'SpatRaster' of cell areas in km².
icwtr	A single-layer 'SpatRaster' of ice/water fraction.
cty_shp	Path to the IMPACT regions shapefile. Must contain a 'NEW_REGION' field used as the country identifier.
landx0	A data frame of IMPACT land use results with columns 'cty', 'fland', 'yrs', 'value'.

Value

A data frame with one row per pixel containing areas, shares, weights, and country assignments.

Author(s)

Abhijeet Mishra, Claude Code

---

Compute per-pixel crop expansion trend

Description

Fits a linear trend over time for the sum of crop land use shares across five crop types ('c3ann', 'c4ann', 'c3per', 'c4per', 'c3nfx'), returning the slope (change per year) for each pixel.

Usage

luh2_crop_trend(luh, year_start, year_end)

Arguments

luh	A 'SpatRaster' returned by [luh2_load()].
year_start	Integer. First year of the trend period (e.g. 1990).
year_end	Integer. Last year of the trend period (e.g. 2015).

Value

A single-layer 'SpatRaster' named '"crop_slope"'.

Author(s)

Abhijeet Mishra, Claude Code

---

Export pixel data and IMPACT totals to GDX

Description

Writes all sets and parameters required by the LUMEN GAMS model into a single GDX file using 'gamstransfer'.

Usage

luh2_export_gdx(df, landx0, output_gdx)

Arguments

df	A pixel-level data frame returned by [luh2_build_pixels()].
landx0	A data frame of IMPACT land use results with columns 'cty', 'fland', 'yrs', 'value'.
output_gdx	Path to write the output GDX file.

Value

Invisibly returns 'output_gdx'. Called for its side effect.

Author(s)

Abhijeet Mishra, Claude Code

---

Extract land use areas for a target year

Description

Subsets the LUH2 raster to a single year, multiplies shares by cell area, and returns both the raw area raster and the 'cellarea' layer for downstream use.

Usage

luh2_extract_year(luh, static_nc, year)

Arguments

luh	A 'SpatRaster' returned by [luh2_load()].
static_nc	Path to the LUH2 'staticData_quarterdeg.nc' file.
year	Integer. Target year (e.g. 2015).

Value

A named list:

'luarea'

'SpatRaster' of land use areas in km² per pool.

'cellarea'

Single-layer 'SpatRaster' of cell areas in km².

'icwtr'

Single-layer 'SpatRaster' of ice/water fraction.

Author(s)

Abhijeet Mishra, Claude Code

---

Load and clean LUH2 states NetCDF

Description

Reads the LUH2 'states.nc' file and removes non-share layers ('secma', 'secmb').

Usage

luh2_load(states_nc)

Arguments

states_nc

Path to the LUH2 'states.nc' file.

Value

A 'SpatRaster' with all land use state share layers.

Author(s)

Abhijeet Mishra, Claude Code

---

Merge planted forest layer into LUH2 shares

Description

Loads a planted forest raster (e.g. from SDPT), carves out area first from 'other', then from 'natfor', and caps any residual planted share at the remaining space after all LUH2 categories. Returns adjusted share rasters.

Usage

luh2_merge_planted(luarea, cellarea, planted_tif, fstnf, cty_shp)

Arguments

luarea	A 'SpatRaster' of land use areas (km²) returned inside the list from [luh2_extract_year()].
cellarea	A single-layer 'SpatRaster' of cell areas in km² (also from [luh2_extract_year()]).
planted_tif	Path to the planted forest GeoTIFF (e.g. 'sdpt_global.tif').
fstnf	Flag if a pixel is forested or not.
cty_shp	Path to the IMPACT regions shapefile. Must contain a 'NEW_REGION' field used as the country identifier.

Value

A 'SpatRaster' of adjusted land use shares (one layer per pool, including 'planted_forest_share').

Author(s)

Abhijeet Mishra, Claude Code

---

Plot LUMEN land use results

Description

Reads GeoTIFFs written by [luh2_write_tifs()] and produces three plots:

'changes'

Faceted map of land use change vs 2021 for years 2035 and 2050, one panel per pool. Diverging red-blue palette, symmetric scale.

'shares'

Faceted map of land use shares for 2021 and 2050, faceted by pool and year.

'dominant'

Map of dominant land use pool per pixel for 2021 and 2050, coloured by pool with alpha proportional to share.

Usage

luh2_plot_results(output_dir, cty_shp, save_png = TRUE)

Arguments

output_dir	Path to directory containing 'lu_<pool>.tif' files and the solution GDX. Country name is derived via 'basename(output_dir)'.
cty_shp	Path to the IMPACT regions shapefile.
save_png	Logical. If 'TRUE' (default), saves each plot as a PNG file in 'output_dir'.

Value

A named list of 'ggplot' objects: 'changes', 'shares', 'dominant'.

Author(s)

Abhijeet Mishra, Claude Code

---

Compute per-pixel linear trend for a land use pool

Description

Sums the specified LUH2 layers for each year in the range and fits a per-pixel linear trend, returning the slope (change per year).

Usage

luh2_pool_trend(luh, pool_vars, year_start, year_end)

Arguments

luh	A 'SpatRaster' returned by [luh2_load()].
pool_vars	Character vector of LUH2 layer name prefixes to sum (e.g. 'c("c3ann", "c4ann", "c3per", "c4per", "c3nfx")' for crop, 'c("primf", "primn", "secdf")' for natural forest, 'c("secdn")' for other).
year_start	Integer. First year of the trend period (e.g. 1990).
year_end	Integer. Last year of the trend period (e.g. 2015).

Value

A single-layer 'SpatRaster' named '"pool_slope"'.

Author(s)

Abhijeet Mishra, Claude Code

---

Calculate land use suitability index from LUH2 historical data

Description

Computes a suitability index for each land pool by averaging historical land use shares over a specified time window. Pixels with consistently high shares of a given land type over centuries are considered more suitable for that land type in future projections.

Usage

luh2_suitability(luh, year_start = 1715, year_end = 2015, subsample = 10)

Arguments

luh	SpatRaster from [luh2_load()].
year_start	Integer. Start year for suitability window (e.g. 1700).
year_end	Integer. End year for suitability window (e.g. 2015).
subsample	Integer. Step size for subsampling years to speed up computation. Default is 10 (every 10th year).

Details

Land pool definitions follow LUH2 variable groupings:

• crop: c3ann, c4ann, c3per, c4per, c3nfx

• natfor: primf, secdf

• past: pastr, range

• other: primn, secdn

Within each year, variables are summed across pool members before averaging across years.

Value

SpatRaster with 4 layers: suit_crop, suit_natfor, suit_past, suit_other. Values range from 0 to 1, representing the mean share of each land pool over the specified window.

Examples

## Not run: 
luh  <- luh2_load("states.nc")
suit <- luh2_suitability(luh, year_start = 1700, year_end = 2015)
plot(suit)

## End(Not run)

---

Write GeoTIFFs from LUMEN solution GDX

Description

Reads the LUMEN solution GDX and writes one multi-layer GeoTIFF per land pool, with one layer per year. Output files are named 'lu_<pool>.tif' and written to 'output_dir'.

Usage

luh2_write_tifs(gdx_path, output_dir)

Arguments

gdx_path	Path to the LUMEN solution GDX file (e.g. '"outputs/CHM/solution_lu.gdx"').
output_dir	Path to the directory where GeoTIFFs will be written. Also used to derive the country name via 'basename(output_dir)'.

Value

Invisibly returns a named list of 'SpatRaster' objects, one per pool.

Author(s)

Abhijeet Mishra, Claude Code

---

Run the full LUH2-to-GDX pipeline

Description

Convenience wrapper that calls all processing steps in sequence and writes the final GDX file. Each intermediate step can be run and tested individually using the underlying functions.

Usage

luh2gdx(
  states_nc,
  static_nc,
  planted_tif,
  cty_shp,
  impact_gdx,
  output_gdx,
  year = 2015,
  year_start = 1990,
  year_end = 2015
)

Arguments

states_nc	Path to the LUH2 'states.nc' file.
static_nc	Path to the LUH2 'staticData_quarterdeg.nc' file.
planted_tif	Path to the planted forest GeoTIFF (e.g. 'sdpt_global.tif').
cty_shp	Path to the IMPACT regions shapefile.
impact_gdx	Path to the IMPACT scenario GDX file.
output_gdx	Path to write the output GDX file.
year	Integer. Target baseline year to extract from LUH2 (e.g. 2015).
year_start	Integer. Start year for trend estimation (e.g. 1990).
year_end	Integer. End year for trend estimation (e.g. 2015).

Value

Invisibly returns the path to the written GDX file.

Author(s)

Abhijeet Mishra, Claude Code

---