integrate_plot

Functions for plotting in the INTEGRATE module.

INTEGRATE Plotting Module - Visualization and Analysis Tools

This module provides comprehensive visualization capabilities for the INTEGRATE geophysical data integration package. It creates publication-quality plots for data analysis, prior/posterior visualization, and results interpretation.

Key Features:

• 1D profile plots for layered earth models

• 2D spatial mapping and interpolation

• Data-model comparison visualizations

• Statistical plots (uncertainty, probability maps)

• Geometry and survey layout visualization

• Customizable plotting styles and colormaps

Main Function Categories:

• plot_profile_*(): 1D vertical profile plotting

• plot_data_*(): Observational data visualization

• plot_geometry(): Survey geometry and layout

• plot_feature_2d(): 2D spatial parameter mapping

• plot_T_EV(): Temperature and evidence visualization

• plot_*_stats(): Statistical analysis plots

Plot Types:

• Discrete categorical models (geological units)

• Continuous parameter models (resistivity, conductivity)

• Uncertainty and probability distributions

• Data fit and residual analysis

• Cumulative thickness and property maps

Output Formats:

• Interactive matplotlib figures

• High-resolution PNG/PDF export

• Customizable figure sizing and DPI

Author: Thomas Mejer Hansen Email: tmeha@geo.au.dk

integrate.integrate_plot.find_points_along_line_segments(X, Y, Xl, Yl, ID=None, tolerance=None, method='closest')

Find point indices that lie along or near specified line segments.

Parameters:

Xarray-like

X coordinates of points

Yarray-like

Y coordinates of points

Xlarray-like

X coordinates defining line segment endpoints (length = number of segments)

Ylarray-like

Y coordinates defining line segment endpoints (length = number of segments)

IDarray-like, optional

Point identifiers (same length as X, Y)

tolerancefloat, optional

Maximum distance from line segments to include points If None, uses 1% of the maximum coordinate range

methodstr, optional

Selection method: ‘closest’ (default), ‘within_tolerance’, or ‘perpendicular’

Returns:

indicesnumpy.ndarray

Indices of points that lie along the line segments

distancesnumpy.ndarray

Distances from selected points to their nearest line segments

segment_idsnumpy.ndarray

Which line segment each selected point is closest to

Notes:

For 3 line segments, len(Xl) = len(Yl) = 3, defining segments: - Segment 0: from (Xl[0], Yl[0]) to (Xl[1], Yl[1]) - Segment 1: from (Xl[1], Yl[1]) to (Xl[2], Yl[2]) - etc.

Examples:

>>> X = np.array([1, 2, 3, 4, 5])
>>> Y = np.array([1, 2, 3, 4, 5])
>>> Xl = np.array([0, 3, 6])  # Two line segments
>>> Yl = np.array([0, 3, 6])
>>> indices, distances, seg_ids = find_points_along_line_segments(X, Y, Xl, Yl)

integrate.integrate_plot.get_colormap_and_limits(cmap_type='default', custom_clim=None)

Return colormap and associated limits for different visualization types.

Creates various colormaps and their associated color limits for different geophysical data visualization needs, with a focus on resistivity and electromagnetic data plotting.

Parameters:

• cmap_type (str, optional) – Type of colormap to return (default is ‘default’): - ‘default’: Red-white-blue-black colormap for general use - ‘resistivity’: Log-scale colormap optimized for resistivity data - ‘entropy’: Grayscale colormap for uncertainty visualization - ‘discrete’: Categorical colormap for discrete classifications - ‘temperature’: Hot colormap for temperature/evidence fields - ‘elevation’: Terrain-like colormap for topographic data - ‘seismic’: Blue-white-red colormap for seismic data

• custom_clim (list or tuple, optional) – Custom color limits as [min, max]. If provided, overrides default limits for the specified colormap type (default is None).

Returns:

• cmap (matplotlib.colors.Colormap) – The colormap object ready for use in matplotlib plotting functions.

• clim (list) – Color scale limits as [min, max] values appropriate for the colormap.

Notes

Default colormap creates a smooth transition: red (low) → white (medium) → blue (high) → black (very high), which is effective for resistivity visualization where extreme values need emphasis.

Examples

>>> cmap, clim = get_colormap_and_limits('default')
>>> # Use with matplotlib: plt.imshow(data, cmap=cmap, vmin=clim[0], vmax=clim[1])

>>> cmap, clim = get_colormap_and_limits('resistivity', custom_clim=[10, 1000])
>>> # Custom limits override defaults for resistivity colormap

integrate.integrate_plot.h5_get_clim_cmap(f_prior_h5, Mstr='/M1')

Retrieve color scale limits and colormap from prior model attributes.

Extracts visualization parameters stored in HDF5 file attributes, providing default values when attributes are not present. Used by plotting functions for consistent color scaling across visualizations.

Parameters:

• f_prior_h5 (str) – Path to the HDF5 file containing prior model data.

• Mstr (str, optional) – Model parameter key string (e.g., ‘/M1’, ‘/M2’, default is ‘/M1’).

Returns:

• clim (list) – Color scale limits as [min_value, max_value]. Returns [10, 500] as default if ‘clim’ attribute is not found.

• cmap (matplotlib.colors.ListedColormap or str) – Colormap object created from stored colormap array, or ‘jet’ string as default if ‘cmap’ attribute is not found.

Notes

The function automatically converts stored colormap arrays to matplotlib ListedColormap objects with proper transposition. Color limits and colormaps are typically set during prior model generation to ensure consistent visualization across different plotting functions.

integrate.integrate_plot.plot_T_EV(f_post_h5, i1=1, i2=1000000000.0, T_min=1, T_max=100, pl='all', hardcopy=False, **kwargs)

Plot temperature and evidence field values from posterior sampling results.

