pyfwg package

Subpackages

Submodules

pyfwg.api module

pyfwg.api.morph_epw_global(*, epw_paths: str | List[str], fwg_jar_path: str, output_dir: str = './morphed_epws', delete_temp_files: bool = True, temp_base_dir: str = './morphing_temp_results', fwg_show_tool_output: bool = False, fwg_params: Dict[str, Any] | None = None, fwg_gcms: List[str] | None = None, fwg_create_ensemble: bool = True, fwg_winter_sd_shift: float = 0.0, fwg_summer_sd_shift: float = 0.0, fwg_month_transition_hours: int = 72, fwg_use_multithreading: bool = True, fwg_interpolation_method_id: int | str = 0, fwg_limit_variables: bool = True, fwg_solar_hour_adjustment: int | str = 1, fwg_diffuse_irradiation_model: int | str = 1, fwg_add_uhi: bool = True, fwg_epw_original_lcz: int = 14, fwg_target_uhi_lcz: int = 1, fwg_output_type: str = 'EPW', fwg_version: str | int | None = None)[source]

Performs a direct, one-shot morphing using the GLOBAL Future Weather Generator tool.

This function provides a simple interface to the morphing process while still allowing full customization of the Future Weather Generator tool. It internally uses the MorphingWorkflowGlobal class to validate all parameters before execution and runs the entire workflow in a single call.

The generated .epw and .stat files are saved directly to the output directory using the default filenames produced by the FWG tool. This function does not perform custom renaming.

Parameters:

  • epw_paths (Union[str, List[str]]) – A single path or a list of paths to the EPW files to be processed.

  • fwg_jar_path (str) – Path to the FutureWeatherGenerator.jar file.

  • output_dir (str, optional) – Directory where the final morphed files will be saved. Defaults to ‘./morphed_epws’.

  • delete_temp_files (bool, optional) – If True, temporary folders are deleted after processing. Defaults to True.

  • temp_base_dir (str, optional) – Base directory for temporary files. Defaults to ‘./morphing_temp_results’.

  • fwg_show_tool_output (bool, optional) – If True, prints the FWG tool’s console output in real-time. Defaults to False.

  • fwg_params (Optional[Dict[str, Any]], optional) – A dictionary for base FWG parameters. Any explicit fwg_ argument will override this. Defaults to None.

  • fwg_gcms (Optional[List[str]], optional) – List of GCMs to use.

  • are ((All other fwg_ arguments are passed directly to the tool and)

  • docstring). (explained in the MorphingWorkflowGlobal.configure_and_preview)

Returns:

A list of absolute paths to the successfully created .epw

and .stat files.

Return type:

List[str]

Raises:

ValueError – If the provided FWG parameters fail validation.

pyfwg.api.morph_epw_europe(*, epw_paths: str | List[str], fwg_jar_path: str, output_dir: str = './morphed_epws_europe', delete_temp_files: bool = True, temp_base_dir: str = './morphing_temp_results_europe', fwg_show_tool_output: bool = False, fwg_params: Dict[str, Any] | None = None, fwg_rcm_pairs: List[str] | None = None, fwg_create_ensemble: bool = True, fwg_winter_sd_shift: float = 0.0, fwg_summer_sd_shift: float = 0.0, fwg_month_transition_hours: int = 72, fwg_use_multithreading: bool = True, fwg_interpolation_method_id: int | str = 0, fwg_limit_variables: bool = True, fwg_solar_hour_adjustment: int | str = 1, fwg_diffuse_irradiation_model: int | str = 1, fwg_add_uhi: bool = True, fwg_epw_original_lcz: int = 14, fwg_target_uhi_lcz: int = 1, fwg_output_type: str = 'EPW', fwg_version: str | int | None = None)[source]

Performs a direct, one-shot morphing using the EUROPE-specific Future Weather Generator tool.

This function provides a simple interface to the morphing process while still allowing full customization of the Europe-specific FWG tool. It internally uses the MorphingWorkflowEurope class to validate all parameters before execution and runs the entire workflow in a single call.

The generated .epw and .stat files are saved directly to the output directory using the default filenames produced by the FWG tool. This function does not perform custom renaming.

