wolfhece.report.tools ===================== .. py:module:: wolfhece.report.tools Module Contents --------------- .. py:class:: Directory_Analysis(*args, **kwds) Bases: :py:obj:`enum.Enum` .. autoapi-inheritance-diagram:: wolfhece.report.tools.Directory_Analysis :parts: 1 :private-bases: 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 - value lookup: >>> Color(1) - name lookup: >>> Color['RED'] Enumerations can be iterated over, and know how many members they have: >>> len(Color) 3 >>> list(Color) [, , ] Methods can be added to enumerations, and members can have their own attributes -- see the documentation for details. .. py:attribute:: PROJECTS :value: 'projets' .. py:attribute:: REPORTS :value: 'rapports' .. py:attribute:: VECTORS :value: 'vecteurs' .. py:attribute:: CLOUDS :value: 'nuages_de_points' .. py:attribute:: IMAGES :value: 'images' .. py:attribute:: CACHE :value: 'cache' .. py:function:: get_lines_from_ax(ax: matplotlib.pyplot.Axes) -> list[shapely.geometry.LineString] Get the lines from a Matplotlib Axes object. :param ax: The Matplotlib Axes object. :return: A list of LineString objects representing the lines in the Axes. .. py:function:: get_labels_from_ax(ax: matplotlib.pyplot.Axes) -> list[str] Get the labels from a Matplotlib Axes object. :param ax: The Matplotlib Axes object. :return: A list of labels from the Axes. .. py:function:: 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. :param ax: The Matplotlib Axes object. :param label: The label of the line to set to black. .. py:function:: 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. :param ax: The Matplotlib Axes object. :param styles: A dict of style where key is the label and value is a tuple with style properties. :return: None .. py:function:: _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. .. py:function:: list_directories(directory: pathlib.Path) -> list[str] List directories in a given path. .. py:function:: create_a_report(title, author) -> wolfhece.report.reporting.RapidReport Create a RapidReport instance. :param title: The title of the report. :param author: The author of the report. :return: An instance of RapidReport. .. py:function:: create_a_wolf_viewer() -> wolfhece.PyGui.WolfMapViewer Create a WolfMapViewer instance. :return: An instance of WolfMapViewer. .. py:function:: 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. :param base_directory: The base directory where the scenarios are located. :param scenario_name: The name of the scenario to find. :return: The path to the scenario directory if found, None otherwise. .. py:function:: get_scenarios_directories(base_directory: pathlib.Path | str, scenario_names: list[str]) -> dict Get the directories of all scenarios within the base directory. :param base_directory: The base directory where the scenarios are located. :param scenario_names: A list of scenario names to find. :return: A list of paths to the scenario directories. .. py:function:: check_if_scenario_exists(base_directory: pathlib.Path | str, scenario_name: str) -> bool Check if a specific scenario exists within the base directory. :param base_directory: The base directory where the scenarios are located. :param scenario_name: The name of the scenario to check. :return: True if the scenario exists, False otherwise. .. py:function:: check_if_scenarios_exist(base_directory: pathlib.Path | str, scenario_names: list[str]) -> bool Check if all specified scenarios exist within the base directory. :param base_directory: The base directory where the scenarios are located. :param scenario_names: A list of scenario names to check. :return: True if all scenarios exist, False otherwise. .. py:function:: check_analysis_directories(base_directory: pathlib.Path | str) -> bool Check if the necessary directories for analysis exist. :param base_directory: The base directory where the analysis directories are located. :return: True if all directories exist, False otherwise. .. py:function:: create_analysis_directories(base_directory: pathlib.Path | str) -> str Create the necessary directories for analysis if they do not exist. :param base_directory: The base directory where the analysis directories will be created. :return: True if directories were created or already exist, False if an error occurred. .. py:function:: get_directories_as_dict(base_directory: pathlib.Path | str) -> dict Get the paths of the analysis directories. :param base_directory: The base directory where the analysis directories are located. :return: A dictionary with the paths of the analysis directories. .. py:function:: get_directories_as_list(base_directory: pathlib.Path | str) -> list Get the paths of the analysis directories as a list. :param base_directory: The base directory where the analysis directories are located. :return: A list with the paths of the analysis directories. Ordered as per Directory_Analysis enum. .. py:function:: _check_version(min_version: str) -> bool Check if the current version is greater than or equal to the minimum version. :param min_version: The minimum required version. :type min_version: str :param current_version: The current version to check against. :type current_version: str :returns: True if the current version is greater than or equal to the minimum version, False otherwise. :rtype: bool .. py:function:: check_available_version_on_pypi() -> str Check the latest available version of the package on PyPI. :returns: The latest version available on PyPI. :rtype: str .. py:function:: can_upgrade_wolfhece() -> bool Check if the current version can be upgraded to the minimum required version. :param min_version: The minimum required version. :type min_version: str :returns: True if the current version can be upgraded, False otherwise. :rtype: bool .. py:function:: check_version(min_version: str) -> bool Check if the current version is greater than or equal to the minimum version. :param min_version: The minimum required version. :type min_version: str :returns: True if the current version is greater than or equal to the minimum version, False otherwise. :rtype: bool .. py:class:: Analysis_Scenarios(base_directory: pathlib.Path | str, storage_directory: pathlib.Path | str = None, name: str = '') .. py:attribute:: _fig_size :value: (20, 10) .. py:attribute:: name :value: 'Analysis_Scenarios' .. py:attribute:: base_directory .. py:attribute:: storage_directory :value: None .. py:attribute:: directories .. py:attribute:: scenarios_directories :type: dict[str:Path] .. py:attribute:: scenarios :value: [] .. py:attribute:: current_scenario :value: None .. py:attribute:: _return_periods :value: [] .. py:attribute:: report :type: wolfhece.report.reporting.RapidReport :value: None .. py:attribute:: _report_name :value: 'analysis_report.docx' .. py:attribute:: _report_saved_once :value: False .. py:attribute:: mapviewer :type: wolfhece.PyGui.WolfMapViewer :value: None .. py:attribute:: _background_images :type: str :value: None .. py:attribute:: _polygons :type: dict[str, wolfhece.pypolygons_scen.Polygons_Analyze] .. py:attribute:: _reference_polygon :type: wolfhece.pypolygons_scen.Polygons_Analyze :value: None .. py:attribute:: _modifications .. py:attribute:: _multiprojects :value: None .. py:attribute:: _landmarks :type: wolfhece.PyGui.Zones :value: None .. py:attribute:: _landmarks_s_label :value: [] .. py:attribute:: _measures :type: dict[str, wolfhece.PyGui.Zones] .. py:attribute:: _measures_zones :type: dict[str, list[str]] .. py:attribute:: _projected_measures :type: dict[tuple[str], list[wolfhece.PyGui.vector, dict]] .. py:attribute:: _cloud :type: list[tuple[float, float, str]] :value: [] .. py:attribute:: _images .. py:attribute:: _zoom :type: dict[str, tuple[float, float, float, float]] .. py:property:: fig_size :type: tuple[float] Return the default figure size for plots. :return: A tuple (width, height) representing the default figure size. .. py:method:: add_zoom(label: str, bounds: tuple[float]) -> None Add a zoom level to the analysis. :param label: The label for the zoom level. :param bounds: A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds. .. py:method:: 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. :param label: The label for the zoom level. :param xy1: A tuple (x1, y1) representing the first point. :param xy2: A tuple (x2, y2) representing the second point. :param zmin: The minimum zoom level. :param zmax: The maximum zoom level. .. py:method:: get_zoom(label: str) -> tuple[float] Get the zoom level bounds for a specific label. :param label: The label for the zoom level. :return: A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds. .. py:property:: measures :type: dict Return the measures used in the analysis. :return: An instance of Zones or None if not set. .. py:method:: 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. :param cloud: A cloud of points as a cloud_vertices instance or a list of tuples (s, z, label). .. py:method:: add_cloud_point(s: float, z: float, label: str = None) -> None Add a point to the cloud in the analysis. :param s: The s-coordinate of the point. :param z: The z-coordinate of the point. :param label: An optional label for the point. .. py:method:: 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. :param x: The X coordinate of the point. :param y: The Y coordinate of the point. :param z: The Z coordinate of the point (optional). :param label: An optional label for the point. .. py:method:: 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. :param measures: A Zones instance or a path to a vector file containing the measures. :param zones: A list of zone names to include in the analysis. If None, all zones in the measures will be used. :param style: A dictionary containing style properties for the measures. Available properties: 'color', 'linestyle', 'linewidth', 'marker', 'markersize', 'alpha'. :param force_all_vectors: If True, all vectors in the zones will be projected on the riverbed, even if they are not used. .. py:method:: get_landmarks_labels() -> list[str] Get the names of the landmarks in the analysis. :return: A list of names of the landmarks. .. py:property:: reference_polygon :type: wolfhece.pypolygons_scen.Polygons_Analyze | None Return the reference polygon used in the analysis. :return: An instance of Polygons_Analyze or None if not set. .. py:property:: landmarks :type: wolfhece.PyGui.Zones | None Return the landmarks used in the analysis. :return: An instance of Zones or None if not set. .. py:method:: add_landmarks(landmarks: wolfhece.PyGui.Zones | str | pathlib.Path) -> None Add landmarks to the analysis. :param landmarks: A Zones instance or a path to a vector file containing the landmarks. .. py:method:: 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. :param x: The X coordinate of the landmark. :param y: The Y coordinate of the landmark. :param name: The name of the landmark. :param z: The Z coordinate of the landmark (optional). .. py:method:: update_landmark(label: str, s_xy: float | tuple[float] = None, z: float = None) -> None Update a landmark in the analysis. :param label: The label of the landmark to update. :param s_xy: The s-coordinate or a tuple (s, xy) to update the landmark's position. :param z: The z-coordinate to update the landmark's elevation (optional). .. py:method:: plot_cloud(ax: matplotlib.pyplot.Axes, bounds: tuple[float]) -> matplotlib.pyplot.Axes Trace the cloud of points on an axis Matplotlib :param ax: axe Matplotlib :param bounds: tuple (xmin, xmax, ymin, ymax) for the plot limits :return: The Matplotlib Axes object with the cloud plotted. .. py:method:: plot_measures(ax: matplotlib.pyplot.Axes, bounds: tuple[float], style: dict = None) -> matplotlib.pyplot.Axes Trace les mesures sur un axe Matplotlib :param ax: axe Matplotlib :param bounds: tuple (xmin, xmax, ymin, ymax) for the plot limits :param style: Optional style dictionary for the measures. Available properties: - 'color': The color of the line. - 'linestyle': The style of the line (e.g., '-', '--', '-.', ':'). :return: The Matplotlib Axes object with the measures plotted. .. py:method:: plot_landmarks(ax: matplotlib.pyplot.Axes, bounds: tuple[float], style: dict = None) -> matplotlib.pyplot.Axes Trace les repères sur un axe Matplotlib :param ax: axe Matplotlib :param bounds: tuple (xmin, xmax, ymin, ymax) for the plot limits :param style: Optional style dictionary for the landmarks. .. py:method:: 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. :param scenario: The name of the scenario to plot waterlines for or a list of scenarios for comparison. :param bounds: A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds or a string label for a zoom level. :param operator: The operator to apply on the waterlines. :param save: If True, save the plot as an image file. :param figsize: A tuple (width, height) representing the size of the figure. If None, uses the default figure size. :param plot_annex: If True, plot the cloud of points, measures, and landmarks. :return: A tuple (fig, ax) where fig is the matplotlib Figure and ax is the matplotlib Axes object. .. py:method:: 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. :param scenario: The name of the scenario to plot heads for or a list of scenarios for comparison. :param bounds: A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds or a string label for a zoom level. :param operator: The operator to apply on the heads. :param plot_annex: If True, plot the cloud of points, measures, and landmarks. :param save: If True, save the plot as an image file. :param figsize: A tuple (width, height) representing the figure size. If None, use the default figure size. :return: A tuple (fig, ax) representing the figure and axes of the plot .. py:method:: 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. :param scenario: The name of the scenario to plot waterlines for or a list of scenarios for comparison. :param bounds: A tuple (xmin, xmax, ymin, ymax) representing the zoom bounds or a string label for a zoom level. :param operator: The operator to apply on the waterlines. :param save: If True, save the plot as an image file. :param figsize: A tuple (width, height) representing the figure size. If None, use the default figure size. :param plot_annex: If True, plot the cloud of points, measures, and landmarks. :return: A tuple (fig, ax) representing the figure and axes of the plot .. py:method:: 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. :param filename: The name of the file to save the image to. :param fig: The figure to save. If None, uses the current active figure. :param dpi: The resolution of the saved image in dots per inch. :param format: The format of the saved image (png, pdf, svg). Default is 'png'. .. py:method:: 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. :param scenario: The name of the scenario to export values for. If None, exports values for all scenarios. :param simulation_key: The key of the simulation to export values for. If None, exports values for all simulations. :param which_values: The type of values to export from the polygons. :param operator: The operator to apply on the values extracted from the polygons. :param filename: The name of the file to export values to. If None, a default name will be used. :param format: The format of the file to export values to (csv or xlsx). Default is 'xlsx'. .. py:method:: 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. :param scenario: The name of the scenario to get values for. If None, gets values for all scenarios. :param which_value: The type of value to extract from the polygons. :param which_operator: The operator to apply on the values extracted from the polygons. :return: A dictionary with the values extracted from the polygons. .. py:method:: 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. .. py:method:: 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. .. py:method:: list_sims_in_all_polygons() -> dict List the simulations in all polygons used in the analysis. :return: A dictionary where keys are scenario names and values are lists of simulations. .. py:method:: cache_data_to_disk() -> None Enable or disable caching of extracted data from polygons. :param cache: If True, enable caching. If False, disable caching. .. py:method:: load_cached_data() -> None Load cached data from polygons if available. This will load the cached data from the polygons used in the analysis. .. py:method:: extract_data_from_polygons() -> dict Extract data from polygons used in the analysis. Apply on all projects in the analysis. .. py:method:: load_results_for_all(epsilon: float = 0.001, verbose: bool = True) Load results for all projects in the analysis. :param epsilon: The tolerance for considering wet cells as wet. .. py:method:: add_projects(projects: list[tuple[str | tuple, str]]) -> None Create a MultiProjects instance for managing all scenario results. .. py:property:: viewer :type: wolfhece.PyGui.WolfMapViewer | None Return the map viewer instance. .. py:method:: autoscale() -> None Autoscale the map viewer to fit the current bounds. .. py:property:: viewer_bounds :type: list Return the current bounds of the map viewer. :return: A list with [xmin, ymin, xmax, ymax] representing the current bounds. .. py:method:: add_vector2viewer(vectorfile: str, id: str) -> None Add a vector to the map viewer. :param vectorfile: The filename of the vector file to be added. :param id: The id of the vector to be displayed in the map viewer. .. py:method:: get_polygon(scenario: str | tuple[str, str] = None) -> wolfhece.pypolygons_scen.Polygons_Analyze Get the polygons for a specific scenario. :param scenario: The name of the scenario to get polygons for. If None, returns polygons for all scenarios. :return: An instance of Polygons_Analyze. .. py:method:: cache_xys(scenario: str | tuple[str, str] = None) -> None Cache the x and y coordinates of the polygons for a specific scenario. :param scenario: The name of the scenario to cache x and y coordinates for. If None, caches for all scenarios. .. py:method:: get_polygons_informations(scenario: str | tuple[str, str] = None) -> dict Get the information of the polygons for a specific scenario. :param scenario: The name of the scenario to get polygons information for. If None, returns information for all scenarios. :return: A dictionary with the polygons information. .. py:property:: polygons :type: dict Return the polygons used in the analysis. .. py:method:: set_reference_riverbed(scenario: str | tuple) -> None Set the reference riverbed for the analysis. :param scenario_name: The name of the scenario to set the reference riverbed for. .. py:property:: return_periods :type: list Return the list of return periods for the analysis. .. py:property:: backgrounds :type: str | None Return the name of the orthophoto. .. py:method:: list_backgrounds() -> list[str] List the available backgrounds in the map viewer. :return: A list of available background names. .. py:method:: list_simulations(scenario: str = None) -> list[str] List the available simulations in the analysis. :param scenario: The name of the scenario to list simulations for. If None, lists all simulations. :return: A list of available simulation names. .. py:method:: check_directories() -> bool Check if the analysis directories exist. :return: True if all directories exist, False otherwise. .. py:method:: add_scenarios(scenario_names: list[tuple[str, str]]) -> dict Add scenarios to the analysis. :param scenario_names: A list of scenario names to add. :return: A dictionary with the paths of the added scenarios. .. py:method:: 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. :param bounds: A list or a tuple with [xmin, ymin, xmax, ymax] defining the bounds to zoom in on. .. py:method:: check_backgrounds() Check the orthophotos in the map viewer. .. py:method:: uncheck_backgrounds() Uncheck the orthophotos in the map viewer. .. py:method:: create_report(title: str, author: str, report_name: str) -> wolfhece.report.reporting.RapidReport Create a report for the analysis. :param title: The title of the report. :param author: The author of the report. :return: An instance of RapidReport. .. py:method:: save_report(report_name: str = None) -> None Save the report to the specified directory. :param report_name: The name of the report file. If None, uses the default report name. .. py:method:: create_wolf_mapviewer() -> wolfhece.PyGui.WolfMapViewer Create a WolfMapViewer instance. :return: An instance of WolfMapViewer. .. py:method:: set_current_scenario(scenario_name: str) -> None Set the current scenario for the analysis. :param scenario_name: The name of the scenario to set as current. .. py:method:: get_scenario_names() -> list[str] Get the names of the scenarios in the analysis. :return: A list of scenario names. .. py:method:: get_scenarios_titles() -> list[str] Get the titles of the scenarios in the analysis. :return: A list of scenario titles. .. py:method:: report_introduction_auto() Automatically generate the introduction section of the report. .. py:method:: 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. :param bounds: A list or a tuple with [xmin, ymin, xmax, ymax] defining the bounds to zoom in on. :param ds: The distance scale for the figure. If None, it will be calculated automatically. :param caption: The caption for the figure. If None, no caption will be added. .. py:method:: load_modifications(ad2viewer: bool = True) Load modifications for scenarios from vecz files. :param ad2viewer: If True, add the modifications to the map viewer. :raises ValueError: If the MapViewer is not initialized. .. py:method:: uncheck_modifications(scenario: str | tuple) -> None Uncheck the modifications for a specific scenario in the map viewer. :param scenario: The name of the scenario to uncheck modifications for. .. py:method:: uncheck_all_modifications() -> None Uncheck all modifications in the map viewer. .. py:method:: check_modifications(scenario: str | tuple) -> bool Check if modifications have been loaded for all scenarios. :return: True if modifications are loaded for all scenarios, False otherwise.