| Title: | Tools for Working with Hansen et al. Global Forest Change Dataset |
|---|---|
| Description: | Supports analyses using the Global Forest Change dataset released by Hansen et al. gfcanalysis was originally written for the Tropical Ecology Assessment and Monitoring (TEAM) Network. For additional details on the Global Forest Change dataset, see: Hansen, M. et al. 2013. "High-Resolution Global Maps of 21st-Century Forest Cover Change." Science 342 (15 November): 850-53. The forest change data and more information on the product is available at <http://earthenginepartners.appspot.com>. |
| Authors: | Alex Zvoleff [aut], Matthew Cooper [cre] |
| Maintainer: | Matthew Cooper <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 1.8.0 |
| Built: | 2024-11-02 03:41:54 UTC |
| Source: | https://github.com/azvoleff/gfcanalysis |
Produces an animation of annual forest change in the area bounded by the
extent of a given AOI, or AOIs. The AOI polygon(s) is(are) also plotted on
the image. The gfc_stack must be pre-calculated using the
annual_stack function. The animation can be either an animated
GIF (if type is set to 'gif') or a series of '.png' files with a
corresponding '.html' webpage showing a simple viewer and the forest change
animation (if type is set to 'html'). The HTML option is recommended
as it requires no additional software to produce it. The animated GIF option
will only work if the imagemagicK software package is installed beforehand
(this is done outside of R).
animate_annual( aoi, gfc_stack, out_dir = getwd(), out_basename = "gfc_animation", site_name = "", type = "html", height = 3, width = 3, dpi = 300, dataset = "GFC-2022-v1.10" )animate_annual( aoi, gfc_stack, out_dir = getwd(), out_basename = "gfc_animation", site_name = "", type = "html", height = 3, width = 3, dpi = 300, dataset = "GFC-2022-v1.10" )
aoi |
one or more AOI polygons as a |
gfc_stack |
a GFC product subset as a
|
out_dir |
folder for animation output |
out_basename |
basename to use when naming animation files |
site_name |
name of the site (used in making title) |
type |
type of animation to make. Can be either "gif" or "html" |
height |
desired height of the animation GIF in inches |
width |
desired width of the animation GIF in inches |
dpi |
dots per inch for the output image |
dataset |
which version of the Hansen data to use
|
Uses thresholded GFC data as output by threshold_gfc to make
an annualized layer stack of forest change. See Details for the class codes
used in the annual raster stack. The animate_annual function
can be used to produce an animation of forest change from the generated
layer stack.
annual_stack(gfc, dataset = "GFC-2022-v1.10")annual_stack(gfc, dataset = "GFC-2022-v1.10")
gfc |
thresholded extract of GFC product for a given AOI (see
|
dataset |
which version of the Hansen data to use |
The output raster stack uses the following codes to describe forest change at each pixel:
| Nodata | 0 |
| Forest | 1 |
| Non-forest | 2 |
| Forest loss | 3 |
| Forest gain | 4 |
| Forest loss and gain | 5 |
| Water | 6 |
Intersects an AOI with the GFC product grid to determine what tiles are need to cover the AOI.
calc_gfc_tiles(aoi)calc_gfc_tiles(aoi)
aoi |
an Area of Interest (AOI) as a |
a sf of the GFC tiles needed to cover
the AOI
tiles <- calc_gfc_tiles(test_poly) plot(tiles) plot(test_poly, lt=2, add=TRUE)tiles <- calc_gfc_tiles(test_poly) plot(tiles) plot(test_poly, lt=2, add=TRUE)
Calculates the pixel area for each line of a raster
calc_pixel_areas(x)calc_pixel_areas(x)
x |
a |
a vector with the area in square meters of the pixels in each line
of x (vector has length equal to nrow(x))
Check if aoi is an sf or sp type object If sp, convert to sf and return
check_aoi(aoi)check_aoi(aoi)
aoi |
the area of interest object |
This function first checks whether each tile in a set GFC product tiles is present locally, and that local file sizes match the file sizes of the files available on the Google server hosting the GFC product. Next, the function downloads all tiles that either are not present locally, or that are present but have file sizes differing from the file on the Google server.
download_tiles( tiles, output_folder, images = c("treecover2000", "lossyear", "gain", "datamask"), dataset = "GFC-2022-v1.10" )download_tiles( tiles, output_folder, images = c("treecover2000", "lossyear", "gain", "datamask"), dataset = "GFC-2022-v1.10" )
tiles |
|
output_folder |
the folder to save output data in |
images |
which images to download. Can be any of 'treecover2000', 'loss', 'gain', 'lossyear', 'datamask', 'first', and 'last'. |
dataset |
which version of the Hansen data to use |
## Not run: output_folder <- 'H:/Data/TEAM/GFC_Product' tiles <- calc_gfc_tiles(test_poly) download_tiles(tiles, output_folder) ## End(Not run)## Not run: output_folder <- 'H:/Data/TEAM/GFC_Product' tiles <- calc_gfc_tiles(test_poly) download_tiles(tiles, output_folder) ## End(Not run)
This function extracts a dataset for a given AOI from a series of
pre-downloaded GFC tiles. The download_tiles function should
be used beforehand in order to download the necessary data to the specified
data_folder. Note that the output file format is fixed as GeoTIFF
with LZW compression.
extract_gfc( aoi, data_folder, to_UTM = FALSE, stack = "change", dataset = "GFC-2022-v1.10", ... )extract_gfc( aoi, data_folder, to_UTM = FALSE, stack = "change", dataset = "GFC-2022-v1.10", ... )
aoi |
an Area of Interest (AOI) as a |
data_folder |
folder where downloaded GFC product tiles are located
(see |
to_UTM |
if TRUE, then reproject the output into the UTM zone of the AOI centroid. If FALSE, retain the original WGS84 projection of the GFC tiles. |
stack |
the layers to extract from the GFC product. Defaults to "change". See Details. |
dataset |
which version of the Hansen data to use |
... |
additional arguments as for |
The stack option can be "change" (the default), "first", or "last".
When set to "change", the forest change layers (treecover2000, loss, gain,
lossyear, and datamask) will be extracted for the given aoi. The
"first" and "last" options will mosaic the 2000 or last year composite top
of atmosphere (TOA) reflectance images (respectively).
RasterStack with GFC layers
download_tiles, annual_stack,
gfc_stats
For a given AOI, this function produces two tables: an annual forest loss
table (in hectares, by default), and a table specifying 1) the total area of
pixels that experienced forest gain and, 2) the total area of pixels that
experienced both loss and gain over the full period (from 2000 through the
end date of the specific product you are using, depending on the chosen
dataset). Note that forest gain and combined loss and gain are not
available in the GFC product on an annualized basis. Use
extract_gfc to extract the GFC data for the AOI, and threshold
it using threshold_gfc prior to running this function.
gfc_stats(aoi, gfc, scale_factor = 1e-04, dataset = "GFC-2022-v1.10")gfc_stats(aoi, gfc, scale_factor = 1e-04, dataset = "GFC-2022-v1.10")
aoi |
one or more Area of Interest (AOI) polygon(s) as a
|
gfc |
extract of GFC product for a given AOI (see
|
scale_factor |
how to scale the output data (from meters). Defaults to .0001 for output in hectares. |
dataset |
which version of the Hansen data to use |
If theaoi object is not in the coordinate
system of gfc, it will be reprojected. If there is a "label"
attribute, it will be used to label the output statistics. Otherwise,
unique names ("AOI 1", "AOI 2", etc.) will be generated and used to label
the output. If multiple AOIs share the same labels, statistics will be
provided for the union of these AOIs.
list with two elements "loss_table", a data.frame with
statistics on forest loss, and "gain_table", with the area of forest gain,
and area that experienced both loss and gain. The units of the output are
hectares (when scale_factor is set to .0001).
Contains a SpatialPolygonsDataFrame with a 10 x 10 degree grid in
WGS84 coordinate system, covering the area from 180W-180E and 80N-60S, the
tile system used by the GFC Product.
Plots a single layer of forest change from a layer stack output by
annual_stack.
plot_gfc(fchg, aoi, title_string = "", size_scale = 1, maxpixels = 50000)plot_gfc(fchg, aoi, title_string = "", size_scale = 1, maxpixels = 50000)
fchg |
a forest change raster layer (a single layer of the layer
stack output by |
aoi |
one or more AOI polygons as a |
title_string |
the plot title |
size_scale |
a number used to scale the size of the plot text |
maxpixels |
the maximum number of pixels from fchg to use in plotting |
Calculates the area (in meters) of each pixel in a raster, scales the value
of each pixel by the area, applies the desired scale factor, and returns the
result as a RasterLayer. Useful for calculating class areas based on
a classified raster in a geographic coordinate system. Assumes that raster
is not rotated (latitudes of every pixel in a given row are identical).
Processes block by block to support handling very large rasters.
scale_by_pixel_area( x, filename, datatype, pixel_areas = NULL, scale_factor = 1 )scale_by_pixel_area( x, filename, datatype, pixel_areas = NULL, scale_factor = 1 )
x |
a |
filename |
(optional) filename for output raster |
datatype |
(optional) datatype for output raster see
|
pixel_areas |
a vector giving the area of each cell in a single column
of the raster. See |
scale_factor |
a value to scale the results by |
RasterLayer with pixel areas (in meters)
This function applies the scale factors provided by Hansen et al. to rescale the first and last TOA reflectance images from integer to floating point. The following scale factors are used: band 3, 508; band 4, 254; band 5, 363; band 7, 423. The output datatype is FLT4S.
scale_toar(x, ...)scale_toar(x, ...)
x |
the "first" or "last" image for a given aoi as a |
... |
additional arguments as for |
RasterStack of TOA reflectance values
Contains a SpatialPolygonsDataFrame with a simplified polygon of the
area within the Tropical Ecology Assessment and Monitoring (TEAM) network
site in Caxiuanã, Brazil.
Uses the GFC data output from extract_gfc to make an
thresholded layer stack with five layers: treecover2000, loss, gain,
lossyear, and datamask layers. See Details for the coding used in each
layer. Note that the output file format is fixed as GeoTIFF with LZW
compression.
threshold_gfc(gfc, forest_threshold = 25, ...)threshold_gfc(gfc, forest_threshold = 25, ...)
gfc |
extract of GFC product for a given AOI (see
|
forest_threshold |
percent woody vegetation to use as a threshold for mapping forest/non-forest |
... |
additional arguments as for writeRaster, such as |
The output uses the following codes to describe forest change at each pixel:
Band 1 (forest2000)
| Non-forest | 0 |
| Forest | 1 |
Band 2 (lossyear)
| No loss | 0 |
| Loss in 2001 | 1 |
| Loss in 2002 | 2 |
| Loss in 2003 | 3 |
| Loss in 2004 | 4 |
| Loss in 2005 | 5 |
| Loss in 2006 | 6 |
| Loss in 2007 | 7 |
| Loss in 2008 | 8 |
| Loss in 2009 | 9 |
| Loss in 2010 | 10 |
| Loss in 2011 | 11 |
| Loss in 2012 | 12 |
| Loss in 2013 | 13 |
| Loss in 2014 | 14 |
Note that lossyear is zero for pixels that were not forested in 2000, and that the 2013 and 2014 loss layers are not available in the original 2013 Hansen dataset (the 2013 loss layer is available in the 2014 and 2015 updates, while the 2014 loss layer is available in the 2015 update only).
Band 3 (gain)
| No gain | 0 |
| Gain | 1 |
Note that gain is zero for pixels that were forested in 2000
Band 4 (lossgain)
| No loss and gain | 0 |
| Loss and gain | 1 |
Note that loss and gain is difficult to interpret from the thresholded
product, as the original GFC product does not provide information on the
sequence (loss then gain, or gain then loss), or the levels of canopy cover
reached prior to loss (for gain then loss) or after loss (for loss then gain
pixels). The layer is calculated here as: lossgain <- gain & (lossyear
!= 0), where loss year and gain are the original GFC gain and lossyear
layers, respectively.
Band 5 (datamask)
| No data | 0 |
| Land | 1 |
| Water | 2 |
RasterBrick with thresholded GFC product (see details above)
For a line or polygon, the UTM zone of the centroid is given, after reprojecting the object into WGS-84.
utm_zone(x, y, proj4string = FALSE) ## S4 method for signature 'numeric,numeric' utm_zone(x, y, proj4string = FALSE) ## S4 method for signature 'Spatial,missing' utm_zone(x, proj4string)utm_zone(x, y, proj4string = FALSE) ## S4 method for signature 'numeric,numeric' utm_zone(x, y, proj4string = FALSE) ## S4 method for signature 'Spatial,missing' utm_zone(x, proj4string)
x |
a longitude (with western hemisphere longitudes negative), or a
|
y |
a latitude (with southern hemisphere latitudes negative), or
missing (if x is a |
proj4string |
if FALSE (default) return the UTM zone as a string (for example "34S" for UTM Zone 34 South). If TRUE, return a proj4string using the EPSG code as an initialization string. |
Based on the code on gis.stackexchange.com at http://bit.ly/17SdcuN.
utm_zone(45, 10) utm_zone(45, -10) utm_zone(45, 10, proj4string=TRUE)utm_zone(45, 10) utm_zone(45, -10) utm_zone(45, 10, proj4string=TRUE)