Python API

Main functions

riskmapjnr: mapping deforestation risk using the moving window approach. https://ecology.ghislainv.fr/riskmapknr/

defor_cat(ldefrate_with_zero_file, riskmap_file='riskmap.tif', ncat=30, method='Equal Area', blk_rows=128, verbose=True)[source]

Categorizing local deforestation rates.

This function categorizes the deforestation risk from the map of local deforestation rates. This function assumes that pixels with zero deforestation risk have been previously identified (see function set_defor_cat_zero()). Three categorization methods can be used, either “Equal Area”, “Equal Interval”, or “Natural Breaks”. When “Equal Area” is used, the classes with a risk > 0 have approximately the same surface area. When “Equal Interval” is used, some risk classes will predominate in the risk map while other classes will be present only in small areas. When “Natural Breaks” is used, the data is normalized before running the slicing algorithm.

Parameters:

  • ldefrate_with_zero_file – Input raster file of local deforestation rates. Deforestation rates are defined by integer values between 1 and 10000 (ten thousand)). Pixels with zero deforestation risk (beyond a given distance from the forest edge) have value 0. This file is typically obtained with function set_defor_cat_zero().

  • riskmap_file – Output raster file with categories of deforestation risk.

  • ncat – Number of deforestation risk categories (zero risk class excluded). Default to 30.

  • method – Method used for categorizing. Either “Equal Interval”, “Equal Area”, or “Natural Breaks”.

  • blk_rows – If > 0, number of rows for computation by block.

  • verbose – Logical. Whether to print messages or not. Default to True.

Returns:

Bins used to categorize the deforestation risk. A raster file with deforestation categories is created (see riskmap_file). Data range from 0 to 30. Raster type is Byte ([0, 255]). NoData value is set to 255.

defrate_per_cat(fcc_file, riskmap_file, time_interval, period='calibration', tab_file_defrate='defrate_per_cat.csv', blk_rows=128, verbose=True)[source]

Compute deforestation rates per category of deforestation risk.

This function computes the historical deforestation rates for each category of spatial deforestation risk.

Parameters:

  • fcc_file – Input raster file of forest cover change at three dates (123). 1: first period deforestation, 2: second period deforestation, 3: remaining forest at the end of the second period. No data value must be 0 (zero).

  • riskmap_file – Input raster file with categories of spatial deforestation risk.

  • time_interval – Time interval (in years) for forest cover change observations.

  • period – Either “calibration” (from t1 to t2), “validation” (or “confirmation” from t2 to t3), or “historical” (full historical period from t1 to t3). Default to “calibration”.

  • tab_file_defrate – Path to the .csv output file with estimates of deforestation rates per category of deforestation risk.

  • blk_rows – If > 0, number of rows for computation by block.

  • verbose – Logical. Whether to print messages or not. Default to True.

Returns:

None. A .csv file with deforestation rates per category of deforestation risk will be created (see tab_file_defrate).

dist_edge_threshold(fcc_file, defor_values, defor_threshold=99.5, dist_file='dist_edge.tif', dist_bins=array([0, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330, 360, 390, 420, 450, 480, 510, 540, 570, 600, 630, 660, 690, 720, 750, 780, 810, 840, 870, 900, 930, 960, 990, 1020, 1050]), tab_file_dist='perc_dist.csv', fig_file_dist='perc_dist.png', figsize=(6.4, 4.8), dpi=100, blk_rows=128, dist_file_available=False, check_fcc=True, verbose=True)[source]

Computing the percentage of total deforestation as a function of the distance to forest edge.

This function computes the percentage of total deforestation as a function of the distance to forest edge. It returns a table with the cumulative percentage of deforestation as distance to forest edge increases. It also identifies the distance threshold for the distance to forest edge so that the deforestation under that threshold is >= 99.5 % of the total deforestation in the landscape. The function also plots the relationship between the percentage of deforestation and the distance to forest edge. A raster of distance to forest edge will be created. The distance unit will be the one of the input file.