Creates 2D spatial scatter plots showing the distribution of temperature (T), evidence (EV), and number of data points across the survey area. Temperature indicates sampling efficiency while evidence shows data fit quality.

Parameters:

• f_post_h5 (str) – Path to the HDF5 file containing posterior sampling results.

• i1 (int, optional) – Starting data point index for plotting (1-based indexing, default is 1).

• i2 (float, optional) – Ending data point index for plotting. If larger than data size, uses all available data (default is 1e+9).

• s (int, optional) – Size of scatter plot markers in points (default is 5).

• T_min (int, optional) – Minimum temperature value for color scale normalization (default is 1).

• T_max (int, optional) – Maximum temperature value for color scale normalization (default is 100).

• pl ({'all', 'T', 'EV', 'ND', 'CHI2', 'N_UNIQUE'}, optional) – Type of plot to generate (default is ‘all’): - ‘all’: plot all available types - ‘T’: temperature field only - ‘EV’: evidence field only - ‘ND’: number of data points only - ‘CHI2’: reduced chi-squared (goodness of fit) only - ‘N_UNIQUE’: number of unique realizations per location

• hardcopy (bool, optional) – Save plots as PNG files with descriptive names (default is False).

• **kwargs (dict) – Additional keyword arguments: - s : int, marker size (default is 1) - plot_data_locations : bool, plot black background dots at all data locations (default is False) - CHI2_min : float, minimum CHI2 color scale value (default is 0) - CHI2_max : float, maximum CHI2 color scale value (default is 5) - N_UNIQUE_min : float, minimum N_UNIQUE color scale value (default is auto) - N_UNIQUE_max : float, maximum N_UNIQUE color scale value (default is auto) - Other matplotlib scatter parameters

Returns:

Function creates and displays plots but does not return values.

Return type:

None

Notes

Temperature values are displayed on log10 scale. Evidence values are clamped to reasonable ranges (1st to 99th percentile) for better visualization. The number of data plot shows non-NaN data count per location.

CHI2 color scale is fixed to [0, 5] by default for consistent comparison across different datasets. Values can be overridden via kwargs.

N_UNIQUE shows the number of unique realizations accepted at each location. This indicates the diversity of accepted models. If N_UNIQUE is not available, run integrate_posterior_stats() first to compute it.

integrate.integrate_plot.plot_boreholes(W, f_prior_h5=None, Mstr='/M2', hardcopy=False, **kwargs)

Plot borehole data as 1-D lithology sticks, one subplot per borehole.

Parameters:

• W (dict, list of dict, or str) –

  Borehole data in one of three forms:

  • A single borehole dict (keys: name, X, Y, depth_top, depth_bottom, class_obs, class_prob, and optionally elevation).

  • A list of such dicts.

  • A path to a JSON file written by write_borehole().

  If any borehole dict contains a non-zero elevation key (float, metres above sea level), the function switches to elevation mode: the shared Y-axis shows absolute elevation instead of depth, and every borehole is vertically positioned at its ground-surface elevation. Boreholes without an elevation key (or with elevation=0) are treated as if they sit at elevation 0 m a.s.l.

• f_prior_h5 (str, optional) – Path to an HDF5 prior file. When supplied, class names and the RGB colormap stored on Mstr are used to colour and label the lithology intervals. When omitted, a default 'tab10' colormap is used and classes are labelled by their numeric ID.

• Mstr (str, optional) – HDF5 dataset key that holds the discrete lithology model in f_prior_h5 (default '/M2'). Must point to a dataset with is_discrete == 1 and class_id / class_name attributes.

• hardcopy (bool, optional) – Save the figure to a PNG file. Default is False.

• **kwargs –

  figsizetuple, optional

  Figure size per subplot column, e.g. (2, 8). Default is (2, 8) per well.

  showInfoint, optional

  Verbosity level. Default 0.

  namestr, optional

  Base name for the saved PNG (without extension). Default is 'boreholes'.

  depth_maxfloat, optional

  Maximum depth shown on y-axis. Defaults to the deepest depth_bottom value across all boreholes.

  titlestr, optional

  Overall figure title.

Returns:

fig

Return type:

matplotlib.figure.Figure

Examples

>>> ig.plot_boreholes(BHOLES)
>>> ig.plot_boreholes(BHOLES, f_prior_h5='PRIOR.h5')
>>> ig.plot_boreholes('all_boreholes.json', f_prior_h5='PRIOR.h5')

integrate.integrate_plot.plot_cumulative_probability_profile(P_hypothesis, i1=0, i2=0, label=None, colors=None, hardcopy=True, name='cumulative_probability_profile')

Plot the cumulative probability profile of different hypotheses.

This function visualizes how the probability of different hypotheses accumulates over a sequence of data points, with each hypothesis represented as a colored area in a stacked plot.

Parameters:

• P_hypothesis (numpy.ndarray) – A 2D array where each row represents a hypothesis and each column represents a data point. Values should be probabilities

• i1 (int, optional) – Starting index for the x-axis (data points)

• i2 (int, optional) – Ending index for the x-axis (data points). If 0, uses the number of data points in P_hypothesis

• label (list of str, optional) – List of labels for each hypothesis. If None, generic labels will be created

• colors (list or numpy.ndarray, optional) – List of colors for each hypothesis. If None, colors from the ‘hot’ colormap will be used

• hardcopy (bool, optional) – If True, saves the figure to a file

• name (str, optional) – Base name for the output file when hardcopy is True

Returns:

None (displays the plot and optionally saves it to a file)

Return type:

None

Note

The plot shows how probabilities accumulate across hypotheses, with each hypothesis represented as a colored band. The total height of all bands at any x position equals 1.0 (or the sum of probabilities for that data point).

integrate.integrate_plot.plot_data(f_data_h5, i_plot=[], Dkey=[], plType='imshow', uselog=True, **kwargs)

Plot observational data from an HDF5 file.

