LogObject Methods

This page details the methods available for the LogObject class which is created following a call to stratapy.core.load().

stratapy.core.LogObject.plot(self, fig=None, ax=None, display_mode='default', feature_mode=None, unit_borders=True, legend_loc='right', legend_columns=1, legend_border=True, figsize=None, dpi=150, ppi=400, x_label='', x_axis=True, y_label=None, y_axis_unit='', spines=False, mineral_size=1, feature_size=1, xmax=None, legend_titles=['Lithologies', 'Minerals', 'Sedimentary Structures', 'Palaeontological Features', 'Tectonic Structures', 'Bed Contacts', 'Sample Indicators'], legend=True, legend_kwargs={}) → tuple

Creates a stratigraphic plot based on the loaded data and specified parameters.

No arguments are required to run this function, but has many optional parameters for customisation including figure size, resolution, legend location, and more - see the documentation for more details.

Parameters:

  • fig (matplotlib.figure.Figure, optional) – The figure object to plot on. If None, a new figure will be created. (Both a fig and ax must be provided to use a pre-existing figure and axes.)

  • ax (matplotlib.axes.Axes, optional) – The axes object to plot on. If None, a new axes will be created. (Both a fig and ax must be provided to use a pre-existing figure and axes.)

  • display_mode (str, optional) – The display mode for the plot. Options are ‘default’, ‘grainsize’, ‘log’. ‘default’ fills in each unit with the pattern or fill, ‘column’ creates a column of filled rectangles, with the rest of each unit only having its outline shown, ‘log’ only shows a rectangle for each unit, ignoring grain sizes completely. Default is ‘default’.

  • feature_mode (str, optional) – How features, minerals and lenses are displayed on the plot. Options are ‘deafult’, ‘semi-merge’, ‘merge’ or ‘off’. ‘default’ displays all features, minerals, and lenses in a column on the right of the log, while ‘semi-merge’ displays features in that column, but minerals and lenses are shown within a units lithology. ‘merge’ displays all features, minerals, and lenses within the units lithology. Default is ‘default’. ‘off’ can be used when no features, minerals, or lenses are to be displayed in the log itself, but they are wanted in the legend. Note: if display_mode is set to ‘log’, feature_mode changes to ‘merge’ unless ‘default’ or another mode is explicitly provided.

  • unit_borders (bool, optional) – If True, borders will be drawn around each unit in the log. Default is True.

  • legend_loc (str, optional) – The location of the legend in the plot: ‘top’, ‘bottom’, ‘right’, ‘left’. Default is ‘right’.

  • legend_columns (int, optional) – The number of columns in the legend. Default is 1.

  • legend_border (bool, optional) – If True, a border will be drawn around the legend. Default is False.

  • figsize (tuple, optional) – The size of the figure in inches (width, height). Default is (10, 10). Does not include the legend. Ignored if fig is provided.

  • dpi (int, optional) – The resolution of the figure in dots per inch. Default is 150. Higher dpi values produce higher quality images but increase file size and rendering time. You may wish to use lower values (e.g. 100) when creating or fine-tuning figures, and increase this (e.g. 300-500) when saving the final figure for publication or other use.

  • ppi (int, optional) – The resolution of the image-based lithological patterns in units, in pixels per inch. Default is 400. A larger ppi will cause patterns to appear more zoomed out, and will increase the rendering time of the plot.

  • x_label (str, optional) – The label for the x-axis. Default is an empty string.

  • x_axis (bool, optional) – If False, the x-axis (ticks, labels, spine, grainsize brackets) will not be displayed. Default is True.

  • y_label (str, optional) – The label for the y-axis. Defaults to ‘Age’, ‘Depth’, or ‘Height’ depending on the input data. If set to an empty string (‘’), it will not display a label.

  • y_axis_unit (str, optional) – The unit for the y-axis. Default is an empty string which uses ‘Ma’ for age inputs and ‘m’ for height/depth inputs. If y_label is set to an empty string, this will not display a unit label.

  • spines (bool, optional) – If True, upper and right spines will be shown on the plot. Default is False.

  • mineral_size (float, optional) – Scaling factor for the size of mineral symbols in the plot. Default is 1.

  • feature_size (float, optional) – Scaling factor for the size of features in the plot. Default is 1.

  • legend_titles (list, optional) – The titles for the legend sections. Default is [‘Lithologies’, ‘Minerals’, ‘Structures’, ‘Fossils’, ‘Bed Contacts’]. Note: the order of display of the legend is fixed (lithologies, then minerals, etc.), only names can be changed.

  • legend_kwargs (dict, optional) – Additional keyword arguments to pass to the legend function, such as frameon, etc. Default is an empty dictionary. Note: this will be overriden by the legend_loc, legend_columns, and legend_border parameters, if they are provided.

  • legend (bool, optional) – If False, no legend will be displayed. Default is True. Note: the sp.standalone_legend() function can be used to create a separate legend figure if no legend is wanted on the main plot.

