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.
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) # 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 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