This function creates visualizations of electromagnetic data including time-series plots, 2D image displays, and other data representations. Supports multiple data types and plotting styles for comprehensive data analysis.

Parameters:

• f_data_h5 (str) – Path to the HDF5 file containing observational data

• i_plot (list or array-like, optional) – Indices of data points to plot. If empty, plots all available data

• Dkey (str or list, optional) – Data keys/identifiers to plot. If empty, uses all available datasets

• plType (str, optional) – Plotting method - ‘imshow’ for 2D image display, ‘plot’ for line plots

• uselog (bool, optional) – Apply logarithmic scaling to data visualization (default is True)

• kwargs (dict) – Additional plotting arguments including hardcopy, figsize, colormap options

Returns:

None (creates matplotlib plots)

Return type:

None

Note

The function automatically handles different data formats and creates appropriate visualizations based on data dimensions and type. Supports saving plots to file when hardcopy=True is specified in kwargs.

Raises:

None

integrate.integrate_plot.plot_data_prior(f_prior_data_h5, f_data_h5, nr=1000, id=1, id_data=None, d_str='d_obs', alpha=0.5, ylim=None, **kwargs)

Compare observed data with prior model predictions.

Creates a logarithmic plot showing prior data realizations (model predictions) overlaid with observed data. Useful for validating forward models and assessing prior-data compatibility before inversion.

Parameters:

• f_prior_data_h5 (str) – Path to the HDF5 file containing prior data realizations from forward modeling.

• f_data_h5 (str) – Path to the HDF5 file containing observed data.

• nr (int, optional) – Maximum number of prior realizations to plot (default is 1000).

• id (int, optional) – Data set identifier for prior data (default is 1).

• id_data (int, optional) – Data set identifier for observed data. If None, uses same as id (default is None).

• d_str (str, optional) – Data array key within the dataset (default is ‘d_obs’).

• alpha (float, optional) – Transparency level for prior realization lines, range 0-1 (default is 0.5).

• ylim (tuple or list, optional) – Y-axis limits as (ymin, ymax). If None, uses automatic scaling (default is None).

• **kwargs (dict) – Additional keyword arguments: - hardcopy : bool, save plot as PNG file (default True)

Returns:

True if plotting was successful.

Return type:

bool

Notes

Prior realizations are plotted as thin black lines with specified transparency. Observed data is plotted as thin red lines. The number of plotted realizations is limited by both the nr parameter and available data. Random sampling is used when more realizations are available than requested.

integrate.integrate_plot.plot_data_prior_post(f_post_h5, i_plot=-1, nr=200, id=0, ylim=None, Dkey=[], **kwargs)

Compare prior predictions, posterior predictions, and observed data.

Creates logarithmic plots showing the evolution from prior to posterior predictions compared to observed data. Displays data fit quality and sampling results with temperature and evidence information.

Parameters:

• f_post_h5 (str) – Path to the HDF5 file containing posterior sampling results.

• i_plot (int, optional) – Index of specific observation to plot. If -1, plots random selection of data points (default is -1).

• nr (int, optional) – Maximum number of realizations to plot for each type (default is 200).

• id (int or list of int, optional) – Data set identifier(s) to plot. If 0, plots all available datasets. If list, plots each dataset separately (default is 0).

• ylim (tuple or list, optional) – Y-axis limits as (ymin, ymax). If None, uses automatic scaling (default is None).

• Dkey (list or str, optional) – Explicit data key specification. If empty, automatically detects available datasets (default is []).

• showInfo (int, optional) – Level of debug output (0=none, >0=verbose).

• is_log (bool, optional) – Use linear instead of logarithmic y-axis (default False).

• hardcopy (bool, optional) – Save plot as PNG file (default False).

• title (str, optional) – Custom title for the plot. If not provided, uses default format 'Data set {Dkey}, Observation # {i_plot+1}'.

Returns:

Function creates and displays plots but does not return values.

Return type:

None

Notes

The plot shows three data types: - Prior realizations (wheat/gray lines): model predictions before inversion - Posterior realizations (black lines): model predictions after inversion - Observed data (red dots with error bars): actual measurements

For specific observations (i_plot >= 0), temperature and log evidence values are displayed. Random subsets are used when more realizations are available than requested.

integrate.integrate_plot.plot_data_xy(f_data_h5, Dkey='D1', data_key='d_obs', data_channel=0, uselog=False, clim=[], **kwargs)

Create 2D spatial plot of actual data values from electromagnetic surveys.

Generates a scatter plot showing the spatial distribution of survey data with color-coding based on actual measured values. Useful for visualizing data distribution and identifying spatial patterns.

Parameters:

• f_data_h5 (str) – Path to the HDF5 file containing observational data.

• Dkey (str, optional) – Data group identifier to plot (e.g., ‘D1’, ‘D2’, default is ‘D1’).

• data_key (str, optional) – Data dataset to plot within the group (default is ‘d_obs’). Options: ‘d_obs’, ‘d_std’, or other datasets in the data group.

• data_channel (int, optional) – Channel/gate number to plot for multi-channel data (default is 0). For data of shape [N_stations, N_channels], selects which channel to display.

• uselog (bool, optional) – Apply logarithmic scaling to the colorbar (default is False).

• clim (list, optional) – Color scale limits as [min, max]. If empty list, uses automatic limits (default is []).

• **kwargs (dict) – Additional keyword arguments: - hardcopy : bool, save plot as PNG file (default False) - s : int, marker size for scatter plot (default 20) - cmap : str, colormap name (default ‘viridis’)

Returns:

The matplotlib figure object containing the plot.

Return type:

matplotlib.figure.Figure

Notes

Coordinates are automatically scaled to kilometers for better readability. The plot uses equal aspect ratio and includes grid lines. For multi-channel data, only the specified channel is displayed. Figure size is automatically adjusted based on the aspect ratio of the survey area.

