striplog.striplog module#

A striplog is a sequence of intervals.

copyright

2019 Agile Geoscience

license

Apache 2.0

class striplog.striplog.Striplog(list_of_Intervals, source=None, order='auto')#

Bases: object

A Striplog is a sequence of intervals.

We will build them from LAS files or CSVs.

Parameters

  • list_of_Intervals (list) – A list of Interval objects.

  • source (str) – A source for the data. Default None.

  • order (str) – ‘auto’, ‘depth’, ‘elevation’, or ‘none’. Please refer to the documentation for details. Best idea is to let the default work. Default: ‘auto’.

anneal(mode='middle')#

Fill in empty intervals by growing from top and base.

Note that this operation happens in-place and destroys any information about the Position (e.g. metadata associated with the top or base). See GitHub issue #54.

If there are overlaps in your striplog, then this method may have unexpected results.

Args
mode (str): One of [‘down’, ‘middle’, ‘up’]. Which way to ‘flood’

into the gaps.

Returns

Striplog. A new instance of the Striplog class.

append(item)#

Implements list-like append() method.

bar(height='thickness', sort=False, reverse=False, legend=None, ax=None, figsize=None, **kwargs)#

Make a bar plot of thickness per interval.

Parameters

  • height (str) – The property of the primary component to plot.

  • sort (bool or function) – Either pass a boolean indicating whether to reverse sort by thickness, or pass a function to be used as the sort key.

  • reverse (bool) – Reverses the sort order.

  • legend (Legend) – The legend to plot with.

  • ax (axis) – Optional axis to plot to.

  • figsize (tuple) – A figure size, (width, height), optional.

  • **kwargs – passed to the matplotlib bar plot command, ax.bar().

Returns

If you sent an axis in, you get it back.

Return type

axis

binary_morphology(attr, operation, step=1.0, p=3)#

Perform a discrete binary morphology operation on the striplog.

Args
attr (str): The attribute to use for the filtering. Must have

boolean values.

operation (str): One of erosion, dilation, opening or

closing.

step (float): The step size to use in discretization. Default is

1 but you might want to use something smaller, e.g. 0.1.

p (int): The length of the structuring element, in samples (not

natual units). Odd numbers are symmetrical and more intuitive. Default is 3.

Returns

Striplog. A new striplog instance.

property components#

Property. Returns the list of compenents in the striplog.

Returns

List. A list of the unique components.

copy()#

Returns a shallow copy.

crop(extent, copy=False)#

Crop to a new depth range.

Parameters

  • extent (tuple) – The new start and stop depth. Must be ‘inside’ existing striplog.

  • copy (bool) – Whether to operate in place or make a copy.

Returns

Operates in place by deault; if copy is True, returns a striplog.

property cum#

Property. Gives the cumulative thickness of all filled intervals.

It would be nice to use sum() for this (by defining __radd__), but I quite like the ability to add striplogs and get a striplog and I don’t think we can have both, it’s too confusing.

Not calling it sum, because that’s a keyword.

Returns

Float. The cumulative thickness.

depth(d)#

For backwards compatibility.

extend(item)#

Implements list-like extend() method.

extract(log, basis, name, function=None)#

‘Extract’ a log into the components of a striplog.

Parameters

  • log (array_like) –

  • basis (array_like) –

  • name (str) –

  • function (function) – input, and returns whatever you want to store in the ‘name’ attribute of the primary component.

Returns

A copy of the striplog.

fill(component=None)#

Fill gaps with the component provided.

Example

t = s.fill(Component({‘lithology’: ‘cheese’}))

find(search_term, index=False)#

Look for a regex expression in the descriptions of the striplog. If there’s no description, it looks in the summaries.

If you pass a Component, then it will search the components, not the descriptions or summaries.

Case insensitive.

Parameters

  • search_term (string or Component) – The thing you want to search for. Strings are treated as regular expressions.

  • index (bool) – Whether to return the index instead of the interval.

Returns

A striplog that contains only the ‘hit’ Intervals.

However, if index was True, then that’s what you get.

Return type

Striplog

find_gaps(index=False)#

Finds gaps in a striplog.

