get_fcc_loss(aoi, buff=0, years=None, source='tmf', perc=75, tile_size=1, crop_to_aoi=False, parallel=False, ncpu=None, output_file='fcc.tif')[source]

Get forest cover change data.

Produce a forest cover change raster file. One band for each year. Value 1 for forest and 0 for non-forest.

Parameters:

  • aoi (str or tuple) – Area of interest defined either by a country iso code (three letters), a vector file path, or an extent in lat/long as a tuple with (xmin, ymin, xmax, ymax).

  • buff (float, optional) – Buffer around the aoi in decimal degrees. Default is 0.

  • years (list of int, optional) – List of years defining time-periods for estimating forest cover change. Default is [2000, 2010, 2020].

  • source ({"tmf", "gfc"}, optional) – Source of forest cover data. Default is "tmf".

  • perc (int, optional) – Tree cover threshold (percentage) for the GFC product. Default is 75.

  • tile_size (int or float, optional) – Tile size in degrees for parallel computing. Default is 1.

  • crop_to_aoi (bool, optional) – Crop the raster to the aoi with buffer. Default is False.

  • parallel (bool, optional) – Use parallel computing. Default is False.

  • ncpu (int or None, optional) – Number of CPUs for parallel computing. Default is None.

  • output_file (str or Path, optional) – Path to output GeoTIFF file. Default is "fcc.tif".

Return type:

None

Examples

>>> get_fcc_loss(
...     aoi="BRA",
...     years=[2000, 2010, 2020],
...     source="tmf",
...     output_file="output/fcc_brazil.tif"
... )
get_fcc_loss_gain(aoi, buff=0, year1=2005, year2=2025, min_years=10, tile_size=1, crop_to_aoi=False, parallel=False, ncpu=None, output_file='fcc.tif')[source]

Get forest cover change data with loss and gain.

Produce a forest cover change raster file with loss and gain.

Parameters:

  • aoi (str or tuple) – Area of interest defined either by a country iso code (three letters), a vector file path, or an extent in lat/long as a tuple with (xmin, ymin, xmax, ymax).

  • buff (float, optional) – Buffer around the aoi in decimal degrees. Default is 0.

  • year1 (int, optional) – Start year. Default is 2005.

  • year2 (int, optional) – End year. Must be greater than year1. Default is 2025.

  • min_years (int, optional) – Minimum consecutive years classified as regrowth to be considered “old regrowth”. Default is 10.

  • tile_size (int or float, optional) – Tile size in degrees. Default is 1.

  • crop_to_aoi (bool, optional) – Crop output raster to the aoi. Default is False.

  • parallel (bool, optional) – Use parallel computing. Default is False.

  • ncpu (int or None, optional) – Number of CPUs for parallel computing. Default is None.

  • output_file (str, optional) – Path to the output GeoTIFF file. Default is "fcc.tif".

Return type:

None

Examples

>>> get_fcc_loss_gain(
...     aoi="MDG",
...     year1=2010,
...     year2=2020,
...     min_years=10,
...     crop_to_aoi=True,
...     output_file="output/fcc_madagascar.tif"
... )

Plot

plot_fcc_loss(input_file, years, output_file='fcc_loss.png', title='Forest cover change', dpi=100, max_pixels=10000000, borders=None, buffer=None, grid=None, xlim=None, ylim=None)[source]

Plot a forest cover change map from the TMF or GFC loss product.

Produces a PNG map from a single-band raster file obtained by summing the bands of a multiband raster produced by get_fcc_loss() (e.g. with sum_raster_bands()). Pixel values encode forest cover change classes:

  • 0 = non-forest at years[0]

  • 1 = deforestation during period 1 (years[0]–years[1])

  • 2 = deforestation during period 2 (years[1]–years[2])

  • … (one class per intermediate period)

  • n = forest at years[-1]

Colors are fixed: transparent for class 0 (non-forest), then orange, red, and forest green for the last class (remaining forest).

If the raster exceeds max_pixels pixels, it is automatically resampled to a coarser resolution before plotting, using nearest neighbour resampling. The resampled raster is saved alongside the input file (suffix _coarsen.tif) and reused on subsequent calls.

Parameters:

  • input_file (str or Path) – Path to the single-band GeoTIFF raster file. Pixel values must be integers in the range 0–n where n = len(years) - 1.

  • years (list of int) – List of years used for the forest cover change computation, e.g. [2000, 2010, 2020]. Used to build legend labels.

  • output_file (str or Path, optional) – Path to the output PNG file. Default is "fcc_loss.png".

  • title (str, optional) – Title displayed above the map. Default is "Forest cover change".

  • dpi (int, optional) – Resolution of the output figure in dots per inch. Default is 100.

  • max_pixels (int, optional) – Maximum number of pixels (rows x columns) allowed before automatic resampling is triggered. Default is 10_000_000.

  • borders (str, Path, geopandas.GeoDataFrame, or None, optional) – Country or administrative borders to overlay as a black line. Accepts a file path or an already-loaded geopandas.GeoDataFrame. Default is None.

  • buffer (str, Path, geopandas.GeoDataFrame, or None, optional) – Buffer polygon to overlay as a black dashed line. Accepts a file path or an already-loaded geopandas.GeoDataFrame. Default is None.

  • grid (str, Path, geopandas.GeoDataFrame, or None, optional) – Download tile grid to overlay as a grey line. Accepts a file path or an already-loaded geopandas.GeoDataFrame. Default is None.

  • xlim (tuple of float or None, optional) – Longitude limits of the map as (xmin, xmax). Default is None (derived from the raster).

  • ylim (tuple of float or None, optional) – Latitude limits of the map as (ymin, ymax). Default is None (derived from the raster).

