Tutorial¶
Intake-stac simply provides a thin interface that combines sat-stac and Intake. It’s basic usage is shown below:
To begin, import intake:
In [1]: import intake
Loading a catalog¶
You can load data from a STAC Catalog by providing the URL to valid STAC Catalog:
In [2]: catalog = intake.open_stac_catalog(
...: 'https://storage.googleapis.com/pdd-stac/disasters/catalog.json',
...: name='planet-disaster-data'
...: )
...:
In [3]: list(catalog)
Out[3]:
['20170831_172754_101c',
'2017831_195552_SS02',
'20170831_195425_SS02',
'20170831_162740_ssc1d1',
'Houston-East-20170831-103f-100d-0f4f-RGB']
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:
In [4]: stac_cat = intake.open_stac_catalog(
...: 'https://landsat-stac.s3.amazonaws.com/catalog.json',
...: name='landsat-stac'
...: )
...:
In [5]: collection_cat = intake.open_stac_collection(
...: 'https://landsat-stac.s3.amazonaws.com/landsat-8-l1/catalog.json',
...: name='landsat-8'
...: )
...:
In [6]: items_cat = intake.open_stac_item(
...: 'https://landsat-stac.s3.amazonaws.com/landsat-8-l1/111/111/2018-11-30/LC81111112018334LGN00.json',
...: name='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:
In [7]: import satstac
In [8]: col = satstac.Collection.open(
...: 'https://landsat-stac.s3.amazonaws.com/landsat-8-l1/catalog.json'
...: )
...:
In [9]: collection_cat = open_stac_collection(col, name='landsat-8')
Using the catalog¶
Once you have a catalog, you can display its entries by iterating through its contents:
In [10]: for id, entry in catalog.items():
....: display(entry)
....:
name: 20170831_172754_101c
container: catalog
plugin: ['stac_item']
description:
direct_access: True
user_parameters: []
metadata:
args:
stac_obj: 20170831_172754_101c
name: 2017831_195552_SS02
container: catalog
plugin: ['stac_item']
description:
direct_access: True
user_parameters: []
metadata:
args:
stac_obj: 2017831_195552_SS02
name: 20170831_195425_SS02
container: catalog
plugin: ['stac_item']
description:
direct_access: True
user_parameters: []
metadata:
args:
stac_obj: 20170831_195425_SS02
name: 20170831_162740_ssc1d1
container: catalog
plugin: ['stac_item']
description:
direct_access: True
user_parameters: []
metadata:
args:
stac_obj: 20170831_162740_ssc1d1
name: Houston-East-20170831-103f-100d-0f4f-RGB
container: catalog
plugin: ['stac_item']
description:
direct_access: True
user_parameters: []
metadata:
args:
stac_obj: Houston-East-20170831-103f-100d-0f4f-RGB
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’):
In [11]: for id, entry in catalog.search('thumbnail').items():
....: display(entry)
....:
name: thumbnail
container: xarray
plugin: ['xarray_image']
description: Thumbnail
direct_access: True
user_parameters: []
metadata:
href: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/20170831_172754_101c_thumb_large.png
title: Thumbnail
type: image/png
args:
urlpath: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/20170831_172754_101c_thumb_large.png
chunks:
name: thumbnail
container: xarray
plugin: ['xarray_image']
description: Thumbnail
direct_access: True
user_parameters: []
metadata:
href: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/SkySat_20170831T195552Z_RGB.png
title: Thumbnail
type: image/png
args:
urlpath: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/SkySat_20170831T195552Z_RGB.png
chunks:
name: thumbnail
container: xarray
plugin: ['xarray_image']
description: Thumbnail
direct_access: True
user_parameters: []
metadata:
href: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/SkySat_PortArthur_s02_20170831T195425Z.png
title: Thumbnail
type: image/png
args:
urlpath: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/SkySat_PortArthur_s02_20170831T195425Z.png
chunks:
name: thumbnail
container: xarray
plugin: ['xarray_image']
description: Thumbnail
direct_access: True
user_parameters: []
metadata:
href: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/SkySat_Freeport_s03_20170831T162740Z.png
title: Thumbnail
type: image/png
args:
urlpath: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/SkySat_Freeport_s03_20170831T162740Z.png
chunks:
name: thumbnail
container: xarray
plugin: ['xarray_image']
description: Thumbnail
direct_access: True
user_parameters: []
metadata:
href: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/Houston-East-20170831-103f-100d-0f4f-3-band.png
title: Thumbnail
type: image/png
args:
urlpath: https://storage.googleapis.com/pdd-stac/disasters/hurricane-harvey/0831/Houston-East-20170831-103f-100d-0f4f-3-band.png
chunks:
Loading a dataset¶
Once you have identified a dataset, you can load it into a xarray.DataArray
using Intake’s to_dask() method:
In [12]: da = entry.to_dask()
In [13]: display(da)
<xarray.DataArray (y: 552, x: 549, channel: 3)>
dask.array<xarray-<this-array>, shape=(552, 549, 3), dtype=uint8, chunksize=(552, 549, 3), chunktype=numpy.ndarray>
Coordinates:
* y (y) int64 0 1 2 3 4 5 6 7 8 ... 543 544 545 546 547 548 549 550 551
* x (x) int64 0 1 2 3 4 5 6 7 8 ... 540 541 542 543 544 545 546 547 548
* channel (channel) int64 0 1 2
Working with sat-search¶
Intake-stac integrates with sat-search to faciliate dynamic search and discovery of assets through a STAC-API. To begin, construct a search query using sat-search:
In [14]: import satsearch
In [15]: results = satsearch.Search.search(
....: collection='landsat-8-l1',
....: bbox=[43.16, -11.32, 43.54, -11.96],
....: sort=['<datetime'], #earliest scene first
....: property=["landsat:tier=T1"])
....:
In [16]: items = results.items()
In [17]: display(items)
<satstac.itemcollection.ItemCollection at 0x7fb95b9267b8>
In the code section above, items is a satstac.ItemsCollection object. Intake-stac can turn this object into an Intake catalog:
In [18]: catalog = intake.open_stac_item_collection(items)
In [19]: list(catalog)
Out[19]:
['LC81630682019093',
'LC81620682019102',
'LC81620692019102',
'LC81630682019109',
'LC81620682019118',
'LC81620692019118',
'LC81620682019134',
'LC81620692019134',
'LC81630682019141',
'LC81620682019150',
'LC81620692019150',
'LC81620682019166',
'LC81620692019166',
'LC81620682019182',
'LC81620692019182',
'LC81630682019189',
'LC81620682019198',
'LC81620692019198',
'LC81630682019205',
'LC81620682019214',
'LC81620692019214',
'LC81620682019230',
'LC81620692019230',
'LC81620682019246',
'LC81620692019246',
'LC81620682019262',
'LC81620692019262',
'LC81620682019278',
'LC81630682019285',
'LC81620682019294',
'LC81620692019294',
'LC81630682019301',
'LC81630682019317',
'LC81620682019326',
'LC81620692019326',
'LC81630682019333',
'LC81620682019358',
'LC81620692019358',
'LC81620682020009',
'LC81620692020009',
'LC81630682020032',
'LC81620682020041',
'LC81620692020041',
'LC81630682020048']