plans.tools.core#

Core tool objects for the PLANS toolset.

This module provides the base building blocks shared by PLANS command-line tools:

ToolParser – a thin wrapper around argparse.ArgumentParser that registers the arguments common to every PLANS tool and offers convenience methods to add tool-specific arguments.
Tool – a base pipeline class implementing a generic load -> process -> export workflow, with per-step logging, elapsed-time tracking and a plain-text run report.
parse_spatial_parameters() and export_parameters() – helper functions to assemble and export spatialized parameter sets.

Features#

Standardized CLI argument parsing shared across PLANS tools.
A base tool pipeline handling logging, step timing and report generation.
Helpers to parse spatial parameter tables and export parameter rasters, catalogs and figures.

Functions

`export_parameters`(folder_output, parameters, ...)	Export a parameters catalog, raster maps and optional figures.
`parse_spatial_parameters`(title, file_parameters)	Build a spatial parameters table for a given file type.

Classes

`Tool`(name, folder_output)	Base class for PLANS command-line processing tools.
`ToolParser`(parser)	Wrapper around `argparse.ArgumentParser` for PLANS CLI tools.

plans.tools.core.parse_spatial_parameters(title, file_parameters)[source]#

Build a spatial parameters table for a given file type.

Looks up the internal file name associated with title in the files specification table, selects the fields flagged for that file in the fields specification table, and merges them with the values provided in file_parameters to assemble a parameters table ready for spatialization.

Parameters:

title (str) – title of the target file, as registered in the files specification table (see plans.config.parse_files()).
file_parameters (str) – path to the ;-separated CSV file holding the parameter values, with at least field and value columns.

Returns:

table with columns field (prefixed with w_), name, value, units and description for each parameter associated with the target file.

Return type:

pandas.DataFrame

plans.tools.core.export_parameters(folder_output, parameters, basin, views, prefix, label, logger)[source]#

Export a parameters catalog, raster maps and optional figures.

Writes the parameters catalog to a CSV file and exports each parameter raster as a GeoTIFF. If views is enabled, also generates a figure for the full raster extent plus a second figure masked to the main basin extent.

Parameters:

folder_output (str or pathlib.Path) – output folder where files are written.
parameters (object) – parameters collection object exposing a catalog (pandas.DataFrame) and a collection mapping of raster objects (each exposing file_data, export_tif, view, apply_aoi_mask and view_specs).
basin (object) – basin/raster object providing the data mask used to clip parameters to the main basin extent.
views (bool) – whether to export figures in addition to the raster catalog.
prefix (str) – filename prefix for the parameters catalog file.
label (str) – label used in log messages.
logger (logging.Logger) – logger instance used to report progress.

Returns:

None

Return type:

None

class plans.tools.core.ToolParser(parser)[source]#

Bases: object

Wrapper around argparse.ArgumentParser for PLANS CLI tools.

On instantiation, registers the arguments shared by every PLANS tool (--output, --verbose, --label and --project). Tool-specific arguments can be added afterwards through the add_* methods (e.g. add_parameters(), add_climate(), add_lulc()).

Parameters:

parser (argparse.ArgumentParser) – argument parser instance to configure.

Variables:

parser (argparse.ArgumentParser) – the wrapped argument parser.
output_default (str) – default value shown for the --output argument.

__init__(parser)[source]#

Initialize the wrapper and register the base arguments.

Parameters:: parser (argparse.ArgumentParser) – argument parser instance to configure.

add_output_folder()[source]#

Register the required --output/-o output folder argument.

Returns:: None
Return type:: None

add_verbose()[source]#

Register the --verbose/-v console output flag.

Returns:: None
Return type:: None

add_views()[source]#

Register the --views/-vs flag to enable plot exports.

Returns:: None
Return type:: None

add_label()[source]#

Register the required --label/-lb utility label argument.

Returns:: None
Return type:: None

add_project()[source]#

Register the optional --project/-pro project name argument.

Returns:: None
Return type:: None

add_parameters()[source]#

Register the required --parameters/-pr argument.

Points to the file holding the simulation parameters.

Returns:: None
Return type:: None

add_climate()[source]#

Register the required --climate/-cl argument.

Points to the file holding the climate series.

Returns:: None
Return type:: None

add_lulc()[source]#

Register the required --lulc/-lu argument.

Points to the file holding the land use / land cover data.

Returns:: None
Return type:: None

add_ldd()[source]#

Register the required --ldd/-ld argument.

Points to the LDD (flow direction) map file.

Returns:: None
Return type:: None

add_aoi()[source]#

Register the optional --aoi/-a argument.

Points to the area-of-interest (AOI) map file.

Returns:: None
Return type:: None

add_attributes()[source]#

Register the required --attributes/-att argument.

Points to the attributes table file.

Returns:: None
Return type:: None

add_scenario()[source]#

Register the required --scenario/-scn argument.

Points to the scenario folder.

Returns:: None
Return type:: None

add_soils()[source]#

Register the required --soils/-so argument.

Points to the soils map file.

