This describes the LIS FrameSet that contains the binary frame data. It is effectively a wrapper around a 2-D numpy array with specific APIs to interface that with a channel specific shape. Importantly FrameSets can be partial in that they need not hold all the data for every frame and every channel. Instead they can hold data for the frames and channels specified by the caller.
The FrameSet module is located in TotalDepth/src/TotalDepth/LIS/core and can be imported thus:
from TotalDepth.LIS.core import FrameSet
The internal representation of the FrameSet uses only Python and numpy structures and types, it is thus ignorant of the LIS file format or data structures apart from that described below.
In the current version of the code there are a number of dependencies on knowledge of the LIS file format (or at least TotalDepth’s representation of that format):
ChArTe objects are constructed from LIS Datum Specification Block objects.
XAxisDecl consists of a straight copy of various Entry Block values.
XAxisDecl relies on the LIS value of the up/down flag.
FrameSet is constructed with a DFSR and extracts the absent value form the DFSR as well as constructing ChArTe and XAxisDecl objects.
These dependencies restrict the use of FrameSet to processing LIS data, if they were removed then FrameSet could be used for other file formats but there is no obvious use case for that as, apart from LIS, TotalDepth supports LAS (trivially simple frame sets) and will support RP66 at some point. The latter may trigger a refactoring of the FrameSet module.
The FrameSet module provides a means of representing LIS frame data.
Created on 10 Jan 2011
Specialisation of exception for FrameSet.
Raised when an illegal operation is performed on a FrameSet.
Raised when FrameSet depends on a frame spacing that can not be determined.
Raised when generating values for multiple channels where the channels are not of the same shape i.e. number of samples, butsts.
Global function for checking indexes and raising an IndexError. msg is expected to have two format fields that take i and l respectively.
Returns a new slice with start=None as 0 and step=None as 1.
Base class for a sequence of objects.
Sub-channel Array Template.
The total number of values in this sub-channel.
Returns the index of a particular sample or channel with bounds checking.
WARNING: This not correct for Dipmeter sub-channels.
Channel Array Template. Constructed with a DatumSpecBlock object.
Implementation note: _index() and _dipmeterIndex() have no bounds checking but are significantly faster for those routines that access then with pre-checked limits.
Number of sub-channels.
Number of bytes per frame in the LIS representation.
Returns a range object that is the sub-channel offset in the frame relative to the start of the channel.
Returns a slice object that is the sub-channel offset in the frame relative to the start of the channel.
Returns the index of a particular sub-channel, sample and burst. Order is (fastest changing first): burst, sample. For those with sub-channels: sub-channel, sample This has bounds checking.
Returns dipmeter data index. Bounds checking is performed.
Contains the representation of a list of Frames and thus a representation of and ‘matrix’ (non literal) of: (frame, channel, sub-channel, sample, burst). Commonly shortened to: (fr, ch, sc, sa, bu) Effectively this is a wrapper around a numpy 2-D array that we treat specially to get our 5-D array (LIS channels are not homogeneous).
Constructed with a DFSR, a slice of frame indexes and an optional list of external channel indexes (defaults to all channels). Duplicates in the theChS will be removed and it will be sorted.
xAxisIndex is the external channel index of the X axis (ignored if indirect X).
Data type used in the underlying numpy array.
Returns a long string that describes me.
Dump the frames to the stream.
Returns the number of bytes in the underlying array implementation.
The number of LIS bytes that make up this FrameSet.
The number of frames currently in this FrameSet.
The number of values in each frame currently in this FrameSet.
The total number of values in the array.
Gives access to the raw numpy array.
Returns a specific frame.
Returns the X axis value for the frame when indirect X is used or None.
The distance stepped by numFr.
Given an external frame number this returns the internal frame number. Will raise an IndexError if the internal frame number is out of range or the external frame number is not in the caller specified slice object.
Given an internal frame number this returns the external frame number. This does _not_ test that the internal frame number exists.
The number of _internal_ channels.
Number of sub-channels for an external channel.
Number of samples for the external channel, sub-channel.
Number of bursts for the external channel, sub-channel.
True if there is an indirect X axis, False otherwise.
The XAxisDecl object created from the DFSR.
Given bytes, convert from Rep Codes to ‘float64’ and populates the appropriate frame and channel(s). This has random write access so the caller needs to be sensitive to the frame and channel location. fr is the internal frame position to write the data to. chFrom, chTo are inclusive and represent external channel indices.
WARNING: It is rare to use this API directly, instead a FrameSet object is usually a member of a LogPass object and that uses this API as a LogPass is capable of finding and reading bytes objects in a file (a LogPass uses RLE and Type01Plan objects to do this efficiently).
Sets an indirect X axis value directly, for example with an EXTRAPOLATE event.
Return the internal channel index from the external one.
The index in the frame of the first value for external channel.
The index in the frame of the value for (external channel, sub-channel, sample, burst). TODO: Provide an API that returns a numpy view of a ch/sc on the frameset.
Returns a single value from an: internal fr, external ch, sc, sa, bu. This is very good at random access but can be quite slow for iteration compared to the generators.
Returns a numpy array that is a view of the current frame set for an external channel and sub channel.
Generates an ordered list of external channel indexes for this (possibly) partial frameset.
Generates values for the external channel and sub channel. sc is ignored unless the channel has > 1 sub-channels. If chIsExternal is True then ch is the external channel index otherwise it is the internal index. The value order is sample/burst.
Generates (xAxis, values) as numbers for the external channel and sub-channel. sc is ignored unless the channel has > 1 sub-channels. If chIsExt is True then ch is the external channel index otherwise it is the internal index.
Generates (xAxis, (values, ...)) as numbers for the list of (channel, sub-channel) indexes. An ExceptionFrameSetMixedChannels will be raised if all ch/sc channels are not of the same form i.e. number of samples and bursts. If chIsExt is True then ch is the external channel index otherwise it is the internal index.
Yields 6 item tuples (fr ext, ch ext, sc, sa, bu value).
Calls .add() on every accumulator (with a unary function) for every internal channel and returns an numpy array of (numSubCh, len(theAccs)) doubles. Each accumulator is expected to have __init__(), add() and value() that returns a double implemented. Will raise a ExceptionFrameSetEmpty if there are no values to analyse. Will return None if theAccs is zero length.
Accumulates the minimum value.
Add a new value.
Return the result.
Accumulates the maximum value.
Add a new value.
Return the result.
Accumulates the mean value.
Add a new value.
Return the result.
Accumulates the standard deviation.
Add a new value.
Return the result.
Accumulates the number of values.
Add a new value.
Return the result.
Base class for acumulating a count of first order differences.
Add a new value.
Return the result.
Counting how many values are an increase from the previous value.
Add a new value.
Counting how many values are equal to the previous value.
Add a new value.
Counting how many values are less than the previous value.
Add a new value.
Measures increment, equal, decrement and computes bias which is: (inc - dec) / total.
Add a new value.
Return the result.