Search and download NASA hyperspectral data with HyperCoast¶
This notebook demonstrates how to search and download NASA hyperspectral data (e.g., EMIT, PACE) and ECOSTRESS temperature data with HyperCoast. Part of the source code is adapted from the NASA OB.DAAC tutorial - Access Data from the Ocean Color Instrument (OCI). Credits to the NASA OB.DAAC team.
# %pip install "hypercoast[extra]"
Import library¶
import hypercoast
Login to Earthdata¶
To download and access the data, you will need to create an Earthdata login. You can register for an account at urs.earthdata.nasa.gov.
hypercoast.nasa_earth_login()
Search for datasets¶
Collections on NASA Earthdata are discovered with the search_datasets function, which accepts an instrument filter as an easy way to get started. Each of the items in the list of collections returned has a "short-name".
results = hypercoast.search_datasets(instrument="oci")
datasets = set()
for item in results:
summary = item.summary()
short_name = summary["short-name"]
if short_name not in datasets:
print(short_name)
datasets.add(short_name)
print(f"\nFound {len(datasets)} unique datasets")
Search for data by short name¶
Next, we use the search_nasa_data function to find granules within a collection. Let's use the short_name for the PACE/OCI Level-2 data product for bio-optical and biogeochemical properties.
results = hypercoast.search_nasa_data(
short_name="PACE_OCI_L2_BGC_NRT",
count=1,
)
We can refine our search by passing more parameters that describe the spatiotemporal domain of our use case. Here, we use the temporal parameter to request a date range and the bounding_box parameter to request granules that intersect with a bounding box. We can even provide a cloud_cover threshold to limit files that have a lower percentage of cloud cover. We do not provide a count, so we'll get all granules that satisfy the constraints.
tspan = ("2024-04-01", "2024-04-16")
bbox = (-76.75, 36.97, -75.74, 39.01)
clouds = (0, 50)
results, gdf = hypercoast.search_nasa_data(
short_name="PACE_OCI_L2_BGC_NRT",
temporal=tspan,
bounding_box=bbox,
cloud_cover=clouds,
return_gdf=True,
)
Display the footprints of the granules that match the search criteria.
gdf.explore()
Displaying a single result shows a direct download link: try it! The link will download the granule to your local machine, which may or may not be what you want to do. Even if you are running the notebook on a remote host, this download link will open a new browser tab or window and offer to save a file to your local machine. If you are running the notebook locally, this may be of use.
results[0]
We can also download all the results with one command.
hypercoast.download_nasa_data(results, out_dir="data")
Search for PACE data¶
hypercoast.nasa_earth_login()
results, gdf = hypercoast.search_pace(
bounding_box=(-83, 25, -81, 28),
temporal=("2024-05-10", "2024-05-16"),
count=10, # use -1 to return all datasets
return_gdf=True,
)
gdf.explore()
Download PACE data¶
Download the first 2 files
hypercoast.download_pace(results[:2], out_dir="data")
Search for EMIT data¶
results, gdf = hypercoast.search_emit(
bounding_box=(-83, 25, -81, 28),
temporal=("2024-04-01", "2024-05-16"),
count=10, # use -1 to return all datasets
return_gdf=True,
)
gdf.explore()
Download EMIT data¶
Download the first 2 files
hypercoast.download_emit(results[:2], out_dir="data")
Download ECOSTRESS data¶
results, gdf = hypercoast.search_ecostress(
bbox=(-120.522, 34.4266, -120.2665, 34.5653),
temporal=("2023-04-01", "2023-04-02"),
count=-1, # use -1 to return all datasets
return_gdf=True,
)
gdf.explore()
hypercoast.download_ecostress(results[:5], out_dir="data")
Interactive search¶
Search for PACE data interactively.
m = hypercoast.Map(center=[27.25, -83.05], zoom=6)
m.search_pace()
m
# m._NASA_DATA_GDF.head()
# hypercoast.download_pace(m._NASA_DATA_RESULTS[:2], out_dir="data")
Search for EMIT data interactively.
m = hypercoast.Map(center=[27.25, -83.05], zoom=6)
m.search_emit()
m
# m._NASA_DATA_GDF.head()
# hypercoast.download_emit(m._NASA_DATA_RESULTS[:2], out_dir="data")
Search for ECOSTRESS data interactively.
m = hypercoast.Map(center=[34.5014, -120.4032], zoom=11)
m.search_ecostress()
m
# m._NASA_DATA_GDF.head()
# hypercoast.download_ecostress(m._NASA_DATA_RESULTS[:2], out_dir="data")