Parameters:

  • epw_paths (Union[str, List[str]]) – A single path or a list of paths to the EPW files to be processed.

  • fwg_jar_path (str) – Path to the FutureWeatherGenerator_Europe.jar file.

  • output_dir (str, optional) – Directory where the final morphed files will be saved. Defaults to ‘./morphed_epws_europe’.

  • delete_temp_files (bool, optional) – If True, temporary folders are deleted after processing. Defaults to True.

  • temp_base_dir (str, optional) – Base directory for temporary files. Defaults to ‘./morphing_temp_results_europe’.

  • fwg_show_tool_output (bool, optional) – If True, prints the FWG tool’s console output in real-time. Defaults to False.

  • fwg_params (Optional[Dict[str, Any]], optional) – A dictionary for base FWG parameters. Any explicit fwg_ argument will override this. Defaults to None.

  • fwg_rcm_pairs (Optional[List[str]], optional) – List of GCM-RCM pairs to use. If None, the tool’s default list is used.

  • morph_epw_global ((All other fwg_ arguments are analogous to the)

  • MorphingWorkflowEurope.configure_and_preview (function and are explained in the)

  • docstring).

Returns:

A list of absolute paths to the successfully created .epw

and .stat files.

Return type:

List[str]

Raises:

ValueError – If the provided FWG parameters fail validation.

pyfwg.constants module

pyfwg.iterator module

class pyfwg.iterator.MorphingIterator(workflow_class: Type[_MorphingWorkflowBase])[source]

Bases: object

Automates running multiple morphing configurations from a structured input.

This class is designed to perform parametric analysis by iterating over different sets of parameters for a given morphing workflow. It uses a Pandas DataFrame to define the different runs.

The typical usage is a structured, multi-step process that provides clarity and control at each stage:

Step 1: Initialization

Instantiate the iterator with the desired workflow class. `python iterator = MorphingIterator(workflow_class=MorphingWorkflowGlobal) `

Step 2: Define Common Parameters (Optional)

Use the set_default_values() method to define parameters that will be the same for all runs in the batch, such as fwg_jar_path.

Step 3: Define the Runs DataFrame

Create a DataFrame that specifies what changes between each run. This can be done in two ways:

  • A) Programmatically with Pandas: Use get_template_dataframe() to get a blank template, then add rows for each run. `python runs_df = iterator.get_template_dataframe() runs_df.loc = {'epw_paths': 'file1.epw', 'fwg_gcms': ['CanESM5']} runs_df.loc = {'epw_paths': 'file2.epw', 'fwg_gcms': ['MIROC6']} `

  • B) Using an Excel Template: Use the utility functions to export a template, edit it in Excel, and then load it back. `python from pyfwg import export_template_to_excel, load_runs_from_excel export_template_to_excel(iterator, 'my_runs.xlsx') # (User edits the Excel file here) runs_df = load_runs_from_excel('my_runs.xlsx') `

Step 4: Generate the Full Execution Plan

Call generate_morphing_workflows() with the DataFrame of runs. This method applies all defaults (from the class and from set_default_values), parses filenames, prepares all the underlying workflow instances, and stores the complete plan for review.

Step 5: Inspect and Verify (Optional)

Before running, you can inspect the iterator.morphing_workflows_plan_df DataFrame and the iterator.prepared_workflows list to ensure everything is configured as expected.

Step 6: Execute the Batch Run

Call run_morphing_workflows() to execute the entire batch of prepared simulations.

workflow_class

The workflow class that will be used for each iteration.

Type:

Type[_MorphingWorkflowBase]

custom_defaults

A dictionary of default parameters set by the user via set_default_values.

Type:

Dict[str, Any]

prepared_workflows

A list of fully configured, ready-to-run workflow instances. Populated by generate_morphing_workflows.

Type:

List[_MorphingWorkflowBase]

morphing_workflows_plan_df

A detailed DataFrame showing the complete configuration for every run in the batch. Populated by generate_morphing_workflows.

Type:

Optional[pd.DataFrame]

