{
"cells": [
{
"cell_type": "markdown",
"id": "be2c57c1-798a-4eaf-b2b8-41c261b657d1",
"metadata": {},
"source": [
"# How to read data from STAC\n",
"\n",
"This notebook shows how to read the data in from a STAC asset using [xarray](https://docs.xarray.dev/en/stable/) and a little hidden helper library called [xpystac](https://pypi.org/project/xpystac/).\n",
"\n",
"## tl;dr\n",
"\n",
"For any PySTAC object that can be represented as an ndimensional dataset you can read the data using the following command:\n",
"\n",
"```python\n",
"xr.open_dataset(object)\n",
"```\n",
"\n",
"## Dependencies\n",
"\n",
"There are lots of optional dependencies depending on where and how the data you are interested in are stored. Here are some of the libraries that you will probably need:\n",
"\n",
"- dask - to delay data loading until access\n",
"- fsspec - to access data from remote storage\n",
"- pystac - STAC object structures\n",
"- xarray, rioxarray - data structures\n",
"- xpystac, stackstac - helper for loading pystac into xarray objects"
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "11dddb09-6313-4822-90ba-26eb6e5c143b",
"metadata": {},
"outputs": [],
"source": [
"!pip install adlfs dask 'fsspec[http]' planetary_computer stackstac xarray xpystac zarr --quiet"
]
},
{
"cell_type": "markdown",
"id": "ad3fb6dc-3529-47bd-a5b3-f5260f23db88",
"metadata": {},
"source": [
"Despite all these install instructions, the import block is very straightforward"
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "2a8afebd-b397-4e7a-b448-0f59cc030e66",
"metadata": {},
"outputs": [],
"source": [
"import pystac\n",
"import xarray as xr"
]
},
{
"cell_type": "markdown",
"id": "6b24745c-b2d5-43d6-9c7e-66458b3a88e3",
"metadata": {},
"source": [
"## Examples\n",
"\n",
"Here are a few examples of the different types of objects that you can open in xarray."
]
},
{
"cell_type": "markdown",
"id": "30da7cfd-2861-4095-b15b-9952a7d824d9",
"metadata": {},
"source": [
"### COGs\n",
"\n",
"Read all the data from the COGs referenced by the assets on an item."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "c77432e6-8b0d-44d2-a947-ec74a529b8cb",
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
The relative humidity with respect to liquid water for T> 0 C, and with respect to ice for T<0 C.
long_name :
Near-Surface Relative Humidity
standard_name :
relative_humidity
units :
%
[20512224000 values with dtype=float32]
huss
(time, lat, lon)
float32
...
cell_measures :
area: areacella
cell_methods :
area: time: mean
comment :
Near-surface (usually, 2 meter) specific humidity.
long_name :
Near-Surface Specific Humidity
standard_name :
specific_humidity
units :
1
[20512224000 values with dtype=float32]
pr
(time, lat, lon)
float32
...
cell_measures :
area: areacella
cell_methods :
area: time: mean
comment :
includes both liquid and solid phases
long_name :
Precipitation
standard_name :
precipitation_flux
units :
kg m-2 s-1
[20512224000 values with dtype=float32]
rlds
(time, lat, lon)
float32
...
cell_measures :
area: areacella
cell_methods :
area: time: mean
comment :
The surface called 'surface' means the lower boundary of the atmosphere. 'longwave' means longwave radiation. Downwelling radiation is radiation from above. It does not mean 'net downward'. When thought of as being incident on a surface, a radiative flux is sometimes called 'irradiance'. In addition, it is identical with the quantity measured by a cosine-collector light-meter and sometimes called 'vector irradiance'. In accordance with common usage in geophysical disciplines, 'flux' implies per unit area, called 'flux density' in physics.
long_name :
Surface Downwelling Longwave Radiation
standard_name :
surface_downwelling_longwave_flux_in_air
units :
W m-2
[20512224000 values with dtype=float32]
rsds
(time, lat, lon)
float32
...
cell_measures :
area: areacella
cell_methods :
area: time: mean
comment :
Surface solar irradiance for UV calculations.
long_name :
Surface Downwelling Shortwave Radiation
standard_name :
surface_downwelling_shortwave_flux_in_air
units :
W m-2
[20512224000 values with dtype=float32]
sfcWind
(time, lat, lon)
float32
...
cell_measures :
area: areacella
cell_methods :
area: time: mean
comment :
near-surface (usually, 10 meters) wind speed.
long_name :
Daily-Mean Near-Surface Wind Speed
standard_name :
wind_speed
units :
m s-1
[20512224000 values with dtype=float32]
tas
(time, lat, lon)
float32
...
cell_measures :
area: areacella
cell_methods :
area: mean time: maximum
comment :
near-surface (usually, 2 meter) air temperature; derived from downscaled tasmax & tasmin
long_name :
Daily Near-Surface Air Temperature
standard_name :
air_temperature
units :
K
[20512224000 values with dtype=float32]
tasmax
(time, lat, lon)
float32
...
cell_measures :
area: areacella
cell_methods :
area: mean time: maximum
comment :
maximum near-surface (usually, 2 meter) air temperature (add cell_method attribute 'time: max')
long_name :
Daily Maximum Near-Surface Air Temperature
standard_name :
air_temperature
units :
K
[20512224000 values with dtype=float32]
tasmin
(time, lat, lon)
float32
...
cell_measures :
area: areacella
cell_methods :
area: mean time: minimum
comment :
minimum near-surface (usually, 2 meter) air temperature (add cell_method attribute 'time: min')
Dr. Rama Nemani: rama.nemani@nasa.gov, Dr. Bridget Thrasher: bridget@climateanalyticsgroup.org
creation_date :
2021-10-04T13:59:21.654137+00:00
disclaimer :
This data is considered provisional and subject to change. This data is provided as is without any warranty of any kind, either express or implied, arising by law or otherwise, including but not limited to warranties of completeness, non-infringement, accuracy, merchantability, or fitness for a particular purpose. The user assumes all risk associated with the use of, or inability to use, this data.
external_variables :
areacella
frequency :
day
history :
2021-10-04T13:59:21.654137+00:00: install global attributes
institution :
NASA Earth Exchange, NASA Ames Research Center, Moffett Field, CA 94035
product :
output
realm :
atmos
references :
BCSD method: Thrasher et al., 2012, Hydrol. Earth Syst. Sci.,16, 3309-3314. Ref period obs: latest version of the Princeton Global Meteorological Forcings (http://hydrology.princeton.edu/data.php), based on Sheffield et al., 2006, J. Climate, 19 (13), 3088-3111.
resolution_id :
0.25 degree
scenario :
historical
source :
BCSD
title :
ACCESS-CM2, r1i1p1f1, historical, global downscaled CMIP6 climate projection data