deafrica_tools.bandindices
Functions for computing remote sensing band indices on Digital Earth Africa data.
Functions
|
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. |
|
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: xarray.Dataset, index: str | list[str] = None, collection: str = None, satellite_mission: str = None, custom_varname: str = None, normalise: bool = True, drop: bool = False, deep_copy: bool = True) xarray.Dataset
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 2022
- 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:
'ASI'(Artificial Surface Index, Yongquan Zhao & Zhe Zhu 2022)'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)'MBI'(Modified Bare Soil Index, Nguyen et al. 2021)'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)'NDTI'(Normalised Difference Turbidity Index, Lacaux et al. 2007)'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) –
Deprecated in version 0.1.7. Use satellite_mission instead.
Valid options are: *
'c2'(for USGS Landsat Collection 2)If ‘c2’, then satellite_mission=’ls’.
's2'(for Sentinel-2)If ‘s2’, then satellite_mission=’s2’.
satellite_mission (str) –
An string that tells the function which satellite mission’s data is being used to calculate the index. This is necessary because different satellite missions use different names for bands covering a similar spectra.
Valid options are:
'ls'(for USGS Landsat)'s2'(for Copernicus Sentinel-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: xarray.Dataset, co_pol: str = 'vv', cross_pol: str = 'vh', index: str | list[str] = None, custom_varname: str = None, drop: bool = False, deep_copy: bool = True) xarray.Dataset
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