Parameters:

  • fcc_file – Input raster file of forest cover change at three dates (123). 1: first period deforestation, 2: second period deforestation, 3: remaining forest at the end of the second period. No data value must be 0 (zero). The raster must be projected to compute Euclidean distances with the gdal_proximity() function.

  • defor_values – Raster values to consider for deforestation. Must correspond to either scalar 1 if first period, or list [1, 2] if both first and second period are considered.

  • defor_threshold – Deforestation threshold (in percent). Default to 99.5.

  • dist_file – Path to either (i) the output raster file of distance to forest edge or (ii) the input raster file of distance to forest edge if dist_file_available is True. Raster of distance to forest edge is computed in the first case only. Default to dist_edge.tif.

  • dist_bins – Array of bins for distances. It has to be 1-dimensional and monotonic. The array must also include zero as the first value. Default to np.arange(0, 1080, step=30).

  • tab_file_dist –

    Path to the table .csv file that will be created. This table includes the following variables:

    • distance: bins of distance to forest edge (in m).

    • npix: the number of deforested pixels in each bin.

    • area: the corresponding area (in ha).

    • cum: the cumulative sum of the deforested area (in ha).

    • perc: the corresponding percentage of total deforestation.

  • fig_file_dist – Path to the plot file that will be created. This plot represents the cumulative deforestation percentage as the distance to forest edge increases.

  • figsize – Figure size.

  • dpi – Resolution for output image.

  • blk_rows – Number of rows for block. This is used to break lage raster files in several blocks of data that can be hold in memory.

  • dist_file_available – Boolean. If True, parameter dist_file indicates the input raster file of distance to forest edge which is not computed. Default to False.

  • check_fcc – Boolean. If True, performs some checks on the fcc input file. Default to True.

  • verbose – Logical. Whether to print messages or not. Default to True.

Returns:

A dictionary. With tot_def: total deforestation (in ha), dist_thresh: the distance threshold, perc: the percentage of deforestation for pixels with distance <= dist_thresh.

local_defor_rate(fcc_file, defor_values, ldefrate_file, win_size, time_interval, rescale_min_val=2, rescale_max_val=10000, blk_rows=128, verbose=True)[source]

Computing the local deforestation rate using a moving window.

This function computes the local deforestation rate using a moving window. SciPy is used for the focal analysis. The uniform_filter is used over the generic_filter. The generic_filter is 40 times slower than the strides implemented in the uniform_filter. For cells on the edge of the raster, the local deforestation rate is computed from a lower number of existing cells in the moving window using mode='constant' and cval=0.

Parameters:

  • fcc_file – Input raster file of forest cover change at three dates (123). 1: first period deforestation, 2: second period deforestation, 3: remaining forest at the end of the second period. NoData value must be 0 (zero).

  • defor_values – Raster values to consider for deforestation. Must correspond to either scalar 1 if first period, or list [1, 2] if both first and second period are considered.

  • ldefrate_file – Output raster file.

  • win_size – Size of the moving window in number of cells. Must be an odd number lower or equal to blk_rows.

  • time_interval – Time interval (in years) for forest cover change observations.

  • rescale_min_val – Integer. Minimal value for rescaling. Down to 1. Default to 1.

  • rescale_max_val – Integer. Maximal value for rescaling. Up to 65535. Default to 10000.

  • blk_rows – Number of rows for block. Must be greater or equal to win_size. This is used to break lage raster files in several blocks of data that can be hold in memory.

  • verbose – Logical. Whether to print messages or not. Default to True.

Returns:

None. A raster with the local deforestation rate will be created (see ldefrate_file). Data range from 1 to 10000. Raster type is UInt16 ([0, 65535]). NoData value is set to 65535.

makemap(fcc_file, time_interval, output_dir='outputs', clean=False, dist_bins=array([0, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330, 360, 390, 420, 450, 480, 510, 540, 570, 600, 630, 660, 690, 720, 750, 780, 810, 840, 870, 900, 930, 960, 990, 1020, 1050]), win_sizes=[5, 11], ncat=30, methods=['Equal Interval', 'Equal Area'], csize=300, no_quantity_error=False, parallel=False, ncpu=None, figsize=(6.4, 4.8), dpi=100, blk_rows=128, verbose=True)[source]

