GEDI_L4B Search and Visualize

Authors: Nikita Susan (UAH), Aimee Barciauskas (DevSeed), Sumant Jha (MSFC/USRA), Alex Mandel (DevSeed)

Date: April 7, 2023

Description: In this example, we demonstrate how to access the GEDI L4B collection and granule data on the MAAP ADE, and then visualize the data using matplotlib.

Run This Notebook

To access and run this tutorial within MAAP’s Algorithm Development Environment (ADE), please refer to the “Getting started with the MAAP” section of our documentation.

Disclaimer: it is highly recommended to run a tutorial within MAAP’s ADE, which already includes packages specific to MAAP, such as maap-py. Running the tutorial outside of the MAAP ADE may lead to errors.

About the Data

GEDI L4B Gridded Aboveground Biomass Density, Version 2

This dataset provides Global Ecosystem Dynamics Investigation (GEDI) Level 4 (L4) data, which has the purpose of providing mean aboveground biomass density (AGBD) and consists of the GEDI_L4A and GEDI_L4B collections. GEDI_L4B uses a sample present within each 1km cell to statistically infer mean AGBD. GEDI is attached to the International Space Station (ISS) and collects data globally between 51.6° N and 51.6° S latitudes at the highest resolution and densest sampling of any light detection and ranging (lidar) instrument in orbit to date; specifically, GEDI L4B data has a spatial resolution of 1km. (Source: GEDI_L4B Version 2 User Guide)

Importing Packages

Within your Jupyter Notebook, start by importing the maap package. Then invoke the MAAP constructor, setting the maap_host argument to ‘api.maap-project.org’.

[22]:

from maap.maap import MAAP
from matplotlib import pyplot
import os
import pprint
import rasterio
import boto3

maap = MAAP(maap_host="api.maap-project.org")

Search for the Collection and Associated Granules

Now, we will search for the collection using the collection short name:

[23]:

collection = maap.searchCollection(cmr_host='cmr.earthdata.nasa.gov', short_name="GEDI_L4B_Gridded_Biomass_2017", limit=100)
print(collection)