Return type:

None

Examples

>>> import stratapy as sp
>>> # Load data from a CSV file
>>> log = sp.load('path/to/your/data.csv')
>>> # Create the figure
>>> log.plot()
stratapy.core.LogObject.save(self, filename='./stratapy_output', transparent=False) → None

Saves the current figure to a file. The filename should include the desired file extension (e.g., .png, .jpg, .pdf, .svg). If no extension is provided, it defaults to .png.

Parameters:

  • filename (str, optional) – The name of the file to save the figure to. Default is ‘./stratapy_output.png’.

  • transparent (bool, optional) – If True, the background of the saved figure will be transparent. Default is False.

Return type:

None

Notes

Saving time increases with figure complexity and quality, so it is recommended to use a lower dpi (e.g., 100) during development and increase it (e.g., 300-500) for final figures. dpi is set when the plot() method of the individual logs is called.

Other matplotlib backends like ‘Cairo’ or ‘Agg’ can be used to speed up saving figures.

>>> from matplotlib import use
>>> use('Cairo')  # or use('Agg')

These may require additional installation of matplotlib dependencies, but can significantly reduce saving time for complex figures.

stratapy.core.LogObject.add_chronostratigraphy(self, ranks_to_display: list = [0, 1, 2, 3, 4, 5], width_ratio: float = 0.2, spacing: float = 0.02) → None

Creates a new axis to the left of the log, showing the chronostratigraphy of the stratigraphic column. Only works if the y-axis is set to ‘age’.

If a more customised chronostratigraphy is desired (for example on more complex subplot layouts, or on a depth/age-based log), you can manually call the sp.chronostratigraphy() function to add chronostratigraphy to a pre-existing axis. More information and examples of this can be found in the documentation.

Parameters:

  • ranks_to_display (array-like, optional) – A list of the ranks to display in the chronostratigraphy axis. Default is [0, 1, 2, 3, 4, 5], which corresponds to the six main ranks (e.g., Super-eonothem, Eonothem, Erathem, System, Series, Stage).

  • width_ratio (float, optional) – The width ratio between the chronostratigraphy axis and the main log axis. Default is 0.2.

  • spacing (float, optional) – The spacing between the chronostratigraphy axis and the main log axis, as a fraction of the main axis width. Default is 0.02 (2% of the main axis width).

Return type:

None

Notes

This method can only be called after the plot() method has been called, and only on logs with the y-axis set to ‘age’.

stratapy.core.LogObject.add_samples(self, samples: list = [], label: str = None, x: float = -0.25, scatter_kwargs={}) → None

Plots scatter points on a log at the desired x position, deafulting to the left of the y-axis.

Keyword arguments can be passed to the scatter function to customise the appearance of the points, such as color, marker style, and size.

This function is designed such that it can be called multiple times to add many points to the log under one legend entry, and repeated for different points, or it can be called separately for each point with a unique label to be explicitly added to the legend.