integrate.integrate_plot.plot_feature_2d(f_post_h5, key='', i1=1, i2=1000000000.0, im=1, iz=0, elevation=None, ic=None, uselog=1, title=None, hardcopy=False, cmap=None, clim=None, **kwargs)

Create 2D spatial scatter plot of model parameter features.

Generates a 2D scatter plot showing the spatial distribution of a specific model parameter feature from posterior sampling results. Supports both continuous and discrete parameters with appropriate colormaps and scaling. For discrete model parameters (e.g., geological units), displays class names on the colorbar when plotting Mode or other discrete statistics.

Parameters:

• f_post_h5 (str) – Path to the HDF5 file containing posterior sampling results.

• key (str, optional) –

  Dataset key within the model group to plot. If empty string, automatically selects ‘Median’ for continuous parameters or ‘Mode’ for discrete parameters (default is ‘’).

  Continuous parameters: ‘Mean’, ‘Median’, ‘Std’

  Discrete parameters: ‘Mode’, ‘P’ (probability), ‘Entropy’

• i1 (int, optional) – Starting data point index for plotting (1-based indexing, default is 1).

• i2 (float, optional) – Ending data point index for plotting. If larger than data size, uses all available data (default is 1e+9).

• im (int, optional) – Model index to plot from (e.g., 1 for M1, 2 for M2, default is 1).

• iz (int, optional) – Feature/layer index within the model parameter array (default is 0). Ignored if elevation is specified.

• elevation (float, optional) – Absolute elevation in meters at which to extract and plot the feature. If provided, extracts values at this elevation using interpolation instead of using layer index iz (default is None).

• ic (int, optional) – Class index for probability extraction when key=’P’. Required when plotting probabilities at a specific elevation or layer. If not provided, defaults to 0 (first class) when needed (default is None).

• uselog (int, optional) – Apply logarithmic normalization to color scale (1=True, 0=False, default is 1). Automatically disabled for discrete statistics (Mode, P, Entropy).

• title (str, optional) – Custom plot title. If None, auto-generates descriptive title (default is None).

• hardcopy (bool, optional) – Save the plot as a PNG file with auto-generated filename (default is False).

• cmap (str or None, optional) – Colormap specification (e.g., ‘viridis’, ‘magma_r’, ‘RdYlBu’). If None, uses colormap from prior file for discrete parameters or default ‘resistivity’ colormap for continuous parameters (default is None). When explicitly provided, overrides discrete colormap from prior file.

• clim (list or None, optional) – Color scale limits as [min, max]. If None, uses automatic limits (default is None). For discrete parameters, automatically set to span all class IDs unless explicitly provided. When explicitly provided, disables discrete colorbar with class labels.

• **kwargs (dict) –

  Additional keyword arguments:

  • plotPoints (bool): If True, overlay small black dots at each data point location (default is False). Useful for showing data coverage.

  • showInfo (int): Debug output level (0=none, 1=basic, 2=verbose, default is 0).

  • s (float): Marker size for scatter plot (default is 1).

  • Other matplotlib scatter() parameters.

Returns:

Function creates and displays the plot but does not return a value.

Return type:

None

Notes

Automatic Parameter Type Detection

The function automatically detects whether the model parameter is discrete (e.g., geological unit classifications) or continuous (e.g., resistivity).

Discrete Parameters:

• Uses discrete colormap from prior file (unless user provides cmap)

• Creates colorbar with class names instead of numeric values (unless user provides clim)

• Applies linear scaling (logarithmic scaling is disabled)

• Inverts colorbar axis to match standard conventions

Class information is retrieved from prior file attributes: ‘class_id’, ‘class_name’, and ‘cmap’.

Continuous Parameters:

• Uses standard colormaps (resistivity, viridis, etc.)

• Logarithmic scaling by default (disable with uselog=0)

• Continuous colorbar with numeric values

Elevation vs Layer Modes:

When elevation is specified:

• Uses extract_feature_at_elevation() to interpolate values at that elevation

• Works with all keys including ‘P’ (probability)

• For key=’P’, the ic parameter specifies which class probability to plot

• Title shows elevation (e.g., “M2/Median[elev=40.0m]”)

When iz is specified (and elevation is None):

• Directly extracts values from layer iz

• For key=’P’, plots probability for class ic at layer iz

• Title shows layer index (e.g., “M1/Median[iz=5]”)

Colormap and Colorbar Control:

• Providing cmap overrides discrete colormap from prior file

• Providing clim disables discrete colorbar (useful for Entropy)

• This allows full customization of visualization

Examples

Continuous Parameters - Using Layer Index (iz)

Plot median resistivity at layer 5:

>>> import integrate as ig
>>> ig.plot_feature_2d('POST.h5', key='Median', im=1, iz=5)

Plot standard deviation at layer 3 with custom colormap:

>>> ig.plot_feature_2d('POST.h5', key='Std', im=1, iz=3,
...                     cmap='viridis', uselog=0)

Continuous Parameters - Using Elevation

Plot median resistivity at 40m elevation:

>>> ig.plot_feature_2d('POST.h5', key='Median', im=1, elevation=40)

Plot mean with data point overlay:

>>> ig.plot_feature_2d('POST.h5', key='Mean', im=1, elevation=25,
...                     plotPoints=True, hardcopy=True)

Discrete Parameters - Using Layer Index (iz)

Plot most probable class (Mode) at layer 3:

>>> ig.plot_feature_2d('POST.h5', key='Mode', im=2, iz=3)

Plot probability of class 2 at layer 4:

>>> ig.plot_feature_2d('POST.h5', key='P', im=2, iz=4, ic=2)

Plot entropy (uncertainty) at layer 2:

>>> ig.plot_feature_2d('POST.h5', key='Entropy', im=2, iz=2)

Discrete Parameters - Using Elevation

