digital_earth_africa_workshop.md

About the workshop

This document will guide you through how to load data on the Digital Earth Africa Sandbox. For a live demonstration of how to set up the DE Africa Sandbox and load data, see the workshop video, recorded as part of the Open Data Cube Conference 2021.

Sign up to the Digital Earth Africa Sandbox

For this session, we’ll be working in an online Jupyter Hub Sandbox environment. The benefit of using this platform is that you can get straight into loading and working with satellite data.

Please create an account and login at https://sandbox.digitalearth.africa/

Choose an area to explore

When working on the Sandbox, you can only load small areas at a time. As such, it is a good idea to know where you want to load data.

1. Visit Digital Earth Africa Maps at https://maps.digitalearth.africa/

2. Zoom in on a location you find interesting or type a location into the search bar on the left-hand side of the interface

   After entering “Cairo” in the search bar, move the map to find an interesting feature

3. Get the coordinates for the area you’re looking at by clicking on the map.

   • Click once on the bottom-left corner of where you want to look; record the coordinates (see red circle below)
   • Click once on the top-right corner of where you want to look; record the coordinates

   

4. Click on the Explore map data button to examine the available satellite data. For this workshop, we suggest you use the Surface reflectance (Sentinel-2) product, shown below:

   

5. Scroll to the bottom of the data catalogue entry to find the layer name for the product. For Sentinel-2, this is s2_l2a (short for Sentinel-2, Level 2a). Record this so you can load the product in the Sandbox.

Set up your notebook

1. Log into the sandbox at https://sandbox.digitalearth.africa/

2. Click the “Python 3” button under the Notebook heading of the Sandbox launcher to start a new notebook

   

3. In the first cell, you’ll need to import the datacube library, and the rgb plotting function from deafrica_tools.plotting library. Type the code shown in the image below

   

4. Press “shift+enter” on your keyboard to run the cell. A red warning will appear, but this is normal

5. Next, set up the datacube.Datacube() object. This allows you to load data. Type the code shown in the image below. When you are finished, press “shift+enter” on your keyboard to run the cell

   

Load data

1. In the next cell, set the bottom, left, top and right coordinates that you recorded from your DE Africa Map exploration. To do this, follow the structure of the code below, replacing the values with those you recorded in your exploration. You’ll also need to set a start and end date for your analysis; we recommend a 2-month window to keep loading times short

   

   This code sets the following variables, which will be used to load the data:

   • bottom = 30.22678
   • left = 30.37643
   • top = 30.26126
   • right = 30.42733
   • start_date = '2019-01-01'
   • end_date = '2021-01-01'

   You can set each value individually, or use the bottom, left = (30.22678, 30.37643) syntax. The bottom, left, top and right values are in decimal degrees.

   Press “shift+enter” to set the values once you are finished.

2. In the next cell, construct the load query by following the code below

   

   This will load the data into a variable called ds, which you can then work with

   The dc.load() command specifies:

   • product = 's2_l2a': The product you selected when viewing data in DE Africa Maps
   • x = (left, right): The values you set in the previous cell (along the longitudinal axis)
   • y = (top, bottom): The values you set in the previous cell (along the latitudinal axis)
   • time = (start_date, end_date): The values you set in the previous cell
   • measurements = ['blue', 'green', 'red', 'nir']: The satellite imagery bands you want to load. In this case, we use blue, green, red and near-infrared (nir)
   • output_crs = 'EPSG:6933': The output coordinate reference system to use
   • resolution = (-10, 10): The output resolution for the data. We use (-10, 10) to specify 10-metre resolution for the latitudinal (y) and longitudinal (x) dimensions of the data.

   Press “shift+enter” to load the data once you are finished. Please be patient while the data loads, indicated by [*] to the left of the cell

3. View the data array you have loaded by typing the name of the data array variable (ds in this case) in the next cell and pressing “shift+enter” on your keyboard

   

   The Dimensions heading shows you the number of satellite observations you’ve loaded (time), as well as how many pixels you’ve loaded in the x and y dimensions

4. After viewing the data array, plot the RGB image for all the observations using the DE Africa rgb function:

   

   After typing out the function shown and pressing “shift+enter”, you should see one image for every observation you loaded

Additional Exploration

Congratulations on loading some data using the Open Data Cube Python API in the Digital Earth Africa Sandbox!

There are more Jupyter Notebooks in the Sandbox that cover various aspects of working with the Open Data Cube. These are stored in the Beginners_guide folder on the Sandbox.

To access these notebooks, double-click the Beginners_guide folder in the Jupyter file explorer.

• To learn about loading data, double-click the Beginners_guide/03_Loading_data.ipynb file.
• To learn about plotting, double-click the Beginners_guide/04_Plotting.ipynb file.
• To learn about analysing data, double-click the Beginners_guide/05_Basic_analysis.ipynb file.

Add more cells to your notebook and explore what you can do with the data. Some ideas:

• You can access each band of the data you loaded as its own array. To get the red band, type ds.red

• You can combine the bands to make a new variable using standard mathematics. For example, the normalised difference vegetation index (NDVI) is defined as

  NDVI = (near-infrared - red)/(near-infrared + red)

  See if you can work out how to calculate this index for your data. (For a guide to doing this, see the Beginners_guide/05_Basic_analysis.ipynb file).

If you want to explore how to use the Open Data Cube to analyse satellite imagery and apply it to various use cases, browse the Real_world_examples folder.