apcac.classes#

Complete workflow to perform APCAC classification on polygons using vector and raster data.

It is designed for use within QGIS via the Python script tool, allowing both full workflow execution and independent function calls for custom analyses.

Warning

This module is intended to run under the QGIS Python Environment.

Important

The following external Python dependencies must be installed in the QGIS Environment via advanced mode: numpy, pandas and geopandas

Features#

Orchestrate a full APCAC analysis, from raster sampling to classification and LaTeX report.
Modular functions to compute hydrology and erosion indexes, fuzzification, and risk classification.
Automatic management of timestamped output folders for reproducible runs and organized outputs.
Easy integration into QGIS Python tools using importlib, with no external installation required.

Overview#

The module defines the main processing steps as functions. Each function creates an output folder with a timestamp for easy tracking. Users may run the full workflow through analysis_apcac or call individual functions independently for more customized analyses.

Script Example#

The following script runs a full APCAC analysis:

import importlib.util as iu

# define the paths to this module
# ----------------------------------------
the_module = "path/to/classes.py"

# setup module with importlib
# ----------------------------------------
spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

# define the paths to input and output folders
# ----------------------------------------
input_dir = "path/to/input_folder"
output_dir = "path/to/output_folder"

# define the path to input database
# ----------------------------------------
input_db = "path/to/data.gpkg"

# define the paths to input rasters
# ----------------------------------------
raster_files = {
    # change this paths
    "t": "path/to/raster_t.tif", # topography layer
    "s": "path/to/raster_s.tif", # soil/pedology layer
    "g": "path/to/raster_g.tif", # geology/aquifers layer
    "c": "path/to/raster_c.tif", # climate layer
    "n": "path/to/raster_n.tif", # conservation layer
    "v": "path/to/raster_v.tif", # anthropic risk layer
    "slope": "path/to/raster_slope.tif", # terrain slope layer
    "uslek": "path/to/raster_uslex.tif", # erodibility layer
}

# define which index has multipliers (the value is divided)
# ----------------------------------------
raster_multipliers = {
    "t": 1000,
    "s": 100,
    "slope": 100,
    # change and add more if needed
}

# call the function
# ----------------------------------------
module.analysis_apcac(
    input_db=input_db,
    input_layer="apcac_bho5k",
    raster_files=raster_files,
    output_folder=output_dir,
    raster_multipliers=raster_multipliers ,
    cleanup=True
)

Functions

`analysis_apcac`(input_db, raster_files, ...)	Orchestrates the complete APCAC (Áreas Prioritárias para Conservação de Água) analysis workflow, from sampling raster indexes to generating the final classification GeoPackage, summary CSV, and LaTeX table.
`analysis_apcac_upscaled`(input_db, ...[, cleanup])	Orchestrates the complete APCAC analysis workflow at an upscaled (aggregated) spatial unit, performing area-weighted aggregation of indexes before calculating the final APCAC classification.
`classify_apcac`(gdf)	Classifies catchments based on natural/anthropic, hydrology, and risk factors using a three-level system (APCAC).
`compute_apcac`(output_folder, input_db[, ...])	Calculates the final APCAC (Áreas Prioritárias para Conservação de Água) classification codes and IDs for the input catchment GeoDataFrame.
`compute_apcac_stats`(output_folder, input_db)	Computes and exports a summary of APCAC classification statistics, including total area and percentages for the Biome (Cerrado) and the Hydrological Influence Zone (ZHI).
`compute_e`(gdf[, n_threshold, ...])	Computes the erosion risk 'e' based on multiple environmental thresholds and adds the result to the GeoDataFrame.
`compute_e2`(gdf[, n_threshold, erosion_threshold])	Computes the erosion risk 'e' based on two environmental thresholds and adds the result to the GeoDataFrame.
`compute_index_a`(output_folder, input_db[, ...])	Computes the raw and fuzzified `a` (hydrology importance) index as a multiplicative combination of the fuzzified `t`, `s`, `g`, and `c` indexes.
`compute_index_e`(output_folder, input_db[, ...])	Computes the binary `e` (erosion/degradation risk) index, classifying areas as having risk (1) if they meet at least one of the three predefined risk conditions: low `n`, high `slope`, or high `uslek`.
`compute_upscaled_indexes`(output_folder, input_db)	Computes area-weighted upscaled (aggregated) values for various indexes and boolean flags from a fine-resolution GeoDataFrame to a coarser spatial unit defined by a grouping field, and saves the results as a new GeoPackage layer.
`get_latex_table`(output_folder, input_csv)	Reads a CSV file containing APCAC summary statistics, converts the data into a fully formatted LaTeX table using summarise_latex, and saves the resulting LaTeX code to a .tex file.