Plot Mode at 30m elevation:

>>> ig.plot_feature_2d('POST.h5', key='Mode', im=2, elevation=30)

Plot probability of class 7 at -30m elevation with custom colormap:

>>> ig.plot_feature_2d('POST.h5', key='P', im=2, elevation=-30, ic=7,
...                     cmap='magma_r', clim=[0, 1])

Plot Entropy with continuous colorbar (override discrete):

>>> ig.plot_feature_2d('POST.h5', key='Entropy', im=2, elevation=30,
...                     clim=[0, 2])

Advanced Usage

Plot subset of data with custom settings:

>>> ig.plot_feature_2d('POST.h5', key='Median', im=1, iz=5,
...                     i1=100, i2=500, uselog=0, cmap='RdYlBu',
...                     clim=[10, 100], plotPoints=True)

See also

extract_feature_at_elevation

Extract feature values at specific elevation

get_discrete_classes

Retrieve class IDs and names for discrete parameters

integrate.integrate_plot.plot_geometry(f_data_h5, i1=0, i2=0, ii=array([], dtype=float64), pl='ELEVATION', hardcopy=False, ax=None, **kwargs)

Plot survey geometry data from INTEGRATE HDF5 files.

Creates 2D scatter plots showing the spatial distribution of survey lines, elevation data, and data point indices. Useful for visualizing survey layout and data coverage.

Parameters:

• f_data_h5 (str) – Path to the HDF5 file containing geometry data. Can be either a data file or posterior file (function automatically detects and uses correct file).

• i1 (int, optional) – Starting index for data points to plot (0-based indexing, default is 0).

• i2 (int, optional) – Ending index for data points to plot. If 0, uses all available data (default is 0).

• ii (numpy.ndarray, optional) – Specific array of indices to plot. If provided, overrides i1 and i2 (default is empty array).

• pl ({'all', 'LINE', 'ELEVATION', 'id', 'NDATA'}, optional) – Type of geometry plot to generate (default is ‘all’): - ‘all’: plot all geometry types - ‘LINE’: survey line numbers only - ‘ELEVATION’: elevation data only - ‘id’: data point indices only - ‘NDATA’: number of valid (non-NaN) data points per location

• hardcopy (bool, optional) – Save plots as PNG files with descriptive names (default is False).

• ax (matplotlib.axes.Axes, optional) – Matplotlib axes object to plot on. If None, creates new figures (default is None).

• **kwargs (dict) – Additional keyword arguments passed to matplotlib scatter function.

• s (int, optional) – Size of scatter plot markers in points (default is 1).

• cmap (str or matplotlib.colors.Colormap, optional) – Colormap to use for color-coding the scatter plots (default is ‘jet’). Can be any valid matplotlib colormap name or colormap object.

Returns:

Function creates and displays plots but does not return values.

Return type:

None

Notes

The function automatically extracts geometry data (X, Y, LINE, ELEVATION) and creates equal-aspect plots with appropriate colorbars and grid lines. All data points are shown as light gray background with selected points highlighted.

integrate.integrate_plot.plot_post_stats(f_post_h5, i_plot=0, Mkey=[], nr=100, use_log=None, showInfo=0, **kwargs)

Visualize posterior model parameter distributions and sample realizations.

Creates comprehensive plots showing parameter histograms and spatial/temporal realizations for posterior model parameters at a specific data point. Similar to plot_prior_stats() but displays the posterior distribution (accepted samples) for a selected observation location.

Parameters:

• f_post_h5 (str) – Path to the HDF5 file containing posterior sampling results.

• i_plot (int, optional) – Data point index to visualize (0-based indexing, default is 0). This selects which observation’s posterior to display.

• Mkey (str or list, optional) – Model parameter key(s) to plot (e.g., ‘M1’, ‘M2’). If empty list, plots statistics for all available model parameters (default is []).

• nr (int, optional) – Maximum number of posterior realizations to display in realization plots. Actual number used is minimum of nr and available accepted samples (default is 100).

• use_log (bool or None, optional) – Whether to use log10 scale for both histogram and realizations plot. If None (default), automatically determines scale based on data range: - Discrete parameters: always linear - Continuous parameters: log if data spans > 2 orders of magnitude, else linear Set to True to force log10 scale, or False to force linear scale.

• showInfo (int, optional) – Verbosity level for diagnostic output. If > 0, prints data range and auto-selected scale choice (default is 0).

• hardcopy (bool, optional) – Save plots as PNG files (default True).

Returns:

Function creates and displays plots but does not return values.

Return type:

None

Notes

Creates a 1x3 subplot layout with custom width ratios.

For continuous parameters: left panel (width 1) shows a histogram of posterior samples, middle panel (width 1.5) shows posterior statistics vs depth (Mean, Median, ±1 Std, using pre-computed stats when available), and right panel (width 2) shows the accepted realizations.

For discrete parameters: left panel (width 1) shows a class distribution histogram, middle panel (width 2) shows class probabilities vs depth for the posterior, and right panel (width 3) shows categorical realizations.

The function reads i_use[i_plot, :] to get accepted sample indices from the posterior file, then retrieves corresponding realizations from the referenced prior file.

For continuous parameters, the histogram shows either log10(values) or linear values, and the realizations use corresponding LogNorm or linear colormap normalization.

The layout uses matplotlib GridSpec with width_ratios=[1, 1.5, 2] for continuous and [1, 2, 3] for discrete parameters.

Examples

>>> # Plot posterior for first data point, all models
>>> plot_post_stats('posterior.h5')
>>>
>>> # Plot posterior for data point 100, model M1
>>> plot_post_stats('posterior.h5', i_plot=100, Mkey='M1')
>>>
>>> # Force linear scale for continuous parameter
>>> plot_post_stats('posterior.h5', i_plot=50, Mkey='M1', use_log=False)