Returns:

The function writes the figure directly to output_file.

Return type:

None

Examples

Simple plot:

>>> plot_fcc_loss(
...     input_file="out_tmf/fcc_tmf.tif",
...     years=[2000, 2010, 2020],
...     output_file="fcc_loss.png",
...     title="Forest cover change 2000-2010-2020, TMF",
...     dpi=100,
... )

Plot with borders, buffer and grid:

>>> plot_fcc_loss(
...     input_file="out_tmf/fcc_tmf.tif",
...     years=[2000, 2010, 2020],
...     output_file="fcc_loss.png",
...     title="Forest cover change 2000-2010-2020, TMF",
...     dpi=200,
...     borders="out_tmf/gadm41_PER_0.gpkg",
...     buffer="out_tmf/gadm41_PER_buffer.gpkg",
...     grid="out_tmf/min_grid.gpkg",
... )
plot_fcc_loss_gain(input_file, output_file='fcc_loss_gain.png', title='Forest cover change, TMF', dpi=100, max_pixels=10000000, borders=None, grid=None, xlim=None, ylim=None)[source]

Plot a forest cover change map from the TMF loss and gain product.

Produces a PNG map from a raster file generated by get_fcc_loss_gain(). The seven transition classes (0–6) are each assigned a distinct color and a legend is added to the right of the map. Optionally, vector layers (borders, grid) can be overlaid and the spatial extent of the map can be controlled.

If the raster exceeds max_pixels pixels, it is automatically resampled to a coarser resolution before plotting, using nearest neighbour resampling. The resampled raster is saved alongside the input file (suffix _coarsen.tif) and reused on subsequent calls.

Class definitions:

  • 0 = stable non-forest

  • 1 = stable forest

  • 2 = forest to deforested

  • 3 = non-forest to old regrowth

  • 4 = forest to old regrowth (via deforestation)

  • 5 = stable old regrowth

  • 6 = old regrowth to deforested

Parameters:

  • input_file (str or Path) – Path to the input GeoTIFF raster file produced by get_fcc_loss_gain(). Pixel values must be integers in the range 0–6.

  • output_file (str or Path, optional) – Path to the output PNG file. Default is "fcc_loss_gain.png".

  • title (str, optional) – Title displayed above the map. Default is "Forest cover change, TMF".

  • dpi (int, optional) – Resolution of the output figure in dots per inch. Default is 100.

  • max_pixels (int, optional) – Maximum number of pixels (rows x columns) allowed before automatic resampling is triggered. Default is 10_000_000.

  • borders (str, Path, geopandas.GeoDataFrame, or None, optional) – Country or administrative borders to overlay as a black line. Default is None.

  • grid (str, Path, geopandas.GeoDataFrame, or None, optional) – Download tile grid to overlay as a grey line. Default is None.

  • xlim (tuple of float or None, optional) – Longitude limits as (xmin, xmax). Default is None.

  • ylim (tuple of float or None, optional) – Latitude limits as (ymin, ymax). Default is None.

Returns:

The function writes the figure directly to output_file.

Return type:

None

Examples

Simple plot:

>>> plot_fcc_loss_gain(
...     input_file="out_tmf_5yr/fcc_tmf.tif",
...     output_file="fcc_loss_gain.png",
...     title="Forest cover change 2015-2025, TMF",
...     dpi=100,
... )

Plot with borders and grid:

>>> plot_fcc_loss_gain(
...     input_file="out_tmf_5yr/fcc_tmf.tif",
...     output_file="fcc_tmf_5yr.png",
...     title="Forest cover change 2015-2025, TMF",
...     dpi=200,
...     borders="data/borders_NCL.gpkg",
...     grid="out_tmf_5yr/grid.gpkg",
...     xlim=(163, 169),
...     ylim=(-23.25, -18.75),
... )

Stat

stat_fcc_loss(input_file, years, epsg, output_file='fcc_statistics.csv')[source]

Compute statistics per class for a TMF or GFC loss forest cover change raster.

Reprojects the input raster to a metric CRS, then uses dask.array.bincount() to count pixels per class and converts counts to hectares. The input raster must be a single-band raster produced by sum_raster_bands() applied to the output of get_fcc_loss().