apcac.classes.analysis_apcac(input_db, raster_files, output_folder, input_layer='apcac_bho5k', raster_multipliers=None, cleanup=True, skip_sampling=False)[source]#

Orchestrates the complete APCAC (Áreas Prioritárias para Conservação de Água) analysis workflow, from sampling raster indexes to generating the final classification GeoPackage, summary CSV, and LaTeX table.

Parameters:

input_db (str) – Path to the initial GeoPackage or database file containing the input vector layer (e.g., catchment polygons).
raster_files (dict) – Dictionary where keys are the desired index names and values are the full paths to the corresponding raster files to be sampled.
output_folder (str) – Path to the main directory where the final and temporary results will be organized.
input_layer (str) – Name of the vector layer within the input database to be processed. Default value = “apcac_bho5k”
raster_multipliers (dict) – [optional] Dictionary of factors to divide the sampled raster mean values by (used for unit conversion).
cleanup (bool) – Flag to indicate whether the intermediate, run-specific folders created during the workflow should be deleted. Default value = True
skip_sampling (bool) – Flag to indicate whether to skip sampling index in raster maps, assuming values are already sampled. Default value = False

Returns:

The file path to the final GeoPackage file containing the complete APCAC classification results.

Return type:

str

Notes

The function executes the following steps in sequence: sampling raster values, fuzzifying indexes, computing index a (hydrology), computing index e (erosion risk), calculating the final APCAC classification, computing summary statistics, and finally generating the LaTeX table.

Script example

import importlib.util as iu

# define the paths to this module
# ----------------------------------------
the_module = "path/to/classes.py"

# setup module with importlib
# ----------------------------------------
spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

# define the paths to input and output folders
# ----------------------------------------
input_dir = "path/to/input_folder"
output_dir = "path/to/output_folder"

# define the path to input database
# ----------------------------------------
input_db = "path/to/data.gpkg"

# define the paths to input rasters
# ----------------------------------------
raster_files = {
    # change this paths
    "t": "path/to/raster_t.tif", # topography layer
    "s": "path/to/raster_s.tif", # soil/pedology layer
    "g": "path/to/raster_g.tif", # geology/aquifers layer
    "c": "path/to/raster_c.tif", # climate layer
    "n": "path/to/raster_n.tif", # conservation layer
    "v": "path/to/raster_v.tif", # anthropic risk layer
    "slope": "path/to/raster_slope.tif", # terrain slope layer
    "uslek": "path/to/raster_uslex.tif", # erodibility layer
}

# define which index has multipliers (the value is divided)
# ----------------------------------------
raster_multipliers = {
    "t": 1000,
    "s": 100,
    "slope": 100,
    # change and add more if needed
}

# call the function
# ----------------------------------------
module.analysis_apcac(
    input_db=input_db,
    input_layer="apcac_bho5k",
    raster_files=raster_files,
    output_folder=output_dir,
    raster_multipliers=raster_multipliers ,
    cleanup=True,
    skip_sampling=False,
)

apcac.classes.analysis_apcac_upscaled(input_db, output_folder, input_layer, field_upscale, field_area, cleanup=True)[source]#

Orchestrates the complete APCAC analysis workflow at an upscaled (aggregated) spatial unit, performing area-weighted aggregation of indexes before calculating the final APCAC classification.

Parameters:

input_db (str) – Path to the GeoPackage or database file containing the fine-resolution input vector layer.
output_folder (str) – Path to the main directory where the final and temporary results will be organized.
input_layer (str) – Name of the vector layer within the input database (fine-resolution) to be processed.
field_upscale (str) – The column name in the input data to use for grouping/dissolving (the ID of the coarser unit).
field_area (str) – The column name representing the area of the features, used for weighted averaging.
cleanup (bool) – Flag to indicate whether the intermediate, run-specific folders created during the workflow should be deleted. Default value = True

