invert4geom.plotting
====================

.. py:module:: invert4geom.plotting


Functions
---------

.. autoapisummary::

   invert4geom.plotting.plot_2_parameter_cv_scores
   invert4geom.plotting.plot_2_parameter_cv_scores_uneven
   invert4geom.plotting.plot_cv_scores
   invert4geom.plotting.plot_convergence
   invert4geom.plotting.plot_dynamic_convergence
   invert4geom.plotting.align_yaxis
   invert4geom.plotting.grid_inversion_results
   invert4geom.plotting.plot_inversion_topo_results
   invert4geom.plotting.plot_inversion_grav_results
   invert4geom.plotting.plot_inversion_iteration_results
   invert4geom.plotting.plot_inversion_results
   invert4geom.plotting.add_light
   invert4geom.plotting.show_prism_layers
   invert4geom.plotting.combined_slice
   invert4geom.plotting.plot_optuna_figures
   invert4geom.plotting.plot_stochastic_results
   invert4geom.plotting.remove_df_from_hoverdata
   invert4geom.plotting.plot_latin_hypercube
   invert4geom.plotting.projection_2d
   invert4geom.plotting.edge_effects


Module Contents
---------------

.. py:function:: plot_2_parameter_cv_scores(scores, parameter_pairs, param_names = ('Hyperparameter 1', 'Hyperparameter 2'), figsize = (5, 3.5), cmap = None)

   plot a scatter plot graph with x axis equal to parameter 1, y axis equal to
   parameter 2, and points colored by cross-validation scores.

   :param scores: score values
   :type scores: list[float]
   :param parameter_pairs: parameter values
   :type parameter_pairs: list[float]
   :param param_names: name to give for the parameters, by default "Hyperparameter"
   :type param_names: tuple[str, str], optional
   :param figsize: size of the figure, by default (5, 3.5)
   :type figsize: tuple[float, float], optional
   :param cmap: matplotlib colormap for scores, by default "viridis"
   :type cmap: str, optional


.. py:function:: plot_2_parameter_cv_scores_uneven(study, param_names, plot_param_names = ('Hyperparameter 1', 'Hyperparameter 2'), figsize = (5, 3.5), cmap = None, best = 'min', logx = False, logy = False, robust = False)

   plot a scatter plot graph with x axis equal to parameter 1, y axis equal to
   parameter 2, and points colored by cross-validation scores.

   :param study:
   :type study: optuna.study.Study
   :param param_names: name to give for the parameters, by default "Hyperparameter"
   :type param_names: tuple[str, str], optional
   :param figsize: size of the figure, by default (5, 3.5)
   :type figsize: tuple[float, float], optional
   :param cmap: matplotlib colormap for scores, by default "viridis"
   :type cmap: str, optional
   :param best: whether the 'min' or 'max' score is considered best, by default 'min'
   :type best: str, optional
   :param logx: make the x or y axes log scale, by default False
   :type logx: bool, optional
   :param logy: make the x or y axes log scale, by default False
   :type logy: bool, optional
   :param robust: use robust color limits
   :type robust: bool, optional


.. py:function:: plot_cv_scores(scores, parameters, logx = False, logy = False, param_name = 'Hyperparameter', figsize = (5, 3.5), plot_title = None, fname = None, best = 'min')

   plot a graph of cross-validation scores vs hyperparameter values

   :param scores: score values
   :type scores: list[float]
   :param parameters: parameter values
   :type parameters: list[float]
   :param logx: make the x or y axes log scale, by default False
   :type logx: bool, optional
   :param logy: make the x or y axes log scale, by default False
   :type logy: bool, optional
   :param param_name: name to give for the parameters, by default "Hyperparameter"
   :type param_name: str, optional
   :param figsize: size of the figure, by default (5, 3.5)
   :type figsize: tuple[float, float], optional
   :param plot_title: title of figure, by default None
   :type plot_title: str | None, optional
   :param fname: filename to save figure, by default None
   :type fname: str | None, optional
   :param best: which value to plot as the best, 'min' or 'max', by default "min"
   :type best: str, optional

   :rtype: a matplotlib figure instance


