GEE and Vegetation Ecology (II) – The `.map` Function

Haoran Wu

---

In last episode I covered some basic functions to manipulate (i.e., to import, to filter, to process, and to visualise) our data. Images are the most commonly used data type, while objects of ImageCollection type are collections of images. In order to perform the same operations on all images in a collection, we need to use ee.ImageCollection.map function.

This episode aims to introduce how to write .map function to perform mathematical operations on image collections.

---

A typical script that manipulates an image collection goes like this:

// This script will not run.
// * 'imgColl'   An object of 'ImageCollection' type.
// * 'img'       An object of 'Image' type.
//                 Represents an image component in 'imgColl'.
// * 'res'       An object of 'Image' type.
//                 Represents the calculated result.
//                 Should be declared within the anonymous function.
imgColl.map(function(img){
  // Operations on each image in 'imgColl' ...
  return res;
});

However, at most of time we require other variables to involve in the calculation. Obviously, we can put an external variable directly into the body of the anonymous function. But programmers dislike the style of using external variables inside the body of a function without being declared as function parameters. A more elegant way is to use two functions:

// This script will not run.
// * 'imgColl'   An object of 'ImageCollection' type.
// * 'img'       An object of 'Image' type.
//                 Represents an image component in 'imgColl'.
// * 'img2'      An object of 'Image' type.
//                 External image that should be taken into consideration.
// * 'res'       An object of 'Image' type.
//                 Represents the calculated result.
//                 Should be declared within the anonymous function.
imgColl.map(function(img2){
  return function(img){
    // Operations on each image in 'imgColl' ...
    // May use 'img2'.
    return res;
  };
}(img2));

Note that the variable img2 is an argument, while the one in Line 10 is a parameter, according to the terminology of computer programming.

Let us take a look at an example.

// ==============================================
// NORMALISE AN IMAGE COLLECTION
// @AUTHOR: Haoran Wu, haoran.wu@wolfson.ox.ac.uk
// @TIME:   19:56 GMT 17/11/2022
// ==============================================
var ndvi = ee.ImageCollection("MODIS/061/MOD13Q1");
  // Import NDVI image collection.
var ndvi_mean = ndvi.reduce(ee.Reducer.mean());
  // Calculate avaeraged NDVI.
var ndvi_var = ndvi.reduce(ee.Reducer.variance());
  // Calculate the variance of NDVI.
 
var ndvi_norm = ndvi.map(function(ndvi_mean, ndvi_var){
  return function(img){
    return img.subtract(ndvi_mean).divide(ndvi_var);
  };
}(ndvi_mean, ndvi_var));
  // Normalisation: (X - mu) / (sigma).
 
print(ndvi_norm);

Now we cover situations of ‘ImageCollection & scalar’ and ‘ImageCollection & Image‘. The final and more complicated situation is the operation of two objects of ImageCollection type.

// This script will not run.
// * 'imgColl1'   An object of 'ImageCollection' type.
// * 'imgColl2'   An object of 'ImageCollection' type.
//                  Same size as 'imgColl1'
//                  Same bands as images in 'imgColl1'
// * 'img1'       An object of 'Image' type.
//                  Represents an image component in 'imgColl1'.
// * 'img2'       An object of 'Image' type.
//                  Represents an image component in 'imgColl2'.
// * 'res'        An object of 'Image' type.
//                  Represents the calculated result.
//                  Should be declared within the anonymous function.
ee.ImageCollection(
  ee.List.sequence({start: 1, end: imgColl1.size(), step: 1}).map(function(imgColl1, imgColl2){
    return function(index){
      var img1 = ee.Image(imgColl1.toList(imgColl1.size()).get(ee.Number(index).subtract(1)));
        // get (index-1) th image in collection 1
      var img2 = ee.Image(imgColl2.toList(imgColl2.size()).get(ee.Number(index).subtract(1)));  
        // get (index-1) th image in collection 2
       
      // Operations on 'img1' and 'img2' ...
       
      return res;
    };
}(imgColl1, imgColl2))
);

Previous: GEE and Vegetation Ecology (I) – Essential Functions of JavaScript Cheat Sheet

Next: GEE and Vegetation Ecology (III) – Managing Errors