dea_tools.wetlands

This module is for processing DEA wetlands data, including Spatial WIT.

License: The code in this notebook is licensed under the Apache License,Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0). Digital Earth Australia data is licensed under the Creative Commons by Attribution 4.0 license (https://creativecommons.org/licenses/by/4.0/).

Contact: If you need assistance, please post a question on the Open Data Cube Discord chat (https://discord.com/invite/4hhBQVas5U) or on the GIS Stack Exchange (https://gis.stackexchange.com/questions/ask?tags=open-data-cube)using the open-data-cube tag (you can view previously asked questions here: https://gis.stackexchange.com/questions/tagged/open-data-cube).

If you would like to report an issue with this script, file one on GitHub: GeoscienceAustralia/dea-notebooks#new

Last modified: July 2025

Functions

WIT_drill(gdf, time[, export_csv, ...])

Runs the Wetlands Insight Tool over a polygon.

classify_pixel(pv, npv, bs)

This function sorts the fractional cover values into their classes to be used in Spatial WIT.

display_wit_stack_with_df(polygon_base_df[, ...])

This functions produces WIT plots.

generate_low_quality_data_periods(df)

This function generates low quality data periods, including the SLC off period: https://www.usgs.gov/faqs/what-landsat-7-etm-slc-data and periods with an observation density of less than four observations within a twelve month (365 days) period.

normalise_wit(polygon_base_df)

This function is to normalise the Fractional Cover vegetation

spatial_wit(ds, wetland_name)

Takes Wetlands Insight Tool classifications and represents them in a spatial way.
dea_tools.wetlands.WIT_drill(gdf, time, export_csv=None, dask_chunks=None, verbose=False, verbose_progress=False)[source]

Runs the Wetlands Insight Tool over a polygon. The code is based on the DEA Wetlands Insight Tool notebook. This function loads FC, WOs, and Landsat Data, and calculates Tasseled Cap Wetness, in order to summarise how the different classes have changed over time.

The output is an Xarray dataset and a pandas dataframe containing a timeseries of the normalised relative fractions of each class at each time-step. This forms the input to produce a stacked line plot.

Last modified March 2025

Parameters:

  • gdf (geopandas.GeoDataFrame) – The dataframe must only contain a single row containing the polygon you wish to interrogate

  • time (tuple) – A tuple containing the time range over which to run the WIT. e.g. (“2014-01-01”, “2015-01-01”)

  • export_csv (string, optional) – To save the returned pandas dataframe as a .csv file, pass a location string (e.g. ‘output/results.csv’)

  • dask_chunks (dict, optional) – To lazily load the datasets using dask, pass a dictionary containing the dimensions over which to chunk e.g. {‘time’:1, ‘x’:2048, ‘y’:2048}.

  • verbose (bool, optional) – If true, print statements are outputted detailing the progress of the tool.

  • verbose_progress (bool, optional) – For use with Dask progress bar.

Returns:

  • ds_wit (xarray.Dataset) – An xarray dataset containing values for each cover class (open water, wet, pv, npv, bs).

  • polygon_base_df (pandas.DataFrame) – A DataFrame containing the normalised timeseries of relative fractions of each cover class (open water, wet, pv, npv, bs).

dea_tools.wetlands.classify_pixel(pv, npv, bs)[source]

This function sorts the fractional cover values into their classes to be used in Spatial WIT.

Last modified March 2025

Parameters:

  • pv (array) – Array containing values for the photosynthetic (green) vegetation class.

  • npv (array) – Array containing values for the non-photosynthetic (dry) vegetation class.

  • bs (array) – Array containing values for the base soil class.

Returns:

Integer values to assign each of the fractional cover classes (https://knowledge.dea.ga.gov.au/data/product/dea-fractional-cover-landsat/).

Return type:

integer

dea_tools.wetlands.display_wit_stack_with_df(polygon_base_df, polygon_name='your_wetland_name', png_name='your_file_name', width=32, height=6, x_axis_labels='years')[source]

This functions produces WIT plots. Function displays a stack plot and saves as a png.

Last modified: July 2023

Parameters:

  • polygon_base_df (pandas DataFrame with columns including:) –

  • ['date' – ‘wet’, ‘water’, ‘norm_bs’, ‘norm_pv’, ‘norm_npv’] polygon_name : string png_name : string x_axis_labels : string with options of “years” or “months” to set either years or months on the x axis as labels

:param‘wet’,

‘water’, ‘norm_bs’, ‘norm_pv’, ‘norm_npv’] polygon_name : string png_name : string x_axis_labels : string with options of “years” or “months” to set either years or months on the x axis as labels

dea_tools.wetlands.generate_low_quality_data_periods(df)[source]

This function generates low quality data periods, including the SLC off period: https://www.usgs.gov/faqs/what-landsat-7-etm-slc-data and periods with an observation density of less than four observations within a twelve month (365 days) period. Off value is 100 where there is low data quality and 0 for good data.

Last modified: July 2023

Parameters:

  • df (pandas DataFrame with columns including:) –

  • ['date'] –

Returns:

  • df (pandas DataFrame with additional column:)

  • [‘off_value’]

dea_tools.wetlands.normalise_wit(polygon_base_df)[source]

This function is to normalise the Fractional Cover vegetation components so users can choose to display the WIT plot in a more readable way. Normalising vegetation components so they total to 1. Normalised values are returned as additional columns.

Last modified: July 2023

polygon_base_df : pandas DataFrame with columns: [‘date’, ‘pv’, ‘npv’, ‘bs’, ‘wet’, ‘water’]

polygon_base_df with columns: [‘index’,

‘date’, ‘pv’, ‘npv’, ‘bs’, ‘wet’, ‘water’, ‘veg_areas’, ‘overall_veg_num’, ‘norm_bs’, ‘norm_pv’, ‘norm_npv’]

A polygon has 11 pixels

[cloud][water][wet][wet][wet][wet][wet][wet][wet][wet][vegetation]
| | |
| | |
| |__> wet = 8/10 = 80% |__> pv/npv/bs == 1/10 = 10%
|
|__> water = 1/10 = 10%

|__> pc_missing = 1/11 ~+ 9.1%

The vegetation pixel relative np, npv, and bs values

[vegetation]

|__> [pv] [npv] [bs]

[ 5] [ 4] [ 2]

Assume vegetation relative values are:

water = 0.1 wet = 0.8

pv = 0.05 npv = 0.04 bs = 0.02

vegetation_area = 1 - water - wet

vegetation_overall_value = pv + npv + bs

print(f”The pv is {pv}

The npv is {npv} The bs is {bs}

The overall number is {water + wet + pv + npv + bs}”)

The pv is 0.05 The npv is 0.04 The bs is 0.02 The overall number is 1.01

The overall number is greater than 1. Let us normalise the result. The water and wet are pixel classification result, so we should not touch them.

pv = pv/vegetation_overall_value*vegetation_area npv = npv/vegetation_overall_value*vegetation_area bs = bs/vegetation_overall_value*vegetation_area

print(f”The normalised pv is {pv}

The normalised npv is {npv}

The normalised bs is {bs} The normalised overall number is

{water + wet + pv + npv + bs}”)

The normalised pv is 0.04545454545454545 The normalised npv is 0.036363636363636355 The normalised bs is 0.018181818181818177 The normalised overall number is 1.0

dea_tools.wetlands.spatial_wit(ds, wetland_name)[source]

Takes Wetlands Insight Tool classifications and represents them in a spatial way. The same caveats for those classifications apply (see Dunn et al., 2023 and DEA Wetlands Insight Tool notebook). The water and wet classes are binary and the vegetation fractional cover classes are percentages per pixel, with the spatial representation scaled accordingly.

Last modified: March 2025

Parameters:

  • ds (xarray.Dataset) – An xarray dataset containing values for each cover class (open water, wet, pv, npv, bs).

  • wetland_name (string) – Value to be used when naming the output files.

Returns:

File path where the GIF animation will be saved.

Return type:

output_path