Quickstart Guide

Overview

This quickstart guide will walk you through a complete land use and cover change (LUCC) analysis workflow using OpenLand. You’ll learn how to load data, run intensity analysis, and create visualizations.

Prerequisites

Before starting, make sure you have:

R version 3.4.0 or higher installed
OpenLand package installed (installation guide)
Basic familiarity with R programming

Complete Example Workflow

We’ll use the São Lourenço Basin dataset, which comes bundled with OpenLand. This dataset contains five land use maps (2002, 2008, 2010, 2012, and 2014) covering approximately 22,400 km² in Brazil’s Pantanal wetland region.

Load the OpenLand package

Start by loading the package and accessing the sample dataset:

library(OpenLand)

# The SL_2002_2014 dataset is included with the package
# It contains pre-computed contingency tables
data(SL_2002_2014)

# View the structure
names(SL_2002_2014)

The SL_2002_2014 dataset has already been processed with contingencyTable(). For your own raster data, see the Raster Input Guide.

Customize category names and colors

Edit the legend table to use meaningful category names and colors:

# Set category names (Portuguese acronyms from original study)
SL_2002_2014$tb_legend$categoryName <- factor(
  c("Ap", "FF", "SA", "SG", "aa", "SF", "Agua", "Iu", "Ac", "R", "Im"),
  levels = c("FF", "SF", "SA", "SG", "aa", "Ap", "Ac", "Im", "Iu", "Agua", "R")
)

# Set colors (one per category in factor order)
SL_2002_2014$tb_legend$color <- c(
  "#FFE4B5",  # Ap - Pasture
  "#228B22",  # FF - Dense Forest
  "#00FF00",  # SA - Savannah
  "#CAFF70",  # SG - Gramineous Savannah
  "#EE6363",  # aa - Water (annual)
  "#00CD00",  # SF - Semi-deciduous Forest
  "#436EEE",  # Agua - Water
  "#FFAEB9",  # Iu - Non-vegetated
  "#FFA54F",  # Ac - Agriculture
  "#68228B",  # R - Reforestation
  "#636363"   # Im - Mosaic
)

Run intensity analysis

Perform three-level intensity analysis, specifying categories of interest:

# Run intensity analysis
# Ap (Pasture) is gaining category
# SG (Gramineous Savannah) is losing category
results <- intensityAnalysis(
  dataset = SL_2002_2014,
  category_n = "Ap",  # Target gaining category
  category_m = "SG"   # Target losing category
)

# The function returns 6 objects
names(results)
# [1] "lulc_table"           "interval_lvl"         
# [3] "category_lvlGain"     "category_lvlLoss"     
# [5] "transition_lvlGain_n" "transition_lvlLoss_m"

Choose category_n as a category that experienced significant gains and category_m as one with notable losses. This focuses the transition-level analysis on the most relevant patterns.

Visualize interval-level results

Plot the interval-level analysis to see change rates over time:

# Plot interval-level intensity
plot(results$interval_lvl,
     labels = c(leftlabel = "Interval Change Area (km²)", 
                rightlabel = "Annual Change Rate (%)"),
     marginplot = c(.3, .3),
     labs = c("Time Interval", "Uniform Rate"))

This plot shows whether change is accelerating, decelerating, or remaining steady across time intervals.

Visualize category-level results

Examine which categories are gaining and losing area:

# Plot category gains
plot(results$category_lvlGain,
     labels = c(leftlabel = bquote("Gain Area (" ~km^2~ ")"),
                rightlabel = "Intensity Gain (%)"),
     marginplot = c(.3, .3),
     labs = c("Categories", "Uniform intensity"),
     fontsize_ui = 8)

# Plot category losses
plot(results$category_lvlLoss,
     labels = c(leftlabel = bquote("Loss Area (" ~km^2~ ")"),
                rightlabel = "Intensity Loss (%)"),
     marginplot = c(.3, .3),
     labs = c("Categories", "Uniform intensity"),
     fontsize_ui = 8)

Visualize transition-level results

Understand which categories Pasture (Ap) is gaining from, and where Gramineous Savannah (SG) is losing to:

# Plot transitions TO Pasture (category_n)
plot(results$transition_lvlGain_n,
     labels = c(leftlabel = bquote("Gain of Ap (" ~km^2~ ")"),
                rightlabel = "Intensity of Gain from Category j (%)"),
     marginplot = c(.3, .3),
     labs = c("Other Categories", "Uniform intensity"))

# Plot transitions FROM Gramineous Savannah (category_m)
plot(results$transition_lvlLoss_m,
     labels = c(leftlabel = bquote("Loss of SG (" ~km^2~ ")"),
                rightlabel = "Intensity of Loss to Category i (%)"),
     marginplot = c(.3, .3),
     labs = c("Other Categories", "Uniform intensity"))

Create additional visualizations

Generate other useful plots to communicate your findings:

