Intake-stac

This is an intake data source for STAC catalogs.

The SpatioTemporal Asset Catalog (STAC) specification provides a common language to describe a range of geospatial information, so it can more easily be indexed and discovered. A 'spatiotemporal asset' is any file that represents information about the earth captured in a certain space and time.

Two examples of these catalogs are:

• https://planet.stac.cloud/?t=catalogs
• https://landsat-stac.s3.amazonaws.com/catalog.json

Radient Earth keeps track of a more complete listing of STAC implementations here.

This project provides an opinionated way for users to load datasets from these catalogs into the scientific Python ecosystem. Currently it uses the intake-xarray pluging and support datatypes including GeoTIFF, netCDF, GRIB, and OpenDAP. Future formats could include plain shapefile data and more.

Requirements

intake >= 0.5.1
intake-xarray >= 0.3.0
sat-stac >= 0.1.3

Installation

intake-stac will eventually be published on PyPI. For now, you can point to xarray You can install it by running the following in your terminal:

pip install git+https://github.com/pangeo-data/intake-stac

You can test the functionality by opening the example notebooks in the examples/ directory:

Usage

The package can be imported using

from intake_stac import StacCatalog, StacCollection, StacItem

Loading a catalog

You can load data from a STAC catalog by providing the URL to valid STAC catalog entry:

catalog = StacCatalog('https://storage.googleapis.com/pdd-stac/disasters/catalog.json', 'planet-disaster-data')
list(catalog)

You can also point to STAC Collections or Items. Each constructor returns a Intake Catalog with the top level corresponding to the STAC object used for initialization.

stac_cat = StacCatalog('https://landsat-stac.s3.amazonaws.com/catalog.json', 'landsat-stac')
collection_cat = StacCollection('https://landsat-stac.s3.amazonaws.com/landsat-8-l1/catalog.json', 'landsat-8')
items_cat = StacItem('https://landsat-stac.s3.amazonaws.com/landsat-8-l1/111/111/2018-11-30/LC81111112018334LGN00.json', 'LC81111112018334LGN00')

Intake-Stac uses sat-stac to parse STAC objects. You can also pass satstac objects (e.g. satstac.Collection) directly to the Intake-Stac constructors:

import satstac
col = satstac.Collection.open('https://landsat-stac.s3.amazonaws.com/landsat-8-l1/catalog.json')
collection_cat = StacCollection(col, 'landsat-8')

Using the catalog

Once you have a catalog, you can display its entries by iterating through its contents:

for entry_id, entry in catalog.items():
    display(entry)

If the catalog has too many entries to comfortably print all at once, you can narrow it by searching for a term (e.g. 'thumbnail'):

for entry_id, entry in catalog.search('thumbnail').items():
  display(entry)

Loading a dataset

Once you have identified a dataset, you can load it into a xarray.DataArray using to_dask():

da = entry.to_dask()

Roadmap

This project is in its early days. We started with this design document and have been working from there.