[{'concept-id': 'C2244602422-ORNL_CLOUD', 'revision-id': '7', 'format': 'application/echo10+xml', 'Collection': {'ShortName': 'GEDI_L4B_Gridded_Biomass_2017', 'VersionId': '2', 'InsertTime': '2022-03-29T00:00:00Z', 'LastUpdate': '2023-06-12T20:25:17Z', 'LongName': 'GEDI L4B Gridded Aboveground Biomass Density, Version 2', 'DataSetId': 'GEDI L4B Gridded Aboveground Biomass Density, Version 2', 'Description': "This Global Ecosystem Dynamics Investigation (GEDI) L4B product provides 1 km x 1 km (1 km,  hereafter) estimates of mean aboveground biomass density (AGBD) based on observations from mission week 19 starting on 2019-04-18 to mission week 138 ending on 2021-08-04. The GEDI L4A Footprint Biomass product converts each high-quality waveform to an AGBD prediction, and the L4B product uses the sample present within the borders of each 1 km cell to statistically infer mean AGBD. The gridding procedure is described in the GEDI L4B Algorithm Theoretical Basis Document (ATBD). Patterson et al. (2019) describes the hybrid model-based mode of inference used in the L4B product. Corresponding 1 km estimates of the standard error of the mean are also provided in the L4B product. Uncertainty is due to both GEDI's sampling of the 1 km area (as opposed to making wall-to-wall observations) and the fact that L4A biomass values are modeled in a process subject to error instead of measured in a process that may be assumed to be error-free.", 'DOI': {'DOI': '10.3334/ORNLDAAC/2017', 'Authority': 'https://doi.org'}, 'Orderable': 'false', 'Visible': 'true', 'RevisionDate': '2022-03-29T00:00:00Z', 'ProcessingLevelId': '4', 'ProcessingLevelDescription': 'model products', 'ArchiveCenter': 'ORNL_DAAC', 'CitationForExternalPublication': 'Dubayah, R.O., J. Armston, S.P. Healey, Z. Yang, P.L. Patterson, S. Saarela, G. Stahl, L. Duncanson, and J.R. Kellner. 2022. GEDI L4B Gridded Aboveground Biomass Density, Version 2. ORNL DAAC, Oak Ridge, Tennessee, USA. https://doi.org/10.3334/ORNLDAAC/2017', 'CollectionState': 'COMPLETE', 'MaintenanceAndUpdateFrequency': 'As needed', 'UseConstraints': {'LicenseURL': {'URL': 'https://science.nasa.gov/earth-science/earth-science-data/data-information-policy', 'Description': 'License URL for data use policy', 'Type': 'Data Use Policy', 'MimeType': 'text/html'}}, 'Price': '0', 'DataFormat': 'GeoTIFF', 'SpatialKeywords': {'Keyword': 'GLOBAL LAND'}, 'Temporal': {'RangeDateTime': {'BeginningDateTime': '2019-04-18T00:00:00Z', 'EndingDateTime': '2021-08-04T23:59:59Z'}}, 'Contacts': {'Contact': {'Role': 'ARCHIVER', 'OrganizationName': 'ORNL_DAAC', 'OrganizationAddresses': {'Address': {'StreetAddress': 'ORNL DAAC User Services Office, P.O. Box 2008, MS 6407, Oak Ridge National Laboratory', 'City': 'Oak Ridge', 'StateProvince': 'Tennessee', 'PostalCode': '37831-6407', 'Country': 'USA'}}, 'OrganizationPhones': {'Phone': {'Number': '(865) 241-3952', 'Type': 'Direct Line'}}, 'OrganizationEmails': {'Email': 'uso@daac.ornl.gov'}}}, 'ScienceKeywords': {'ScienceKeyword': [{'CategoryKeyword': 'EARTH SCIENCE', 'TopicKeyword': 'BIOSPHERE', 'TermKeyword': 'ECOSYSTEMS', 'VariableLevel1Keyword': {'Value': 'TERRESTRIAL ECOSYSTEMS'}}, {'CategoryKeyword': 'EARTH SCIENCE', 'TopicKeyword': 'BIOSPHERE', 'TermKeyword': 'VEGETATION', 'VariableLevel1Keyword': {'Value': 'BIOMASS'}}, {'CategoryKeyword': 'EARTH SCIENCE', 'TopicKeyword': 'SPECTRAL/ENGINEERING', 'TermKeyword': 'LIDAR', 'VariableLevel1Keyword': {'Value': 'LIDAR WAVEFORM'}}]}, 'Platforms': {'Platform': {'ShortName': 'ISS', 'LongName': 'MUSES', 'Type': 'Space Stations/Crewed Spacecraft', 'Instruments': {'Instrument': {'ShortName': 'GEDI', 'LongName': 'Global Ecosystem Dynamics Investigation'}}}}, 'Campaigns': {'Campaign': {'ShortName': 'GEDI', 'LongName': 'Global Ecosystem Dynamics Investigation'}}, 'OnlineAccessURLs': {'OnlineAccessURL': {'URL': 'https://daac.ornl.gov/gedi/GEDI_L4B_Gridded_Biomass/', 'URLDescription': 'This link allows direct data access via Earthdata login'}}, 'OnlineResources': {'OnlineResource': [{'URL': 'https://daac.ornl.gov/GEDI/guides/GEDI_L4B_Gridded_Biomass.html', 'Description': 'ORNL DAAC Data Set Documentation', 'Type': "USER'S GUIDE"}, {'URL': 'https://doi.org/10.3334/ORNLDAAC/2017', 'Description': 'Data set Landing Page DOI URL', 'Type': 'DATA SET LANDING PAGE'}, {'URL': 'https://data.ornldaac.earthdata.nasa.gov/public/gedi/GEDI_L4B_Gridded_Biomass/comp/GEDI_L4B_ATBD_v1.0.pdf', 'Description': 'GEDI L4B Gridded Aboveground Biomass Density, Version 2: GEDI_L4B_ATBD_v1.0.pdf', 'Type': 'GENERAL DOCUMENTATION'}, {'URL': 'https://data.ornldaac.earthdata.nasa.gov/public/gedi/GEDI_L4B_Gridded_Biomass/comp/GEDI_L4B_Gridded_Biomass.pdf', 'Description': 'GEDI L4B Gridded Aboveground Biomass Density, Version 2: GEDI_L4B_Gridded_Biomass.pdf', 'Type': 'GENERAL DOCUMENTATION'}, {'URL': 'https://daac.ornl.gov/GEDI/guides/GEDI_L4B_Gridded_Biomass_Fig1.png', 'Description': 'Gridded mean aboveground biomass density (top) and standard error of the mean (bottom).', 'Type': 'GET RELATED VISUALIZATION', 'MimeType': 'image/png'}, {'URL': 'https://gedi.umd.edu', 'Description': 'GEDI Project Site', 'Type': 'PROJECT HOME PAGE', 'MimeType': 'text/html'}, {'URL': 'https://webmap.ornl.gov/wcsdown/dataset.jsp?ds_id=2017', 'Description': 'Web Coverage Service for this collection.', 'Type': 'WEB COVERAGE SERVICE (WCS)', 'MimeType': 'application/gml+xml'}]}, 'Spatial': {'SpatialCoverageType': 'HORIZONTAL', 'HorizontalSpatialDomain': {'Geometry': {'CoordinateSystem': 'CARTESIAN', 'BoundingRectangle': {'WestBoundingCoordinate': '-180.00', 'NorthBoundingCoordinate': '52.00', 'EastBoundingCoordinate': '180.00', 'SouthBoundingCoordinate': '-52.00'}}}, 'GranuleSpatialRepresentation': 'CARTESIAN'}, 'DirectDistributionInformation': {'Region': 'us-west-2', 'S3BucketAndObjectPrefixName': 's3://ornl-cumulus-prod-protected/gedi/GEDI_L4B_Gridded_Biomass/', 'S3CredentialsAPIEndpoint': 'https://data.ornldaac.earthdata.nasa.gov/s3credentials', 'S3CredentialsAPIDocumentationURL': 'https://data.ornldaac.earthdata.nasa.gov/s3credentialsREADME'}}}]