Returns:

The file path to the final GeoPackage file, which contains the complete APCAC classification results for the upscaled spatial units.

Return type:

str

Notes

The function first computes the upscaled indexes and geometries using compute_upscaled_indexes, then proceeds with the standard steps: fuzzifying indexes, computing index ‘a’ (hydrology), computing index ‘e’ (erosion risk), calculating the final APCAC classification for the upscaled units, computing summary statistics, and finally generating the LaTeX table.

Script example

import importlib.util as iu

# define the paths to this module
# ----------------------------------------
the_module = "path/to/classes.py"

# setup module with importlib
# ----------------------------------------
spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

# define the paths to input and output folders
# ----------------------------------------
input_dir = "path/to/input_folder"
output_dir = "path/to/output_folder"

# define the path to input database
# ----------------------------------------
input_db = "path/to/data.gpkg"

# call the function
# ----------------------------------------
output_file = module.analysis_apcac_upscaled(
    input_db=input_db,
    output_folder=output_dir,
    input_layer="apcac_bho5k",
    field_upscale="nunivotto4",
    field_area="nuareacont"
)

apcac.classes.compute_index_a(output_folder, input_db, input_layer='apcac_bho5k')[source]#

Computes the raw and fuzzified a (hydrology importance) index as a multiplicative combination of the fuzzified t, s, g, and c indexes.

Parameters:

output_folder (str) – Path to the directory where temporary and final output files will be stored.
input_db (str) – Path to the GeoPackage or database file containing the input vector layer.
input_layer (str) – Name of the vector layer within the input database to be processed. Default value = “apcac_bho5k”

Returns:

The file path to the final GeoPackage file, which contains the input layer with the new a_raw and fuzzified a columns.

Return type:

str

Script example

import importlib.util as iu

# define the paths to this module
# ----------------------------------------
the_module = "path/to/classes.py"

spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

# define the paths to input and output folders
# ----------------------------------------
input_dir = "path/to/input_folder"
output_dir = "path/to/output_folder"

# define the path to input database
# ----------------------------------------
input_db = f"{input_dir}/path/to/data.gpkg"


# call the function
# ----------------------------------------
output_file = module.compute_index_a(
    input_db=input_db,
    output_folder=output_dir,
    input_layer="apcac_bho5k",
)

apcac.classes.compute_index_e(output_folder, input_db, input_layer='apcac_bho5k', n_threshold=None, slope_threshold=None, uslek_threshold=None, erosion_threshold=None, use_e2=True)[source]#

Computes the binary e (erosion/degradation risk) index, classifying areas as having risk (1) if they meet at least one of the three predefined risk conditions: low n, high slope, or high uslek.

Parameters:

output_folder (str) – Path to the directory where temporary and final output files will be stored.
input_db (str) – Path to the GeoPackage or database file containing the input vector layer.
input_layer (str) – Name of the vector layer within the input database to be processed. Default value = “apcac_bho5k”
n_threshold (float) – [optional] The maximum n value (vegetation index) considered to indicate risk. Default value = N1
slope_threshold (float) – [optional] The minimum slope value considered to indicate risk. Default value = SLOPE_THRESHOLD
uslek_threshold (float) – [optional] The minimum uslek value (soil erodibility) considered to indicate risk. Default value = USLEK_THRESHOLD
erosion_threshold (float) – [optional] The minimum erosion value (user defined) considered to indicate risk. Default value = EROSION_THRESHOLD

Returns:

The file path to the final GeoPackage file, which contains the input layer with the new boolean risk columns (is_risk_n, is_risk_slope, is_risk_uslek) and the final e index.

Return type:

str

Script example

import importlib.util as iu

# define the paths to this module
# ----------------------------------------
the_module = "path/to/classes.py"

spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

# define the paths to input and output folders
# ----------------------------------------
input_dir = "path/to/input_folder"
output_dir = "path/to/output_folder"

# define the path to input database
# ----------------------------------------
input_db = f"{input_dir}/path/to/data.gpkg"


# call the function
# ----------------------------------------
output_file = module.compute_index_e(
    input_db=input_db,
    output_folder=output_dir,
    input_layer="apcac_bho5k",
)

