Skip to main content

MODIS Tools

MODIS Tools is a Python library to easily (and quickly) download MODIS imagery from the NASA Earthdata platform.

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.

Example

After adding your username and password, the snippet below will download MOD13A1 granules for Nigeria for 2016, 2017, and 2018 to the current directory.

from modis_tools.auth import ModisSession
from modis_tools.resources import CollectionApi, GranuleApi
from modis_tools.granule_handler import GranuleHandler

username = ""  # Update this line
password = ""  # Update this line

# Authenticate a session
session = ModisSession(username=username, password=password)

# Query the MODIS catalog for collections
collection_client = CollectionApi(session=session)
collections = collection_client.query(short_name="MOD13A1", version="006")

# Query the selected collection for granules
granule_client = GranuleApi.from_collection(collections[0], session=session)

# Filter the selected granules via spatial and temporal parameters
nigeria_bbox = [2.1448863675, 4.002583177, 15.289420717, 14.275061098]
nigeria_granules = granule_client.query(start_date="2016-01-01", end_date="2018-12-31", bounding_box=nigeria_bbox)

# Download the granules
GranuleHandler.download_from_granules(nigeria_granules, session)

Further Details and Options

Authentication

With username and password:

from modis_tools.auth import ModisSession
from modis_tools.resources import CollectionApi

username = ""
password = ""

# Reusable session
session = ModisSession(username=username, password=password)
collection_client = CollectionApi(session=session)
# - or -
collection_client = CollectionApi(username=username, password=password)

With session as context manager

...
with ModisSession(username=username, password=password) as session:
    collection_client = CollectionApi(session=session)
    ...

Using a netrc file, you can create clients without authentication:

from modis_tools.auth import add_earthdata_netrc, remove_earthdata_netrc

username = ""
password = ""
# Create an entry for Earthdata in the ~/.netrc file, only needs to be run once
add_earthdata_netrc(username, password)

...
# Now sessions can be created without passing username and password explicitly
session = ModisSession()
granule_client = GranuleApi()

# You can remove the credentials if necessary. It will only remove
# the Earthdata entry
remove_earthdata_netrc()
...

Query Parameters

You can interact with the Earthdata Search API to browse collections and granules via the CollectionApi and GranuleApi classes respectively. Most query parameters for collections and granules listed in the Earthdata documentation can be passed directly to either class's query() method.

Note: To specify a modifier for a parameter (eg. parameter[option]), you'll need to unpack it from a dictionary: **{"parameter[option]": "value"} rather than passing it directly as a keyword argument.

Note: Response models for both classes' query() methods can be found in modis_tools/models.py.

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

# Create a GranuleApi from a Collection, the `concept_id` search parameter is set
# to the collection
granule_client = GranuleApi.from_collection(collections[0])
# Granules collection returns a generator with matching granules
granules = granule_client.query(start_date="2019-02-02", limit=50)

Some parameters will be preprocessed and formatted. You can also use the raw parameters shown in the Earthdata documentation, but you'll have to make sure the format is correct.

Time parameters

Time ranges can be defined by at least one of start_date and end_date that can be passed as datetime.datetime objects, or strings/dicts/tuples that can be parsed to datetime objects. time_delta can be a datetime.timedelta object or something that can be parsed to one.

from datetime import datetime, timedelta

# Any of the following definitions work for both `start_date` and `end_date`
start_date = datetime(2017, 12, 31)
start_date = {"year": 2017, "month": 12, "day": 31}
start_date = "2017-12-31"
start_date = (2017, 12, 31)

# Any of the following definitions for time_delta will create a one year time range.
# Sign of time delta doesn't matter, it will be determined by whether start or end
# is provided
time_delta = timedelta(365)
time_delta = 365 # Days is the default unit for time_delta
time_delta = {"weeks": 52, "days": 1}

end_date = datetime(2018, 12, 31)

# With the above parameters, the following three will query the same time range
granules = granule_client.query(start_date=start_end, end_date=end_date)
granules = granule_client.query(time_delta=time_delta, start_date=start_date)
granules = granule_client.query(time_delta=time_delta, end_date=end_date)

# If only one of start or end is provided, the date query is open ended
granules = granule_client.query(start_date=start_end)

Spatial parameters

