wolfhece.report.tools

Module Contents

class wolfhece.report.tools.Directory_Analysis(*args, **kwds)

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

• attribute access:

>>> Color.RED
<Color.RED: 1>

• value lookup:

>>> Color(1)
<Color.RED: 1>

• name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

PROJECTS = 'projets'

REPORTS = 'rapports'

VECTORS = 'vecteurs'

CLOUDS = 'nuages_de_points'

IMAGES = 'images'

CACHE = 'cache'

wolfhece.report.tools.get_lines_from_ax(ax: matplotlib.pyplot.Axes) → list[shapely.geometry.LineString]

Get the lines from a Matplotlib Axes object.

Parameters:

ax – The Matplotlib Axes object.

Returns:

A list of LineString objects representing the lines in the Axes.

wolfhece.report.tools.get_labels_from_ax(ax: matplotlib.pyplot.Axes) → list[str]

Get the labels from a Matplotlib Axes object.

Parameters:

ax – The Matplotlib Axes object.

Returns:

A list of labels from the Axes.

wolfhece.report.tools.set_lines_as_black(ax: matplotlib.pyplot.Axes, label: str | list[str] = None) → None

Set the line with the specified label to black in a Matplotlib Axes object.

Parameters:

• ax – The Matplotlib Axes object.

• label – The label of the line to set to black.

wolfhece.report.tools.change_style_in_ax(ax: matplotlib.pyplot.Axes, styles: dict[str, dict]) → None

Change the style of lines in a Matplotlib Axes object.

Available style properties: - color: The color of the line. - linestyle: The style of the line (e.g., ‘-’, ‘–’, ‘-.’, ‘:’). - linewidth: The width of the line. - marker: The marker style (e.g., ‘o’, ‘x’, ‘^’). - markersize: The size of the marker. - alpha: The transparency of the line (0.0 to 1.0). - label: The label for the line in the legend.

This function will iterate through all lines in the Axes and apply the styles based on the provided dictionary.

Parameters:

• ax – The Matplotlib Axes object.

• styles – A dict of style where key is the label and value is a tuple with style properties.

Returns:

None

wolfhece.report.tools._sanitize_scenario_name(scenario_name: str | tuple[str, str]) → str

Sanitize the scenario name to ensure it is a string. This function will strip whitespace and ensure the name is a string. :param name: The scenario name to sanitize. :return: A sanitized string representing the scenario name.

wolfhece.report.tools.list_directories(directory: pathlib.Path) → list[str]

List directories in a given path.

wolfhece.report.tools.create_a_report(title, author) → wolfhece.report.reporting.RapidReport

Create a RapidReport instance.

Parameters:

• title – The title of the report.

• author – The author of the report.

Returns:

An instance of RapidReport.

wolfhece.report.tools.create_a_wolf_viewer() → wolfhece.PyGui.WolfMapViewer

Create a WolfMapViewer instance.

Returns:

An instance of WolfMapViewer.

wolfhece.report.tools.find_scenario_directory(base_directory: pathlib.Path | str, scenario_name: str) → pathlib.Path | None

Find the directory of a specific scenario within the base directory and subdirectories.

Parameters:

• base_directory – The base directory where the scenarios are located.

• scenario_name – The name of the scenario to find.

Returns:

The path to the scenario directory if found, None otherwise.

wolfhece.report.tools.get_scenarios_directories(base_directory: pathlib.Path | str, scenario_names: list[str]) → dict

Get the directories of all scenarios within the base directory.

Parameters:

• base_directory – The base directory where the scenarios are located.

• scenario_names – A list of scenario names to find.

Returns:

A list of paths to the scenario directories.

wolfhece.report.tools.check_if_scenario_exists(base_directory: pathlib.Path | str, scenario_name: str) → bool

Check if a specific scenario exists within the base directory.

Parameters:

• base_directory – The base directory where the scenarios are located.

• scenario_name – The name of the scenario to check.

Returns:

True if the scenario exists, False otherwise.

wolfhece.report.tools.check_if_scenarios_exist(base_directory: pathlib.Path | str, scenario_names: list[str]) → bool

Check if all specified scenarios exist within the base directory.

Parameters:

• base_directory – The base directory where the scenarios are located.

• scenario_names – A list of scenario names to check.

Returns:

True if all scenarios exist, False otherwise.

wolfhece.report.tools.check_analysis_directories(base_directory: pathlib.Path | str) → bool

Check if the necessary directories for analysis exist.

Parameters:

base_directory – The base directory where the analysis directories are located.

Returns:

True if all directories exist, False otherwise.

wolfhece.report.tools.create_analysis_directories(base_directory: pathlib.Path | str) → str

