Lab 22 - Time Series Charting

Before You Start

• Prerequisites: Image Collections module, Spectral Indices module, Time Series Charting module.
• Estimated time: 40 minutes
• You will need: GEE Code Editor access

Lab Instructions

In this lab, we'll analyze NDVI dynamics near Gainesville, Florida. We'll compare forest, cropland, and urban areas, then create a spatial map of vegetation trends across the region. Let's get started.

Part 1 - Define sample points

First, we need three sample points representing different land cover types. We'll label each one so that our charts display meaningful legend entries.

// Define three sample points near Gainesville, FL
var forest = ee.Geometry.Point([-82.35, 29.65]);
var cropland = ee.Geometry.Point([-82.5, 29.5]);
var urban = ee.Geometry.Point([-82.32, 29.65]);

// Create a labeled FeatureCollection
var regions = ee.FeatureCollection([
  ee.Feature(forest, {'label': 'Forest'}),
  ee.Feature(cropland, {'label': 'Cropland'}),
  ee.Feature(urban, {'label': 'Urban'})
]);

// Add points to the map for reference
Map.centerObject(regions, 10);
Map.addLayer(forest, {color: 'green'}, 'Forest Point');
Map.addLayer(cropland, {color: 'orange'}, 'Cropland Point');
Map.addLayer(urban, {color: 'red'}, 'Urban Point');

Understanding the code:

• ee.Feature(geometry, properties) creates a feature with a location and metadata. The 'label' property is what the chart will use as each series name.
• ee.FeatureCollection([]) groups the three features into a collection that charting functions can iterate over.

Part 2 - Build a cloud-masked NDVI collection

Let's load four years of Landsat 8 imagery (2020 through 2023), apply cloud masking, and compute NDVI for every image. Four years gives us enough data to spot real trends.

// Cloud masking function for Landsat 8 SR
function maskL8sr(image) {
  var qaMask = image.select('QA_PIXEL').bitwiseAnd(1 << 3).eq(0)
      .and(image.select('QA_PIXEL').bitwiseAnd(1 << 4).eq(0));
  return image.updateMask(qaMask)
      .multiply(0.0000275).add(-0.2);
}

// Load Landsat 8 collection for 2020-2023
var collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2')
  .filterDate('2020-01-01', '2023-12-31')
  .filterBounds(regions)
  .filter(ee.Filter.lt('CLOUD_COVER', 30))
  .map(maskL8sr)
  .map(function(img) {
    var ndvi = img.normalizedDifference(['SR_B5', 'SR_B4']).rename('NDVI');
    return img.addBands(ndvi);
  });

print('Total images in collection:', collection.size());

Understanding the code:

• The .map(maskL8sr) call applies cloud masking to every image in the collection.
• The second .map() adds an NDVI band to each image using .normalizedDifference().
• Four years of data provides enough observations for reliable trend detection.

Part 3 - Chart NDVI at a single point

Let's use ui.Chart.image.series() to plot NDVI over time at the forest point. This chart will reveal the seasonal cycle and overall trajectory. Let's see it in action.

// Chart NDVI at the forest point
var forestChart = ui.Chart.image.series({
  imageCollection: collection.select('NDVI'),
  region: forest,
  reducer: ee.Reducer.mean(),
  scale: 30
}).setOptions({
  title: 'NDVI Time Series - Forest (2020-2023)',
  vAxis: {title: 'NDVI', minValue: 0, maxValue: 1},
  hAxis: {title: 'Date'},
  lineWidth: 1,
  pointSize: 3,
  series: {0: {color: 'green'}}
});

print(forestChart);

Understanding the code:

• ui.Chart.image.series() extracts NDVI from every image at the specified point and plots it as a time series.
• ee.Reducer.mean() averages the pixel values within the region (for a single point, it simply returns the value at that pixel).
• .setOptions() customizes the chart with titles, axis labels, colors, and point sizes.

Part 4 - Compare all three land cover types

Here's where it gets interesting. Let's plot all three land cover types on the same chart using ui.Chart.image.seriesByRegion(). This reveals how each land cover responds differently to seasonal cycles.

// Chart NDVI for all three regions
var comparisonChart = ui.Chart.image.seriesByRegion({
  imageCollection: collection.select('NDVI'),
  regions: regions,
  reducer: ee.Reducer.mean(),
  band: 'NDVI',
  scale: 30,
  seriesProperty: 'label'
}).setOptions({
  title: 'NDVI by Land Cover Type (2020-2023)',
  vAxis: {title: 'NDVI', minValue: 0, maxValue: 1},
  hAxis: {title: 'Date'},
  lineWidth: 1,
  pointSize: 3,
  series: {
    0: {color: 'orange'},
    1: {color: 'green'},
    2: {color: 'gray'}
  }
});

print(comparisonChart);

Understanding the code:

• seriesByRegion() creates a separate line for each feature in the FeatureCollection.
• seriesProperty: 'label' uses the label property from each feature as the legend name.
• The series option assigns colors to each line (the order matches the FeatureCollection order).

Part 5 - Detect NDVI trends with linear regression

Now let's get quantitative. We'll apply ee.Reducer.linearFit() to figure out whether NDVI is increasing or decreasing over the four-year period. First, we need to add a time band to each image.

// Add a time band to each image (fractional years since 2020)
var withTime = collection.map(function(img) {
  var ndvi = img.select('NDVI');
  var timeImage = ee.Image.constant(
    img.date().difference('2020-01-01', 'year')
  ).float().rename('time');
  return ndvi.addBands(timeImage);
});

// Apply linear regression (bands must be in order: time, NDVI)
var trend = withTime.select(['time', 'NDVI'])
  .reduce(ee.Reducer.linearFit());

// Print trend values at each sample point
print('Forest trend:', trend.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: forest, scale: 30, maxPixels: 1e9
}));
print('Cropland trend:', trend.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: cropland, scale: 30, maxPixels: 1e9
}));
print('Urban trend:', trend.reduceRegion({
  reducer: ee.Reducer.mean(),
  geometry: urban, scale: 30, maxPixels: 1e9
}));

Understanding the code:

• img.date().difference('2020-01-01', 'year') converts each image date to fractional years since January 1, 2020. This makes the slope interpretable as "NDVI change per year."
• ee.Reducer.linearFit() expects bands in order: independent variable (time) first, dependent variable (NDVI) second.
• The result has two bands: scale (the slope) and offset (the intercept).

Part 6 - Map the trend spatially

Let's apply the trend analysis to every pixel in the study area to create a spatial map of greening and browning. We'll use a diverging color palette so that greening pixels show up green and browning pixels show up red.

// Visualize the slope (trend) spatially
Map.addLayer(trend.select('scale'), {
  min: -0.05,
  max: 0.05,
  palette: ['red', 'orange', 'lightyellow', 'lightgreen', 'darkgreen']
}, 'NDVI Trend (2020-2023)');

// Add reference points on top
Map.addLayer(regions, {color: 'blue'}, 'Sample Points');

// Add a true color basemap for context
var composite = collection.median();
Map.addLayer(composite, {
  bands: ['SR_B4', 'SR_B3', 'SR_B2'],
  min: 0, max: 0.3
}, 'True Color Composite', false);

Understanding the code:

• trend.select('scale') extracts only the slope band from the linear fit result.
• The diverging palette centers on light yellow (no change), with green for positive slopes and red for negative slopes.
• The min and max of -0.05 to 0.05 represent a range of 0.05 NDVI units change per year.
• The true color composite is added but turned off by default (false parameter). Toggle it on for context.