deafrica_tools.bandindices

Functions for computing remote sensing band indices on Digital Earth Africa data.

Functions

calculate_indices(ds[, index, collection, …])

Takes an xarray dataset containing spectral bands, calculates one of a set of remote sensing indices, and adds the resulting array as a new variable in the original dataset.

dualpol_indices(ds[, co_pol, cross_pol, …])

Takes an xarray dataset containing dual-polarization radar backscatter, calculates one or a set of indices, and adds the resulting array as a new variable in the original dataset.

deafrica_tools.bandindices.calculate_indices(ds, index=None, collection=None, custom_varname=None, normalise=True, drop=False, deep_copy=True)

Takes an xarray dataset containing spectral bands, calculates one of a set of remote sensing indices, and adds the resulting array as a new variable in the original dataset.

Last modified: July 2021

Parameters
  • ds (xarray Dataset) – A two-dimensional or multi-dimensional array with containing the spectral bands required to calculate the index. These bands are used as inputs to calculate the selected water index.

  • index (str or list of strs) –

    A string giving the name of the index to calculate or a list of strings giving the names of the indices to calculate:

    • 'AWEI_ns' (Automated Water Extraction Index, no shadows, Feyisa 2014)

    • 'AWEI_sh' (Automated Water Extraction Index, shadows, Feyisa 2014)

    • 'BAEI' (Built-Up Area Extraction Index, Bouzekri et al. 2015)

    • 'BAI' (Burn Area Index, Martin 1998)

    • 'BSI' (Bare Soil Index, Rikimaru et al. 2002)

    • 'BUI' (Built-Up Index, He et al. 2010)

    • 'CMR' (Clay Minerals Ratio, Drury 1987)

    • 'ENDISI' (Enhanced Normalised Difference for Impervious Surfaces Index, Chen et al. 2019)

    • 'EVI' (Enhanced Vegetation Index, Huete 2002)

    • 'FMR' (Ferrous Minerals Ratio, Segal 1982)

    • 'IOR' (Iron Oxide Ratio, Segal 1982)

    • 'LAI' (Leaf Area Index, Boegh 2002)

    • 'MNDWI' (Modified Normalised Difference Water Index, Xu 1996)

    • 'MSAVI' (Modified Soil Adjusted Vegetation Index, Qi et al. 1994)

    • 'NBI' (New Built-Up Index, Jieli et al. 2010)

    • 'NBR' (Normalised Burn Ratio, Lopez Garcia 1991)

    • 'NDBI' (Normalised Difference Built-Up Index, Zha 2003)

    • 'NDCI' (Normalised Difference Chlorophyll Index, Mishra & Mishra, 2012)

    • 'NDMI' (Normalised Difference Moisture Index, Gao 1996)

    • 'NDSI' (Normalised Difference Snow Index, Hall 1995)

    • 'NDVI' (Normalised Difference Vegetation Index, Rouse 1973)

    • 'NDWI' (Normalised Difference Water Index, McFeeters 1996)

    • 'SAVI' (Soil Adjusted Vegetation Index, Huete 1988)

    • 'TCB' (Tasseled Cap Brightness, Crist 1985)

    • 'TCG' (Tasseled Cap Greeness, Crist 1985)

    • 'TCW' (Tasseled Cap Wetness, Crist 1985)

    • 'WI' (Water Index, Fisher 2016)

  • collection (str) –

    An string that tells the function what data collection is being used to calculate the index. This is necessary because different collections use different names for bands covering a similar spectra.

    Valid options are:

    • 'c2' (for USGS Landsat Collection 2)

    • 's2' (for Sentinel-2)

    As of July 2021, options for 'c1' (USGS Landsat Collection 1) have been removed as Collection 1 data has been archived. The improved version of Landsat data can be accessed through Collection 2.

  • custom_varname (str, optional) – By default, the original dataset will be returned with a new index variable named after index (e.g. ‘NDVI’). To specify a custom name instead, you can supply e.g. custom_varname=’custom_name’. Defaults to None, which uses index to name the variable.

  • normalise (bool, optional) – Some coefficient-based indices (e.g. 'WI', 'BAEI', 'AWEI_ns', 'AWEI_sh', 'TCW', 'TCG', 'TCB', 'EVI', 'LAI', 'SAVI', 'MSAVI') produce different results if surface reflectance values are not scaled between 0.0 and 1.0 prior to calculating the index. Setting normalise=True first scales values to a 0.0-1.0 range by dividing by 10000.0. Defaults to True.

  • drop (bool, optional) – Provides the option to drop the original input data, thus saving space. If drop=True, returns only the index and its values.

  • deep_copy (bool, optional) – If deep_copy=False, calculate_indices will modify the original array, adding bands to the input dataset and not removing them. If the calculate_indices function is run more than once, variables may be dropped incorrectly producing unexpected behaviour. This is a bug and may be fixed in future releases. This is only a problem when drop=True.

Returns

ds – The original xarray Dataset inputted into the function, with a new varible containing the remote sensing index as a DataArray. If drop = True, the new variable/s as DataArrays in the original Dataset.

Return type

xarray Dataset

deafrica_tools.bandindices.dualpol_indices(ds, co_pol='vv', cross_pol='vh', index=None, custom_varname=None, drop=False, deep_copy=True)

Takes an xarray dataset containing dual-polarization radar backscatter, calculates one or a set of indices, and adds the resulting array as a new variable in the original dataset.

Last modified: July 2021

Parameters
  • ds (xarray Dataset) – A two-dimensional or multi-dimensional array containing the two polarization bands.

  • co_pol (str) – Measurement name for the co-polarization band. Default is ‘vv’ for Sentinel-1.

  • cross_pol (str) – Measurement name for the cross-polarization band. Default is ‘vh’ for Sentinel-1.

  • index (str or list of strs) –

    A string giving the name of the index to calculate or a list of strings giving the names of the indices to calculate:

    • 'RVI' (Radar Vegetation Index for dual-pol, Trudel et al. 2012; Nasirzadehdizaji et al., 2019; Gururaj et al., 2019)

    • 'VDDPI' (Vertical dual depolarization index, Periasamy 2018)

    • 'theta' (pseudo scattering-type, Bhogapurapu et al. 2021)

    • 'entropy' (pseudo scattering entropy, Bhogapurapu et al. 2021)

    • 'purity' (co-pol purity, Bhogapurapu et al. 2021)

    • 'ratio' (cross-pol/co-pol ratio)

  • custom_varname (str, optional) – By default, the original dataset will be returned with a new index variable named after index (e.g. ‘RVI’). To specify a custom name instead, you can supply e.g. custom_varname=’custom_name’. Defaults to None, which uses index to name the variable.

  • drop (bool, optional) – Provides the option to drop the original input data, thus saving space. If drop=True, returns only the index and its values.

  • deep_copy (bool, optional) – If deep_copy=False, calculate_indices will modify the original array, adding bands to the input dataset and not removing them. If the calculate_indices function is run more than once, variables may be dropped incorrectly producing unexpected behaviour. This is a bug and may be fixed in future releases. This is only a problem when drop=True.

Returns

ds – The original xarray Dataset inputted into the function, with a new varible containing the remote sensing index as a DataArray. If drop = True, the new variable/s as DataArrays in the original Dataset.

Return type

xarray Dataset