.. py:function:: plot_convergence(results, params, inversion_region = None, figsize = (5, 3.5), fname = None)

   plot a graph of L2-norm and delta L2-norm vs iteration number.

   :param results: gravity result dataframe
   :type results: pandas.DataFrame
   :param params: inversion parameters output from function `run_inversion()`
   :type params: dict[str, typing.Any]
   :param inversion_region: inside region of inversion, by default None
   :type inversion_region: tuple[float, float, float, float] | None, optional
   :param figsize: width and height of figure, by default (5, 3.5)
   :type figsize: tuple[float, float], optional
   :param fname: filename to save figure, by default None
   :type fname: str | None, optional


.. py:function:: plot_dynamic_convergence(l2_norms, l2_norm_tolerance, delta_l2_norms, delta_l2_norm_tolerance, starting_misfit, figsize = (5, 3.5))

   plot a dynamic graph of L2-norm and delta L2-norm vs iteration number.

   :param l2_norms: list of l2 norm values
   :type l2_norms: list[float]
   :param l2_norm_tolerance: l2 norm tolerance
   :type l2_norm_tolerance: float
   :param delta_l2_norms: list of delta l2 norm values
   :type delta_l2_norms: list[float]
   :param delta_l2_norm_tolerance: delta l2 norm tolerance
   :type delta_l2_norm_tolerance: float
   :param starting_misfit: starting misfit rmse
   :type starting_misfit: float
   :param figsize: width and height of figure, by default (5, 3.5)
   :type figsize: tuple[float, float], optional


.. py:function:: align_yaxis(ax1, v1, ax2, v2)

   adjust ax2 ylimit so that v2 in ax2 is aligned to v1 in ax1.
   From https://stackoverflow.com/a/10482477/18686384


.. py:function:: grid_inversion_results(misfits, topos, corrections, prisms_ds, grav_results, region)

   create grids from the various data variables of the supplied gravity dataframe and
   prism dataset

   :param misfits: list of misfit column names in the gravity results dataframe
   :type misfits: list[str]
   :param topos: list of topography variable names in the prism dataset
   :type topos: list[str]
   :param corrections: list of correction variable names in the prism dataset
   :type corrections: list[str]
   :param prisms_ds: resulting dataset of prism layer from the inversion
   :type prisms_ds: xarray.Dataset
   :param grav_results: resulting dataframe of gravity data from the inversion
   :type grav_results: pandas.DataFrame
   :param region: region to use for gridding in format (xmin, xmax, ymin, ymax)
   :type region: tuple[float, float, float, float]

   :returns: * **misfit_grids** (*list[xarray.DataArray]*) -- list of misfit grids
             * **topo_grids** (*list[xarray.DataArray]*) -- list of topography grids
             * **corrections_grids** (*list[xarray.DataArray]*) -- list of correction grids


.. py:function:: plot_inversion_topo_results(prisms_ds, region = None, constraints_df = None, constraint_style = 'x.3c', fig_height = 12)

   plot the initial and final topography grids from the inversion and their difference

   :param prisms_ds: dataset resulting from inversion
   :type prisms_ds: xarray.Dataset
   :param topo_cmap_perc: value to multiple min and max values by for colorscale, by default 1
   :type topo_cmap_perc: float, optional
   :param region: clip grids to this region before plotting
   :type region: tuple[float, float, float, float], optional
   :param constraints_df: constraint points to include in the plots
   :type constraints_df: pandas.DataFrame, optional
   :param constraint_style: pygmt style string for for constraint points, by default 'x.3c'
   :type constraint_style: str, optional
   :param fig_height: height of the figure, by default 12
   :type fig_height: float, optional


