API Documentation
This page provides a summary of spectral-recovery's public API. For details and examples, see the relevant tutorials in the Documentation page.
Reading timeseries data
src.spectral_recovery.io.raster.read_timeseries(path_to_tifs, band_names=None, array_type='dask')
Reads a timeseries of tifs into a 4D Xarray DataArray.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path_to_tifs |
dict or str
|
Dict of str paths to TIFs with keys as the year each raster or str path to directory containing TIFs. |
required |
band_names |
dict
|
Dictionary mapping band numbers to band names. If not provided, band names will be read from the TIFs band descriptions. Values can be short or long spectral band names or short index names. |
None
|
array_type |
(dask, numpy)
|
The type of array to use store data, either numpy or dask. NumPy arrays will be loaded into memory while Dask arrays will be lazily evaluated until being explicitly loaded into memory with a .compute() call. Default is "dask". |
"dask"
|
Returns:
| Name | Type | Description |
|---|---|---|
stacked_data |
DataArray
|
A 4D DataArray containing all rasters passed to
|
Notes
If passing a directory of tifs to path_to_tifs, each file must be named following a 'YYYY.tif' format, where 'YYYY' is a valid year.
Reading restoration site data
src.spectral_recovery.io.polygon.read_restoration_sites(path, dist_rest_years=None)
Read restoration polygons
A loose wrapper of the geopandas.read_file function that ensures each polygon has a valid disturbance and restoration start year.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path |
str
|
path to restoration polygon vector file |
required |
dist_rest_years |
dict
|
Mapping of polygon id to a list with disturbance and restoration start years, respectively. e.g {0: [2006. 2007]} will map a disturbance start of 2006 and restoration start of 2007 to polygon 0. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
restoration_polygons |
GeoDataFrame
|
The restoration site polygons with assiged disturbance start, and restoration start years. Disturbance start years are stored in "dist_start" col while restoration start years are stored in "rest_start" col. |
Computing indices
src.spectral_recovery.indices.compute_indices(timeseries_data, indices, constants=None, **kwargs)
Compute spectral indices.
Compute spectral indices using the spyndex package or manually implemented indices.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timeseries_data |
DataArray
|
The timeseries of spectral bands to compute indices with. Must contain band, time, y, and x dimensions. |
required |
indices |
list of str
|
list of spectral indices to compute |
required |
constants |
dict of flt
|
constant and value pairs e.g {"L": 0.5} |
None
|
kwargs |
dict
|
Additional kwargs for wrapped spyndex.computeIndex function. |
{}
|
Returns:
| Name | Type | Description |
|---|---|---|
index_stack |
DataArray
|
DataArray of spectral indices, with spectral indices stacked along the band coordinate dimension. |
Computing recovery targets
Historic recovery targets
src.spectral_recovery.targets.historic
Methods for computing historic recovery targets
median(restoration_sites, timeseries_data, reference_years, scale)
Median target method for historic targets.
Sequentially computes the median over time and, optionally, the spatial dimensions (x and y) for each restoration site in the GeoDataFrame. Scale parameter used to determine the scale of the target for each polygon.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
restoration_sites |
GeoDataFrame
|
The restoration sites to compute a recovery targets for. |
required |
timeseries_data |
DataArray
|
The timeseries of indices to derive the recovery target from. Must contain band, time, y, and x dimensions. |
required |
reference_years |
dict
|
Dictionary mapping reference_start and reference_end years to each polygon in restoration_sites, e.g {0: {"reference_start": 2017, "reference_end": 2018}} |
required |
scale |
(polygon, pixel)
|
The scale to compute target for. Either 'polygon' which results in one value per-band (median of the polygon(s) across time), or 'pixel' which results in a value for each pixel per-band (median of each pixel across time). |
"polygon"
|
Returns:
| Name | Type | Description |
|---|---|---|
median_targets |
dict
|
Dictionary of DataArrays containing the median recovery target for each restoration site by polygon ID. If scale="polygon", then DataArrays have coordinate dimensions "band". If scale="pixel", has coordinate dimensions "band", "y" and "x". |
Notes
Differs from spectral_recovery.targets.reference.median because 1) can be parameterized on scale, and 2) because multiple polygons are not reduced into a single value, i.e if 3 sites are given to this method then recovery targets are given for each of those 3 sites.
window(restoration_sites, timeseries_data, reference_years, N=3, na_rm=False)
Windowed recovery target method, parameterized on window size.
The windowed method first computes the median along the time dimension and then for each pixel p in the restoration site polygon, computes the mean of a window of NxN pixels centred on pixel p, setting the mean to the recovery target value.
Implementation is based on raster focal method in R.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
restoration_sites |
GeoDataFrame
|
The restoration sites to compute a recovery targets for. |
required |
timeseries_data |
DataArrah
|
The timeseries of indices to derive the recovery target from. Must contain band, time, y, and x dimensions. |
required |
reference_years |
dict
|
Dictionary mapping between each polygon and a list with a reference start and reference end year. respectivaly, e.g {0: [2017, 2018]} |
required |
N |
int
|
Size of the window (NxN). Must be odd. Default is 3. |
3
|
na_rm |
bool
|
If True, NaN will be removed from focal computations. The result will only be NA if all focal cells are NA., using na.rm=TRUE may not be a good idea in this function because it can unbalance the effect of the weights |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
window_targets |
dict
|
Dictionary of DataArrays containing the median recovery target for each restoration site by polygon ID. |
Reference recovery targets
src.spectral_recovery.targets.reference
Methods for computing reference-based recovery targets
median(reference_sites, timeseries_data, reference_start, reference_end)
Median target method for reference sites.
Sequentially computes the median over time and the spatial dimensions (x and y). If there is more than one reference site in the GeoDataFrame then the median is also then taken from all reference site medians.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
restoration_sites |
GeoDataFrame or str
|
The restoration sites to compute a recovery targets for. If str, must be a patch to a vector file containing one more more polygons. |
required |
timeseries_data |
DataArray
|
The timeseries of indices to derive the recovery target from. Must contain band, time, y, and x dimensions. |
required |
reference_start |
int
|
Start year of reference window. Must exist in timeseries_data's time coordinates. |
required |
reference_end |
int
|
End year of reference window. Must exist in timeseries_data's time coordinates. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
median_t |
DataArray
|
DataArray of the median recovery targets with 1 coordinate dimension, "band". |
Notes
Differs from spectral_recovery.targets.historic.median because 1) no scale parameter is given because a reference site can only be of scale "polygon", and 2) because multiple polygons are reduced to a single value.
Compute recovery metrics
src.spectral_recovery.metrics
Methods for computing recovery metrics.
compute_metrics(metrics, timeseries_data, restoration_sites, recovery_targets=None, timestep=5, percent_of_target=80)
Compute recovery metrics for each restoration site.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
metrics |
list of str
|
The names of recovery metrics to compute. Accepted values: - "Y2R": Years-to-Recovery - "R80P": Recovered 80 Percent - "deltaIR": delta Index Regrowth - "YrYr": Year-on-Year Average - "RRI": Relative Recovery Indicator |
required |
timeseries_data |
DataArray
|
The timeseries of indices to compute recovery metrics with. Must contain band, time, y, and x dimensions. |
required |
restoration_sites |
GeoDataFrame
|
The restoration sites to compute a recovery targets for. |
required |
recovery_targets |
DataArray or dict
|
The recovery targets. Either a dict mapping polygon IDs to xarray.DataArrays of recovery targets or a single xarray.DataArray. |
None
|
timestep |
int
|
The timestep post-restoration to consider when computing recovery metrics. Only used for "R80P", "deltaIR", and "YrYr" and "RRI" recovery metrics. Default = 5. |
5
|
percent_of_target |
int
|
The percent of the recovery target to consider when computing recovery metrics. Only used for "Y2R" and "R80P". Default = 80. |
80
|
Returns:
| Name | Type | Description |
|---|---|---|
metric_ds |
Dataset
|
Dataset of restoration site ID variables, each containing an array of recovery metrics specific to each site. |
Notes
Recovery target arrays must be broadcastable to the timeseries_data when timeseries_data is clipped to each restoration site.
deltair(restoration_start, timeseries_data, timestep=5)
Per-pixel deltaIR.
The absolute change in a spectral index’s value at a point in the restoration monitoring window from the start of the restoration monitoring window. The default is the change that has occurred 5 years into the restoration from the start of the restoration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
restoration_start |
int
|
The start year of restoration activities. |
required |
timeseries_data |
DataArray
|
The timeseries of indices to compute dIR with. Must contain band, time, y, and x coordinate dimensions. |
required |
timestep |
int
|
The timestep post-restoration to compute deltaIR with. |
5
|
Returns:
| Name | Type | Description |
|---|---|---|
deltair_v |
DataArray
|
DataArray containing the deltaIR value for each pixel. |
r80p(restoration_start, timeseries_data, recovery_target, timestep=5, percent_of_target=80)
Per-pixel R80P.
The extent to which the trajectory has reached 80% of the recovery
target value. The metric commonly uses the maximum value from the
4th or 5th year of restoration window to show the extent to which a
pixel has reached 80% of the target value 5 years into the restoration
window. However for monitoring purposes, this tool uses the selected timestep
or defaults to the current timestep to provide up to date recovery
progress. 80% of the recovery target value is the default, however this
can be changed by modifying the value of percent.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
restoration_start |
int
|
The start year of restoration activities. |
required |
timeseries_data |
DataArray
|
The timeseries of indices to compute R80P with. Must contain band, time, y, and x coordinate dimensions. |
required |
recovery_target |
DataArray
|
Recovery target values. Must be broadcastable to timeseries_data. |
required |
timestep |
int
|
The timestep post-restoration to compute R80P with. |
5
|
percent_of_target |
int
|
The percent of the recovery target to consider when computing R80P. |
80
|
Returns:
| Name | Type | Description |
|---|---|---|
r80p_v |
DataArray
|
DataArray containing the R80P value for each pixel. |
rri(disturbance_start, restoration_start, timeseries_data, timestep=5)
Per-pixel RRI.
A modified version of the commonly used RI, the RRI accounts for noise in trajectory by using the maximum from the 4th or 5th year in monitoring window. The metric relates recovery magnitude to disturbance magnitude, and is the change in index value in 4 or 5 years divided by the change due to disturbance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
disturbance_start |
int
|
The start year of the disturbance event. |
required |
restoration_start |
int
|
The start year of restoration activities. |
required |
timeseries_data |
DataArray
|
The timeseries of indices to compute RRI with. Must contain band, time, y, and x coordinate dimensions. |
required |
timestep |
int
|
The timestep post-restoration to compute RRI with. |
5
|
Returns:
| Name | Type | Description |
|---|---|---|
rri_v |
DataArray
|
DataArray containing the RRI value for each pixel. |
y2r(restoration_start, timeseries_data, recovery_target, percent_of_target=80)
Per-pixel Y2R.
The length of time taken (in time steps/years) for a given pixel to
first reach 80% of its recovery target value. The percent can be modified
by changing the value of percent.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
restoration_start |
int
|
The start year of restoration activities. |
required |
timeseries_data |
DataArray
|
The timeseries of indices to compute Y2R with. Must contain band, time, y, and x coordinate dimensions. |
required |
recovery_target |
DataArray
|
Recovery target values. Must be broadcastable to timeseries_data. |
required |
percent_of_target |
int
|
The percent of the recovery target to consider when computing Y2R. |
80
|
Returns:
| Name | Type | Description |
|---|---|---|
y2r_v |
DataArray
|
DataArray containing the number of years taken for each pixel to reach the recovery target value. NaN represents pixels that have not yet reached the recovery target value. |
yryr(restoration_start, timeseries_data, timestep=5)
Per-pixel YrYr.
The average annual recovery rate relative to a fixed time interval
during the restoration monitoring window. The default is the first 5
years of the restoration window, however this can be changed by specifying
the parameter timestep.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
restoration_start |
int
|
The start year of restoration activities. |
required |
timeseries_data |
DataArray
|
The timeseries of indices to compute YrYr with. Must contain band, time, y, and x coordinate dimensions. |
required |
timestep |
int
|
The timestep post-restoration to compute YrYr with. |
5
|
Returns:
| Name | Type | Description |
|---|---|---|
yryr_v |
DataArray
|
DataArray containing the YrYr value for each pixel. |
Plot spectral trajectory
src.spectral_recovery.plotting
Methods for plotting spectral trajectories
plot_spectral_trajectory(timeseries_data, restoration_site, recovery_target, reference_start=None, reference_end=None, path=None)
Plot the spectral trajectory of the restoration polygon
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timeseries_data |
DataArray
|
A timeseries of indices to plot the spectral trajectory with. |
required |
restoration_site |
GeoDataFrame
|
The resoration site to plot a spectral trajectory of. |
required |
recovery_target |
DataArray
|
The recovery target value for the given restoration site. |
required |
reference_start |
int
|
The first/start reference year. |
None
|
reference_end |
int
|
The final/end reference year. |
None
|
path |
str
|
Path and filename for writing plot. |
None
|