pyissm.inversion.plot

Inversion plotting tools for pyISSM.

This module contains various functions for plotting inversion diagnostics for ISSM models.

Functions

plot_convergence_history(convergence_history)

Plot optimization convergence metrics over iterations.

plot_lcurve(diagnostics[, alpha_col, ...])

Plot inversion L-curve.

plot_run_summary(md, output_pdf[, ...])

Generate PDF summary report for inversion run.

plot_sensitivity_heatmap(diagnostics, x, y, ...)

Plot a sensitivity heatmap from tabular diagnostics data.
pyissm.inversion.plot.plot_convergence_history(convergence_history, metrics=None, log=True, ax=None, figsize=(6.4, 4.8), constrained_layout=True)

Plot optimization convergence metrics over iterations.

Parameters:

  • convergence_history (pandas.DataFrame) – Table containing an "iteration" column and one or more metric columns to plot against iteration.

  • metrics (list of str or None, optional) – Metric column names to plot. If None (default), all columns except "iteration" are plotted.

  • log (bool, optional) – If True (default), use a logarithmic scale for the y-axis.

  • ax (matplotlib.axes.Axes, optional) – Axes object to draw on. If None, a new figure and axes are created.

  • figsize (tuple of float, optional) – Size of the figure in inches (width, height). Default is (6.4, 4.8).

  • constrained_layout (bool, optional) – Whether to use constrained layout in figure. Default is True.

Returns:

  • fig (matplotlib.figure.Figure) – The created Matplotlib figure. Returned only if a new figure was created.

  • ax (matplotlib.axes.Axes) – The axes containing the heatmap. If an axes was passed in, this is the same object; if no axes was passed, this is the newly created axes.

Notes

This function does not validate metric names. A missing metric column will raise a pandas KeyError during plotting.

Example

: code-block:: python

>>> convergence_history = pyissm.inversion.metrics.extract_convergence_history(md)
>>> fig, ax = plot_convergence_history(convergence_history)
pyissm.inversion.plot.plot_lcurve(diagnostics, alpha_col=None, misfit_cols=None, regularization_col=None, ax=None, annotate=True, sort_alpha=True, marker='s', figsize=(7, 6), constrained_layout=True, **kwargs)

Plot inversion L-curve.

Parameters:

  • diagnostics (pandas.DataFrame) – Diagnostics table generated from sensitivity analysis.

  • alpha_col (str, optional) –

    Column containing regularization coefficient values.

    If None, automatically inferred from regularization term:

    • cost_501 -> cf501

    • cost_502 -> cf502

    • cost_503 -> cf503

  • misfit_cols (list of str, optional) –

    Cost-function columns contributing to model-data misfit.

    If None, automatically inferred as all cost-function columns except total cost and regularization term.

  • regularization_col (str, optional) –

    Regularization cost-function column.

    If None:

    • uses cost_501 if present

    • uses cost_502 if present

    • uses cost_503 if present

    • raises error if both exist

    • raises error if neither exist

  • ax (matplotlib.axes.Axes, optional) – Existing axis.

  • annotate (bool, default = True) – Label points with alpha values.

  • sort_alpha (bool, default = True) – Sort curve by alpha before plotting.

  • marker (str, default = “s”) – Marker style.

  • figsize (tuple, default = (7, 6)) – Figure size when creating a new figure.

  • constrained_layout (bool, default = True) – Whether to use constrained layout when creating a new figure.

  • **kwargs – Passed to matplotlib plotting function.

Returns:

  • fig (matplotlib.figure.Figure) – The created Matplotlib figure. Returned only if a new figure was created.

  • ax (matplotlib.axes.Axes) – The axes containing the plot. If an axes was passed in, this is the same object; if no axes was passed, this is the newly created axes.

Example

: code-block:: python

>>> manifest = pd.read_csv('./sensitivity_runs/manifest.csv')
>>> diagnostics = pyissm.inversion.sensitivity.compute_sensitivity_diagnostics(manifest, output_dir = './sensitivity_runs')
>>> fig, ax = plot_lcurve(diagnostics)
pyissm.inversion.plot.plot_run_summary(md, output_pdf, diagnostics=None, plot_kwargs=None)

Generate PDF summary report for inversion run.

Saves a multi-page PDF report to the specified path, containing visualizations and diagnostics of the inversion run. The first page includes spatial plots of observed velocity, modelled velocity, velocity residuals, and the inverted control parameter field. The second page includes a convergence history plot, histograms of velocity residuals and inverted field slopes, and a text summary of key diagnostics. Plot appearance can be customized via the plot_kwargs parameter.

Parameters:

  • md (pyissm.Model) – ISSM model object containing inversion results.

  • output_pdf (str) – Path to output PDF file.

  • diagnostics (dict, optional) – Model diagnostics. Default is None. Computed internally if not provided.

  • plot_kwargs (dict, optional) – Plot keyword arguments. Default is None.

Returns:

None. Saves the generated report to the specified PDF file.

Example

: code-block:: python

>>> plot.plot_run_summary(md, output_pdf = f'./sensitivity_runs/run_001_1_1/run_001_1_summary.pdf')
pyissm.inversion.plot.plot_sensitivity_heatmap(diagnostics, x, y, value, cmap='viridis', ax=None, figsize=(6.4, 4.8), constrained_layout=True, **kwargs)

Plot a sensitivity heatmap from tabular diagnostics data.

Parameters:

  • diagnostics (pandas.DataFrame) – Input table containing at least the columns specified by x, y, and value.

  • x (str) – Column name used for heatmap x-axis categories.

  • y (str) – Column name used for heatmap y-axis categories.

  • value (str) – Column name whose values populate the heatmap cells.

  • cmap (str or matplotlib.colors.Colormap, optional) – Colormap used to render the heatmap. Defaults to "viridis".

  • ax (matplotlib.axes.Axes, optional) – Axes object to draw on. If None, a new figure and axes are created.

  • figsize (tuple of float, optional) – Figure size in inches as (width, height). Defaults to (6.4, 4.8).

  • constrained_layout (bool, optional) – Whether to use Matplotlib constrained layout. Defaults to True.

  • **kwargs – Additional keyword arguments forwarded to matplotlib.axes.Axes.imshow().

Returns:

  • fig (matplotlib.figure.Figure) – The created Matplotlib figure. Returned only if a new figure was created.

  • ax (matplotlib.axes.Axes) – The axes containing the heatmap. If an axes was passed in, this is the same object; if no axes was passed, this is the newly created axes.

Notes

The heatmap is generated via pandas.DataFrame.pivot_table() using y as the index, x as the columns, and value as cell values.

Example

: code-block:: python

>>> manifest = pd.read_csv('./sensitivity_runs/manifest.csv')
>>> diagnostics = pyissm.inversion.sensitivity.compute_sensitivity_diagnostics(manifest, output_dir = './sensitivity_runs')
>>> fig, ax = pyissm.inversion.plot.plot_sensitivity_heatmap(diagnostics, x = 'cf101', y = 'cf103', value = 'vel_rmse')