set_default_values(*, final_output_dir: str | None = None, output_filename_pattern: str | None = None, scenario_mapping: Dict[str, str] | None = None, fwg_jar_path: str | None = None, run_incomplete_files: bool | None = None, delete_temp_files: bool | None = None, temp_base_dir: str | None = None, fwg_show_tool_output: bool | None = None, fwg_params: Dict[str, Any] | None = None, fwg_gcms: List[str] | None = None, fwg_rcm_pairs: List[str] | None = None, fwg_create_ensemble: bool | None = None, fwg_winter_sd_shift: float | None = None, fwg_summer_sd_shift: float | None = None, fwg_month_transition_hours: int | None = None, fwg_use_multithreading: bool | None = None, fwg_interpolation_method_id: int | None = None, fwg_limit_variables: bool | None = None, fwg_solar_hour_adjustment: int | None = None, fwg_diffuse_irradiation_model: int | None = None, fwg_add_uhi: bool | None = None, fwg_epw_original_lcz: int | None = None, fwg_target_uhi_lcz: int | None = None, fwg_version: str | int | None = None)[source]

Sets default parameter values for all runs in the batch.

This method is a convenient way to define parameters that are common to all runs in a parametric study, such as fwg_jar_path or a shared output_filename_pattern.

Any parameter set here will be used for every row in the DataFrame unless a different value is specified for that parameter in the row itself. This follows a clear priority order: 1. (Lowest) Hardcoded defaults from the workflow class. 2. (Medium) Defaults set with this method. 3. (Highest) Values specified directly in the runs DataFrame.

The method has an explicit signature for all possible arguments, providing auto-completion and type hints in your editor. It also includes a validation check to warn the user if they provide a model-specific argument that is not applicable to the chosen workflow (e.g., providing fwg_rcm_pairs for a MorphingWorkflowGlobal instance).