Make maps of deforestation risk and select the best.

This function peforms all the necessary steps to obtain a map of the deforestation risk following the JNR methodology.

Parameters:

  • fcc_file – Input raster file of forest cover change at three dates (123). 1: first period deforestation, 2: second period deforestation, 3: remaining forest at the end of the second period. No data value must be 0 (zero). The raster must be projected to compute Euclidean distances with the gdal_proximity() function.

  • time_interval – A list of two numbers. Time interval (in years) for forest cover change observations for the two periods of time.

  • output_dir –

    Output directory for files (rasters, tables, and figures) produced by calling the makemap() function:

    • calval: A directory for files produced during the calibration and validation steps:

      • dist_edge_cal.tif: Raster of distance to forest edge at the start of the calibration period (same as dist_edge.tif).

      • perc_dist_cal.csv: Table of cumulative deforestation with distance to forest edge for the calibration period.

      • perc_dist_cal.png: Figure of cumulative deforestation with distance to forest edge for the calibration period.

      • ldefrate_ws{s}.tif: Rasters of local deforestation rates for each window size s for the calibration period.

      • ldefrate_with_zero_ws{s}.tif: Rasters of local deforestation rates with zero category for each window size s for the calibration period.

      • riskmap_ws{s}_{m}.tif: Riskmaps with categories of deforestation risk for each window size s and slicing method m for the calibration period.

      • defrate_per_cat_ws{s}_{m}.csv: Tables of deforestation rate per category of deforestation risk for each window size s and slicing method m for the calibration period.

      • dist_edge_v.tif: Raster of distance to forest edge at the start of the validation period.

      • ldefrate_with_zero_ws{s}_v.tif: Rasters of local deforestation rates with zero category for each window size s at the start of the validation period.

      • riskmap_ws{s}_{m}_v.tif: Riskmaps with categories of deforestation risk for each window size s and slicing method m at the start of the validation period.

      • pred_obs_ws{s}_{m}.csv: Tables of predictions vs. observations for each window size s and slicing method m for the validation period.

      • pred_obs_ws{s}_{m}.png: Figures of predictions vs. observations for each window size s and slicing method m for the validation period.

    • modcomp: A directory containing files for model comparison:

      • pred_obs_ws{s}_{m}.csv: Table of predictions vs. observations for the validation period for the best model with window size s and slicing method m.

      • pred_obs_ws{s}_{m}.png: Figure of predictions vs. observations for the validation period for the best model with window size s and slicing method m.

      • mod_comp.csv: Table for relationship between wRMSE and window size by slicing method.

      • mod_comp.png: Figure for relationship between wRMSE and window size by slicing method.

    • fullhist: A directory containing files for the full historical period (historical period = calibration period + validation period):

      • dist_edge.tif: Raster file of distance to forest edge at the start of the historical period (corresponding to start of calibration period).

      • perc_dist.csv: Table of cumulative deforestation with distance to forest edge for the historical period.

      • perc_dist.png: Figure of cumulative deforestation with distance to forest edge for the historical period.

      • ldefrate_ws{s}.tif: Raster of local deforestation rates for the best model with window size s for the historical period.

      • ldefrate_with_zero_ws{s}.tif: Raster of local deforestation rates with zero category for the best model with window size s for the historical period.

      • riskmap_ws{s}_{m}.tif: Riskmap with categories of deforestation risk using the best model with window size s and slicing method m at the start of the historical period.

      • defrate_per_cat_ws{s}_{m}.csv: Table of deforestation rate per category of deforestation risk for the best model with window size s and slicing method m for the historical period.

    • endval: A directory containing files at the end of the validation period that can be used for future projections:

      • dist_edge_ev.tif: Raster of distance to forest edge at the end of the validation period.

      • ldefrate_with_zero_ws{s}_ev.tif: Raster of local deforestation probability with zero category for the best model with window size s at the end of the validation period.

      • riskmap_ws{s}_{m}_ev.tif: Riskmap with categories of deforestation risk for the best model with window size s and slicing method m at the end of the validation period.

  • clean – Logical. Delete the calval directory at the end of the computation. Default to False.

  • dist_bins – Array of bins for distances. It has to be 1-dimensional and monotonic. The array must also include zero as the first value. Default to np.arange(0, 1080, step=30).

  • win_sizes – A list of numbers representing the different sizes of the moving window in number of cells. Must be odd numbers lower or equal to blk_rows. Default to [5, 11].

  • ncat – Number of deforestation risk categories (zero risk class excluded). Default to 30.

  • methods – Methods used for categorizing. Either “Equal Interval” (abbreviated “ei”), “Equal Area” (“ea”), or “Natural Breaks” (“nb”).

  • csize – Spatial cell size in number of pixels. Must correspond to a distance < 10 km. Default to 300 corresponding to 9 km for a 30 m resolution raster.

  • no_quantity_error – Correct the deforestation rates to avoid a “quantity” error on deforestation due to differences in total deforestation between first and second periods. This point is being discussed to improve the JNR methodology.

  • parallel – Logical. Parallel (if True) or sequential (if False) computing. Default to False.

  • ncpu – Number of CPUs for parallel computing.

  • figsize – Figure sizes.

  • dpi – Resolution for output images.

  • blk_rows – If > 0, number of rows for computation by block.

  • verbose – Logical. Whether to print messages or not. Default to True.

