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
)

Documentation#

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.

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_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.

sample_indexes(output_folder, input_db, ...)

Samples mean values from multiple raster files over a vector layer (e.g., catchments) and merges the results into a GeoDataFrame.
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.sample_indexes(output_folder, input_db, raster_files, input_layer='apcac_bho5k', raster_multipliers=None)[source]#

Samples mean values from multiple raster files over a vector layer (e.g., catchments) and merges the results into a 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.

  • raster_files (dict) – Dictionary where keys are the desired column names (index names) and values are the full paths to the corresponding raster files.

  • input_layer (str) – Name of the vector layer within the input database to use for zonal statistics. Default value = “apcac_bho5k”

  • raster_multipliers (dict) – [optional] Dictionary where keys are the index names (from raster_files) and values are factors by which the sampled mean values should be divided (e.g., to convert units).

Returns:

The file path to the final GeoPackage file containing the input layer with the new sampled index columns.

Return type:

str

Notes

The process uses QGIS’s native zonal statistics algorithm (native:zonalstatisticsfb) to calculate the mean of each raster within the polygons of the input vector layer.

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"

# define the paths to input rasters
# ----------------------------------------
raster_files = {
    # change this paths
    "t": f"{input_dir}/path/to/raster_t.tif",
    "s": f"{input_dir}/path/to/raster_s.tif",
    "g": f"{input_dir}/path/to/raster_g.tif",
    "c": f"{input_dir}/path/to/raster_c.tif",
    "n": f"{input_dir}/path/to/raster_n.tif",
    "v": f"{input_dir}/path/to/raster_v.tif",
    "slope": f"{input_dir}/path/to/raster_slope.tif",
    "uslek": f"{input_dir}/path/to/raster_uslek.tif",
}

# 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.sample_indexes(
    input_db=input_db,
    raster_files=raster_files,
    output_folder=output_dir,
    raster_multipliers=raster_multipliers,
    input_layer="apcac_bho5k",
)
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)[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 – Name of the vector layer within the input database to be processed. Default value = “apcac_bho5k”

  • 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

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')[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.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,
)