integrate.integrate_plot.plot_posterior_cumulative_thickness(f_post_h5, im=2, icat=[0], property='median', usePrior=False, **kwargs)

Plot posterior cumulative thickness for specified categories.

Creates a scatter plot showing the spatial distribution of cumulative thickness statistics (median, mean, standard deviation, or relative standard deviation) for selected geological categories from posterior sampling results.

Parameters:

• f_post_h5 (str) – Path to the HDF5 file containing posterior sampling results.

• im (int, optional) – Model index for thickness calculation (default is 2).

• icat (int or list of int, optional) – Category index or list of category indices to include in thickness calculation (default is [0]).

• property ({'median', 'mean', 'std', 'relstd'}, optional) – Statistical property to plot (default is ‘median’): - ‘median’: median thickness - ‘mean’: mean thickness - ‘std’: standard deviation of thickness - ‘relstd’: relative standard deviation (std/median)

• usePrior (bool, optional) – Whether to use prior data instead of posterior data (default is False).

• **kwargs (dict) – Additional keyword arguments: - hardcopy : bool, save plot as PNG file (default False) - s : float, scatter point size (default 10)

Returns:

The matplotlib figure object containing the plot.

Return type:

matplotlib.figure.Figure

Notes

The function calls ig.posterior_cumulative_thickness() to compute thickness statistics and creates a 2D scatter plot with equal aspect ratio and colorbar. Output files are saved with descriptive names when hardcopy=True.

integrate.integrate_plot.plot_prior_stats(f_prior_h5, Mkey=[], nr=100, use_log=None, showInfo=0, **kwargs)

Visualize prior model parameter distributions and sample realizations.

Creates comprehensive plots showing parameter histograms, logarithmic distributions, and spatial/temporal realizations for prior model parameters. Useful for validating prior distributions before inversion.

Parameters:

• f_prior_h5 (str) – Path to the HDF5 file containing prior model realizations.

• Mkey (str or list, optional) – Model parameter key(s) to plot (e.g., ‘M1’, ‘M2’). If empty list, plots statistics for all available model parameters (default is []).

• nr (int, optional) – Maximum number of realizations to display in realization plots. Actual number used is minimum of nr and available realizations (default is 100).

• use_log (bool or None, optional) – Whether to use log10 scale for both histogram and realizations plot. If None (default), automatically determines scale based on data range: - Discrete parameters: always linear - Continuous parameters: log if data spans > 2 orders of magnitude, else linear Set to True to force log10 scale, or False to force linear scale. For continuous parameters, this controls both the histogram bins (log10 values) and the color normalization in the realizations plot (LogNorm vs linear).

• showInfo (int, optional) – Verbosity level for diagnostic output. If > 0, prints data range and auto-selected scale choice (default is 0).

• hardcopy (bool, optional) – Save plots as PNG files (default True).

Returns:

Function creates and displays plots but does not return values.

Return type:

None

Notes

Creates a 1x3 subplot layout with custom width ratios.

For continuous parameters: left panel (width 1) shows a histogram, middle panel (width 1.5) shows statistics vs depth (Mean, Median, ±1 Std), and right panel (width 2) shows realizations with LogNorm or linear colormap.

For discrete parameters: left panel (width 1) shows a class distribution histogram, middle panel (width 2) shows class probabilities vs depth, and right panel (width 3) shows categorical realizations.

The use_log parameter controls log10 vs linear scaling for histogram bins and colormap normalization. When use_log=None, log scale is chosen automatically for continuous parameters spanning more than 2 orders of magnitude.

Automatic Scale Selection (when use_log=None): For continuous parameters, the function automatically chooses between log and linear scale based on the data range. Log scale is used if the data spans more than 2 orders of magnitude (e.g., 0.1 to 100 or larger), otherwise linear scale is used. This ensures appropriate visualization for both wide-range parameters (like resistivity) and narrow-range parameters (like thickness in meters).

Color limits and colormaps are automatically retrieved from file attributes. Multi-dimensional parameters show spatial patterns, while single parameters show temporal variation.

The layout uses matplotlib GridSpec with width_ratios=[1, 1.5, 2] for continuous and [1, 2, 3] for discrete parameters.

Examples

>>> # Plot with default (log10 for continuous, linear for discrete)
>>> plot_prior_stats('prior.h5', Mkey='M1')
>>>
>>> # Force linear scale for continuous parameter
>>> plot_prior_stats('prior.h5', Mkey='M1', use_log=False)
>>>
>>> # Force log scale
>>> plot_prior_stats('prior.h5', Mkey='M1', use_log=True)

integrate.integrate_plot.plot_profile(f_post_h5, i1=1, i2=1000000000.0, ii=array([], dtype=float64), im=0, xaxis='index', gap_threshold=None, panels=None, **kwargs)

Plot 1D profiles from posterior sampling results.

This function creates vertical profile plots showing the posterior distribution of model parameters as a function of depth or model layer. Automatically detects model type (discrete or continuous) and calls appropriate plotting function.

Parameters:

• f_post_h5 (str) – Path to the HDF5 file containing posterior sampling results.

• i1 (int, optional) – Starting index for the data points to plot (1-based indexing, default is 1).

• i2 (float, optional) – Ending index for the data points to plot (1-based indexing, default is 1e+9).

• ii (numpy.ndarray, optional) – Specific array of indices to plot. If provided, overrides i1 and i2 (default is empty array).

• im (int, optional) – Model identifier to plot. If 0, automatically detects and plots all models (default is 0).

• xaxis (str, optional) – X-axis type for plotting (default is ‘index’). Options: - ‘index’ : Sequential indices (0, 1, 2, …) - ‘id’ : Data point ID from the file - ‘x’ : X coordinate (easting) - ‘y’ : Y coordinate (northing)

• gap_threshold (float, optional) – Threshold for making large gaps transparent. If the distance between consecutive data points exceeds this value, the region becomes transparent. If None, no gap transparency is applied (default is None).