Returns:

A dictionary. With:

  • tot_def: total deforestation (in ha) during the entire historical period.

  • dist_thresh: the distance threshold.

  • perc: the percentage of deforestation for pixels with distance <= dist_thresh.

  • ncell: the number of grid cells with forest cover > 0 at the beginning of the validation period.

  • csize: the cell size in number of pixels.

  • csize_km: the cell size in kilometers.

  • no_quantity_error: no_quantity_error argument.

  • ws_hat: window size of the best risk map.

  • m_hat: slicing method of the best risk map.

  • wRMSE_hat: weighted Root Mean Squared Error (in hectares) of the best risk map.

set_defor_cat_zero(ldefrate_file, dist_file, dist_thresh, ldefrate_with_zero_file='ldefrate_with_zero.tif', blk_rows=128, verbose=True)[source]

Set a value of one (1) to pixels with zero deforestation risk. A null risk of deforestation is assumed when distance to forest edge is greater than the distance threshold. NoData value is set to zero (0).

Parameters:

  • ldefrate_file – Input raster file of local deforestation rates. Deforestation rates are defined by integer values between rescale_min_val (e.g. 2) and rescale_max_val (e.g. 10000). This file is typically obtained with function local_defor_rate().

  • dist_file – Path to the distance to forest edge raster file.

  • dist_thresh – The distance threshold. This distance threshold is used to identify pixels with zero deforestation risk.

  • ldefrate_with_zero_file – Output raster file. Default to “ldefrate_with_zero.tif” in the current working directory. Pixels with zero deforestation risk are assigned a value of 1.

  • blk_rows – If > 0, number of rows for computation by block.

  • verbose – Logical. Whether to print messages or not. Default to True.

Returns:

None. A raster file identifying pixels with zero risk of deforestation (value 1) will be created (see ldefrate_with_zero_file).

validation(fcc_file, time_interval, riskmap_file, tab_file_defrate, csize=300, no_quantity_error=False, tab_file_pred='pred_obs.csv', fig_file_pred='pred_obs.png', figsize=(6.4, 4.8), dpi=100, verbose=True)[source]

Validation of the deforestation risk map.

This function computes the observed and predicted deforestion (in ha) for the validation time period. Deforestion is computed for spatial grid cells of a maximum size of 10km. Deforestation rate estimates obtained with the defrate_per_cat function are used to compute the predicted deforestation in each grid cell. The function creates both a .csv file with the validation data and a plot comparing predictions vs. observations. The function returns the weighted Root Mean Squared Error (wRMSE, in hectares) associated with the deforestation predictions.