Pixel values encode the following classes:

  • 0 = non-forest at years[0]

  • 1 = deforestation during period 1 (years[0]–years[1])

  • 2 = deforestation during period 2 (years[1]–years[2])

  • … (one class per intermediate period)

  • n = forest at years[-1]

Parameters:

  • input_file (str or Path) – Path to the single-band GeoTIFF raster file (in EPSG:4326) produced by sum_raster_bands().

  • years (list of int) – List of years, e.g. [2000, 2010, 2020].

  • epsg (int) – EPSG code of a metric CRS (e.g. 32740 for UTM zone 40S).

  • output_file (str or Path, optional) – Path to the output CSV file. Default is "fcc_statistics.csv".

Returns:

DataFrame with columns category, label, count, area_ha. Also written to output_file.

Return type:

pandas.DataFrame

Examples

>>> import geefcc
>>> res_df = geefcc.stat_fcc_loss(
...     input_file="out_tmf/fcc_tmf.tif",
...     years=[2000, 2010, 2020],
...     epsg=32740,
...     output_file="fcc_statistics.csv",
... )
stat_fcc_loss_gain(input_file, epsg, output_file='fcc_statistics.csv')[source]

Compute statistics per class for a TMF loss and gain forest cover change raster.

Reprojects the input raster to a metric CRS, then uses dask.array.bincount() to count pixels per class and converts counts to hectares.

The seven transition classes produced by get_fcc_loss_gain() are:

  • 0 = stable non-forest

  • 1 = stable forest

  • 2 = forest to deforested

  • 3 = non-forest to old regrowth

  • 4 = forest to old regrowth (via deforestation)

  • 5 = stable old regrowth

  • 6 = old regrowth to deforested

Parameters:

  • input_file (str or Path) – Path to the input GeoTIFF raster file (in EPSG:4326) produced by get_fcc_loss_gain().

  • epsg (int) – EPSG code of a metric CRS (e.g. 32740 for UTM zone 40S).

  • output_file (str or Path, optional) – Path to the output CSV file. Default is "fcc_statistics.csv".

Returns:

DataFrame with columns category, label, count, area_ha. All seven classes included. Also written to output_file.

Return type:

pandas.DataFrame

Notes

The reprojected raster is saved alongside the input file (suffix _epsg<EPSG>.tif) and reused on subsequent calls.

Examples

>>> import geefcc
>>> res_df = geefcc.stat_fcc_loss_gain(
...     input_file="out_tmf_5yr/fcc_tmf.tif",
...     epsg=32740,
...     output_file="fcc_statistics.csv",
... )

Utilities

ee_initialize(token_name, project, **kwargs)[source]

Initialize Google Earth Engine (GEE).

Parameters:

  • token_name (str) – The name of the environment variable containing the Earth Engine authentication token.

  • project (str) – Name of the Google Cloud project to use with Earth Engine.

  • **kwargs (dict, optional) – Additional keyword arguments passed to ee.Initialize().

Return type:

None

sum_raster_bands(input_file, output_file='sum.tif', blk_rows=128, verbose=True)[source]

Sum the raster bands of a multi-band input file into a single output band.

Reads the input raster file band by band in configurable block sizes to manage memory usage, computes the pixel-wise sum across all bands, and writes the result to a single-band GeoTIFF output file.

Parameters:

  • input_file (str or Path) – Path to the input raster file containing several bands to be summed.

  • output_file (str or Path, optional) – Path to the output GeoTIFF file with one band corresponding to the sum of the input bands. Defaults to "sum.tif".

  • blk_rows (int, optional) – Number of rows per processing block. Used to break large raster files into several blocks of data that can be held in memory at one time. Defaults to 128.

  • verbose (bool, optional) – Whether to print progress messages during processing. Defaults to True.

Returns:

The function writes results directly to output_file and does not return a value.

Return type:

None

Raises:

RuntimeError – If input_file cannot be opened by GDAL or if the output raster cannot be created.

Notes

  • The output raster is created with gdal.GDT_Byte data type, DEFLATE compression, and BIGTIFF support enabled.

  • A NoData value of 255 is assigned to the output band.

  • If output_file already exists, it will be removed before the new file is created.

  • Band statistics are computed and flushed to disk after all blocks have been processed.

Examples

>>> sum_raster_bands(
...     input_file="input_multiband.tif",
...     output_file="sum.tif",
...     blk_rows=256,
...     verbose=True,
... )
make_dir(newdir)[source]

Make new directory.

Handles three cases:

  • Already exists, silently complete

  • Regular file in the way, raise an exception

  • Parent directory(ies) does not exist, make them as well

Parameters:

newdir (str or Path) – Directory path to create.

Raises:

OSError – If a file with the same name as the desired directory already exists.

Examples

>>> make_dir("/tmp/new_directory")
>>> make_dir("/tmp/parent/child/grandchild")

Deprecated

get_fcc(aoi, buff=0, years=None, source='tmf', perc=75, tile_size=1, crop_to_aoi=False, parallel=False, ncpu=None, output_file='fcc.tif')[source]

Deprecated since version 0.1.8.

Use get_fcc_loss() instead.