# Import the following libraries
# For fetching from the Raster API
import requests
# For making maps
import folium
import folium.plugins
from folium import Map, TileLayer
# For talking to the STAC API
from pystac_client import Client
# For working with data
import pandas as pd
# For making time series
import matplotlib.pyplot as plt
# For formatting date/time data
import datetime
# Custom functions for working with GHGC data via the API
import ghgc_utils
OCO-2 GEOS Column CO₂ Concentrations
Access this Notebook
You can launch this notebook in the US GHG Center JupyterHub by clicking the link below. If you are a new user, you should first sign up for the hub by filling out this request form and providing the required information.
Access the OCO-2 GEOS Column CO₂ Concentrations notebook in the US GHG Center JupyterHub.
Table of Contents
Data Summary and Application
- Spatial coverage: Global
- Spatial resolution: 0.5° x 0.625°
- Temporal extent: January 1, 2015 - February 28, 2022
- Temporal resolution: Daily
- Unit: Parts per million
- Utility: Climate Research
For more, visit the OCO-2 GEOS Column CO₂ Concentrations data overview page.
Approach
- Identify available dates and temporal frequency of observations for the given collection using the GHGC API
/stac
endpoint. The collection processed in this notebook is the OCO-2 GEOS Column CO₂ Concentrations data product. - Pass the STAC item into the raster API
/collections/{collection_id}/items/{item_id}/tilejson.json
endpoint. - Using
folium.plugins.DualMap
, visualize two tiles (side-by-side), allowing time point comparison. - After the visualization, perform zonal statistics for a given polygon.
About the Data
OCO-2 GEOS Column CO2 Concentrations
In July 2014, NASA successfully launched the first dedicated Earth remote sensing satellite to study atmospheric carbon dioxide (CO₂) from space. The Orbiting Carbon Observatory-2 (OCO-2) is an exploratory science mission designed to collect space-based global measurements of atmospheric CO₂ with the precision, resolution, and coverage needed to characterize sources and sinks (fluxes) on regional scales (≥1000 km). This dataset provides global gridded, daily column-averaged carbon dioxide (XCO₂) concentrations from January 1, 2015 - February 28, 2022. The data are derived from OCO-2 observations that were input to the Goddard Earth Observing System (GEOS) Constituent Data Assimilation System (CoDAS), a modeling and data assimilation system maintained by NASA’s Global Modeling and Assimilation Office (GMAO). Concentrations are measured in moles of carbon dioxide per mole of dry air (mol CO₂/mol dry) at a spatial resolution of 0.5° x 0.625°. Data assimilation synthesizes simulations and observations, adjusting modeled atmospheric constituents like CO₂ to reflect observed values. With the support of NASA’s Carbon Monitoring System (CMS) Program and the OCO Science Team, this dataset was produced as part of the OCO-2 mission which provides the highest quality space-based XCO₂ retrievals to date.
For more information regarding this dataset, please visit the OCO-2 GEOS Column CO₂ Concentrations data overview page.
Terminology
Navigating data via the GHGC API, you will encounter terminology that is different from browsing in a typical filesystem. We’ll define some terms here which are used throughout this notebook. - catalog
: All datasets available at the /stac
endpoint - collection
: A specific dataset, e.g. OCO-2 GEOS Column CO2 Concentrations - item
: One granule in the dataset, e.g. one daily file of CO2 concentrations - asset
: A variable available within the granule, e.g. XCO2 or XCO2 precision - STAC API
: SpatioTemporal Asset Catalogs - Endpoint for fetching metadata about available datasets - Raster API
: Endpoint for fetching data itself, for imagery and statistics
Install the Required Libraries
Required libraries are pre-installed on the GHG Center Hub. If you need to run this notebook elsewhere, please install them with this line in a code cell:
%pip install requests folium rasterstats pystac_client pandas matplotlib –quiet
Query the STAC API
STAC API Collection Names
Now, you must fetch the dataset from the STAC API by defining its associated STAC API collection ID as a variable. The collection ID, also known as the collection name, for the OCO-2 GEOS Column CO2 Concentrations dataset is oco2geos-co2-daygrid-v10r.*
**You can find the collection name of any dataset on the GHGC data portal by navigating to the dataset landing page within the data catalog. The collection name is the last portion of the dataset landing page’s URL, and is also listed in the pop-up box after clicking “ACCESS DATA.”*
# Provide STAC and RASTER API endpoints
= "https://earth.gov/ghgcenter/api/stac"
STAC_API_URL = "https://earth.gov/ghgcenter/api/raster"
RASTER_API_URL
# Please use the collection name similar to the one used in STAC collection.
# Name of the collection for OCO-2 GEOS Column CO₂ Concentrations.
= "oco2geos-co2-daygrid-v10r" collection_name
Examining the contents of our collection
under the temporal
variable, we see that the data is available from January 2015 to February 2022. By looking at the dashboard:time density
, we can see that these observations are collected daily.
# Using PySTAC client
# Fetch the collection from the STAC API using the appropriate endpoint
# The 'pystac' library allows a HTTP request possible
= Client.open(STAC_API_URL)
catalog = catalog.get_collection(collection_name)
collection
# Print the properties of the collection to the console
collection
- type "Collection"
- id "oco2geos-co2-daygrid-v10r"
- stac_version "1.0.0"
- description "This dataset provides global gridded, daily column-averaged carbon dioxide (XCO₂) concentrations from January 1, 2015 - February 28, 2022. The data are derived from Orbiting Carbon Observatory-2 (OCO-2) satellite observations that were input to the Goddard Earth Observing System (GEOS) Constituent Data Assimilation System (CoDAS), a modeling and data assimilation system maintained by NASA’s Global Modeling and Assimilation Office (GMAO). Concentrations are measured in moles of carbon dioxide per mole of dry air (mol CO₂/mol dry) at a spatial resolution of 0.5° x 0.625°. Data assimilation synthesizes simulations and observations, adjusting modeled atmospheric constituents like CO₂ to reflect observed values. With the support of NASA’s Carbon Monitoring System (CMS) Program and the OCO Science Team, this dataset was produced as part of the OCO-2 mission which provides the highest quality space-based XCO₂ retrievals to date. The source data can be found at https://doi.org/10.5067/Y9M4NM9MPCGH"
links[] 5 items
0
- rel "items"
- href "https://earth.gov/ghgcenter/api/stac/collections/oco2geos-co2-daygrid-v10r/items"
- type "application/geo+json"
1
- rel "parent"
- href "https://earth.gov/ghgcenter/api/stac/"
- type "application/json"
2
- rel "root"
- href "https://earth.gov/ghgcenter/api/stac"
- type "application/json"
- title "US GHG Center STAC API"
3
- rel "self"
- href "https://earth.gov/ghgcenter/api/stac/collections/oco2geos-co2-daygrid-v10r"
- type "application/json"
4
- rel "http://www.opengis.net/def/rel/ogc/1.0/queryables"
- href "https://earth.gov/ghgcenter/api/stac/collections/oco2geos-co2-daygrid-v10r/queryables"
- type "application/schema+json"
- title "Queryables"
stac_extensions[] 2 items
- 0 "https://stac-extensions.github.io/render/v1.0.0/schema.json"
- 1 "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json"
renders
xco2
assets[] 1 items
- 0 "xco2"
- nodata 0
rescale[] 1 items
0[] 2 items
- 0 412
- 1 422
- colormap_name "magma"
dashboard
assets[] 1 items
- 0 "xco2"
- nodata 0
rescale[] 1 items
0[] 2 items
- 0 412
- 1 422
- colormap_name "magma"
item_assets
xco2
- type "image/tiff; application=geotiff; profile=cloud-optimized"
roles[] 2 items
- 0 "data"
- 1 "layer"
- title "Average Dry-Air Column CO₂ (XCO₂)"
- description "Daily dry air column-averaged mole fractions of carbon dioxide created from data assimilations of OCO-2 satellite retrievals."
xco2prec
- type "image/tiff; application=geotiff; profile=cloud-optimized"
roles[] 2 items
- 0 "data"
- 1 "layer"
- title "Average Dry-Air Column CO₂ Precision (XCO₂PREC)"
- description "Random errors for daily dry air column-averaged mole fractions of carbon dioxide calculated using a posteriori diagnostics."
- dashboard:is_periodic True
- dashboard:time_density "day"
- title "OCO-2 GEOS Column CO₂ Concentrations v10r"
extent
spatial
bbox[] 1 items
0[] 4 items
- 0 -180.0
- 1 -90.0
- 2 180.0
- 3 90.0
temporal
interval[] 1 items
0[] 2 items
- 0 "2015-01-01T00:00:00Z"
- 1 "2022-02-28T00:00:00Z"
- license "CC0-1.0"
summaries
datetime[] 2 items
- 0 "2015-01-01T00:00:00Z"
- 1 "2022-02-28T00:00:00Z"
# Check total number of items available
#items = list(collection.get_items()) # Convert the iterator to a list
#print(f"Found {len(items)} items")
# Examining the first item in the collection
#items[0]
# The search function lets you search for items within a specific date/time range
= catalog.search(
search =collection_name,
collections=['2016-03-01T00:00:00Z','2016-07-31T00:00:00Z']
datetime
)# Take a look at the items we found
for item in search.item_collection():
print(item)
<Item id=oco2geos-co2-daygrid-v10r-20160731>
<Item id=oco2geos-co2-daygrid-v10r-20160730>
<Item id=oco2geos-co2-daygrid-v10r-20160729>
<Item id=oco2geos-co2-daygrid-v10r-20160728>
<Item id=oco2geos-co2-daygrid-v10r-20160727>
<Item id=oco2geos-co2-daygrid-v10r-20160726>
<Item id=oco2geos-co2-daygrid-v10r-20160725>
<Item id=oco2geos-co2-daygrid-v10r-20160724>
<Item id=oco2geos-co2-daygrid-v10r-20160723>
<Item id=oco2geos-co2-daygrid-v10r-20160722>
<Item id=oco2geos-co2-daygrid-v10r-20160721>
<Item id=oco2geos-co2-daygrid-v10r-20160720>
<Item id=oco2geos-co2-daygrid-v10r-20160719>
<Item id=oco2geos-co2-daygrid-v10r-20160718>
<Item id=oco2geos-co2-daygrid-v10r-20160717>
<Item id=oco2geos-co2-daygrid-v10r-20160716>
<Item id=oco2geos-co2-daygrid-v10r-20160715>
<Item id=oco2geos-co2-daygrid-v10r-20160714>
<Item id=oco2geos-co2-daygrid-v10r-20160713>
<Item id=oco2geos-co2-daygrid-v10r-20160712>
<Item id=oco2geos-co2-daygrid-v10r-20160711>
<Item id=oco2geos-co2-daygrid-v10r-20160710>
<Item id=oco2geos-co2-daygrid-v10r-20160709>
<Item id=oco2geos-co2-daygrid-v10r-20160708>
<Item id=oco2geos-co2-daygrid-v10r-20160707>
<Item id=oco2geos-co2-daygrid-v10r-20160706>
<Item id=oco2geos-co2-daygrid-v10r-20160705>
<Item id=oco2geos-co2-daygrid-v10r-20160704>
<Item id=oco2geos-co2-daygrid-v10r-20160703>
<Item id=oco2geos-co2-daygrid-v10r-20160702>
<Item id=oco2geos-co2-daygrid-v10r-20160701>
<Item id=oco2geos-co2-daygrid-v10r-20160630>
<Item id=oco2geos-co2-daygrid-v10r-20160629>
<Item id=oco2geos-co2-daygrid-v10r-20160628>
<Item id=oco2geos-co2-daygrid-v10r-20160627>
<Item id=oco2geos-co2-daygrid-v10r-20160626>
<Item id=oco2geos-co2-daygrid-v10r-20160625>
<Item id=oco2geos-co2-daygrid-v10r-20160624>
<Item id=oco2geos-co2-daygrid-v10r-20160623>
<Item id=oco2geos-co2-daygrid-v10r-20160622>
<Item id=oco2geos-co2-daygrid-v10r-20160621>
<Item id=oco2geos-co2-daygrid-v10r-20160620>
<Item id=oco2geos-co2-daygrid-v10r-20160619>
<Item id=oco2geos-co2-daygrid-v10r-20160618>
<Item id=oco2geos-co2-daygrid-v10r-20160617>
<Item id=oco2geos-co2-daygrid-v10r-20160616>
<Item id=oco2geos-co2-daygrid-v10r-20160615>
<Item id=oco2geos-co2-daygrid-v10r-20160614>
<Item id=oco2geos-co2-daygrid-v10r-20160613>
<Item id=oco2geos-co2-daygrid-v10r-20160612>
<Item id=oco2geos-co2-daygrid-v10r-20160611>
<Item id=oco2geos-co2-daygrid-v10r-20160610>
<Item id=oco2geos-co2-daygrid-v10r-20160609>
<Item id=oco2geos-co2-daygrid-v10r-20160608>
<Item id=oco2geos-co2-daygrid-v10r-20160607>
<Item id=oco2geos-co2-daygrid-v10r-20160606>
<Item id=oco2geos-co2-daygrid-v10r-20160605>
<Item id=oco2geos-co2-daygrid-v10r-20160604>
<Item id=oco2geos-co2-daygrid-v10r-20160603>
<Item id=oco2geos-co2-daygrid-v10r-20160602>
<Item id=oco2geos-co2-daygrid-v10r-20160601>
<Item id=oco2geos-co2-daygrid-v10r-20160531>
<Item id=oco2geos-co2-daygrid-v10r-20160530>
<Item id=oco2geos-co2-daygrid-v10r-20160529>
<Item id=oco2geos-co2-daygrid-v10r-20160528>
<Item id=oco2geos-co2-daygrid-v10r-20160527>
<Item id=oco2geos-co2-daygrid-v10r-20160526>
<Item id=oco2geos-co2-daygrid-v10r-20160525>
<Item id=oco2geos-co2-daygrid-v10r-20160524>
<Item id=oco2geos-co2-daygrid-v10r-20160523>
<Item id=oco2geos-co2-daygrid-v10r-20160522>
<Item id=oco2geos-co2-daygrid-v10r-20160521>
<Item id=oco2geos-co2-daygrid-v10r-20160520>
<Item id=oco2geos-co2-daygrid-v10r-20160519>
<Item id=oco2geos-co2-daygrid-v10r-20160518>
<Item id=oco2geos-co2-daygrid-v10r-20160517>
<Item id=oco2geos-co2-daygrid-v10r-20160516>
<Item id=oco2geos-co2-daygrid-v10r-20160515>
<Item id=oco2geos-co2-daygrid-v10r-20160514>
<Item id=oco2geos-co2-daygrid-v10r-20160513>
<Item id=oco2geos-co2-daygrid-v10r-20160512>
<Item id=oco2geos-co2-daygrid-v10r-20160511>
<Item id=oco2geos-co2-daygrid-v10r-20160510>
<Item id=oco2geos-co2-daygrid-v10r-20160509>
<Item id=oco2geos-co2-daygrid-v10r-20160508>
<Item id=oco2geos-co2-daygrid-v10r-20160507>
<Item id=oco2geos-co2-daygrid-v10r-20160506>
<Item id=oco2geos-co2-daygrid-v10r-20160505>
<Item id=oco2geos-co2-daygrid-v10r-20160504>
<Item id=oco2geos-co2-daygrid-v10r-20160503>
<Item id=oco2geos-co2-daygrid-v10r-20160502>
<Item id=oco2geos-co2-daygrid-v10r-20160501>
<Item id=oco2geos-co2-daygrid-v10r-20160430>
<Item id=oco2geos-co2-daygrid-v10r-20160429>
<Item id=oco2geos-co2-daygrid-v10r-20160428>
<Item id=oco2geos-co2-daygrid-v10r-20160427>
<Item id=oco2geos-co2-daygrid-v10r-20160426>
<Item id=oco2geos-co2-daygrid-v10r-20160425>
<Item id=oco2geos-co2-daygrid-v10r-20160424>
<Item id=oco2geos-co2-daygrid-v10r-20160423>
<Item id=oco2geos-co2-daygrid-v10r-20160422>
<Item id=oco2geos-co2-daygrid-v10r-20160421>
<Item id=oco2geos-co2-daygrid-v10r-20160420>
<Item id=oco2geos-co2-daygrid-v10r-20160419>
<Item id=oco2geos-co2-daygrid-v10r-20160418>
<Item id=oco2geos-co2-daygrid-v10r-20160417>
<Item id=oco2geos-co2-daygrid-v10r-20160416>
<Item id=oco2geos-co2-daygrid-v10r-20160415>
<Item id=oco2geos-co2-daygrid-v10r-20160414>
<Item id=oco2geos-co2-daygrid-v10r-20160413>
<Item id=oco2geos-co2-daygrid-v10r-20160412>
<Item id=oco2geos-co2-daygrid-v10r-20160411>
<Item id=oco2geos-co2-daygrid-v10r-20160410>
<Item id=oco2geos-co2-daygrid-v10r-20160409>
<Item id=oco2geos-co2-daygrid-v10r-20160408>
<Item id=oco2geos-co2-daygrid-v10r-20160407>
<Item id=oco2geos-co2-daygrid-v10r-20160406>
<Item id=oco2geos-co2-daygrid-v10r-20160405>
<Item id=oco2geos-co2-daygrid-v10r-20160404>
<Item id=oco2geos-co2-daygrid-v10r-20160403>
<Item id=oco2geos-co2-daygrid-v10r-20160402>
<Item id=oco2geos-co2-daygrid-v10r-20160401>
<Item id=oco2geos-co2-daygrid-v10r-20160331>
<Item id=oco2geos-co2-daygrid-v10r-20160330>
<Item id=oco2geos-co2-daygrid-v10r-20160329>
<Item id=oco2geos-co2-daygrid-v10r-20160328>
<Item id=oco2geos-co2-daygrid-v10r-20160327>
<Item id=oco2geos-co2-daygrid-v10r-20160326>
<Item id=oco2geos-co2-daygrid-v10r-20160325>
<Item id=oco2geos-co2-daygrid-v10r-20160324>
<Item id=oco2geos-co2-daygrid-v10r-20160323>
<Item id=oco2geos-co2-daygrid-v10r-20160322>
<Item id=oco2geos-co2-daygrid-v10r-20160321>
<Item id=oco2geos-co2-daygrid-v10r-20160320>
<Item id=oco2geos-co2-daygrid-v10r-20160319>
<Item id=oco2geos-co2-daygrid-v10r-20160318>
<Item id=oco2geos-co2-daygrid-v10r-20160317>
<Item id=oco2geos-co2-daygrid-v10r-20160316>
<Item id=oco2geos-co2-daygrid-v10r-20160315>
<Item id=oco2geos-co2-daygrid-v10r-20160314>
<Item id=oco2geos-co2-daygrid-v10r-20160313>
<Item id=oco2geos-co2-daygrid-v10r-20160312>
<Item id=oco2geos-co2-daygrid-v10r-20160311>
<Item id=oco2geos-co2-daygrid-v10r-20160310>
<Item id=oco2geos-co2-daygrid-v10r-20160309>
<Item id=oco2geos-co2-daygrid-v10r-20160308>
<Item id=oco2geos-co2-daygrid-v10r-20160307>
<Item id=oco2geos-co2-daygrid-v10r-20160306>
<Item id=oco2geos-co2-daygrid-v10r-20160305>
<Item id=oco2geos-co2-daygrid-v10r-20160304>
<Item id=oco2geos-co2-daygrid-v10r-20160303>
<Item id=oco2geos-co2-daygrid-v10r-20160302>
<Item id=oco2geos-co2-daygrid-v10r-20160301>
# Restructure our items into a dictionary where keys are the datetime items
# Then we can query more easily by date/time, e.g. "2020-03-10"
= search.item_collection()
items = {item.properties["datetime"][:10]: item for item in items} items_dict
# Before we go further, let's pick which asset to focus on for the remainder of the notebook.
# We'll focus on XCO2 concentrations:
= "xco2" asset_name
Creating Maps Using Folium
In this notebook, we will explore the temporal impacts of CO₂ emissions. We will visualize the outputs on a map using folium.
Fetch Imagery from Raster API
Here we get information from the Raster API
which we will add to our map in the next section.
= ["2016-03-01","2016-07-25"] dates
Below, we use some statistics of the raster data to set upper and lower limits for our color bar. These are saved as the rescale_values
, and will be passed to the Raster API in the following step(s).
# Extract collection name and item ID for the first date
= items_dict[dates[0]]
first_date = first_date.collection_id
collection_id = first_date.id
item_id # Select relevant asset
object = first_date.assets[asset_name]
= object.extra_fields.get("raster:bands", [{}])
raster_bands # Printer raster bands' information
raster_bands
[{'scale': 1.0,
'offset': 0.0,
'sampling': 'area',
'data_type': 'float64',
'histogram': {'max': 407.97830297378823,
'min': 397.2987979068421,
'count': 11.0,
'buckets': [35994.0,
21204.0,
28584.0,
9807.0,
9617.0,
29793.0,
52299.0,
18758.0,
1682.0,
198.0]},
'statistics': {'mean': 401.71009609341064,
'stddev': 2.678157330984702,
'maximum': 407.97830297378823,
'minimum': 397.2987979068421,
'valid_percent': 0.00048091720529393656}}]
# Use statistics to generate an appropriate color bar range.
= {
rescale_values "max": raster_bands[0].get("histogram", {}).get("max"),
"min": raster_bands[0].get("histogram", {}).get("min"),
}
print(rescale_values)
{'max': 407.97830297378823, 'min': 397.2987979068421}
Now, you will pass the item id
, collection name
, asset name
, and the rescale values
to the Raster API endpoint, along with a colormap. This step is done twice, one for each date/time you will visualize, and tells the Raster API which collection, item, and asset you want to view, specifying the colormap and colorbar ranges to use for visualization. The API returns a JSON with information about the requested image. Each image will be referred to as a tile.
# Choose a colormap for displaying the data
# Make sure to capitalize per Matplotlib standard colormap names
# For more information on Colormaps in Matplotlib, please visit https://matplotlib.org/stable/users/explain/colors/colormaps.html
= "magma" color_map
# Make a GET request to retrieve information for the date mentioned below
= requests.get(
tile1 f"{RASTER_API_URL}/collections/{collection_id}/items/{item_id}/tilejson.json?"
f"&assets={asset_name}"
f"&color_formula=gamma+r+1.05&colormap_name={color_map.lower()}"
f"&rescale={rescale_values["min"]},{rescale_values["max"]}"
).json()
# Print the properties of the retrieved granule to the console
tile1
{'tilejson': '2.2.0',
'version': '1.0.0',
'scheme': 'xyz',
'tiles': ['https://earth.gov/ghgcenter/api/raster/collections/oco2geos-co2-daygrid-v10r/items/oco2geos-co2-daygrid-v10r-20160301/tiles/WebMercatorQuad/{z}/{x}/{y}@1x?assets=xco2&color_formula=gamma+r+1.05&colormap_name=magma&rescale=397.2987979068421%2C407.97830297378823'],
'minzoom': 0,
'maxzoom': 24,
'bounds': [-180.3125, -90.25, 179.6875, 90.25],
'center': [-0.3125, 0.0, 0]}
# Repeat the above for your second date/time
# Note that we do not calculate new rescale_values for this tile
# We want date tiles 1 and 2 to have the same colorbar range for visual comparison
= items_dict[dates[1]]
second_date # Extract collection name and item ID
= second_date.collection_id
collection_id = second_date.id
item_id
= requests.get(
tile2 f"{RASTER_API_URL}/collections/{collection_id}/items/{item_id}/tilejson.json?"
f"&assets={asset_name}"
f"&color_formula=gamma+r+1.05&colormap_name={color_map.lower()}"
f"&rescale={rescale_values["min"]},{rescale_values["max"]}"
).json()
# Print the properties of the retrieved granule to the console
tile2
{'tilejson': '2.2.0',
'version': '1.0.0',
'scheme': 'xyz',
'tiles': ['https://earth.gov/ghgcenter/api/raster/collections/oco2geos-co2-daygrid-v10r/items/oco2geos-co2-daygrid-v10r-20160725/tiles/WebMercatorQuad/{z}/{x}/{y}@1x?assets=xco2&color_formula=gamma+r+1.05&colormap_name=magma&rescale=397.2987979068421%2C407.97830297378823'],
'minzoom': 0,
'maxzoom': 24,
'bounds': [-180.3125, -90.25, 179.6875, 90.25],
'center': [-0.3125, 0.0, 0]}
Generate Map
# Initialize the map, specifying the center of the map and the starting zoom level.
# 'folium.plugins' allows mapping side-by-side via 'DualMap'
# Map is centered on the position specified by "location=(lat,lon)"
= folium.plugins.DualMap(location=(34, -95), zoom_start=3)
map_
# Define the first map layer (January 2020)
= TileLayer(
map_layer_1 =tile1["tiles"][0], # Path to retrieve the tile
tiles="GHG", # Set the attribution
attr=0.8, # Adjust the transparency of the layer
opacity=True,
overlay=f"{collection.title}, {dates[0]}"
name
)
# Add the first layer to the Dual Map
map_layer_1.add_to(map_.m1)
# Define the second map layer (January 2000)
= TileLayer(
map_layer_2 =tile2["tiles"][0], # Path to retrieve the tile
tiles="GHG", # Set the attribution
attr=0.8, # Adjust the transparency of the layer,
opacity=True,
overlay=f"{collection.title}, {dates[1]}"
name
)
# Add the second layer to the Dual Map
map_layer_2.add_to(map_.m2)
# Add a layer control to switch between map layers
=False).add_to(map_)
folium.LayerControl(collapsed
# Add colorbar
# We can use 'generate_html_colorbar' from the 'ghgc_utils' module
# to create an HTML colorbar representation.
= ghgc_utils.generate_html_colorbar(color_map,rescale_values,label=f'{items[0].assets[asset_name].title} (ppm)')
legend_html
# Add colorbar to the map
map_.get_root().html.add_child(folium.Element(legend_html))
# Visualize the Dual Map
map_
Calculating Zonal Statistics
To perform zonal statistics, first we need to create a polygon. In this use case we are creating a polygon in Texas (USA).
# Give the AOI a name to use in plots later on
= "Los Angeles Area, California"
aoi_name # Create AOI polygon as a GEOJSON
= {
aoi "type": "Feature", # Create a feature object
"properties": {},
"geometry": { # Set the bounding coordinates for the polygon
"coordinates": [
[-119.42, 34.43],
[-119.42,33.4],
[-117,33.4],
[-117,34.43],
[-119.42,34.43]
[
]
],"type": "Polygon",
}, }
# Quick Folium map to visualize this AOI
= folium.Map(location=(34, -118), zoom_start=7)
map_ # Add AOI to map
=aoi_name).add_to(map_)
folium.GeoJson(aoi, name# Add data layer to map to visualize how many grid cells lie within our AOI
map_layer_2.add_to(map_)# Add colorbar
= ghgc_utils.generate_html_colorbar(color_map,rescale_values,label=f'{items[0].assets[asset_name].title} (ppm)')
legend_html
map_.get_root().html.add_child(folium.Element(legend_html)) map_
We can generate the statistics for the AOI using a function from the ghgc_utils
module, which fetches the data and its statistics from the Raster API.
%%time
# Statistics will be returned as a Pandas DataFrame
= ghgc_utils.generate_stats(items,aoi,url=RASTER_API_URL,asset=asset_name)
df # Print the first five rows of statistics from our DataFrame
5) df.head(
Generating stats...
Done!
CPU times: user 470 ms, sys: 49.4 ms, total: 520 ms
Wall time: 48 s
datetime | min | max | mean | count | sum | std | median | majority | minority | unique | histogram | valid_percent | masked_pixels | valid_pixels | percentile_2 | percentile_98 | date | |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 | 2016-07-31T00:00:00+00:00 | 402.73201375384815037251 | 403.07208473677752635922 | 402.93507734400418485166 | 8.18999958038330078125 | 3300.03811436910700649605 | 0.10187300118277758942 | 402.95861617778427898884 | 402.73201375384815037251 | 402.73201375384815037251 | 15.00000000000000000000 | [[1, 1, 0, 4, 1, 0, 2, 1, 2, 3], [402.73201375... | 100.00000000000000000000 | 0.00000000000000000000 | 15.00000000000000000000 | 402.73201375384815037251 | 403.07208473677752635922 | 2016-07-31 00:00:00+00:00 |
1 | 2016-07-30T00:00:00+00:00 | 402.56199281429871916771 | 403.14309808309189975262 | 402.87968166898525623765 | 8.18999958038330078125 | 3299.58442381394706899300 | 0.18230482625803307029 | 402.89328171638771891594 | 402.56199281429871916771 | 402.56199281429871916771 | 15.00000000000000000000 | [[2, 1, 2, 0, 3, 1, 0, 2, 2, 2], [402.56199281... | 100.00000000000000000000 | 0.00000000000000000000 | 15.00000000000000000000 | 402.56199281429871916771 | 403.13536737812677301918 | 2016-07-30 00:00:00+00:00 |
2 | 2016-07-29T00:00:00+00:00 | 402.74460479849949479103 | 403.47748290514573454857 | 403.08157310314629739878 | 8.18999958038330078125 | 3301.23791457500874457764 | 0.22896203256865310660 | 403.08183815795928239822 | 402.74460479849949479103 | 402.74460479849949479103 | 15.00000000000000000000 | [[2, 3, 2, 0, 2, 2, 2, 1, 0, 1], [402.74460479... | 100.00000000000000000000 | 0.00000000000000000000 | 15.00000000000000000000 | 402.74460479849949479103 | 403.47748290514573454857 | 2016-07-29 00:00:00+00:00 |
3 | 2016-07-28T00:00:00+00:00 | 402.90020115207875051055 | 403.52593350689858198166 | 403.25796667511235682468 | 8.18999958038330078125 | 3302.68257785539344695280 | 0.18016015602694981923 | 403.24078145204111933708 | 402.90020115207875051055 | 402.90020115207875051055 | 15.00000000000000000000 | [[1, 2, 2, 0, 1, 3, 1, 3, 0, 2], [402.90020115... | 100.00000000000000000000 | 0.00000000000000000000 | 15.00000000000000000000 | 402.90020115207875051055 | 403.52593350689858198166 | 2016-07-28 00:00:00+00:00 |
4 | 2016-07-27T00:00:00+00:00 | 403.53622898692265152931 | 404.49955122312525190864 | 404.01733968265892826821 | 8.18999958038330078125 | 3308.90184246855415040045 | 0.27792947176049037639 | 403.96333133685402572155 | 403.53622898692265152931 | 403.53622898692265152931 | 15.00000000000000000000 | [[1, 3, 0, 2, 3, 1, 1, 1, 2, 1], [403.53622898... | 100.00000000000000000000 | 0.00000000000000000000 | 15.00000000000000000000 | 403.53622898692265152931 | 404.49955122312525190864 | 2016-07-27 00:00:00+00:00 |
Time-Series Analysis
We can now explore the XCO₂ concentrations time series (January 1, 2015 - February 28, 2022) available for the Dallas, Texas area of the U.S. We can plot the data set using the code below:
= plt.figure(figsize=(10,5))
fig = df.sort_values(by="datetime")
df
="mean"
which_stat
plt.plot("datetime"],
df[
df[which_stat],="#F6AA1C",
color="-",
linestyle=2,
linewidth=f"{which_stat.capitalize()} Column CO₂ concentrations",
label
)
plt.legend()"Date")
plt.xlabel("ppm")
plt.ylabel(f"{which_stat.capitalize()} Column CO₂ concentrations for {aoi_name}")
plt.title(# Format x tick frequency and labels
"datetime"][::10])
plt.xticks(df[=plt.gca()
ax0:10] for d in df["datetime"]][::10],rotation=45,ha="right")
ax.set_xticklabels([d[
# Add data citation
plt.text(min(df["datetime"]), # X-coordinate of the text
min(), # Y-coordinate of the text
df[which_stat].# Text to be displayed
f"Source: {collection.title}",
=9, # Font size
fontsize="left", # Horizontal alignment
horizontalalignment="top", # Vertical alignment
verticalalignment="blue", # Text color
color
)
# Plot the time series
plt.show()
Summary
In this notebook, we have successfully explored, analyzed, and visualized the STAC collection for OCO-2 GEOS Column CO₂ Concentrations.
- Install and import the necessary libraries
- Fetch the collection from STAC collections using the appropriate endpoints
- Count the number of existing granules within the collection
- Map and compare the Column-Averaged XCO₂ Concentrations Levels for two distinctive months/years
- Generate zonal statistics for the area of interest (AOI)
- Visualizing the Data as a Time Series
If you have any questions regarding this user notebook, please contact us using the feedback form.