API

Premade Datasets

Supported Datasets

sankee uses Dataset objects to define the parameters for commonly used collections of classified imagery. The following premade datasets are included:

Dataset	Name	Extent	Years
LCMS_LC	Landscape Change Monitoring System - Land Cover	CONUS + SE AK	1985-2021 (annual)
LCMS_LU	Landscape Change Monitoring System - Land Use	CONUS + SE AK	1985-2021 (annual)
NLCD	National Land Cover Database	CONUS	2001-2019 (irregular)
MODIS_LC_TYPE1	MODIS Land Cover - Type 1	Global	2001-2020 (annual)
MODIS_LC_TYPE2	MODIS Land Cover - Type 2	Global	2001-2020 (annual)
MODIS_LC_TYPE3	MODIS Land Cover - Type 3	Global	2001-2020 (annual)
CGLS_LC100	Copernicus Global Land Cover	Global	2015-2019 (annual)
LCMAP	Landscape Change Monitoring, Assessment, and Projection	CONUS	1985-2020 (annual)
CCAP_LC30	NOAA Coastal Change Analysis Program 30m	CONUS (wetlands)	2015-2019 (irregular)
CA_FOREST_LC	Canada Forestest Ecosystem Land Cover	Canada (forests)	1984-2019 (annual)
CORINE	Coordination of Information on the Environment	Europe (partial)	1986-2018 (irregular)

Dataset methods

Datasets have some helpful properties and methods:

class sankee.datasets.Dataset(name: str, id: str, band: str, labels: dict[int, str], palette: dict[int, str], years: list[int], nodata: None | int = None)[source]

property keys: list[int]: Return the label keys of the dataset.

property df: DataFrame: Return a Pandas dataframe describing the dataset parameters.

property collection: ImageCollection: The ee.ImageCollection representing the dataset.

get_year(year: int) → Image[source]: Get one year’s image from the dataset. Set the metadata properties for visualization.

Sankifying a Premade Dataset

To create a Sankey diagram from a dataset, use Dataset.sankify().

Dataset.sankify(years: list[int], region: ~ee.geometry.Geometry, max_classes: None | int = None, n: int = 500, title: str | None = None, scale: int | None = None, seed: int = 0, exclude: None = None, label_type: str = 'class', theme: str | ~sankee.themes.Theme = <sankee.themes.Theme object>) → SankeyPlot[source]

Generate an interactive Sankey plot showing land cover change over time from a series of years in the dataset.

Parameters:

years (List[int]) – The years to include in the plot. Select at least two unique years.
region (ee.Geometry) – A region to generate samples within. The region must overlap all images.
max_classes (int, default None) – If a value is provided, small classes will be removed until max_classes remain. Class size is calculated based on total times sampled in the time series.
n (int, default 500) – The number of sample points to randomly generate for characterizing all images. More samples will provide more representative data but will take longer to process.
title (str, default None) – An optional title that will be displayed above the Sankey plot.
scale (int, default None) – The scale in image units to perform sampling at. If none is provided, GEE will attempt to use the image’s nominal scale, which may cause errors depending on the image projection.
seed (int, default 0) – The seed value used to generate repeatable results during random sampling.
label_type (str, default "class") – The type of label to display for each link, one of “class”, “percent”, or “count”. Selecting “class” will use the class label, “percent” will use the proportion of sampled pixels in each class, and “count” will use the number of sampled pixels in each class.
theme (str or Theme) – The theme to apply to the Sankey diagram. Can be the name of a built-in theme (e.g. “d3”) or a custom sankee.Theme object.

Returns:

An interactive Sankey plot widget.

Return type:

SankeyPlot

Example

For example, the code below creates a Sankey diagram from 2 years of LCMS Land Use data:

import sankee
import ee

ee.Initialize()

dataset = sankee.datasets.LCMS_LU
aoi = ee.Geometry.Point([-115.184978, 35.964608]).buffer(1000)
dataset.sankify(years=[1985, 2020], region=aoi, max_classes=3)

Custom Datasets

If you want to use classified data not included with sankee, you can use sankify() instead. Parameters are similar to using a premade dataset, but you will have to manually specify the images, labels, and palette that are automatically included with premade datasets.

sankee.sankify(image_list: list[ee.image.Image], band: str, labels: dict[int, str], palette: dict[int, str], region: None | Geometry = None, label_list: None | list[str] = None, max_classes: None | int = None, n: int = 500, title: None | str = None, scale: None | int = None, seed: int = 0, label_type: None | Literal['class', 'percent', 'count'] = 'class', theme: str | Theme = 'default') → SankeyPlot[source]

Generate an interactive Sankey plot showing land cover change over time from a series of images.

Parameters:

image_list (List[ee.Image]) – An ordered list of images representing a time series of classified data. Each image will be sampled to generate the Sankey plot. Any length of list is allowed, but lists with more than 3 or 4 images may produce unusable plots.
band (str) – The name of the band in all images of image_list that contains classified data.
labels (dict) – The labels associated with each value of all images in image_list. Any values not defined in the labels will be dropped from the sampled data.
palette (dict) – The colors associated with each value of all images in image_list.
region (ee.Geometry, default None) – A region to generate samples within. The region must overlap all images. If none is provided, the geometry of the first image will be used. For this to work, images must be bounded.
label_list (List[str], default None) – An ordered list of labels corresponding to the images. The list must be the same length as image_list. If none is provided, sequential numeric labels will be automatically assigned starting at 0. Labels are displayed on-hover on the Sankey nodes.
max_classes (int, default None) – If a value is provided, small classes will be removed until max_classes remain. Class size is calculated based on total times sampled in the time series.
n (int, default 500) – The number of sample points to randomly generate for characterizing all images. More samples will provide more representative data but will take longer to process.
title (str, default None) – An optional title that will be displayed above the Sankey plot.
scale (int, default None) – The scale in image units to perform sampling at. If none is provided, GEE will attempt to use the image’s nominal scale, which may cause errors depending on the image projection.
seed (int, default 0) – The seed value used to generate repeatable results during random sampling.
label_type (str, default "class") – The type of label to display for each link, one of “class”, “percent”, “count”, or None. Selecting “class” will use the class label, “percent” will use the proportion of sampled pixels in each class, and “count” will use the number of sampled pixels in each class. None will disable link labels.
theme (str or Theme) – The theme to apply to the Sankey diagram. Can be the name of a built-in theme (e.g. “d3”) or a custom sankee.Theme object.

Returns:

An interactive Sankey plot widget.

Return type:

SankeyPlot

Example

Here’s an example creating a Sankey diagram from two Dynamic World scenes, acquired immediately before and after the 2020 Beachie Creek fire in western Oregon, USA.

import sankee
import ee

ee.Initialize()

# Load two images
pre = ee.Image("GOOGLE/DYNAMICWORLD/V1/20200904T185921_20200904T190750_T10TEQ")
post = ee.Image("GOOGLE/DYNAMICWORLD/V1/20201009T190319_20201009T190349_T10TEQ")
aoi = ee.Geometry.Point([-122.30239918572622, 44.802882471354316]).buffer(1000)

# Define the band name and the class labels and colors corresponding to each pixel value.
band = "label"

labels = {
    0: "water",
    1: "trees",
    2: "grass",
    3: "flooded_vegetation",
    4: "crops",
    5: "shrub_and_scrub",
    6: "built",
    7: "bare",
    8: "snow_and_ice"
}

palette = {
    0: "#419BDF",
    1: "#397D49",
    2: "#88B053",
    3: "#7A87C6",
    4: "#E49635",
    5: "#DFC35A",
    6: "#C4281B",
    7: "#A59B8F",
    8: "#B39FE1"
}

# Generate the Sankey diagram from the two images
sankee.sankify(
    image_list=[pre, post],
    region=aoi,
    band=band,
    labels=labels,
    palette=palette,
)

Themes

Custom and built-in themes can be used to customize the appearance of Sankey diagrams. datasets.Dataset.sankify() and sankify() both accept a theme parameter that can be used to specify the name of a built-in theme (see sankee.themes.THEMES.keys()) or a custom Theme object.

class sankee.Theme(label_style: None | str = None, title_style: None | str = None, node_kwargs: None | dict = None, link_kwargs: None | dict = None)[source]

label_style

CSS style for the node labels.

Type:: str, optional

title_style

CSS style for the figure title.

Type:: str, optional

node_kwargs

Keyword arguments applied to Sankey nodes. See the Plotly Sankey.node documentation for details.

Type:: dict, optional

link_kwargs

Keyword arguments applied to Sankey links. See the Plotly Sankey.link documentation for details.

Type:: dict, optional

Examples

>>> theme = Theme(
...     label_style="""
...         color: #fff;
...         font-weight: 600;
...         letter-spacing: -1px;
...         text-shadow:
...             0 0 4px black,
...             -1px 1px 0 #76777a,
...             1px 1px 0 #76777a,
...             1px -1px 0 #76777a,
...             -1px -1px 0 #76777a;
...     """,
...     title_style="""
...         color: #fff;
...         font-weight: 900;
...         word-spacing: 10px;
...         letter-spacing: 3px;
...         text-shadow:
...             0 0 1px black,
...             0 0 2px black,
...             0 0 4px black;
...     """,
...     node_kwargs=dict(
...         pad=30,
...         thickness=10,
...         line=dict(color="#505050", width=1.5),
...     ),
...     link_kwargs=dict(
...         line=dict(color="#909090", width=1),
...     ),
... )