apcac.classes.compute_upscaled_indexes(output_folder, input_db, field_upscale=None, input_layer='apcac_bho5k', field_area=None)[source]#

Computes area-weighted upscaled (aggregated) values for various indexes and boolean flags from a fine-resolution GeoDataFrame to a coarser spatial unit defined by a grouping field, and saves the results as a new GeoPackage layer.

Parameters:

output_folder (str) – Path to the directory where temporary and final output files will be stored.
input_db (str) – Path to the GeoPackage or database file containing the input vector layer (fine-resolution catchments).
field_upscale (str) – [optional] The column name in the input data to use for grouping/dissolving (the ID of the coarser unit). Default value = “nunivotto5”
input_layer (str) – Name of the vector layer within the input database to be processed. Default value = “apcac_bho5k”
field_area (str) – [optional] The column name representing the area of the features, used for weighted averaging. Default value = “nuareacont”

Returns:

The file path to the final GeoPackage file, which contains the upscaled indexes merged with the dissolved geometries of the coarser spatial units.

Return type:

str

Notes

The function first calculates the upscaled values using upscale_indexes, then dissolves the geometries based on the grouping field, and finally merges the upscaled data with the dissolved geometries.

Script example

import importlib.util as iu

# define the paths to this module
# ----------------------------------------
the_module = "path/to/classes.py"

# setup module with importlib
# ----------------------------------------
spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

# define the paths to input and output folders
# ----------------------------------------
input_dir = "path/to/input_folder"
output_dir = "path/to/output_folder"

# define the path to input database
# ----------------------------------------
input_db = "path/to/data.gpkg"

# call the function
# ----------------------------------------
output_file = module.compute_upscaled_indexes(
    input_db=input_db,
    output_folder=output_dir,
    input_layer="apcac_bho5k",
    field_upscale="nunivotto4",
)

apcac.classes.compute_apcac(output_folder, input_db, input_layer='apcac_bho5k', subset=None)[source]#

Calculates the final APCAC (Áreas Prioritárias para Conservação de Água) classification codes and IDs for the input catchment GeoDataFrame.

Parameters:

output_folder (str) – Path to the directory where temporary and final output files will be stored.
input_db (str) – Path to the GeoPackage or database file containing the input vector layer with all required index columns.
input_layer (str) – Name of the vector layer within the input database to be processed. Default value = “apcac_bho5k”

Returns:

The file path to the final GeoPackage file, which contains the input layer with the full set of APCAC classification columns (cd_apcac, id_apcac, and their component parts).

Return type:

str

Notes

This function wraps the three-level classification logic (natural/anthropic, hydrology, and risk) defined in classify_apcac.

Script example

import importlib.util as iu

# define the paths to this module
# ----------------------------------------
the_module = "path/to/classes.py"

spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

# define the paths to input and output folders
# ----------------------------------------
input_dir = "path/to/input_folder"
output_dir = "path/to/output_folder"

# define the path to input database
# ----------------------------------------
input_db = f"{input_dir}/path/to/data.gpkg"


# call the function
# ----------------------------------------
output_file = module.compute_apcac(
    input_db=input_db,
    output_folder=output_dir,
    input_layer="apcac_bho5k",
)

apcac.classes.compute_apcac_stats(output_folder, input_db, input_layer='apcac_bho5k')[source]#

Computes and exports a summary of APCAC classification statistics, including total area and percentages for the Biome (Cerrado) and the Hydrological Influence Zone (ZHI).

Parameters:

output_folder (str) – Path to the directory where the output CSV file will be saved.
input_db (str) – Path to the GeoPackage or database file containing the classified vector layer.
input_layer (str) – Name of the vector layer within the input database to be processed, which must contain the cd_apcac column. Default value = “apcac_bho5k”

Returns:

The file path to the resulting CSV file containing the APCAC summary statistics.

Return type:

str

Notes

This function loads the classified catchment data, calls the summarise function to aggregate the statistics, and saves the resulting table to a CSV file.

Script example

import importlib.util as iu

# define the paths to this module
# ----------------------------------------
the_module = "path/to/classes.py"

spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

# define the paths to input and output folders
# ----------------------------------------
input_dir = "path/to/input_folder"
output_dir = "path/to/output_folder"

# define the path to input database
# ----------------------------------------
input_db = f"{input_dir}/path/to/data.gpkg"


