Radiant MLHub Logo

How to use the Radiant MLHub API to browse and download the LandCoverNet dataset

This Jupyter notebook, which you may copy and adapt for any use, shows basic examples of how to use the API to download labels and source imagery for the LandCoverNet dataset. Full documentation for the API is available at docs.mlhub.earth.

We'll show you how to set up your authorization, list collection properties, and retrieve the items (the data contained within them) from those collections.

Each item in our collection is explained in json format compliant with STAC label extension definition.

Citation

Alemohammad S.H., Ballantyne A., Bromberg Gaber Y., Booth K., Nakanuku-Diggs L., & Miglarese A.H. (2020) "LandCoverNet: A Global Land Cover Classification Training Dataset", Version 1.0, Radiant MLHub. [Date Accessed] https://doi.org/10.34911/rdnt.d2ce8i

Dependencies

This notebook utilizes the radiant-mlhub Python client for interacting with the API. If you are running this notebooks using Binder, then this dependency has already been installed. If you are running this notebook locally, you will need to install this yourself.

See the official radiant-mlhub docs for more documentation of the full functionality of that library.

Authentication

Create an API Key

Access to the Radiant MLHub API requires an API key. To get your API key, go to dashboard.mlhub.earth. If you have not used Radiant MLHub before, you will need to sign up and create a new account. Otherwise, sign in. In the API Keys tab, you'll be able to create API key(s), which you will need. Do not share your API key with others: your usage may be limited and sharing your API key is a security risk.

Configure the Client

Once you have your API key, you need to configure the radiant_mlhub library to use that key. There are a number of ways to configure this (see the Authentication docs for details).

For these examples, we will set the MLHUB_API_KEY environment variable. Run the cell below to save your API key as an environment variable that the client library will recognize.

If you are running this notebook locally and have configured a profile as described in the Authentication docs, then you do not need to execute this cell.

In [ ]:
import os
from radiant_mlhub import Dataset

os.environ['MLHUB_API_KEY'] = 'PASTE_YOUR_API_KEY_HERE'

Listing Collection Properties

The following cell makes a request to the API for the properties for the LandCoverNet labels collection and prints out a few important properties.

In [ ]:
dataset = Dataset.fetch('ref_landcovernet_af_v1')

print(f'Title: {dataset.title}')
print(f'DOI: {dataset.doi}')
print(f'Citation: {dataset.citation}')
print('\nCollection IDs and License:')
for collection in dataset.collections:
    print(f'    {collection.id} - {collection.license}')

Downloading Assets

NOTE: If you are running these notebooks using Binder these resources will be downloaded to the remote file system that the notebooks are running on and not to your local file system. If you want to download the files to your machine, you will need to clone the repo and run the notebook locally.

This next cell will call the dataset download function with a filter specified which only downloads the labels assets within the ref_landcovernet_af_v1_labels collection. For more information about filtering downloads, reference the collection and asset key filtering method in the Python client documenation.

In [ ]:
asset_filter = dict(
    ref_landcovernet_af_v1_labels=['labels'],
)

dataset.download(collection_filter=asset_filter)

Download All Assets

The following cell uses the dataset.download function to download the ref_landcovernet_af_v1 dataset to the current working directory.

In [ ]:
dataset.download()