Multi-Panel Logs

The multi_fig() function allows you to plot multiple stratigraphic logs in a single figure, each on its own axis, with a shared legend. This is ideal for comparing several logs side-by-side or in a grid, while maintaining individual axes and full customisation for each log. You can provide your own matplotlib figure and axes, or let multi_fig() create them automatically, control whether the logs share y-axes or have independent y-axes, and use all the same legend customisation options as for single logs.

Parameters

Required:

  • files A list (or other iterable) of file paths to your stratigraphic data files. Each file will be loaded and plotted as a separate log.

Optional:

  • nrows and ncols The number of rows and columns of axes to create for the logs. By default, a single row of axes is created. You can specify both nrows and ncols to create a custom grid layout (e.g., nrows=2, ncols=3 for a 2x3 grid).

  • sharey and sharex If True, all logs will share the same y-axis and/or x-axis limits. This is useful for directly comparing logs on the same scale. By default, each log has its own independent axes.

  • fig and axes You can provide your own matplotlib figure and axes to use for the logs. If not provided, they will be created automatically based on nrows and ncols.

  • fig_kwargs A dictionary of keyword arguments to pass to matplotlib’s plt.subplots() function when creating the figure and axes. This allows you to control the overall figure size, layout, and other properties.

  • **kwargs Any additional keyword arguments are passed directly to the LogObject.plot() method or sp.load() function for each log (see stratapy.core.LogObject.plot() or stratapy.core.load() for full details). This allows you to control all aspects of the plot, such as display mode, legend options, font size, figure size, and more.

Examples

Providing a list of files will automatically create a row of figures with a shared legend.

Here we call the returned item panel instead of log since it contains multiple logs. See below for details on the return value and its methods.

files = ['examples.multi_log_1.csv', 'examples.multi_log_2.csv', 'examples.multi_log_3.csv', 'examples.multi_log_4.csv', 'examples.multi_log_5.csv', 'examples.multi_log_6.csv']

# Call multi_fig and adjust the figure size and legend options by passing parameters which are usually passed to LogObject.plot() or sp.load()
panel = sp.multi_fig(files, figsize=(24, 6), legend_loc='bottom', legend_columns=4)

# Optionally save the figure
panel.save('my_figure.png')
Example of using multi_fig to plot multiple logs in a single figure

We can also tell the function to create a custom layout of axes, for example a 2x3 grid instead of a single row.

files = ['examples.multi_log_1.csv', 'examples.multi_log_2.csv', 'examples.multi_log_3.csv', 'examples.multi_log_4.csv', 'examples.multi_log_5.csv', 'examples.multi_log_6.csv']

# Request a 2x3 grid of axes, and adjust the figure size accordingly
panel = sp.multi_fig(files, nrows=2, ncols=3, figsize=(16, 22))
Controlling the layout of multiple logs using multi_fig

We can also set all logs to share the same x- and y-axis limits, useful for comparing logs directly against one other.

Here we also use the ‘grainsize’ display mode and ‘merge’ feature mode to show how all formatting and style options are inherited from LogObject.plot().

files = ['examples.multi_log_1.csv', 'examples.multi_log_2.csv', 'examples.multi_log_3.csv', 'examples.multi_log_4.csv', 'examples.multi_log_5.csv', 'examples.multi_log_6.csv']

# Here we use a 2x3 grid, with shared x- and y-axes, as well as use the 'grainsize' display mode
panel = sp.multi_fig(files, nrows=2, ncols=3, figsize=(16, 22), sharey=True, sharex=True, display_mode='grainsize', feature_mode='merge')
Using multi_fig to create multiple logs with shared axes

Tip

This function automatically provides a legend to encompass all logs, however, if you need more control over the legend or multi-figure plots, you can also use the stratapy.core.standalone_legend() function to create a standalone legend, or set legend=False in multi_fig() to prevent a legend from being created.

Return Value & Methods

multi_fig() returns a MultiLogObject instance, which contains the figure, axes, logs, and legend, as well as a convenient .save() method to save the figure to a file:

  • fig: The matplotlib figure object

  • axes: List of axes for each log

  • logs: List of LogObject instances for each log

  • leg: The legend object.

You can call .save(filename) on the returned object to save the figure.

panel = sp.multi_fig(files)
panel.save('my_multi_log_figure.png')

Special Notes and Quirks

  • The number of files must be less than or equal to the number of axes created (either automatically or provided by the user). If there are more axes than files, the extra axes will not be displayed.

  • All logs must have the same y-axis mode (e.g., all in age, all in depth, or all in height).

  • The legend is shared and automatically includes all relevant entries from all logs.

  • All formatting and style options are inherited from LogObject.plot() or sp.load() and can be passed directly to multi_fig() for convenience.