• panels (list of str or None, optional) –

  Controls which panels to display. Options depend on model type:

  For continuous models: [‘value’, ‘std’, ‘stats’] For discrete models: [‘mode’, ‘entropy’, ‘stats’]

  See plot_profile_continuous() and plot_profile_discrete() for detailed options (default is None, shows all panels).

• **kwargs (dict) – Additional plotting arguments passed to discrete/continuous plotting functions. Both model types support ‘alpha’ (float, 0.0-1.0) to apply uncertainty-based transparency to the main profile panel (median/mean for continuous, mode for discrete).

Returns:

Creates matplotlib plots.

Return type:

None

Notes

The function automatically computes posterior statistics if not present in the file. For discrete models, calls plot_profile_discrete(). For continuous models, calls plot_profile_continuous().

Examples

Plot all models with all panels:

>>> plot_profile(f_post_h5, im=0)

Plot only median resistivity for model 1:

>>> plot_profile(f_post_h5, im=1, panels=['value'])

Plot mode and stats for discrete model 2:

>>> plot_profile(f_post_h5, im=2, panels=['mode', 'stats'])

Plot discrete model with full uncertainty transparency on mode:

>>> plot_profile(f_post_h5, im=2, alpha=1.0)

Plot continuous model with partial transparency:

>>> plot_profile(f_post_h5, im=1, alpha=0.5)

Plot profile with X coordinates on x-axis:

>>> plot_profile(f_post_h5, im=1, xaxis='x')

Plot profile with Y coordinates on x-axis:

>>> plot_profile(f_post_h5, im=1, xaxis='y')

Plot profile with data IDs on x-axis:

>>> plot_profile(f_post_h5, im=1, xaxis='id')

integrate.integrate_plot.plot_profile_continuous(f_post_h5, i1=1, i2=1000000000.0, ii=array([], dtype=float64), im=1, xaxis='index', gap_threshold=None, panels=None, **kwargs)

Create vertical profile plots for continuous model parameters.

Generates a 4-panel plot showing continuous parameter distributions with depth, including mean/median values, standard deviation, and temperature/evidence curves. Supports transparency based on uncertainty for better visualization.

Parameters:

• f_post_h5 (str) – Path to the HDF5 file containing posterior sampling results.

• i1 (int, optional) – Starting data point index for profile plotting (1-based indexing, default is 1).

• i2 (float, optional) – Ending data point index for profile plotting. If larger than data size, uses all available data (default is 1e+9).

• ii (numpy.ndarray, optional) – Specific array of indices to plot. If provided, overrides i1 and i2 (default is empty array).

• im (int, optional) – Model index to plot (e.g., 1 for M1, 2 for M2, default is 1).

• xaxis (str, optional) – X-axis type for plotting (default is ‘id’). Options: - ‘index’ : Sequential indices (0, 1, 2, …) - ‘id’ : Data point ID from the file - ‘x’ : X coordinate (easting) - ‘y’ : Y coordinate (northing)

• gap_threshold (float, optional) – Threshold for making large gaps transparent. If the distance between consecutive data points exceeds this value, regions after the gaps become completely transparent to indicate missing data. If None, no gap transparency is applied (default is None).

• panels (list of str or None, optional) – Controls which panels to display. Each panel maintains consistent size regardless of which are shown. Options: - None (default): Show all panels [‘value’, ‘std’, ‘stats’] - [‘value’]: Only median/mean resistivity - [‘std’]: Only standard deviation - [‘stats’]: Only temperature and log-likelihood - Any combination of the above (e.g., [‘value’, ‘stats’]) Accepted panel names: ‘value’, ‘median’, ‘mean’, ‘std’, ‘uncertainty’, ‘stats’, ‘temperature’, ‘t’

• hardcopy (bool, optional) – Save plot as PNG file (default False).

• cmap (str or colormap, optional) – Color scheme for plotting (default 'jet').

• key (str, optional) – Statistic to plot, either 'Mean' or 'Median' (default 'Median').

• alpha (float, optional) – Transparency scaling factor based on normalized standard deviation (0.0=no transparency, default; 1.0=full uncertainty-based transparency).

• txt (str, optional) – Additional text for filename.

• showInfo (int, optional) – Level of debug output (0=none, >0=verbose).

• clim (list, optional) – Color scale limits [min, max].

• std_min (float, optional) – Minimum std for transparency normalization; values below render as fully opaque. Default is np.nanmin(Std).

• std_max (float, optional) – Maximum std for transparency normalization; values above render with maximum transparency. Default is 0.6 * np.nanmax(Std).

• show_n_unique (bool, optional) – If True, adds a plot of unique realizations in the stats panel (default False).

• plot_kl (bool, optional) – If True, plot KL divergence instead of standard deviation in the std panel. Falls back to Std if /Mx/KL does not exist (default False).

Returns:

Function creates and displays the plot but does not return values.

Return type:

None

Notes

The plot structure uses 3 subplots: ax[0] shows mean or median values (or a line plot with confidence bounds for single-parameter models), ax[1] shows standard deviation or KL divergence (hidden for single-parameter models), and ax[2] shows temperature and evidence curves.

Transparency can be applied based on uncertainty levels when alpha > 0. Depth coordinates are computed relative to surface elevation.

Examples

Show only median resistivity profile:

>>> plot_profile_continuous(f_post_h5, panels=['value'])

Show median with full uncertainty transparency (alpha=1.0):

>>> plot_profile_continuous(f_post_h5, panels=['value'], alpha=1.0)

Show median with partial transparency (alpha=0.5):

>>> plot_profile_continuous(f_post_h5, panels=['value'], alpha=0.5)

Show median and stats (no std):

>>> plot_profile_continuous(f_post_h5, panels=['value', 'stats'])

Show only standard deviation:

>>> plot_profile_continuous(f_post_h5, panels=['std'])

integrate.integrate_plot.plot_profile_discrete(f_post_h5, i1=1, i2=1000000000.0, ii=array([], dtype=float64), im=1, xaxis='index', gap_threshold=None, panels=None, **kwargs)

Create vertical profile plots for discrete categorical model parameters.

Generates a 3-panel plot showing discrete model parameter distributions with depth, including mode, entropy, and temperature/evidence curves. Designed for geological unit classification results.

Parameters:

• f_post_h5 (str) – Path to the HDF5 file containing posterior sampling results.

• i1 (int, optional) – Starting data point index for profile plotting (1-based indexing, default is 1).

• i2 (float, optional) – Ending data point index for profile plotting. If larger than data size, uses all available data (default is 1e+9).

• ii (numpy.ndarray, optional) – Specific array of indices to plot. If provided, overrides i1 and i2 (default is empty array).

• im (int, optional) – Model index to plot (e.g., 1 for M1, 2 for M2, default is 1).

• xaxis (str, optional) – X-axis type for plotting (default is ‘index’). Options: - ‘index’ : Sequential indices (0, 1, 2, …) - ‘id’ : Data point ID from the file - ‘x’ : X coordinate (easting) - ‘y’ : Y coordinate (northing)

• gap_threshold (float, optional) – Threshold for making large gaps transparent. If the distance between consecutive data points exceeds this value, regions after the gaps become completely transparent to indicate missing data. If None, no gap transparency is applied (default is None).

• panels (list of str or None, optional) –

  Controls which panels to display. Each panel maintains consistent size regardless of which are shown. Options: - None (default): Show all panels [‘mode’, ‘entropy’, ‘stats’] - [‘mode’]: Only mode (most probable class) - [‘entropy’]: Only entropy (uncertainty) - [‘stats’]: Only temperature and log-likelihood - Any combination of the above (e.g., [‘mode’, ‘stats’]) Accepted panel names: ‘mode’, ‘entropy’, ‘stats’, ‘temperature’, ‘t’

  Note: The stats panel optionally shows the number of unique realizations when show_n_unique=True is passed in kwargs.

• alpha (float, optional) – Transparency scaling factor based on entropy (0.0=no transparency, default; 1.0=full entropy-based transparency where high-uncertainty regions become transparent).

• entropy_min (float, optional) – Minimum entropy for transparency scaling; values below are fully opaque. Default is np.nanmin(Entropy) from the data.

• entropy_max (float, optional) – Maximum entropy for transparency scaling; values above reach maximum transparency. Default is 0.6 * np.nanmax(Entropy).

• hardcopy (bool, optional) – Save plot as PNG file (default False).

• txt (str, optional) – Additional text for filename.

• showInfo (int, optional) – Level of debug output (0=none, >0=verbose).

• show_n_unique (bool, optional) – If True, adds a plot of the number of unique realizations in the stats panel, sharing the temperature y-axis (default False).

• clim (list, optional) – Color scale limits for discrete classes.

• plot_kl (bool, optional) – If True, plot KL divergence instead of entropy in the entropy panel. KL is plotted only if the /Mx/KL dataset exists; otherwise entropy is used as fallback (default False).

Returns:

Function creates and displays the plot but does not return values.

Return type:

None

Notes

The plot structure uses 3 subplots: ax[0] shows the mode (most probable class, optionally with entropy-based transparency), ax[1] shows entropy (0=certain, 1=maximum uncertainty), and ax[2] shows temperature and evidence curves.

Class names and colors are automatically retrieved from prior file attributes. Depth coordinates are computed relative to surface elevation.

When alpha > 0, the mode panel shows both classification and uncertainty in one view: solid colors indicate high certainty, transparent colors indicate high uncertainty. The alpha value (0.0 to 1.0) controls the strength of this transparency effect.

Examples

Show only mode profile:

>>> plot_profile_discrete(f_post_h5, panels=['mode'])

Show mode with full uncertainty transparency (alpha=1.0):

>>> plot_profile_discrete(f_post_h5, panels=['mode'], alpha=1.0)

Show mode with partial transparency (alpha=0.5):

>>> plot_profile_discrete(f_post_h5, panels=['mode'], alpha=0.5)

Show mode and stats (no entropy):

>>> plot_profile_discrete(f_post_h5, panels=['mode', 'stats'])

Show only entropy:

>>> plot_profile_discrete(f_post_h5, panels=['entropy'])

Show all panels with transparency on mode:

>>> plot_profile_discrete(f_post_h5, alpha=1.0)

Show mode with custom entropy range for transparency:

>>> plot_profile_discrete(f_post_h5, alpha=0.8, entropy_min=0.1, entropy_max=0.7)

integrate.integrate_plot.setup_matplotlib_backend()

Configure matplotlib to use an interactive backend if available.

This function automatically detects the environment and configures matplotlib to use an appropriate backend for displaying plots:

• In Jupyter notebooks: Does nothing (notebooks handle backend automatically)

• In regular Python scripts: Tries to use TkAgg, Qt5Agg, or GTK3Agg

• Falls back to Agg if no GUI backend available

Safe to call in both scripts and notebooks. Specifically designed for WSL with WSLg support where GUI applications work but matplotlib may default to non-interactive backends.

Examples

>>> import integrate as ig
>>> ig.setup_matplotlib_backend()  # Call before importing matplotlib.pyplot
>>> import matplotlib.pyplot as plt

Notes

Call this function before importing matplotlib.pyplot to ensure the backend is configured correctly. If called in a Jupyter notebook, it will detect this and do nothing, allowing the notebook to use its built-in backends.

If no interactive backend is available (e.g., tkinter not installed), the function will print a warning and fall back to the Agg backend (file-only). To install tkinter on Ubuntu/Debian: sudo apt-get install python3-tk