Next, we can search for granules using the searchGranule function and the concept ID from our collection search above:

[24]:

COLLECTIONID = collection[0]['concept-id']
results = maap.searchGranule(cmr_host='cmr.earthdata.nasa.gov',concept_id=COLLECTIONID)  # COLLECTIONID 'C2244602422-ORNL_CLOUD'
print(f'Got {len(results)} results')
results[0]['Granule']

Got 10 results

[24]:

{'GranuleUR': 'GEDI_L4B_Gridded_Biomass.GEDI04_B_MW019MW138_02_002_05_R01000M_PS.tif',
 'InsertTime': '2022-03-29T00:00:00Z',
 'LastUpdate': '2023-04-10T21:58:24Z',
 'Collection': {'ShortName': 'GEDI_L4B_Gridded_Biomass_2017',
  'VersionId': '2'},
 'DataGranule': {'DataGranuleSizeInBytes': '20103343',
  'SizeMBDataGranule': '20.103343',
  'Checksum': {'Value': '025a141348906d5e612262218c496a2d468446ca30875439be6651d851bfbe23',
   'Algorithm': 'SHA-256'},
  'DayNightFlag': 'BOTH',
  'ProductionDateTime': '2022-03-29T00:00:00Z'},
 'Temporal': {'RangeDateTime': {'BeginningDateTime': '2019-04-18T00:00:00Z',
   'EndingDateTime': '2021-08-04T23:59:59Z'}},
 'Spatial': {'HorizontalSpatialDomain': {'Geometry': {'BoundingRectangle': {'WestBoundingCoordinate': '-180',
     'NorthBoundingCoordinate': '52',
     'EastBoundingCoordinate': '180',
     'SouthBoundingCoordinate': '-52'}}}},
 'MeasuredParameters': {'MeasuredParameter': [{'ParameterName': 'LIDAR WAVEFORM'},
   {'ParameterName': 'BIOMASS'},
   {'ParameterName': 'TERRESTRIAL ECOSYSTEMS'}]},
 'Platforms': {'Platform': {'ShortName': 'ISS',
   'Instruments': {'Instrument': {'ShortName': 'GEDI'}}}},
 'Campaigns': {'Campaign': {'ShortName': 'GEDI'}},
 'Price': '0',
 'OnlineAccessURLs': {'OnlineAccessURL': [{'URL': 'https://data.ornldaac.earthdata.nasa.gov/protected/gedi/GEDI_L4B_Gridded_Biomass/data/GEDI04_B_MW019MW138_02_002_05_R01000M_PS.tif',
    'URLDescription': 'Download GEDI04_B_MW019MW138_02_002_05_R01000M_PS.tif',
    'MimeType': 'image/tiff'},
   {'URL': 'https://data.ornldaac.earthdata.nasa.gov/public/gedi/GEDI_L4B_Gridded_Biomass/data/GEDI04_B_MW019MW138_02_002_05_R01000M_PS.tif.sha256',
    'URLDescription': 'Download GEDI04_B_MW019MW138_02_002_05_R01000M_PS.tif.sha256'},
   {'URL': 's3://ornl-cumulus-prod-protected/gedi/GEDI_L4B_Gridded_Biomass/data/GEDI04_B_MW019MW138_02_002_05_R01000M_PS.tif',
    'URLDescription': 'This link provides direct download access via S3 to the granule',
    'MimeType': 'image/tiff'}]},
 'OnlineResources': {'OnlineResource': [{'URL': 'https://daac.ornl.gov/GEDI/guides/GEDI_L4B_Gridded_Biomass.html',
    'Description': 'ORNL DAAC Data Set Documentation',
    'Type': "USER'S GUIDE"},
   {'URL': 'https://doi.org/10.3334/ORNLDAAC/2017',
    'Description': 'Data set Landing Page DOI URL',
    'Type': 'DATA SET LANDING PAGE'},
   {'URL': 'https://daac.ornl.gov/daacdata/gedi/GEDI_L4B_Gridded_Biomass/comp/GEDI_L4B_ATBD_v1.0.pdf',
    'Description': 'Data Set Documentation',
    'Type': 'GENERAL DOCUMENTATION'},
   {'URL': 'https://daac.ornl.gov/daacdata/gedi/GEDI_L4B_Gridded_Biomass/comp/GEDI_L4B_Gridded_Biomass.pdf',
    'Description': 'Data Set Documentation',
    'Type': 'GENERAL DOCUMENTATION'},
   {'URL': 'https://webmap.ornl.gov/sdat/pimg/2017_9.png',
    'Description': 'GEDI L4B Gridded Prediction Stratum, Version 2, Mission Weeks 19-138',
    'Type': 'BROWSE',
    'MimeType': 'image/png'},
   {'URL': 'https://data.ornldaac.earthdata.nasa.gov/s3credentials',
    'Description': 'api endpoint to retrieve temporary credentials valid for same-region direct s3 access',
    'Type': 'VIEW RELATED INFORMATION'}]},
 'Orderable': 'false',
 'DataFormat': 'COG'}