Create the necessary directories for analysis if they do not exist.

Parameters:

base_directory – The base directory where the analysis directories will be created.

Returns:

True if directories were created or already exist, False if an error occurred.

wolfhece.report.tools.get_directories_as_dict(base_directory: pathlib.Path | str) → dict

Get the paths of the analysis directories.

Parameters:

base_directory – The base directory where the analysis directories are located.

Returns:

A dictionary with the paths of the analysis directories.

wolfhece.report.tools.get_directories_as_list(base_directory: pathlib.Path | str) → list

Get the paths of the analysis directories as a list.

Parameters:

base_directory – The base directory where the analysis directories are located.

Returns:

A list with the paths of the analysis directories. Ordered as per Directory_Analysis enum.

wolfhece.report.tools._check_version(min_version: str) → bool

Check if the current version is greater than or equal to the minimum version.

Parameters:

• min_version (str) – The minimum required version.

• current_version (str) – The current version to check against.

Returns:

True if the current version is greater than or equal to the minimum version, False otherwise.

Return type:

bool

wolfhece.report.tools.check_available_version_on_pypi() → str

Check the latest available version of the package on PyPI.

Returns:

The latest version available on PyPI.

Return type:

str

wolfhece.report.tools.can_upgrade_wolfhece() → bool

Check if the current version can be upgraded to the minimum required version.

Parameters:

min_version (str) – The minimum required version.

Returns:

True if the current version can be upgraded, False otherwise.

Return type:

bool

wolfhece.report.tools.check_version(min_version: str) → bool

Check if the current version is greater than or equal to the minimum version.

Parameters:

min_version (str) – The minimum required version.

Returns:

True if the current version is greater than or equal to the minimum version, False otherwise.

Return type:

bool

class wolfhece.report.tools.Analysis_Scenarios(base_directory: pathlib.Path | str, storage_directory: pathlib.Path | str = None, name: str = '')

_fig_size = (20, 10)

name = 'Analysis_Scenarios'

base_directory

storage_directory = None

directories

scenarios_directories: dict[str:Path]

scenarios = []

current_scenario = None

_return_periods = []

report: wolfhece.report.reporting.RapidReport = None

_report_name = 'analysis_report.docx'

_report_saved_once = False

mapviewer: wolfhece.PyGui.WolfMapViewer = None

_background_images: str = None

_polygons: dict[str, wolfhece.pypolygons_scen.Polygons_Analyze]

_reference_polygon: wolfhece.pypolygons_scen.Polygons_Analyze = None

_modifications

_multiprojects = None

_landmarks: wolfhece.PyGui.Zones = None

_landmarks_s_label = []

_measures: dict[str, wolfhece.PyGui.Zones]

_measures_zones: dict[str, list[str]]

_projected_measures: dict[tuple[str], list[wolfhece.PyGui.vector, dict]]

_cloud: list[tuple[float, float, str]] = []

_images

_zoom: dict[str, tuple[float, float, float, float]]

property fig_size: tuple[float]

Return the default figure size for plots.

Returns:

A tuple (width, height) representing the default figure size.

add_zoom(label: str, bounds: tuple[float]) → None

Add a zoom level to the analysis.

Parameters:

• label – The label for the zoom level.

• bounds – A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds.

add_zoom_from_XY(label: str, xy1: tuple[float], xy2: tuple[float], zmin: float, zmax: float) → None

Add a zoom level to the analysis from X and Y coordinates.

Parameters:

• label – The label for the zoom level.

• xy1 – A tuple (x1, y1) representing the first point.

• xy2 – A tuple (x2, y2) representing the second point.

• zmin – The minimum zoom level.

• zmax – The maximum zoom level.

get_zoom(label: str) → tuple[float]

Get the zoom level bounds for a specific label.

Parameters:

label – The label for the zoom level.

Returns:

A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds.

property measures: dict

Return the measures used in the analysis.

Returns:

An instance of Zones or None if not set.

add_cloud(cloud: wolfhece.PyGui.cloud_vertices | list[tuple[float, float, str]] | str = None, label: str = '') → None

Add a cloud of points to the analysis.

Parameters:

cloud – A cloud of points as a cloud_vertices instance or a list of tuples (s, z, label).

add_cloud_point(s: float, z: float, label: str = None) → None

Add a point to the cloud in the analysis.

Parameters:

• s – The s-coordinate of the point.

• z – The z-coordinate of the point.

• label – An optional label for the point.

add_cloud_point_XY(x: float, y: float, z: float = None, label: str = None) → None

Add a point to the cloud in the analysis from X and Y coordinates.