Returns:: None
Return type:: None

get_args()[source]#

Parse and return the command-line arguments.

Returns:: parsed arguments namespace.
Return type:: argparse.Namespace

get_args_as_dict()[source]#

Parse the command-line arguments and return them as a dictionary.

Returns:: mapping of argument destination names to parsed values.
Return type:: dict

class plans.tools.core.Tool(name, folder_output)[source]#

Bases: object

Base class for PLANS command-line processing tools.

Implements a generic load -> process -> export pipeline with per-step logging, elapsed-time tracking and a plain-text run report (log echo preceded by a specs and runtimes header). Subclasses are expected to override load_data(), process_data() and export_data() with their actual logic.

Parameters:

name (str) – name of the tool, used in log messages and the report header.
folder_output (str or pathlib.Path) – output folder where logs, report and runtime files are written. Created if it does not already exist.

Variables:

name (str) – tool name.
folder_output (pathlib.Path) – output folder for this run.
file_logs (pathlib.Path) – path to the raw log file.
file_report (pathlib.Path) – path to the final assembled report file.
logger (logging.Logger or None) – logger used by the tool, set via set_logger().
verbose (bool) – whether the logger also writes to the console.
views (bool) – whether the tool should also export figures.
label (str) – utility label for this run.
name_project (str or None) – optional project name, included in the logger name.
runtimes (pandas.DataFrame or None) – table of step runtimes, set by export_runtimes().
sleeper (float) – seconds slept by the default pipeline steps.

__init__(name, folder_output)[source]#

Initialize the tool and create the output folder.

Parameters:

name (str) – name of the tool, used in log messages and the report header.
folder_output (str or pathlib.Path) – output folder where logs, report and runtime files are written. Created if it does not already exist.

set_logger()[source]#

Instantiate and assign the tool’s logger.

Builds the logger name from name (and name_project, when set) and assigns the result to logger via get_logger().

Returns:: None
Return type:: None

run()[source]#

Execute the full tool pipeline.

Ensures a logger is set, then runs load_data(), process_data() and export_data() in sequence (each wrapped by step() for logging and timing). Afterwards, exports the runtimes table, logs the total elapsed time and the output location, and writes the final report file via make_readme_file().

Returns:: None
Return type:: None

step(method, label)[source]#

Run a single pipeline step with logging and timing.

Logs the start of the step, executes method, logs its completion with the elapsed time, and appends the step label and elapsed time to ls_steps and ls_times.

Parameters:

method (callable) – no-argument callable implementing the step (e.g. load_data()).
label (str) – step label, used for logging and as the key into self.msg["concluded"].

Returns:

None

Return type:

None

load_data()[source]#

Load input data.

Placeholder implementation that only sleeps for sleeper seconds. Subclasses should override this method with actual data-loading logic.

Returns:: None
Return type:: None

process_data()[source]#

Process previously loaded data.

Placeholder implementation that only sleeps for sleeper seconds. Subclasses should override this method with actual processing logic.

Returns:: None
Return type:: None

export_data()[source]#

Export processed data.

Placeholder implementation that only sleeps for sleeper seconds. Subclasses should override this method with actual export logic.

Returns:: None
Return type:: None

export_runtimes()[source]#

Build and export the runtimes table.

Assembles a table with one row per executed step plus a total row, computes each step’s percentage share of the total elapsed time, writes it to filename_runtimes inside folder_output, and stores the result in runtimes.

Returns:: None
Return type:: None

format_runtimes_str()[source]#

Format the runtimes table as a fixed-width text block.

Returns:: column-aligned, uppercase-headed string representation of runtimes, rounded to three decimal places.
Return type:: str

make_readme_file()[source]#

Assemble the final run report file.

Reads the raw log file, prepends a header block (title, run specs and formatted runtimes table), and writes the combined content to file_report.

Returns:: None
Return type:: None

sleep()[source]#

Pause execution for sleeper seconds.

Used as a placeholder delay by the default load_data(), process_data() and export_data() implementations.

Returns:: None
Return type:: None

static format_msg_elapsed(msg, time)[source]#

Format a message with an elapsed-time suffix.

Parameters:

msg (str) – base message.
time (float) – elapsed time, in seconds.

Returns:

formatted message, e.g. "<msg> in 1.23 seconds".

Return type:

str

static format_msg_output(folder)[source]#

Format a message pointing the user to an output folder.

Parameters:: folder (str or pathlib.Path) – output folder path to display.
Returns:: formatted message.
Return type:: str

static get_logger(name='tool', log_file='run_log.txt', talk=True)[source]#

Create (or reconfigure) a logging.Logger.

Clears any handlers already attached to a logger of the same name, then attaches a file handler (always) and, when talk is True, a console handler as well. Both handlers share a timestamped DEBUG-level format that includes the logger name.

Parameters:

name (str) – logger name.
log_file (str or pathlib.Path) – path to the log file to write to.
talk (bool) – whether to also emit log records to the console.

Returns:

configured logger instance, set to DEBUG level.

Return type:

logging.Logger