Parameters:

  • fcc_file – Input raster file of forest cover change at three dates (123). 1: first period deforestation, 2: second period deforestation, 3: remaining forest at the end of the second period. No data value must be 0 (zero).

  • time_interval – Time interval (in years) for forest cover change observations during the validation period.

  • riskmap_file – Input raster file with categories of spatial deforestation risk. This file is typically obtained with function defor_cat().

  • tab_file_defrate – Path to the .csv input file with estimates of deforestation rates per category of deforestation risk. This file is typically obtained with function defrate_per_cat().

  • csize – Spatial cell size in number of pixels. Must correspond to a distance < 10 km. Default to 300 corresponding to 9 km for a 30 m resolution raster.

  • no_quantity_error – Correct the deforestation rates to avoid a “quantity” error on deforestation due to differences in total deforestation between first and second periods. This point is being discussed to improve the JNR methodology.

  • tab_file_pred – Path to the .csv output file with validation data.

  • fig_file_pred – Path to the .png output file for the predictions vs. observations plot.

  • figsize – Figure size.

  • dpi – Resolution for output image.

  • verbose – Logical. Whether to print messages or not. Default to True.

Returns:

A dictionary. With wRMSE: weighted Root Mean Squared Error (in hectares) for the deforestation predictions, ncell: the number of grid cells with forest cover > 0 at the beginning of the validation period, csize: the cell size in number of pixels, csize_km: the cell size in kilometers.

Plot functions

fcc123(input_fcc_raster, output_file='fcc123.png', maxpixels=500000, borders=None, zoom=None, col=[(255, 165, 0, 255), (227, 26, 28, 255), (34, 139, 34, 255)], figsize=(11.69, 8.27), dpi=300, **kwargs)[source]

Plot forest-cover change (fcc123) map.

This function plots the forest-cover change map with 2 deforestation time-periods (2000 -> 2010 -> 2020 for example) plus the remaining forest (3 classes).

Parameters:

  • input_fcc_raster – Path to fcc123 raster.

  • output_file – Name of the plot file.

  • maxpixels – Maximum number of pixels to plot.

  • borders – Vector file to be plotted.

  • zoom – Zoom to region (xmin, xmax, ymin, ymax).

  • col – List of rgba colors for classes 123.

  • figsize – Figure size in inches.

  • dpi – Resolution for output image.

  • **kwargs – see below.

Keyword Arguments:

Additional arguments to plot borders.

Returns:

A Matplotlib figure of the forest cover change map.

riskmap(input_risk_map, output_file='prob.png', maxpixels=500000, borders=None, legend=False, figsize=(11.69, 8.27), dpi=300, **kwargs)[source]

Plot deforestation risk map.

This function plots the spatial probability of deforestation.

Parameters:

  • input_risk_map – Path to risk map.

  • output_file – Name of the plot file.

  • maxpixels – Maximum number of pixels to plot.

  • borders – Vector file to be plotted.

  • legend – Add colorbar if True.

  • figsize – Figure size in inches.

  • dpi – Resolution for output image.

  • **kwargs – see below.

Keyword Arguments:

Additional arguments to plot borders.

Returns:

A Matplotlib figure of the map of spatial probability of deforestation.

Miscellaneous functions

invlogit(x)[source]

Compute the inverse-logit of a numpy array.

We differenciate the positive and negative values to avoid under/overflow with the use of exp().

Parameters:

x – Numpy array.

Returns:

Return the inverse-logit of the array.

make_dir(newdir)[source]

Make new directory

  • Already exists, silently complete

  • Regular file in the way, raise an exception

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

Parameters:

newdir – Directory path to create.

tree(dir_path: Path, level: int = -1, limit_to_directories: bool = False, length_limit: int = 1000)[source]

Given a directory Path object print a visual tree structure.

Parameters:

  • dir_path – Directory path.

  • level – Option to limit recursion to a given level.

  • limit_to_directories – Option to limit to just directories.

  • length_limit – Length limit of the output in number of lines.

Returns:

Visual tree stucture.

main()[source]

riskmapjnr.riskmapjnr: provides entry point main().

Running riskmapjnr in the terminal prints riskmapjnr description and version. Can be used to check that the riskmapjnr Python package has been correctly imported.