.. py:function:: plot_inversion_grav_results(grav_results, region, iterations, constraints_df = None, fig_height = 12, constraint_style = 'x.3c')

   plot the initial and final misfit grids from the inversion and their difference

   :param grav_results: resulting dataframe of gravity data from the inversion
   :type grav_results: pandas.DataFrame
   :param region: region to use for gridding in format (xmin, xmax, ymin, ymax)
   :type region: tuple[float, float, float, float]
   :param iterations: list of all the iteration numbers
   :type iterations: list[int]
   :param constraints_df: constraint points to include in the plots
   :type constraints_df: pandas.DataFrame, optional
   :param fig_height: height of the figure, by default 12
   :type fig_height: float, optional
   :param constraint_style: pygmt style string for for constraint points, by default 'x.3c'
   :type constraint_style: str, optional


.. py:function:: plot_inversion_iteration_results(grids, grav_results, topo_results, parameters, iterations, topo_cmap_perc = 1, misfit_cmap_perc = 1, corrections_cmap_perc = 1, constraints_df = None, constraint_size = 1)

   plot the starting misfit, updated topography, and correction grids for a specified
   number of the iterations of an inversion

   :param grids: list[xarray.DataArray]]
                 lists of misfit, topography, and correction grids
   :type grids: tuple[list[xarray.DataArray], list[xarray.DataArray],
   :param grav_results: gravity dataframe resulting from the inversion
   :type grav_results: pandas.DataFrame
   :param topo_results: topography dataframe resulting from the inversion
   :type topo_results: pandas.DataFrame
   :param parameters: inversion parameters resulting from the inversion
   :type parameters: dict[str, typing.Any]
   :param iterations: list of all the iteration numbers which occurred in the inversion
   :type iterations: list[int]
   :param topo_cmap_perc: value to multiply the max and min colorscale values by, by default 1
   :type topo_cmap_perc: float, optional
   :param misfit_cmap_perc: value to multiply the max and min colorscale values by, by default 1
   :type misfit_cmap_perc: float, optional
   :param corrections_cmap_perc: value to multiply the max and min colorscale values by, by default 1
   :type corrections_cmap_perc: float, optional
   :param constraints_df: constraint points to include in the plots
   :type constraints_df: pandas.DataFrame, optional
   :param constraint_size: size for constraint points, by default 1
   :type constraint_size: float, optional


.. py:function:: plot_inversion_results(grav_results, topo_results, parameters, grav_region, iters_to_plot = None, plot_iter_results = True, plot_topo_results = True, plot_grav_results = True, constraints_df = None, **kwargs)

   plot various results from the inversion

   :param grav_results: gravity results dataframe or filename
   :type grav_results: pandas.DataFrame | str
   :param topo_results: topography results dataframe or filename
   :type topo_results: pandas.DataFrame | str
   :param parameters: inversion parameters dictionary or filename
   :type parameters: dict[str, typing.Any] | str
   :param grav_region: region to use for gridding in format (xmin, xmax, ymin, ymax), by default None
   :type grav_region: tuple[float, float, float, float] | None
   :param iters_to_plot: number of iterations to plot, including the first and last, by default None
   :type iters_to_plot: int | None, optional
   :param plot_iter_results: plot the iteration results, by default True
   :type plot_iter_results: bool, optional
   :param plot_topo_results: plot the topography results, by default True
   :type plot_topo_results: bool, optional
   :param plot_grav_results: plot the gravity results, by default True
   :type plot_grav_results: bool, optional
   :param constraints_df: constraint points to include in the plots
   :type constraints_df: pandas.DataFrame, optional


.. py:function:: add_light(plotter, prisms)

   add a light to a pyvista plotter object

   :param plotter: pyvista plotter object
   :type plotter: pyvista.Plotter
   :param prisms: harmonica prisms layer
   :type prisms: xarray.Dataset


.. py:function:: show_prism_layers(prisms, cmap = 'viridis', color_by = 'density', region = None, clip_box = False, **kwargs)

   show prism layers using PyVista

   :param prisms: either a single harmonica prism layer of list of layers,
   :type prisms: list | xarray.Dataset
   :param cmap: matplotlib colorscale to use, by default "viridis"
   :type cmap: str, optional
   :param color_by: either use a variable of the prism_layer dataset, typically 'density' or
                    'thickness', or choose 'constant' to have each layer colored by a unique color
                    use kwarg `colors` to alter these colors, by default is "density"
   :type color_by: str, optional
   :param region: region to clip the model to, by default None
   :type region: tuple[float, float, float, float], optional
   :param clip_box: clip a corner out of the model to help visualize, by default False
   :type clip_box: bool, optional


.. py:function:: combined_slice(study, attribute_names, parameter_name = None)

   plot combined slice plots for optimizations.

   :param study: the optuna study object
   :type study: optuna.study.Study
   :param target_names: list of names for parameters in the study
   :type target_names: list[str]

   :returns: a plotly figure
   :rtype: plotly.graph_objects.Figure


.. py:function:: plot_optuna_figures(study, target_names, include_duration = False, plot_history = True, plot_slice = True, plot_importance = True)

   plot the results of an optuna optimization

   :param study: the optuna study object
   :type study: optuna.study.Study
   :param target_names: list of names for parameters in the study
   :type target_names: list[str]
   :param include_duration: whether to add the duration to the plot, by default False
   :type include_duration: bool, optional
   :param plot_history: choose to plot the optimization history, by default True
   :type plot_history: bool, optional
   :param plot_slice: choose to plot the parameter values vs. score for each parameter, by default
                      True
   :type plot_slice: bool, optional


.. py:function:: plot_stochastic_results(stats_ds, points = None, region = None, **kwargs)

   Plot the (weighted) standard deviation (uncertainty) and mean of the stochastic
   ensemble. Optionally, plot points as well.

   :param stats_ds: dataset with the merged inversion results, generate from function
                    `uncertainty.model_ensemble_stats`.
   :type stats_ds: xarray.Dataset
   :param points: dataframe with points to plot, by default None
   :type points: pandas.DataFrame | None, optional

   :keyword cmap: colormap to use for the ensemble mean, by default "rain"
   :kwtype cmap: str, optional
   :keyword unit: unit of the data, by default "m"
   :kwtype unit: str, optional
   :keyword reverse_cpt: reverse the ensemble mean colormap, by default True
   :kwtype reverse_cpt: bool, optional
   :keyword label: label for the colorbar, by default "ensemble mean"
   :kwtype label: str, optional
   :keyword points_label: label for the points, by default None
   :kwtype points_label: str, optional
   :keyword fig_height: height of the figure, by default 12
   :kwtype fig_height: float, optional


.. py:function:: remove_df_from_hoverdata(plot)

   Remove the dataframe from the hoverdata of a plotly plot

   :param plot: plotly figure
   :type plot: plotly.graph_objects.Figure

   :returns: plotly figure with the dataframe removed from the hoverdata
   :rtype: plotly.graph_objects.Figure


.. py:function:: plot_latin_hypercube(params_dict, plot_individual_dists = True, plot_2d_projections = True)

   With a dictionary of parameters and their sampled values, plot the individual
   distributions and or the 2D projections of the parameter pairs.

   :param params_dict: dictionary of sampled parameter values, can be created manually or from the
                       output of func:`.uncertainty.create_lhc`
   :type params_dict: dict[str, dict[str, typing.Any]]
   :param plot_individual_dists: choose to plot distribution of each parameter, by default True
   :type plot_individual_dists: bool, optional
   :param plot_2d_projections: choose to plot the 2D projection of each parameter pair, by default True
   :type plot_2d_projections: bool, optional


.. py:function:: projection_2d(sample, var_names)

   Plots the sample projected on each 2D plane

   :param sample: The sampled values
   :type sample: NDArray
   :param var_names: The names of the variables
   :type var_names: list[str]


.. py:function:: edge_effects(grav_ds, prism_layer, inner_region, plot_profile = True)

   Show the gravity edge effects and the percentage decay within the inner region and
   optionally a profile across the region.

   :param grav_ds: the gravity dataset
   :type grav_ds: xr.Dataset
   :param prism_layer: the prism layer
   :type prism_layer: xr.DataArray
   :param inner_region: the inside region, where forward gravity is calculated
   :type inner_region: tuple[float, float, float, float]
   :param plot_profile: plot a profile across the region, by default True
   :type plot_profile: bool, optional