Accessing and Downloading the Granule from ORNL DAAC S3

Before downloading, we’ll get the collection and file name:

[25]:

granule_ur=results[0]['Granule']['GranuleUR'].split(".")
collection_name=granule_ur[0]
file_name=granule_ur[1]

print(collection_name)
print(file_name)

GEDI_L4B_Gridded_Biomass
GEDI04_B_MW019MW138_02_002_05_R01000M_PS

Now we’ll proceed to get tempory s3 credentials, and then download the tif file to our workspace:

[26]:

def get_s3_creds(url):
    return maap.aws.earthdata_s3_credentials(url)

def get_s3_client(s3_cred_endpoint):
    creds=get_s3_creds(s3_cred_endpoint)
    boto3_session = boto3.Session(
            aws_access_key_id=creds['accessKeyId'],
            aws_secret_access_key=creds['secretAccessKey'],
            aws_session_token=creds['sessionToken']
    )
    return boto3_session.client("s3")

def download_s3_file(s3, bucket, collection_name, file_name):
    os.makedirs("/projects/gedi_l4b", exist_ok=True) # create directories, as necessary
    download_path=f"/projects/gedi_l4b/{file_name}.tif"
    s3.download_file(bucket, f"gedi/{collection_name}/data/{file_name}.tif", download_path)
    return download_path

[27]:

s3_cred_endpoint= 'https://data.ornldaac.earthdata.nasa.gov/s3credentials'
s3=get_s3_client(s3_cred_endpoint)

[28]:

bucket="ornl-cumulus-prod-protected"
download_path=download_s3_file(s3, bucket, collection_name, file_name)
download_path

[28]:

'/projects/gedi_l4b/GEDI04_B_MW019MW138_02_002_05_R01000M_PS.tif'

Open the local file using rasterio, and print the shape of the data to verify if the file was read properly:

[29]:

src = rasterio.open(download_path)
data = src.read(1)

print(data.shape)

(14616, 34704)

Plot the Data

Finally, we’ll use matplotlib to visualize our .tif file:

[30]:

pyplot.imshow(data)
pyplot.show()
../../_images/science_GEDI_GEDI_L4B_23_0.png