Parameters:

• x – The X coordinate of the point.

• y – The Y coordinate of the point.

• z – The Z coordinate of the point (optional).

• label – An optional label for the point.

add_measures(measures: wolfhece.PyGui.Zones | str | pathlib.Path, zones: list[str] = None, style: dict = None, force_all_vectors: bool = False) → None

Add measures to the analysis.

Parameters:

• measures – A Zones instance or a path to a vector file containing the measures.

• zones – A list of zone names to include in the analysis. If None, all zones in the measures will be used.

• style – A dictionary containing style properties for the measures. Available properties: ‘color’, ‘linestyle’, ‘linewidth’, ‘marker’, ‘markersize’, ‘alpha’.

• force_all_vectors – If True, all vectors in the zones will be projected on the riverbed, even if they are not used.

get_landmarks_labels() → list[str]

Get the names of the landmarks in the analysis.

Returns:

A list of names of the landmarks.

property reference_polygon: wolfhece.pypolygons_scen.Polygons_Analyze | None

Return the reference polygon used in the analysis.

Returns:

An instance of Polygons_Analyze or None if not set.

property landmarks: wolfhece.PyGui.Zones | None

Return the landmarks used in the analysis.

Returns:

An instance of Zones or None if not set.

add_landmarks(landmarks: wolfhece.PyGui.Zones | str | pathlib.Path) → None

Add landmarks to the analysis.

Parameters:

landmarks – A Zones instance or a path to a vector file containing the landmarks.

add_landmark_from_XY(x: float, y: float, label: str, z: float = None) → None

Add a landmark to the analysis from X and Y coordinates.

Parameters:

• x – The X coordinate of the landmark.

• y – The Y coordinate of the landmark.

• name – The name of the landmark.

• z – The Z coordinate of the landmark (optional).

update_landmark(label: str, s_xy: float | tuple[float] = None, z: float = None) → None

Update a landmark in the analysis.

Parameters:

• label – The label of the landmark to update.

• s_xy – The s-coordinate or a tuple (s, xy) to update the landmark’s position.

• z – The z-coordinate to update the landmark’s elevation (optional).

plot_cloud(ax: matplotlib.pyplot.Axes, bounds: tuple[float]) → matplotlib.pyplot.Axes

Trace the cloud of points on an axis Matplotlib

Parameters:

• ax – axe Matplotlib

• bounds – tuple (xmin, xmax, ymin, ymax) for the plot limits

Returns:

The Matplotlib Axes object with the cloud plotted.

plot_measures(ax: matplotlib.pyplot.Axes, bounds: tuple[float], style: dict = None) → matplotlib.pyplot.Axes

Trace les mesures sur un axe Matplotlib

Parameters:

• ax – axe Matplotlib

• bounds – tuple (xmin, xmax, ymin, ymax) for the plot limits

• style – Optional style dictionary for the measures. Available properties: - ‘color’: The color of the line. - ‘linestyle’: The style of the line (e.g., ‘-’, ‘–’, ‘-.’, ‘:’).

Returns:

The Matplotlib Axes object with the measures plotted.

plot_landmarks(ax: matplotlib.pyplot.Axes, bounds: tuple[float], style: dict = None) → matplotlib.pyplot.Axes

Trace les repères sur un axe Matplotlib

Parameters:

• ax – axe Matplotlib

• bounds – tuple (xmin, xmax, ymin, ymax) for the plot limits

• style – Optional style dictionary for the landmarks.

plot_waterlines(scenario: str | tuple[str, str] | list[str] | list[tuple[str, str]], bounds: tuple[float] | str, operator: wolfhece.pypolygons_scen.operators = operators.MEDIAN, plot_annex: bool = True, save: bool = False, figsize: tuple[float] = None) → tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

Plot the waterlines for a specific scenario.

Parameters:

• scenario – The name of the scenario to plot waterlines for or a list of scenarios for comparison.

• bounds – A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds or a string label for a zoom level.

• operator – The operator to apply on the waterlines.

• save – If True, save the plot as an image file.

• figsize – A tuple (width, height) representing the size of the figure. If None, uses the default figure size.

• plot_annex – If True, plot the cloud of points, measures, and landmarks.

Returns:

A tuple (fig, ax) where fig is the matplotlib Figure and ax is the matplotlib Axes object.

plot_waterheads(scenario: str | tuple[str, str], bounds: tuple[float] | str, operator: wolfhece.pypolygons_scen.operators = operators.MEDIAN, plot_annex: bool = True, save: bool = False, figsize: tuple[float] = None) → tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

Plot the heads for a specific scenario.

Parameters:

• scenario – The name of the scenario to plot heads for or a list of scenarios for comparison.

• bounds – A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds or a string label for a zoom level.

• operator – The operator to apply on the heads.

• plot_annex – If True, plot the cloud of points, measures, and landmarks.

• save – If True, save the plot as an image file.

• figsize – A tuple (width, height) representing the figure size. If None, use the default figure size.

Returns:

A tuple (fig, ax) representing the figure and axes of the plot

plot_Froude(scenario: str | tuple[str, str] | list[str] | list[tuple[str, str]], bounds: tuple[float] | str, operator: wolfhece.pypolygons_scen.operators = operators.MEDIAN, plot_annex: bool = True, save: bool = False, figsize: tuple[float] = None) → tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

Plot the Froude for a specific scenario.

Parameters:

• scenario – The name of the scenario to plot waterlines for or a list of scenarios for comparison.

• bounds – A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds or a string label for a zoom level.

• operator – The operator to apply on the waterlines.

• save – If True, save the plot as an image file.

• figsize – A tuple (width, height) representing the figure size. If None, use the default figure size.

• plot_annex – If True, plot the cloud of points, measures, and landmarks.

Returns:

A tuple (fig, ax) representing the figure and axes of the plot

save_image(filename: str, fig: matplotlib.pyplot.Figure = None, dpi: int = 300, format: Literal['png', 'pdf', 'svg'] = 'png') → None

Save the current figure as an image file.

Parameters:

• filename – The name of the file to save the image to.

• fig – The figure to save. If None, uses the current active figure.

• dpi – The resolution of the saved image in dots per inch.

• format – The format of the saved image (png, pdf, svg). Default is ‘png’.

export_values_as(scenario: str | tuple[str, str] = None, simulation_key: list[str] = None, which_values: list[wolfhece.pypolygons_scen.stored_values_unk] = [stored_values_unk.TOPOGRAPHY, stored_values_unk.WATERDEPTH, stored_values_unk.WATERLEVEL, stored_values_unk.HEAD, stored_values_coords.X, stored_values_coords.Y], operator: wolfhece.pypolygons_scen.operators = operators.MEDIAN, filename: str = None, format: Literal['xlsx', 'csv'] = 'xlsx') → None

Export values from polygons for a specific scenario to a file.

Parameters:

• scenario – The name of the scenario to export values for. If None, exports values for all scenarios.

• simulation_key – The key of the simulation to export values for. If None, exports values for all simulations.

• which_values – The type of values to export from the polygons.

• operator – The operator to apply on the values extracted from the polygons.

• filename – The name of the file to export values to. If None, a default name will be used.

• format – The format of the file to export values to (csv or xlsx). Default is ‘xlsx’.

get_values_from_polygons(scenario: str | tuple[str, str] = None, which_value: wolfhece.pypolygons_scen.stored_values_unk = stored_values_unk.HEAD, which_operator: wolfhece.pypolygons_scen.operators = operators.MEDIAN) → dict

Get values from polygons for a specific scenario.

Parameters:

• scenario – The name of the scenario to get values for. If None, gets values for all scenarios.

• which_value – The type of value to extract from the polygons.

• which_operator – The operator to apply on the values extracted from the polygons.

Returns:

A dictionary with the values extracted from the polygons.

list_groups_in_polygons(scenario: str | tuple[str, str]) → list[str]

List the groups in the polygons used in the analysis. :param scenario: The name of the scenario to list groups for. If None, lists groups for all scenarios.

list_sims_in_polygons(scenario: str | tuple[str, str]) → list[str]

List the simulations in the polygons used in the analysis. :param scenario: The name of the scenario to list simulations for. If None, lists simulations for all scenarios.

list_sims_in_all_polygons() → dict

List the simulations in all polygons used in the analysis.

Returns:

A dictionary where keys are scenario names and values are lists of simulations.

cache_data_to_disk() → None

Enable or disable caching of extracted data from polygons.

Parameters:

cache – If True, enable caching. If False, disable caching.

load_cached_data() → None

Load cached data from polygons if available.

This will load the cached data from the polygons used in the analysis.

extract_data_from_polygons() → dict

Extract data from polygons used in the analysis.

Apply on all projects in the analysis.

load_results_for_all(epsilon: float = 0.001, verbose: bool = True)

Load results for all projects in the analysis.

Parameters:

epsilon – The tolerance for considering wet cells as wet.

add_projects(projects: list[tuple[str | tuple, str]]) → None

Create a MultiProjects instance for managing all scenario results.

property viewer: wolfhece.PyGui.WolfMapViewer | None

Return the map viewer instance.

autoscale() → None

Autoscale the map viewer to fit the current bounds.

