Skip to main content

​
Overview

The barplotLand() function creates a grouped bar plot showing the areas of land use and cover (LUC) categories at each time point in the analyzed period. This visualization helps track how category extents change over time.

​
Function Signature

barplotLand(
  dataset,
  legendtable,
  title = NULL,
  caption = "LUC Categories",
  xlab = "Year",
  ylab = "Area (km2 or pixel)",
  area_km2 = TRUE,
  ...
)

​
Parameters

​
dataset
data.frame
required
A table of multi-step transitions (lulc_Multistep) generated by contingencyTable().
​
legendtable
data.frame
required
A table containing the LUC legend items and their respective colors (tb_legend).
​
title
character
default:"NULL"
The title of the plot. Use NULL for no title.
​
caption
character
default:"LUC Categories"
The caption/title for the legend.
​
xlab
character
default:"Year"
Label for the x-axis.
​
ylab
character
default:"Area (km2 or pixel)"
Label for the y-axis.
​
area_km2
logical
default:"TRUE"
If TRUE, areas are shown in km²; if FALSE, in pixel counts.
​
...
additional arguments
Additional theme parameters passed to ggplot2::theme(). Use this to customize plot appearance.

​
Return Value

Returns a ggplot2 bar plot object showing:
  • X-axis: Time points (years)
  • Y-axis: Area (km² or pixel count)
  • Grouped bars: One bar per category at each time point
  • Color coding: Based on the legend table

​
Usage Examples

​
Basic Bar Plot

library(OpenLand)

# Prepare the legend
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")
)

SL_2002_2014$tb_legend$color <- c(
  "#FFE4B5", "#228B22", "#00FF00", "#CAFF70", "#EE6363", "#00CD00",
  "#436EEE", "#FFAEB9", "#FFA54F", "#68228B", "#636363"
)

# Create bar plot
barplotLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend,
  area_km2 = TRUE
)

​
With Custom Labels and Title

barplotLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend,
  title = "Land Use Category Distribution Over Time",
  caption = "Land Use Categories",
  xlab = "Time Point",
  ylab = bquote("Area (" ~ km^2 ~ ")"),
  area_km2 = TRUE
)

​
Using Pixel Counts

barplotLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend,
  ylab = "Number of Pixels",
  area_km2 = FALSE
)

​
Advanced Customization

​
Custom ggplot2 Theme

Use the ... parameter to pass additional theme customization: 
barplotLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend,
  title = "São Lourenço Basin Land Use (2002-2014)",
  xlab = "Year",
  ylab = bquote("Area (" ~ km^2 ~ ")"),
  # Additional ggplot2 theme parameters
  plot.title = element_text(size = 16, face = "bold"),
  axis.text.x = element_text(angle = 45, hjust = 1),
  legend.position = "bottom",
  panel.background = element_rect(fill = "white"),
  panel.grid.major = element_line(color = "gray90")
)

​
Combining with ggplot2 Layers

Since the function returns a ggplot2 object, you can add additional layers: 
library(ggplot2)

barplotLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend
) +
  theme_minimal() +
  theme(
    legend.position = "right",
    axis.text = element_text(size = 12)
  ) +
  scale_y_continuous(labels = scales::comma)

​
Saving the Plot

As a ggplot2 object, save using ggsave(): 
# Create the plot
p <- barplotLand(
  dataset = SL_2002_2014$lulc_Multistep,
  legendtable = SL_2002_2014$tb_legend,
  title = "Land Use Distribution"
)

# Save as PNG
ggsave(
  "barplot_land.png",
  plot = p,
  width = 12,
  height = 6,
  dpi = 300
)

# Save as PDF for publication
ggsave(
  "barplot_land.pdf",
  plot = p,
  width = 12,
  height = 6
)

​
Interpretation Guide

​
Reading the Plot

  • Each year has a group of bars, one per category
  • Bar height represents the area of that category at that time point
  • Color identifies the category (from legend table)
  • Changes over time are visible by comparing bars of the same color across years

​
Example Analysis

# Look for:
# 1. Categories that increase over time (bars getting taller)
# 2. Categories that decrease over time (bars getting shorter)
# 3. Stable categories (consistent bar height)
# 4. Dominant categories (tallest bars at each time point)
This plot shows the state (area) of each category at each time point, not the transitions between them. For transition visualization, use sankeyLand() or chordDiagramLand().

​
Comparison with Other Plots

Plot TypeShowsBest For
barplotLand()Category areas at each time pointTracking category extent over time
netgrossplot()Net vs. gross change totalsUnderstanding change magnitude and direction
sankeyLand()Transitions between categoriesVisualizing flows and transitions
chordDiagramLand()One-step transitionsCompact visualization of bidirectional flows
Use barplotLand() to identify which categories are expanding or contracting, then use intensity analysis to understand why.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us