Parameters

  • index (bool) – If True, returns indices of intervals with

  • them. (gaps after) –

Returns

A striplog of all the gaps. A sort of anti-striplog.

Return type

Striplog

find_overlaps(index=False)#

Find overlaps in a striplog.

Parameters

  • index (bool) – If True, returns indices of intervals with

  • them. (gaps after) –

Returns

A striplog of all the overlaps as intervals.

Return type

Striplog

classmethod from_canstrat(filename, source='canstrat')#

Eat a Canstrat DAT file and make a striplog.

classmethod from_csv(filename=None, text=None, dlm=',', lexicon=None, points=False, include=None, exclude=None, remap=None, function=None, null=None, ignore=None, source=None, stop=None, fieldnames=None)#

Load from a CSV file or text.

Args

filename (str): The filename, or use text. text (str): CSV data as a string, or use filename. dlm (str): The delimiter, default ‘,’. lexicon (Lexicon): The lexicon to use, optional. Only needed if parsing descriptions (e.g. cuttings). points (bool): Whether to make a point dataset (as opposed to ordinary intervals with top and base. Default is False. include: Default is None. exclude: Default is None. remap: Default is None. function: Default is None. null: Default is None. ignore: Default is None. source: Default is None. stop: Default is None. fieldnames: Default is None.

Returns

Striplog. A new instance.

classmethod from_descriptions(text, lexicon=None, source='CSV', dlm=',', points=False, abbreviations=False, complete=False, order='depth', columns=None)#
Convert a CSV string into a striplog. Expects 2 or 3 fields:

top, description OR top, base, description

Parameters

  • text (str) – The input text, given by well.other.

  • lexicon (Lexicon) – A lexicon, required to extract components.

  • source (str) – A source. Default: ‘CSV’.

  • dlm (str) – The delimiter, given by well.dlm. Default: ‘,’

  • points (bool) – Whether to treat as points or as intervals.

  • abbreviations (bool) – Whether to expand abbreviations in the description. Default: False.

  • complete (bool) – Whether to make ‘blank’ intervals, or just leave gaps. Default: False.

  • order (str) – The order, ‘depth’ or ‘elevation’. Default: ‘depth’.

  • columns (tuple or list) – The names of the columns.

Returns

A striplog object.

Return type

Striplog

Example

# TOP BOT LITH 312.34, 459.61, Sandstone 459.71, 589.61, Limestone 589.71, 827.50, Green shale 827.60, 1010.84, Fine sandstone

classmethod from_dict(dictionary)#

Take a dictionary of the form name:depth and return a striplog of complete intervals.

classmethod from_image(filename, start, stop, legend, source='Image', col_offset=0.1, row_offset=2, tolerance=0, background=None)#

Read an image and generate Striplog.

Parameters

  • filename (str) – An image file, preferably high-res PNG.

  • start (float or int) – The depth at the top of the image.

  • stop (float or int) – The depth at the bottom of the image.

  • legend (Legend) – A legend to look up the components in.

  • source (str) – A source for the data. Default: ‘Image’.

  • col_offset (Number) – The proportion of the way across the image from which to extract the pixel column. Default: 0.1 (ie 10%).

  • row_offset (int) – The number of pixels to skip at the top of each change in colour. Default: 2.

  • tolerance (float) – The Euclidean distance between hex colours, which has a maximum (black to white) of 441.67 in base 10. Default: 0.

  • background (array) – A background colour (as hex) to ignore.

Returns

The striplog object.

Return type

Striplog

classmethod from_img(*args, **kwargs)#

For backwards compatibility.

classmethod from_las3(string, lexicon=None, source='LAS', dlm=',', abbreviations=False)#

Turn LAS3 ‘lithology’ section into a Striplog.

Parameters

  • string (str) – A section from an LAS3 file.

  • lexicon (Lexicon) – The language for conversion to components.

  • source (str) – A source for the data.

  • dlm (str) – The delimiter.

  • abbreviations (bool) – Whether to expand abbreviations.

Returns

The striplog object.

Return type

Striplog

Note

Handles multiple ‘Data’ sections. It would be smarter for it to handle one at a time, and to deal with parsing the multiple sections in the Well object.

Does not read an actual LAS file. Use the Well object for that.

classmethod from_log(log, cutoff=None, components=None, legend=None, legend_field=None, field=None, right=False, basis=None, source='Log')#

Turn a 1D array into a striplog, given a cutoff.

Parameters

  • log (array-like) – A 1D array or a list of integers.

  • cutoff (number or array-like) – The log value(s) at which to bin the log. Optional.

  • components (array-like) – A list of components. Use this or legend.

  • legend (Legend) – A legend object. Use this or components.

  • legend_field ('str') – If you’re not trying to match against components, then you can match the log values to this field in the Decors.

  • field (str) – The field in the Interval’s data to store the log values as.

  • right (bool) – Which side of the cutoff to send things that are equal to, i.e. right on, the cutoff.

  • basis (array-like) – A depth basis for the log, so striplog knows where to put the boundaries.

  • source (str) – The source of the data. Default ‘Log’.

Returns

The striplog object.

Return type

Striplog

classmethod from_macrostrat(lng, lat, buffer_size=0.2)#
Create a striplog from components derived using the MacroStrat API.

This is simply a helper function to make things easier, but it works because we know what our data looks like in advance.

Note: In order to plot this, you will need to add space for text and

other decoration. This simply gives a Striplog back which _can_ be plotted.

Parameters

  • lng (float) – The longitude of the site.

  • lat (float) – The latitude of the site.

  • buffer_size (float) – The size of the buffer to use, in degrees.

Returns

Striplog. A new striplog instance.

Example

>>> lng = -64.3573186
>>> lat = 44.4454632
>>> buffer_size = 0.3
>>> striplog.striplog.from_macrostrat(lng, lat, buffer_size)
{'top': Position({'middle': 358.9, 'units': 'm'}),
    'base': Position({'middle': 419.2, 'units': 'm'}),
    'description': '', 'data': {}, 'components': [Component({
        'map_id': 948660.0, 'scale': 'small', 'source_id': 7.0,
        'name': 'Devonian plutonic: undivided granitic rocks',
        'age': 'devonian', 'lith': 'plutonic: undivided granitic rocks',
        'best_age_top': 358.9, 'best_age_bottom': 419.2, 't_int': 94.0,
        'b_int': 94.0, 'color': '#cb8c37', 'source': 'MacroStrat.org (CC-BY)})]}
{'top': Position({'middle': 358.9, 'units': 'm'}),
    'base': Position({'middle': 541.0, 'units': 'm'}),
    'description': '', 'data': {}, 'components': [Component({
        'map_id': 948228.0, 'scale': 'small', 'source_id': 7.0,
        'name': 'Cambrian-Devonian sedimentary', 'age': 'cambrian-devonian',
        'lith': 'sedimentary', 'best_age_top': 358.9, 'best_age_bottom': 541.0,
        't_int': 94.0, 'b_int': 122.0, 'color': '#99c08d',
        'source': 'MacroStrat.org (CC-BY)})]}
{'top': Position({'middle': 443.8, 'units': 'm'}),
    'base': Position({'middle': 541.0, 'units': 'm'}),
    'description': '', 'data': {}, 'components': [Component({
        'map_id': 973359.0, 'scale': 'small', 'source_id': 7.0,
        'name': 'Cambrian-Ordovician sedimentary', 'age': 'cambrian-ordovician',
        'lith': 'sedimentary', 'best_age_top': 443.8, 'best_age_bottom': 541.0,
        't_int': 112.0, 'b_int': 122.0, 'color': '#409963',
        'source': 'MacroStrat.org (CC-BY)})]}
classmethod from_petrel(filename, stop=None, points=False, null=None, function=None, include=None, exclude=None, remap=None, ignore=None)#

Makes a striplog from a Petrel text file.

Returns

striplog.

get_data(field, function=None, default=None)#

Get data from the striplog.

hist(lumping=None, summary=False, sort=True, plot=True, legend=None, ax=None, rotation=0, ha='center')#

Plots a histogram and returns the data for it.

Parameters

  • lumping (str) – If given, the bins will be lumped based on this attribute of the primary components of the intervals encountered.

  • summary (bool) – If True, the summaries of the components are returned as the bins. Otherwise, the default behaviour is to return the Components themselves.

  • sort (bool) – If True (default), the histogram is sorted by value, starting with the largest.

  • plot (bool) – If True (default), produce a bar plot.

  • legend (Legend) – The legend with which to colour the bars.

  • ax (axis) – An axis object, which will be returned if provided. If you don’t provide one, it will be created but not returned.

  • rotation (int) – The rotation angle of the x-axis tick labels. Default is 0 but -45 is useful.

  • ha (str) – The horizontal alignment of the x-axis tick labels. Default is ‘center’ but ‘left’ is good for -ve rotation.

Returns

A tuple of tuples of entities and counts.

Return type

Tuple

histogram(lumping=None, summary=False, sort=True, plot=True, legend=None, ax=None, rotation=0, ha='center')#

Plots a histogram and returns the data for it.

Parameters

  • lumping (str) – If given, the bins will be lumped based on this attribute of the primary components of the intervals encountered.

  • summary (bool) – If True, the summaries of the components are returned as the bins. Otherwise, the default behaviour is to return the Components themselves.

  • sort (bool) – If True (default), the histogram is sorted by value, starting with the largest.

  • plot (bool) – If True (default), produce a bar plot.

  • legend (Legend) – The legend with which to colour the bars.

  • ax (axis) – An axis object, which will be returned if provided. If you don’t provide one, it will be created but not returned.

  • rotation (int) – The rotation angle of the x-axis tick labels. Default is 0 but -45 is useful.

  • ha (str) – The horizontal alignment of the x-axis tick labels. Default is ‘center’ but ‘left’ is good for -ve rotation.

Returns

A tuple of tuples of entities and counts.

Return type

Tuple

insert(index, item)#
intersect(other)#

Makes a striplog of all intersections.

Parameters

with. (Striplog. The striplog instance to intersect) –

Returns

Striplog. The result of the intersection.

invert(copy=False)#

Inverts the striplog, changing its order and the order of its contents.

Operates in place by default.

Parameters

copy (bool) – Whether to operate in place or make a copy.

Returns

None if operating in-place, or an inverted copy of the striplog

if not.

is_binary(attr=None)#

Determine if attr, which must be an attribute of every primary component, allows this striplog to be interpreted as a binary striplog. If no attr is provided, the first attribute of the primary comp- onent is used.

max_field(field)#
property mean#

Property. Returns the mean thickness of all filled intervals.

Returns

Float. The mean average of interval thickness.

merge(attr, reverse=False)#

Merge the intervals in a striplog, using an attribute of the primary component for priority ordering.

Args

attr (str): The attribute of the component you want to use. You must provide an attribute. reverse (bool): Whether to reverse the condition.

Returns

Striplog: The merged striplog.

merge_neighbours(strict=True)#

Makes a new striplog in which matching neighbours (for which the components are the same) are unioned. That is, they are replaced by a new Interval with the same top as the uppermost and the same bottom as the lowermost.

Args
strict (bool): If True, then all of the components must match.

If False, then only the primary must match.

Returns

Striplog. A new striplog.

merge_overlaps()#

Merges overlaps by merging overlapping Intervals.

The function takes no arguments and returns None. It operates on the striplog ‘in place’

TODO: This function will not work if any interval overlaps more than

one other intervals at either its base or top.

net_to_gross(attr)#

Compute the ratio of intervals having that attribute as True to the total thickness.

TODO

Allow user to give a cut-off value to apply to the attribute, if it’s a continuous scalar and not boolean.

Args

attr (str): Which attribute to use. Must have boolean values.

Returns

float. The net:gross ratio.

next()#

For Python 2 compatibility.

plot(legend=None, width=1.5, ladder=True, aspect=10, ticks=(1, 10), match_only=None, ax=None, return_fig=False, colour=None, cmap='viridis', default=None, style='intervals', field=None, label=None, **kwargs)#

Hands-free plotting.

Parameters

  • legend (Legend) – The Legend to use for colours, etc.

  • width (int) – The width of the plot, in inches. Default 1.

  • ladder (bool) – Whether to use widths or not. Default True.

  • aspect (int) – The aspect ratio of the plot. Default 10.

  • ticks (int or tuple) – The (minor,major) tick interval for depth. Only the major interval is labeled. Default (1,10).

  • match_only (list) – A list of strings matching the attributes you want to compare when plotting.

  • ax (ax) – A maplotlib axis to plot onto. If you pass this, it will be returned. Optional.

  • return_fig (bool) – Whether or not to return the maplotlib fig object. Default False.

  • colour (str) – Which data field to use for colours.

  • cmap (cmap) – Matplotlib colourmap. Default viridis.

  • default (float) – The default (null) value.

  • style (str) – Can be ‘tops’, ‘points’ or ‘field’ for different types of plot. If you use ‘field’, give the name of the field as the field argument.

  • field (str) – The name of the field to use for the width parameter.

  • label (str) – Can be the name of a single Component attribute, or a format string with multiple attributes, like “{colour} {lithology}”.

  • patches.Rectangle. (**kwargs are passed through to matplotlib's) –

Returns

None. Unless you specify return_fig=True or pass in an ax.

plot_axis(ax, legend, ladder=False, default_width=1, match_only=None, colour=None, colour_function=None, cmap=None, default=None, width_field=None, **kwargs)#

Plotting, but only the Rectangles. You have to set up the figure. Returns a matplotlib axis object.

Parameters

  • ax (axis) – The matplotlib axis to plot into.

  • legend (Legend) – The Legend to use for colours, etc.

  • ladder (bool) – Whether to use widths or not. Default False.

  • default_width (int) – A width for the plot if not using widths. Default 1.

  • match_only (list) – A list of strings matching the attributes you want to compare when plotting.

  • colour (str) – Which data field to use for colours.

  • cmap (cmap) – Matplotlib colourmap. Default viridis.

  • default (float) – The default (null) value.

  • width_field (str) – The field to use for the width of the patches.

  • patches.Rectangle. (**kwargs are passed through to matplotlib's) –

Returns

The matplotlib.pyplot axis.

Return type

axis

plot_field(ax, legend=None, field=None, **kwargs)#

Plotting, but only for tops (as opposed to intervals).

plot_points(ax, legend=None, field=None, field_function=None, undefined=0, **kwargs)#

Plotting, but only for points (as opposed to intervals).

plot_tops(ax, legend=None, field=None, **kwargs)#

Plotting, but only for tops (as opposed to intervals).

pop(index)#

Implements list-like pop() method.

prune(limit=None, n=None, percentile=None, keep_ends=False)#

Remove intervals below a certain limit thickness. In place.

Parameters

  • limit (float) – Anything thinner than this will be pruned.

  • n (int) – The n thinnest beds will be pruned.

  • percentile (float) – The thinnest specified percentile will be pruned.

  • keep_ends (bool) – Whether to keep the first and last, regardless of whether they meet the pruning criteria.

quality(tests, alias=None)#

Run a series of tests and return the corresponding results.

Based on curve testing for welly.

Parameters

tests (list) – a list of functions.

Returns

list. The results. Stick to booleans (True = pass) or ints.

read_at(d, index=False)#
Get the index of the interval at a particular ‘depth’ (though this

might be an elevation or age or anything).

Parameters

  • d (Number) – The ‘depth’ to query.

  • index (bool) – Whether to return the index instead of the interval.

Returns

The interval, or if index==True the index of the

interval, at the specified ‘depth’, or None if the depth is outside the striplog’s range.

Return type

Interval

shift(delta=None, start=None)#

Shift all the intervals by delta (negative numbers are ‘up’) or by setting a new start depth.

Returns a copy of the striplog.

property start#

Property. The closest Position to the datum.

Returns

Position.

property stop#

Property. The furthest Position from the datum.

Returns

Position.

thickest(n=1, index=False)#

Returns the thickest interval(s) as a striplog.

Parameters

  • n (int) – The number of thickest intervals to return. Default: 1.

  • index (bool) – If True, only the indices of the intervals are returned. You can use this to index into the striplog.

Returns

Interval. The thickest interval. Or, if index was True, the index of the thickest interval.

thinnest(n=1, index=False)#

Returns the thinnest interval(s) as a striplog.

Parameters

  • n (int) – The number of thickest intervals to return. Default: 1.

  • index (bool) – If True, only the indices of the intervals are returned. You can use this to index into the striplog.

Returns

Interval. The thickest interval. Or, if index was True, the index of the thickest interval.

to_binary_log(attr, step)#

Adaptation of to_log but deals with binary attributes of striplogs.

Args

attr (str): Which attribute to make into a log.

to_canstrat(filename, params)#

Write a Canstrat ASCII file.

Parameters

  • filename (str) –

  • params (dict) – The well details. You can use a welly header object.

Returns:

to_csv(filename=None, as_text=True, use_descriptions=False, dlm=',', header=True)#

Returns a CSV string built from the summaries of the Intervals.

Parameters

  • use_descriptions (bool) – Whether to use descriptions instead of summaries, if available.

  • dlm (str) – The delimiter.

  • header (bool) – Whether to form a header row.

Returns

A string of comma-separated values.

Return type

str

to_flag(**kwargs)#

A wrapper for to_log() that returns a boolean array. Useful for masking. Has the same interface as to_log().

to_las3(use_descriptions=False, dlm=',', source='Striplog')#

Returns an LAS 3.0 section string.

Parameters

  • use_descriptions (bool) – Whether to use descriptions instead of summaries, if available.

  • dlm (str) – The delimiter.

  • source (str) – The sourse of the data.

Returns

A string forming Lithology section of an LAS3 file.

Return type

str

to_log(step=1.0, start=None, stop=None, basis=None, field=None, field_function=None, bins=True, dtype='float', table=None, sort_table=False, legend=None, legend_field=None, match_only=None, undefined=0, return_meta=False)#

Return a fully sampled log from a striplog. Useful for crossplotting with log data, for example.

Parameters

  • step (float) – The step size. Default: 1.0.

  • start (float) – The start depth of the new log. You will want to match the logs, so use the start depth from the LAS file. Default: The basis if provided, else the start of the striplog.

  • stop (float) – The stop depth of the new log. Use the stop depth of the LAS file. Default: The basis if provided, else the stop depth of the striplog.

  • field (str) – If you want the data to come from one of the attributes of the components in the striplog, provide it.

  • field_function (function) – Provide a function to apply to the field you are asking for. It’s up to you to make sure the function does what you want.

  • bins (bool) – Whether to return the index of the items from the lookup table. If False, then the item itself will be returned.

  • dtype (str) – The NumPy dtype string for the output log.

  • table (list) – Provide a look-up table of values if you want. If you don’t, then it will be constructed from the data.

  • sort_table (bool) – Whether to sort the table or not. Default: False.

  • legend (Legend) – If you want the codes to come from a legend, provide one. Otherwise the codes come from the log, using integers in the order of prevalence. If you use a legend, they are assigned in the order of the legend.

  • legend_field (str) – If you want to get a log representing one of the fields in the legend, such as ‘width’ or ‘grainsize’.

  • match_only (list) – If you only want to match some attributes of the Components (e.g. lithology), provide a list of those you want to match.

  • undefined (number) – What to fill in where no value can be determined, e.g. -999.25 or np.nan. Default 0.

  • return_meta (bool) – If True, also return the depth basis (np.linspace), and the component table.

Returns

If return_meta was True, you get:

  • The log data as an array of ints.

  • The depth basis as an array of floats.

  • A list of the components in the order matching the ints.

If return_meta was False (the default), you only get the log data.

Return type

ndarray

property top#

Property.

union(other)#

Makes a striplog of all unions.

Parameters

with. (Striplog. The striplog instance to union) –

Returns

Striplog. The result of the union.

property unique#

Property. Summarize a Striplog with some statistics.

Returns

List. A list of (Component, total thickness thickness) tuples.

exception striplog.striplog.StriplogError#

Bases: Exception

Generic error class.