Parameters:

  • * (keyword-only) – All arguments must be specified by name.

  • the ((All arguments are optional and correspond to the parameters of)

  • method). (workflow's configure_and_preview)

get_template_dataframe() → DataFrame[source]

Generates an empty Pandas DataFrame with the correct parameter columns.

This helper method provides a convenient, error-proof template for the user to define their parametric runs.

It works by dynamically inspecting the signature of the configure_and_preview method of the workflow class that was passed to the iterator’s constructor (e.g., MorphingWorkflowGlobal). This ensures that the DataFrame columns perfectly match the required and optional arguments of the specific workflow, preventing typos and errors.

The template also includes the essential columns for the iterator: epw_paths, input_filename_pattern, and keyword_mapping.

Returns:

An empty Pandas DataFrame with columns corresponding to all the configurable parameters for a batch run.

Return type:

pd.DataFrame

generate_morphing_workflows(runs_df: DataFrame, input_filename_pattern: str | None = None, keyword_mapping: Dict | None = None, raise_on_overwrite: bool = True)[source]

Generates a detailed execution plan and prepares all workflow instances.

This method is the core of the planning phase. It orchestrates the entire setup for a batch run by performing several key tasks:

  1. Applies Defaults: It takes the user’s (potentially sparse) DataFrame of runs and creates a complete, fully populated version by applying all default values from the class and from the set_default_values method.

  2. Maps Categories: It performs a “dry run” of the file mapping for each run to extract categories from the EPW filenames.

  3. Enriches the Plan: It adds new columns (cat_*) to the plan DataFrame, showing the extracted categories for each run.

  4. Validates for Filename Overwrites: It performs two layers of validation to prevent data loss: first by checking for varying parameters, and then by simulating all final filenames to detect any direct collisions.

  5. Stores the Plan: The final, validated DataFrame is stored in self.morphing_workflows_plan_df for user inspection.

  6. Prepares Workflows: It instantiates and fully configures a MorphingWorkflow object for each run in the plan. These ready-to-run instances are stored in self.prepared_workflows.

Parameters:

  • runs_df (pd.DataFrame) – The user’s DataFrame of runs. Each row represents a unique configuration to be executed.

  • input_filename_pattern (Optional[str], optional) – A regex pattern for filename mapping, applied as a default to every run unless overridden in the DataFrame. Defaults to None.

  • keyword_mapping (Optional[Dict], optional) – A dictionary of keyword rules for filename mapping, applied as a default to every run unless overridden in the DataFrame.

  • raise_on_overwrite (bool, optional) – If True (default), raises a ValueError if a definitive filename overwrite is detected in Layer 2 validation. Layer 1 validation will always only warn.

Raises:

ValueError – If raise_on_overwrite is True and a definitive file overwrite is detected.

run_morphing_workflows(show_tool_output: bool | None = None)[source]

Executes the batch of prepared morphing workflows.

This method is the final step in the iterator’s workflow. It takes no arguments to define the scenarios, as it relies entirely on the list of workflow instances that were created and configured by the generate_morphing_workflows method.

It iterates through the self.prepared_workflows list and calls the execute_morphing method on each one that was found to have a valid configuration during the preparation phase.

Parameters:

show_tool_output (Optional[bool], optional) –

A flag to globally override the console output setting for all workflows in this specific batch execution.

  • If True or False, it will force this behavior for all runs, ignoring the fwg_show_tool_output value in the plan.

  • If None (the default), each run will use the fwg_show_tool_output value that was defined for it in the execution plan.

Raises:

RuntimeError – If generate_morphing_workflows() has not been run first, as there are no prepared workflows to execute.

pyfwg.utils module

pyfwg.utils.copy_tutorials(dest_dir: str = './pyfwg_tutorials')[source]

Copies the example Jupyter notebooks and their required data files to a local directory.

This function provides a convenient way for users to access the tutorial files that are bundled with the installed package. It finds all content (notebooks, data folders, etc.) within the package’s tutorials subfolder and copies it to a user-specified location, making the examples fully functional and ready to run.

It intelligently copies both individual files and entire subdirectories, while automatically excluding Python-specific files like __init__.py and __pycache__ directories from all levels of the copy.

If the destination directory does not exist, it will be created.

Parameters:

dest_dir (str, optional) – The path to the destination folder where the tutorials and data will be copied. Defaults to ‘./pyfwg_tutorials’ in the current working directory.

pyfwg.utils.detect_fwg_version(jar_path: str) → str[source]

Detects the major version of the Future Weather Generator from the JAR filename.

Parameters:

jar_path (str) – The path to the FWG JAR file.

Returns:

The major version number as a string (e.g., “4”, “3”).

Return type:

str

Raises:

ValueError – If the version cannot be detected from the filename.

pyfwg.utils.uhi_morph(*, fwg_epw_path: str, fwg_jar_path: str, fwg_output_dir: str, fwg_original_lcz: int, fwg_target_lcz: int, java_class_path_prefix: str | None = None, fwg_limit_variables: bool = True, show_tool_output: bool = False, raise_on_error: bool = True, fwg_version: str | int | None = None)[source]

Applies only the Urban Heat Island (UHI) effect to an EPW file.

This function is a direct wrapper for the UHI_Morph class within the Future Weather Generator tool. It modifies an EPW file to reflect the climate of a different Local Climate Zone (LCZ) without applying future climate change scenarios.

By default, this function is designed to “fail fast” by raising an exception if the external tool encounters any error. This behavior can be controlled with the raise_on_error flag, which is useful when this function is called internally by other utility functions (like check_lcz_availability) that need to handle the error gracefully.

Parameters:

  • fwg_epw_path (str) – Path to the source EPW file.

  • fwg_jar_path (str) – Path to the FutureWeatherGenerator.jar file.

  • fwg_output_dir (str) – Directory where the final UHI-morphed file will be saved.

  • fwg_original_lcz (int) – The LCZ of the original EPW file.

  • fwg_target_lcz (int) – The target LCZ for which to calculate the UHI effect.

  • java_class_path_prefix (str, optional) – The Java package prefix for the tool (e.g., ‘futureweathergenerator’ or ‘futureweathergenerator_europe’). If None, it will be auto-detected from the JAR filename.

  • fwg_limit_variables (bool, optional) – If True, bounds variables to their physical limits. Defaults to True.

  • show_tool_output (bool, optional) – If True, prints the tool’s console output in real-time. Defaults to False.

  • raise_on_error (bool, optional) – If True, the function will raise an exception if the external tool fails. If False, it will log the error but not stop the program, allowing the calling function to handle the failure. Defaults to True.

  • fwg_version (Optional[Union[str, int]], optional) – Explicitly provide the FWG version. If None, it will be auto-detected.

Raises:

  • FileNotFoundError – If the ‘java’ command is not found and raise_on_error is True.

  • subprocess.CalledProcessError – If the FWG tool returns a non-zero exit code and raise_on_error is True.

pyfwg.utils.check_lcz_availability(*, epw_path: str, original_lcz: int, target_lcz: int, fwg_jar_path: str, java_class_path_prefix: str | None = None, show_tool_output: bool = False, fwg_version: str | int | None = None) → bool | Dict[str, List][source]

Checks if the specified original and target LCZs are available for a given EPW file.

This utility function internally calls uhi_morph in a temporary directory to validate the LCZ pair. It is designed to be used as a pre-flight check before running a full morphing workflow.

The function operates by intentionally letting uhi_morph fail if an LCZ is invalid. It then catches the subprocess.CalledProcessError, silently parses the tool’s error output to find the list of valid LCZs, and diagnoses which of the user’s inputs was incorrect.

Parameters:

  • epw_path (str) – Path to the source EPW file to check.

  • original_lcz (int) – The original LCZ number you want to validate.

  • target_lcz (int) – The target LCZ number you want to validate.

  • fwg_jar_path (str) – Path to the FutureWeatherGenerator.jar file.

  • java_class_path_prefix (str, optional) – The Java package prefix for the tool. If None, it will be auto-detected from the JAR filename.

  • show_tool_output (bool, optional) – If True, prints the underlying FWG tool’s console output in real-time. This is useful for debugging the check itself. Defaults to False.

  • fwg_version (Optional[Union[str, int]], optional) – Explicitly provide the FWG version. If None, it will be auto-detected.

Returns:

  • True if both LCZs are available.

  • A dictionary with keys ‘invalid_messages’ (listing specific errors) and ‘available’ (listing valid LCZ descriptions) if validation fails due to unavailable LCZs.

  • False if an unexpected error occurs (e.g., Java not found).

Return type:

Union[bool, Dict[str, List]]

pyfwg.utils.get_available_lczs(*, epw_paths: str | List[str], fwg_jar_path: str, java_class_path_prefix: str | None = None, show_tool_output: bool = False, fwg_version: str | int | None = None) → Dict[str, List[int]][source]

Gets the available Local Climate Zones (LCZs) for one or more EPW files.

This utility function iterates through a list of EPW files and runs a check to determine which LCZs are available for morphing at each location. It reuses the check_lcz_availability function by intentionally probing with an invalid LCZ to trigger the error that lists all available zones.

After processing each file, it logs an INFO message summarizing the available LCZs found.

Parameters:

  • epw_paths (Union[str, List[str]]) – A single path or a list of paths to the EPW files to be checked.

  • fwg_jar_path (str) – Path to the FutureWeatherGenerator.jar file.

  • java_class_path_prefix (str, optional) – The Java package prefix for the tool. If None (default), it will be auto-detected from the JAR filename (contains ‘europe’ -> ‘futureweathergenerator_europe’, else ‘futureweathergenerator’).

  • show_tool_output (bool, optional) – If True, prints the underlying FWG tool’s console output in real-time. Defaults to False.

  • fwg_version (Optional[Union[str, int]], optional) – Explicitly provide the FWG version. If None, it will be auto-detected.

Returns:

A dictionary where keys are the EPW filenames and values are sorted lists of the available LCZ numbers (as integers). If a file cannot be processed, its value will be an empty list.

Return type:

Dict[str, List[int]]

pyfwg.utils.export_template_to_excel(iterator, file_path: str = 'runs_template.xlsx')[source]

Generates and exports a run template DataFrame to an Excel file.

This function uses the iterator’s get_template_dataframe method to create a blank template and saves it as an Excel file, ready for the user to fill in with different runs.

Parameters:

  • iterator (MorphingIterator) – An initialized MorphingIterator instance.

  • file_path (str, optional) – The path where the Excel file will be saved. Defaults to ‘runs_template.xlsx’.

pyfwg.utils.load_runs_from_excel(file_path: str) → DataFrame[source]

Loads a DataFrame of runs from an Excel file, converting data types correctly.

This function reads an Excel file into a Pandas DataFrame and then performs crucial data type conversions. It intelligently converts string representations of lists (e.g., “[‘CanESM5’, ‘MIROC6’]”) back into actual Python lists, which is essential for the iterator to function correctly.

Parameters:

file_path (str) – The path to the Excel file containing the runs.

Returns:

A DataFrame with the data types corrected and ready for use with the MorphingIterator.

Return type:

pd.DataFrame

pyfwg.utils.sanitize_epw_minutes(epw_path: str)[source]

Sanitizes an EPW file by replacing minute ‘60’ with ‘0’ in data records. This prevents issues with strict date-time libraries (like java.time) that expect MinuteOfHour to be between 0 and 59.

Parameters:

epw_path (str) – The path to the EPW file to sanitize.

pyfwg.utils.get_fwg_parameters_info() → Dict[str, Dict[str, Any]][source]

Returns a comprehensive dictionary of all FWG parameters, their descriptions, defaults, and allowed values.

This function is intended to help users understand the available options for both the Global and Europe-specific Future Weather Generator tools within pyfwg.

pyfwg.workflow module

class pyfwg.workflow.MorphingWorkflowGlobal[source]

Bases: _MorphingWorkflowBase

Manages the morphing workflow for the GLOBAL Future Weather Generator tool.

This class inherits all the step-by-step logic from the base workflow and is pre-configured to work specifically with the global climate models (GCMs) and SSP scenarios.

The intended usage is to follow the three-step process:

  1. map_categories(): Analyze input filenames to extract categories.

  2. configure_and_preview(): Define and validate all execution parameters and preview the results.

  3. execute_morphing(): Run the final computation.

This class is ideal for advanced use cases that require custom file renaming and detailed control over the morphing process for global climate data.

inputs

A dictionary that stores all user-provided configuration from every step of the workflow. It serves as the central “memory” for the instance.

Type:

Dict[str, Any]

epw_categories

A dictionary mapping the absolute path of each successfully and completely categorized EPW file to a dictionary of its categories.

Type:

Dict[str, Dict[str, str]]

incomplete_epw_categories

Similar to epw_categories, but stores files that were mapped but are missing one or more expected categories based on the keyword_mapping rules.

Type:

Dict[str, Dict[str, str]]

epws_to_be_morphed

The definitive list of absolute EPW file paths that will be processed when execute_morphing() is called.

Type:

List[str]

rename_plan

A detailed mapping that outlines the renaming and moving operations for each generated file.

Type:

Dict[str, Dict[str, str]]

is_config_valid

A boolean flag that is set to True only if all parameters provided in configure_and_preview pass the internal validation checks.

Type:

bool

tool_scenarios: List[str] = ['ssp126', 'ssp245', 'ssp370', 'ssp585']
valid_models: set = {'BCC_CSM2_MR', 'CAS_ESM2_0', 'CMCC_ESM2', 'CNRM_CM6_1', 'CNRM_CM6_1_HR', 'CNRM_ESM2_1', 'CanESM5', 'CanESM5_1', 'CanESM5_CanOE', 'EC_Earth3', 'EC_Earth3_Veg', 'EC_Earth3_Veg_LR', 'FGOALS_g3', 'GFDL_ESM4', 'GISS_E2_1_G', 'GISS_E2_1_H', 'GISS_E2_2_G', 'IPSL_CM6A_LR', 'MIROC6', 'MIROC_ES2H', 'MIROC_ES2L', 'MRI_ESM2_0', 'UKESM1_0_LL'}
model_arg_name: str = 'gcms'
java_class_path_prefix: str = 'futureweathergenerator'
scenario_placeholder_name: str = 'ssp'
configure_and_preview(*, final_output_dir: str, output_filename_pattern: str, scenario_mapping: Dict[str, str] | None = None, fwg_jar_path: str, run_incomplete_files: bool = False, delete_temp_files: bool = True, temp_base_dir: str = './morphing_temp_results', fwg_show_tool_output: bool = False, fwg_params: Dict[str, Any] | None = None, fwg_gcms: List[str] | None = None, fwg_create_ensemble: bool = True, fwg_winter_sd_shift: float = 0.0, fwg_summer_sd_shift: float = 0.0, fwg_month_transition_hours: int = 72, fwg_use_multithreading: bool = True, fwg_interpolation_method_id: int | str = 0, fwg_limit_variables: bool = True, fwg_solar_hour_adjustment: int | str = 1, fwg_diffuse_irradiation_model: int | str = 1, fwg_add_uhi: bool = True, fwg_epw_original_lcz: int = 14, fwg_target_uhi_lcz: int = 1, fwg_output_type: str = 'EPW', fwg_version: str | int | None = None)[source]

STEP 2: Configures, validates, and previews the plan for the GLOBAL tool.

This method combines configuration and preview into a single, robust step. It gathers all parameters for the morphing execution, validates them against the known constraints for the global tool, and then generates a detailed “dry run” plan of the final filenames for user review.

The output_filename_pattern can now include placeholders for any FWG parameter (e.g., {fwg_interpolation_method_id}).

Parameters:

  • final_output_dir (str) – The path for the final output files.

  • output_filename_pattern (str) – The template for final filenames. Must contain {ssp} and {year}.

  • scenario_mapping (Optional[Dict[str, str]], optional) – Mapping for scenario names. Defaults to None.

  • fwg_jar_path (str) – Path to the FutureWeatherGenerator.jar file.

  • run_incomplete_files (bool, optional) – If True, also processes partially categorized files. Defaults to False.

  • delete_temp_files (bool, optional) – If True, deletes temporary folders after processing. Defaults to True.

  • temp_base_dir (str, optional) – Base directory for temporary files. Defaults to ‘./morphing_temp_results’.

  • fwg_show_tool_output (bool, optional) – If True, prints the FWG tool’s console output in real-time. Defaults to False.

  • fwg_params (Optional[Dict[str, Any]], optional) – A dictionary for base FWG parameters. Any explicit fwg_ argument will override this. Defaults to None.

  • fwg_gcms (Optional[List[str]], optional) – A specific list of GCMs to use. If None, the full default list is used.

  • fwg_create_ensemble (bool, optional) – If True, creates an ensemble.

  • fwg_winter_sd_shift (float, optional) – Winter standard deviation shift.

  • fwg_summer_sd_shift (float, optional) – Summer standard deviation shift.

  • fwg_month_transition_hours (int, optional) – Hours for month transition.

  • fwg_use_multithreading (bool, optional) – Use multithreading.

  • fwg_interpolation_method_id (int, optional) – Interpolation method ID.

  • fwg_limit_variables (bool, optional) – Limit variables to physical bounds.

  • fwg_solar_hour_adjustment (int, optional) – Solar hour adjustment option.

  • fwg_diffuse_irradiation_model (int, optional) – Diffuse irradiation model option.

  • fwg_add_uhi (bool, optional) – Add UHI effect.

  • fwg_epw_original_lcz (int, optional) – Original EPW LCZ.

  • fwg_target_uhi_lcz (int, optional) – Target UHI LCZ.

  • fwg_output_type (str, optional) – Output format (e.g., ‘EPW’, ‘SPAIN_MET’). Defaults to ‘EPW’.

class pyfwg.workflow.MorphingWorkflowEurope[source]

Bases: _MorphingWorkflowBase

Manages the morphing workflow for the EUROPE-specific Future Weather Generator tool.

This class inherits all the step-by-step logic from the base workflow and is pre-configured to work specifically with the European GCM-RCM model pairs and RCP scenarios.

The intended usage is to follow the three-step process:

  1. map_categories(): Analyze input filenames to extract categories.

  2. configure_and_preview(): Define and validate all execution parameters and preview the results.

  3. execute_morphing(): Run the final computation.

This class is ideal for advanced use cases that require custom file renaming and detailed control over the morphing process for European climate data.

inputs

A dictionary that stores all user-provided configuration from every step of the workflow. It serves as the central “memory” for the instance.

Type:

Dict[str, Any]

epw_categories

A dictionary mapping the absolute path of each successfully and completely categorized EPW file to a dictionary of its categories.

Type:

Dict[str, Dict[str, str]]

incomplete_epw_categories

Similar to epw_categories, but stores files that were mapped but are missing one or more expected categories based on the keyword_mapping rules.

Type:

Dict[str, Dict[str, str]]

epws_to_be_morphed

The definitive list of absolute EPW file paths that will be processed when execute_morphing() is called.

Type:

List[str]

rename_plan

A detailed mapping that outlines the renaming and moving operations for each generated file.

Type:

Dict[str, Dict[str, str]]

is_config_valid

A boolean flag that is set to True only if all parameters provided in configure_and_preview pass the internal validation checks.

Type:

bool

tool_scenarios: List[str] = ['rcp26', 'rcp45', 'rcp85']
valid_models: set = {'CNRM_CERFACS_CNRM_CM5_CNRM_ALADIN63', 'ICHEC_EC_EARTH_DMI_HIRHAM5', 'ICHEC_EC_EARTH_SMHI_RCA4', 'MOHC_HadGEM2_ES_DMI_HIRHAM5', 'MOHC_HadGEM2_ES_SMHI_RCA4', 'MPI_M_MPI_ESM_LR_SMHI_RCA4', 'NCC_NorESM1_M_SMHI_RCA4'}
model_arg_name: str = 'rcm_pairs'
java_class_path_prefix: str = 'futureweathergenerator_europe'
scenario_placeholder_name: str = 'rcp'
configure_and_preview(*, final_output_dir: str, output_filename_pattern: str, scenario_mapping: Dict[str, str] | None = None, fwg_jar_path: str, run_incomplete_files: bool = False, delete_temp_files: bool = True, temp_base_dir: str = './morphing_temp_results_europe', fwg_show_tool_output: bool = False, fwg_params: Dict[str, Any] | None = None, fwg_rcm_pairs: List[str] | None = None, fwg_create_ensemble: bool = True, fwg_winter_sd_shift: float = 0.0, fwg_summer_sd_shift: float = 0.0, fwg_month_transition_hours: int = 72, fwg_use_multithreading: bool = True, fwg_interpolation_method_id: int | str = 0, fwg_limit_variables: bool = True, fwg_solar_hour_adjustment: int | str = 1, fwg_diffuse_irradiation_model: int | str = 1, fwg_add_uhi: bool = True, fwg_epw_original_lcz: int = 14, fwg_target_uhi_lcz: int = 1, fwg_output_type: str = 'EPW', fwg_version: str | int | None = None)[source]

STEP 2: Configures, validates, and previews the plan for the EUROPE tool.

This method combines configuration and preview into a single, robust step. It gathers all parameters for the morphing execution, validates them against the known constraints for the Europe-specific tool, and then generates a detailed “dry run” plan of the final filenames for user review.

The output_filename_pattern can now include placeholders for any FWG parameter (e.g., {fwg_interpolation_method_id}).

Parameters:

  • final_output_dir (str) – The path for the final output files.

  • output_filename_pattern (str) – The template for final filenames. Must contain {rcp} and {year}.

  • scenario_mapping (Optional[Dict[str, str]], optional) – Mapping for scenario names (e.g., {‘rcp26’: ‘RCP-2.6’}). Defaults to None.

  • fwg_jar_path (str) – Path to the FutureWeatherGenerator_Europe.jar file.

  • run_incomplete_files (bool, optional) – If True, also processes partially categorized files. Defaults to False.

  • delete_temp_files (bool, optional) – If True, deletes temporary folders after processing. Defaults to True.

  • temp_base_dir (str, optional) – Base directory for temporary files. Defaults to ‘./morphing_temp_results_europe’.

  • fwg_show_tool_output (bool, optional) – If True, prints the FWG tool’s console output in real-time. Defaults to False.

  • fwg_params (Optional[Dict[str, Any]], optional) – A dictionary for base FWG parameters. Any explicit fwg_ argument will override this. Defaults to None.

  • fwg_rcm_pairs (Optional[List[str]], optional) – A specific list of GCM-RCM pairs to use. If None, the full default list is used.

  • fwg_create_ensemble (bool, optional) – If True, creates an ensemble.

  • fwg_winter_sd_shift (float, optional) – Winter standard deviation shift.

  • fwg_summer_sd_shift (float, optional) – Summer standard deviation shift.

  • fwg_month_transition_hours (int, optional) – Hours for month transition.

  • fwg_use_multithreading (bool, optional) – Use multithreading.

  • fwg_interpolation_method_id (int, optional) – Interpolation method ID.

  • fwg_limit_variables (bool, optional) – Limit variables to physical bounds.

  • fwg_solar_hour_adjustment (int, optional) – Solar hour adjustment option.

  • fwg_diffuse_irradiation_model (int, optional) – Diffuse irradiation model option.

  • fwg_add_uhi (bool, optional) – Add UHI effect.

  • fwg_epw_original_lcz (int, optional) – Original EPW LCZ.

  • fwg_target_uhi_lcz (int, optional) – Target UHI LCZ.

  • fwg_output_type (str, optional) – Output format (e.g., ‘EPW’, ‘SPAIN_MET’). Defaults to ‘EPW’.

Module contents

pyfwg: Python Future Weather Generator

This file serves as the main entry point for the pyfwg package. It handles the initial setup, such as configuring the logging system with optional color support, and it defines the public API by importing the key classes, functions, and constants from the various modules. This allows users to access all primary features directly from the top-level pyfwg import.