property viewer_bounds: list

Return the current bounds of the map viewer.

Returns:

A list with [xmin, ymin, xmax, ymax] representing the current bounds.

add_vector2viewer(vectorfile: str, id: str) → None

Add a vector to the map viewer.

Parameters:

• vectorfile – The filename of the vector file to be added.

• id – The id of the vector to be displayed in the map viewer.

get_polygon(scenario: str | tuple[str, str] = None) → wolfhece.pypolygons_scen.Polygons_Analyze

Get the polygons for a specific scenario.

Parameters:

scenario – The name of the scenario to get polygons for. If None, returns polygons for all scenarios.

Returns:

An instance of Polygons_Analyze.

cache_xys(scenario: str | tuple[str, str] = None) → None

Cache the x and y coordinates of the polygons for a specific scenario.

Parameters:

scenario – The name of the scenario to cache x and y coordinates for. If None, caches for all scenarios.

get_polygons_informations(scenario: str | tuple[str, str] = None) → dict

Get the information of the polygons for a specific scenario.

Parameters:

scenario – The name of the scenario to get polygons information for. If None, returns information for all scenarios.

Returns:

A dictionary with the polygons information.

property polygons: dict

Return the polygons used in the analysis.

set_reference_riverbed(scenario: str | tuple) → None

Set the reference riverbed for the analysis.

Parameters:

scenario_name – The name of the scenario to set the reference riverbed for.

property return_periods: list

Return the list of return periods for the analysis.

property backgrounds: str | None

Return the name of the orthophoto.

list_backgrounds() → list[str]

List the available backgrounds in the map viewer.

Returns:

A list of available background names.

list_simulations(scenario: str = None) → list[str]

List the available simulations in the analysis.

Parameters:

scenario – The name of the scenario to list simulations for. If None, lists all simulations.

Returns:

A list of available simulation names.

check_directories() → bool

Check if the analysis directories exist.

Returns:

True if all directories exist, False otherwise.

add_scenarios(scenario_names: list[tuple[str, str]]) → dict

Add scenarios to the analysis.

Parameters:

scenario_names – A list of scenario names to add.

Returns:

A dictionary with the paths of the added scenarios.

get_image(bounds: list | tuple, ds: float = None) → tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

Get a figure and axes for displaying the map with the specified bounds.

Parameters:

bounds – A list or a tuple with [xmin, ymin, xmax, ymax] defining the bounds to zoom in on.

check_backgrounds()

Check the orthophotos in the map viewer.

uncheck_backgrounds()

Uncheck the orthophotos in the map viewer.

create_report(title: str, author: str, report_name: str) → wolfhece.report.reporting.RapidReport

Create a report for the analysis.

Parameters:

• title – The title of the report.

• author – The author of the report.

Returns:

An instance of RapidReport.

save_report(report_name: str = None) → None

Save the report to the specified directory.

Parameters:

report_name – The name of the report file. If None, uses the default report name.

create_wolf_mapviewer() → wolfhece.PyGui.WolfMapViewer

Create a WolfMapViewer instance.

Returns:

An instance of WolfMapViewer.

set_current_scenario(scenario_name: str) → None

Set the current scenario for the analysis.

Parameters:

scenario_name – The name of the scenario to set as current.

get_scenario_names() → list[str]

Get the names of the scenarios in the analysis.

Returns:

A list of scenario names.

get_scenarios_titles() → list[str]

Get the titles of the scenarios in the analysis.

Returns:

A list of scenario titles.

report_introduction_auto()

Automatically generate the introduction section of the report.

report_add_figure_from_zoom(bounds: list | tuple, caption: str = None, ds: float = None) → None

Add a figure to the report from the current zoomed view of the map viewer.

Parameters:

• bounds – A list or a tuple with [xmin, ymin, xmax, ymax] defining the bounds to zoom in on.

• ds – The distance scale for the figure. If None, it will be calculated automatically.

• caption – The caption for the figure. If None, no caption will be added.

load_modifications(ad2viewer: bool = True)

Load modifications for scenarios from vecz files.

Parameters:

ad2viewer – If True, add the modifications to the map viewer.

Raises:

ValueError – If the MapViewer is not initialized.

uncheck_modifications(scenario: str | tuple) → None

Uncheck the modifications for a specific scenario in the map viewer.

Parameters:

scenario – The name of the scenario to uncheck modifications for.

uncheck_all_modifications() → None

Uncheck all modifications in the map viewer.

check_modifications(scenario: str | tuple) → bool

Check if modifications have been loaded for all scenarios.

Returns:

True if modifications are loaded for all scenarios, False otherwise.