Parameters:

  • samples (list) – A list of y-values (numeric) to plot on the log.

  • label (str, optional) – The label for the sample points to be displayed in the legend. If None, the points will be plotted without a legend entry. Default is None.

  • x (float, optional) – The x-coordinate on the log where the samples will be plotted. Default is -0.25, which places them just to the left of the y-axis.

  • scatter_kwargs (dict, optional) – Additional keyword arguments to pass to ax.scatter, such as color, marker, s, etc. Default is an empty dictionary. Warning: no validation is performed, so an error will be returned if any kwargs are not valid for ax.scatter; see matplotlib.axes.Axes.scatter or examples below.

Return type:

None

Notes

Any scatter kwargs provided are passed directly to the ax.scatter() function without validation; ensure that the kwargs are valid for that function.

Examples

>>> # Another example with default scatter kwargs
>>> log.add_samples(samples=[-20, -15, -10, -5, 0, 5, 10])

This will plot black circles at the specified y-values on the left side of the log, using the default scatter appearance (black color, circle marker, size 5).

>>> # Assuming ``log`` has already been created and plotted
>>> log.add_samples(samples=[50, 53, 57.5], label='Rock Samples', scatter_kwargs={'color': 'red', 'marker': 'x', 's': 50})

This will plot red crosses at the specified y-values (50, 53, 57.5) on the left side of the log, with a size of 50, and add a similar marker to the ‘Sample Indicators’ section of the legend with the label ‘Rock Samples’.

stratapy.core.LogObject.add_twin_axis(self, offset: float = 0, limits=None, label='', spacing: float = 80) → None

Adds a secondary y-axis to the left of the existing axis with an offset applied or a custom axis range.

Parameters:

  • offset (float, optional) – The offset to apply to the y-axis limits; new axis will be plotted with this offset applied to the existing y-axis limits. Default is 0, which will not add a new axis.

  • limits (list, optional) – Instead of a fixed offset, the lower and upper limits of the new y-axis can be provided as a list of two numeric values [lower_limit, upper_limit]. Overrides the offset parameter, if both are provided.

  • ylabel (str, optional) – The label for the new y-axis. Default is blank (‘’).

  • spacing (float, optional) – The spacing between the new y-axis and the existing y-axis, in points. Default is 80. Enables more control over the positioning of the new twin axis.

Return type:

None

stratapy.core.LogObject.add_labels(self, labels: list, fontsize: float = 12, padding: float = 5) → None

Enables the user to provide a list of strings which will be displayed to the right of each unit - the length of the list must match the number of units.

Parameters:

  • labels (list) – Strings to be displayed next to each unit in the log.

  • fontsize (float, optional) – The font size of the labels. Default is 12.

  • padding (float, optional) – The padding between the labels and the units, as a percentage of the x-axis range. Default is 5 (5% of the x-axis range).

Return type:

None

Notes

Labels are plotted to the right of each unit, at the middle of the unit’s height. If the log is in ‘log’ display mode, labels are plotted to the right of the x-axis with padding applied.

Draws a triangle in the between two y-axis bounds on the log. By default, it will place the trend to the right of the log, but specifying an x-coordinate will place the triangle at that position instead (either a numeric value or an x-tick label).

Multiple triangles can be added by calling this method multiple times with different bounds.

Note, the xmax parameter in the plot() method can be used to add extra space between a log and the features column where trends can be fit in.

Parameters:

  • bounds (list) – A list of two numeric values representing the y-axis bounds between which the triangle will be drawn. The triangle will point from the first value to the second value.

  • x (float or str, optional) – The x-coordinate where the triangle will be placed. If a string is provided, it should match one of the x-tick labels in the log. If None, the triangle will be placed to the right of the grain size axis. Default is None.

  • triangle_type (str, optional) – The type of triangle to draw. Options are ‘isosceles’ or ‘right-angled’, or variations thereof. Default is ‘isosceles’.

  • fill_color (str, optional) – The fill color of the triangle. Default is ‘black’.

  • edge_color (str, optional) – The edge color of the triangle. Default is ‘black’.

  • linewidth (float, optional) – The line width of the triangle’s edge. Default is 1.0.

Return type:

None

Examples

>>> import stratapy as sp
>>> log = sp.load('./examples.sedimentary.csv')
>>> log.plot(xmax=7.5)
>>> log.add_trends([3,2.3], x=7.3)