Announcing MODIS Tools 1.0

Fraym is excited to launch the official 1.0 version of our first open source project: MODIS Tools! MODIS Tools is a Python library to easily download MODIS imagery from the NASA Earthdata platform, and is released under the Apache-2.0 license.

Why it exists

Fraym relies on access to high quality earth observation data to inform our mapping and surface prediction work, particularly from the MODIS family of imagery. Previously, the most common ways to access MODIS data were via NASA-provided standalone scripts, manual interaction with the Earth Explorer platform, or using the pre-existing pyModis library. 

We wanted a simple, reusable tool that could seamlessly integrate with our geospatial data processing workflows. That ruled out the first two choices. The pyModis library is a great open source library that we’ve used in the past, but it has far more features (and therefore dependencies) than we needed and we found ourselves looking for additional flexibility. As such, with MODIS Tools, we focused on building out the ability to easily interact with various Earthdata API endpoints with minimal overhead and maximum flexibility.

Collaboration is one of Fraym’s core values. Just as our work depends on access to high quality data in the public domain, we fully recognize the importance of open source libraries to our own tech stack. We’re very excited to release MODIS Tools as our first contribution back to the wider open source community and hope that it helps to enhance public access to an important source of geospatial data.

Key features

Lightweight – MODIS Tools has a minimal set of dependencies for querying the Earthdata APIs, downloading the data, and nothing more.

Flexible – Each major Earthdata API has a corresponding MODIS Tools class so the download workflow is as decomposable as you need. All Earthdata API endpoint query parameters are supported. 

Simple – Instead of specifying individual MODIS tiles by number (e.g. “h35, v17”), automatically select tiles by passing in a geometry object or bounding box instead.

Fast – Multithreaded downloading allows you to speed up large data transfers.

Intelligent – Automatically checks your download destination to avoid downloading duplicate files unnecessarily

How it works

First, install MODIS Tools into your environment of choice:

pip install modis-tools

NASA’s Earthdata portal organizes MODIS data into collections, products, and granules. MODIS Tools provides a series of classes to search MODIS collection metadata for products, select the tiles you want, and download granules from the results of those queries. All you need are Earthdata account credentials and the desired MODIS product’s short name and version. 

First, authenticate a ModisSession with your Earthdata credentials:

from modis-tools.auth import ModisSession
from modis-tools.resources import CollectionApi

username = "
password = "

# Reusable session
session = ModisSession(username=username, password=password)

# Or as a context manager
with ModisSession(username=username, password=password) as session:
    ...

Then instantiate a client for the Collection API and query it with the MODIS product details:

from modis-tools.resources import CollectionApi

collection_client = CollectionApi(session=session)

# Collections query returns a list of matching collections
collections = collection_client.query(short_name="MOD13A1", version="006")

Once you’ve found the right collection, select the granules you want and query the Granule API with further filters. 

# Create a GranuleApi from a Collection
granule_client = GranuleApi.from_collection(collections[0])

# Granules collection returns a generator with matching granules
granules = granule_client.query(limit=50)

You can optionally filter the granule query with spatial and temporal filters:

from datetime import datetime

# Query by date range
start_date = datetime(2017, 12, 31)
end_date = datetime(2018, 12, 31)
granules = granule_client.query(start_date=start_end, end_date=end_date)

# Query by spatial extent
df = gpd.read_file("/Users/leith/Desktop/mwi_country.geojson")
geom = df.geometry[0]
malawi_granules = granule_client.query(start_date="2017-01-01", end_date="2018-12-31", spatial=geom)

The spatial object passed to the spatial argument can be OGR Geometry objects, shapely geometry objects, or GeoJSON geometries. Alternatively, you may pass a bounding box to the bounding_box argument. All coordinates should be in longitude, latitude format. Most query parameters for the Collections API and Granules API in the Earthdata documentation are supported.

Finally, download the MODIS data for your selected granules with GranuleHandler, optionally specifying a destination path and/or whether to use multithreaded downloading:

# Basic usage
GranuleHandler.download_from_granules(granules, session=session)

# Specifying an output path
GranuleHandler.download_from_granules(granules, session=session, path="../Desktop")

# Specifying number of threads to use, -1 is all cores
GranuleHandler.download_from_granules(granules, modis_session=session, threads=-1)

MODIS Tools is an open source project. If there are features you would like to see or build, all contributions and/or feature requests are welcome via the project Github repository.

Fraym Open Source Team: Christina Paton, Jamie Sgro, Jonathan Tan, Leith McIndewar