The spatial and bounding_box parameters for collections and granules will parse ogr Geometrys, shapely geometrys (used by geopandas), or GeoJSONs features/geometries. Multipolygons and geometry collections are converted to convex hulls for simpler queries. All spatial queries should be in (longitude, latitude) order.

If bounding box is a geometry object, the envelope will be calculated. As a list or tuple, bounding box should be in the order (xmin, ymin, xmax, ymax).

import geopandas as gpd

df = gpd.read_file("/Users/leith/Desktop/dhs_mwi.geojson")
geom = df.geometry[0]

malawi_granules = granule_client.query(start_date="2017-01-01", end_date="2018-12-31", spatial=geom)

...
from osgeo import ogr

ds = ogr.GetDriverByName("GeoJSON").Open("drc.geojson")
l = ds.GetLayer()
feat = l.GetNextFeature()

drc_granules = granule_client.query(start_date="2015-09-01", bounding_box=feat.geometry)

Downloading

The return value of a query with the GranuleAPI is a generator. This avoids calling the MODIS API more than is immediately needed if more than one page of results is found.

Iterating through a generator consumes it. If you need to reuse the values, convert it to a list with list(granules).

GranuleHandler.download_from_granules(granules, session=session)

# Files paths can be traced from the granule return values
file_paths = GranuleHandler.download_from_granules(granules, session=session)

# Saves to current directory, use `path` to save somewhere else
GranuleHandler.download_from_granules(granules, session=session, path="../Desktop")

Multithreaded Downloads

The threads parameter in GranuleHandler.download_from_granules() specifies how many concurrent processes or threads should be used while downloading.

threads is an integer, specifying the maximum number of concurrently running workers.

  • If 1 is given, no parallelism is used at all, which is useful for debugging.
  • If set to -1, all CPUs are used.
  • For threads below -1, (n_cpus + 1 + n_jobs) are used. For example with threads=-2, all CPUs but one are used.
GranuleHandler.download_from_granules(nigeria_granules, modis_session=session, threads=-1)

MODIS Data Types

Currently modis_tools only supports downloading of hdf file type.

Development and Testing

Setting up a development environment

  • To install all production dependencies, run:

    pip install -r requirements.txt
    
  • To install dev-dependencies to run tests, run:

    pip install -e .[test]
    
  • Note that gdal is optionally supported as an extra dependency. This is for users who wish to use ogr.Geometry objects to spatially query the modis data to be retrieved. Assuming you have all the libraries installed to run gdal, you can install this dependency with:

    pip install -e .[gdal]
    
  • To install more than one extra dependency-set, separate them with a comma as seen in the below example. The full list of supported dependency-sets are listed under extras_require in setup.py:

    pip install -e .[test,gdal]
    

Testing

  1. All tests can be found in ./tests with a directory structure mirroring the directory structure of the files being tested
  2. To run tests, navigate terminal to the root of this repo, and
    1. To run only unit tests (faster) run the following: pytest -m "not integration_test"
    2. To run only integration tests (slower) run the following: pytest -m integration_test
    3. To run the whole test suit, run: pytest

Metadata

Release files for modis-tools 1.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for modis-tools 1.1.0
File Size Uploaded Provenance Actions
modis_tools-1.1.0.tar.gz 22.9 kB Without provenance Details for modis_tools-1.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for modis-tools 1.1.0
File Interpreter ABI Platform Actions
modis_tools-1.1.0-py3-none-any.whl Python 3 none any Details for modis_tools-1.1.0-py3-none-any.whl

Total release size: 46.5 kB

Release files / modis_tools-1.1.0.tar.gz

Download URL modis_tools-1.1.0.tar.gz
Size 22.9 kB
Tags Source
SHA-256 checksum
How to use checksums
c2cc428748780ab02dcb8e1c0f45a574c90e9b248e4b7c5c0db932cbfe748d2f
BLAKE2b-256 checksum
How to use checksums
f16433482413c36237a7f8ab7ac9888d145824d7f2c4d2f204ce69ecb7655954
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.9.12

Release files / modis_tools-1.1.0-py3-none-any.whl

Download URL modis_tools-1.1.0-py3-none-any.whl
Size 23.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
588909d052a7869636c521b2928c9c19a147a748eab0dc755521d16beffa8238
BLAKE2b-256 checksum
How to use checksums
5bdd0df17d5685384190cd39ca4a8b048014922f796fc8e35b3fd580f4c49000
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/4.0.1 CPython/3.9.12

Security for modis-tools 1.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page