# Net and gross changes
netgrossplot(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend,
  xlab = "LUC Category",
  ylab = bquote("Area (" ~ km^2 ~ ")"),
  changesLabel = c(GC = "Gross changes", NG = "Net Gain", NL = "Net Loss"),
  color = c(GC = "gray70", NG = "#006400", NL = "#EE2C2C")
)

# Chord diagram (one-step transitions)
chordDiagramLand(
  dataset = SL_2002_2014$lulc_Onestep,
  legendtable = SL_2002_2014$tb_legend
)

# Category areas over time
barplotLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend,
  area_km2 = TRUE
)

Working with Your Own Data

To analyze your own raster time series:

library(OpenLand)
library(raster)

# 1. Load your rasters (must be named: name_year.tif)
my_rasters <- stack("path/to/rasters/")

# 2. Create contingency tables
ct <- contingencyTable(
  input_raster = my_rasters,
  pixelresolution = 30  # Your pixel size in meters
)

# 3. Edit legend (category names and colors)
ct$tb_legend$categoryName <- factor(
  c("Forest", "Agriculture", "Urban", "Water"),
  levels = c("Forest", "Agriculture", "Urban", "Water")
)

ct$tb_legend$color <- c("#228B22", "#FFD700", "#FF0000", "#0000FF")

# 4. Run intensity analysis
results <- intensityAnalysis(
  dataset = ct,
  category_n = "Urban",       # Gaining category
  category_m = "Forest"       # Losing category
)

# 5. Plot results
plot(results$interval_lvl)

Your raster files must follow the naming convention {name}_{year}.tif (e.g., landscape_2020.tif). Learn more in the Data Preparation Guide.

Understanding the Output

The intensityAnalysis() function returns an S4 object with six components:

Component	Type	Description
`lulc_table`	data.frame	Contingency table of all transitions
`interval_lvl`	Interval S4	Interval-level analysis comparing change rates across time periods
`category_lvlGain`	Category S4	Category-level analysis of gross gains
`category_lvlLoss`	Category S4	Category-level analysis of gross losses
`transition_lvlGain_n`	Transition S4	Transition-level analysis: sources of gains for category n
`transition_lvlLoss_m`	Transition S4	Transition-level analysis: destinations of losses from category m

Each S4 object contains:

Slot 1: lookupcolor - Color mapping for categories
Slot 2: Data table with analysis results
Slot 3: Stationarity test results

Interpreting Results

Stationarity Tests

Each analysis level includes stationarity tests that determine if patterns are consistent across time intervals:

“Y” (Yes): Pattern is stationary - consistent across time
“N” (No): Pattern is non-stationary - varies across time

For example, an “Active Gain” with stationarity = “N” means the category is actively gaining at intensities that vary across time intervals.

Key Metrics

St (Interval level): Observed annual rate of change in an interval
U (Uniform rate): Expected rate if change was uniform across all intervals
Gtj / Lti (Category level): Observed gain/loss intensity for a category
Rtin / Qtmj (Transition level): Observed transition intensity between specific categories

When observed intensity > uniform intensity, the change is considered “active” or “targeted”. When observed < uniform, it’s “dormant” or “avoided”.

Next Steps

Core Concepts

Dive deeper into the intensity analysis methodology

Visualization Guide

Learn about all visualization options and customization

API Reference

Explore detailed function documentation

Examples

See complete real-world case studies

Common Issues

Error: 'From' and 'To' columns not found

Make sure your contingency table was created with contingencyTable(). This error occurs when using incorrectly formatted data.

Plot shows no arrows or annotations

Check that your marginplot parameter provides enough space. Try marginplot = c(.3, .3) or larger values.

Category names appear as numbers

You need to edit the tb_legend$categoryName column with factor levels. See Step 2 above.

Colors don't match categories

Ensure colors are in the same order as the factor levels in categoryName, not the original category values.

References

Aldwaik, S. Z., & Pontius, R. G. (2012). Intensity analysis to unify measurements of size and stationarity of land changes by interval, category, and transition. Landscape and Urban Planning, 106(1), 103-114. https://doi.org/10.1016/j.landurbplan.2012.02.010

Getting Started

Core Concepts

Guides

Examples

Overview

Prerequisites

Complete Example Workflow

Working with Your Own Data

Understanding the Output

Interpreting Results

Stationarity Tests

Key Metrics

Next Steps

Core Concepts

Visualization Guide

API Reference

Examples

Common Issues

References

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Examples

​Overview

​Prerequisites

​Complete Example Workflow

​Working with Your Own Data

​Understanding the Output

​Interpreting Results

​Stationarity Tests

​Key Metrics

​Next Steps

Core Concepts

Visualization Guide

API Reference

Examples

​Common Issues

​References

Build docs developers (and LLMs) love

Overview

Prerequisites

Complete Example Workflow

Working with Your Own Data

Understanding the Output

Interpreting Results

Stationarity Tests

Key Metrics

Next Steps

Common Issues

References