# call the function
# ----------------------------------------
output_file = module.compute_apcac_stats(
    input_db=input_db,
    output_folder=output_dir,
    input_layer="apcac_bho5k",
)

apcac.classes.classify_apcac(gdf)[source]#

Classifies catchments based on natural/anthropic, hydrology, and risk factors using a three-level system (APCAC).

Parameters:: gdf (geopandas.GeoDataFrame) – GeoDataFrame containing catchment data with n, a, c, v, and e columns for classification.
Returns:: GeoDataFrame with added classification columns: cd_apcac_n, id_apcac_n, cd_apcac_a, id_apcac_a, cd_apcac_risk, id_apcac_risk, cd_apcac, and id_apcac.
Return type:: geopandas.GeoDataFrame

apcac.classes.compute_e(gdf, n_threshold=None, slope_threshold=None, uslek_threshold=None)[source]#

Computes the erosion risk ‘e’ based on multiple environmental thresholds and adds the result to the GeoDataFrame.

Parameters:

gdf (geopandas.GeoDataFrame) – GeoDataFrame containing the environmental factors n, slope, and uslek.
n_threshold (float or None) – [optional] The threshold value for the n factor (e.g., vegetation cover). Defaults to a predefined global constant N1.
slope_threshold (float or None) – [optional] The minimum slope value considered risky. Defaults to a predefined global constant SLOPE_THRESHOLD.
uslek_threshold (float or None) – [optional] The minimum USLE-K factor value considered risky. Defaults to a predefined global constant USLEK_THRESHOLD.

Returns:

The input GeoDataFrame with new boolean columns (is_risk_n, is_risk_slope, is_risk_uslek) and the final combined erosion risk column (e).

Return type:

geopandas.GeoDataFrame

Notes

The erosion risk e is classified as 1 (risk) if the n factor is below its threshold AND either the ‘slope’ or ‘uslek’ factors are above their respective thresholds. Otherwise, e is 0 (no risk). The process first calculates intermediate boolean risk columns for each factor.

apcac.classes.compute_e2(gdf, n_threshold=None, erosion_threshold=None)[source]#

Computes the erosion risk ‘e’ based on two environmental thresholds and adds the result to the GeoDataFrame.

Parameters:

gdf (geopandas.GeoDataFrame) – GeoDataFrame containing the environmental factors n, and erosion.
n_threshold (float or None) – [optional] The threshold value for the n factor (e.g., vegetation cover). Defaults to a predefined global constant N1.
erosion_threshold (float or None) – [optional] The minimum erosion factor value considered risky. Defaults to a predefined global constant EROSION_THRESHOLD.

Returns:

The input GeoDataFrame with new boolean columns (is_risk_n, is_risk_slope, is_risk_uslek) and the final combined erosion risk column (e).

Return type:

geopandas.GeoDataFrame

Notes

The erosion risk e is classified as 1 (risk) if the n factor is below its threshold AND either the ‘erosion’ factor is above its respective threshold. Otherwise, e is 0 (no risk). The process first calculates intermediate boolean risk columns for each factor.

apcac.classes.get_latex_table(output_folder, input_csv)[source]#

Reads a CSV file containing APCAC summary statistics, converts the data into a fully formatted LaTeX table using summarise_latex, and saves the resulting LaTeX code to a .tex file.

Parameters:

output_folder (str) – Path to the directory where the output LaTeX file will be saved.
input_csv (str) – Path to the input CSV file containing the APCAC summary statistics (e.g., the output of compute_apcac_stats).

Returns:

The file path to the resulting LaTeX (.tex) file containing the formatted APCAC summary table.

Return type:

str

Script example

import importlib.util as iu

# define the paths to this module
# ----------------------------------------
the_module = "path/to/classes.py"

spec = iu.spec_from_file_location("module", the_module)
module = iu.module_from_spec(spec)
spec.loader.exec_module(module)

# define the paths to input and output folders
# ----------------------------------------
input_dir = "path/to/input_folder"
output_dir = "path/to/output_folder"

# define the path to input data
# ----------------------------------------
input_file = f"{input_dir}/path/to/data.csv"

# call the function
# ----------------------------------------
output_file = module.get_latex_table(
    input_csv=input_file,
    output_folder=output_dir,
)