segyio 2.0.0a1__cp312-cp312-win_amd64.whl

segyio/trace.py

@@ -0,0 +1,1624 @@
+try:
+    from collections.abc import Sequence # noqa
+except ImportError:
+    from collections import Sequence # noqa
+
+import contextlib
+import itertools
+import warnings
+import sys
+try: from future_builtins import zip
+except ImportError: pass
+
+import numpy as np
+
+from .line import HeaderLine
+from .field import Field, HeaderFieldAccessor
+from .utils import castarray
+
+class Sequence(Sequence):
+
+    # unify the common optimisations and boilerplate of Trace, RawTrace, and
+    # Header, which all obey the same index-oriented interface, and all share
+    # length and wrap-around properties.
+    #
+    # It provides a useful negative-wrap index method which deals
+    # appropriately with IndexError and python2-3 differences.
+
+    def __init__(self, length):
+        self.length = length
+
+    def __len__(self):
+        """x.__len__() <==> len(x)"""
+        return self.length
+
+    def __iter__(self):
+        """x.__iter__() <==> iter(x)"""
+        # __iter__ has a reasonable default implementation from Sequence. It's
+        # essentially this loop:
+        # for i in range(len(self)): yield self[i]
+        # However, in segyio that means the double-buffering, buffer reuse does
+        # not happen, which is *much* slower (the allocation of otherwised
+        # reused numpy objects takes about half the execution time), so
+        # explicitly implement it as [:]
+        return self[:]
+
+    def wrapindex(self, i):
+        if i < 0:
+            i += len(self)
+
+        if not 0 <= i < len(self):
+            # in python2, int-slice comparison does not raise a type error,
+            # (but returns False), so force a type-error if this still isn't an
+            # int-like.
+            _ = i + 0
+            raise IndexError('trace index out of range')
+
+        return i
+
+class Trace(Sequence):
+    """
+    The Trace implements the array interface, where every array element, the
+    data trace, is a numpy.ndarray. As all arrays, it can be random accessed,
+    iterated over, and read strided. Data is read lazily from disk, so
+    iteration does not consume much memory. If you want eager reading, use
+    Trace.raw.
+
+    This mode gives access to reading and writing functionality for traces.
+    The primary data type is ``numpy.ndarray``. Traces can be accessed
+    individually or with python slices, and writing is done via assignment.
+
+    Notes
+    -----
+    .. versionadded:: 1.1
+
+    .. versionchanged:: 1.6
+        common list operations (Sequence)
+
+    Examples
+    --------
+    Read all traces in file f and store in a list:
+
+    >>> l = [numpy.copy(tr) for tr in trace[:]]
+
+    Do numpy operations on a trace:
+
+    >>> tr = trace[10]
+    >>> tr = tr * 2
+    >>> tr = tr - 100
+    >>> avg = numpy.average(tr)
+
+    Perform some seismic processing on a trace. E.g resample from 2ms spacing
+    to 4ms spacing (note there is no anti-alias filtering in this example):
+
+    >>> tr = scipy.signal.resample(tr, len(tr)/2)
+
+    Double every trace value and write to disk. Since accessing a trace
+    gives a numpy value, to write to the respective trace we need its index:
+
+    >>> for i, tr in enumerate(trace):
+    ...     tr = tr * 2
+    ...     trace[i] = tr
+
+    """
+
+    def __init__(self, segyfd, dtype, tracecount, samples, readonly):
+        super(Trace, self).__init__(tracecount)
+        self.segyfd = segyfd
+        self.dtype = dtype
+        self.shape = samples
+        self.readonly = readonly
+
+    def __getitem__(self, i):
+        """trace[i] or trace[i, j]
+
+        ith trace of the file, starting at 0. trace[i] returns a numpy array,
+        and changes to this array will *not* be reflected on disk.
+
+        When i is a tuple, the second index j (int or slice) is the depth index
+        or interval, respectively. j starts at 0.
+
+        When i is a slice, a generator of numpy arrays is returned.
+
+        Parameters
+        ----------
+        i : int or slice
+        j : int or slice
+
+        Returns
+        -------
+        trace : numpy.ndarray of dtype or generator of numpy.ndarray of dtype
+
+        Notes
+        -----
+        .. versionadded:: 1.1
+
+        Behaves like [] for lists.
+
+        .. note::
+
+            This operator reads lazily from the file, meaning the file is read
+            on ``next()``, and only one trace is fixed in memory. This means
+            segyio can run through arbitrarily large files without consuming
+            much memory, but it is potentially slow if the goal is to read the
+            entire file into memory. If that is the case, consider using
+            `trace.raw`, which reads eagerly.
+
+        Examples
+        --------
+        Read every other trace:
+
+        >>> for tr in trace[::2]:
+        ...     print(tr)
+
+        Read all traces, last-to-first:
+
+        >>> for tr in trace[::-1]:
+        ...     tr.mean()
+
+        Read a single value. The second [] is regular numpy array indexing, and
+        supports all numpy operations, including negative indexing and slicing:
+
+        >>> trace[0][0]
+        1490.2
+        >>> trace[0][1]
+        1490.8
+        >>> trace[0][-1]
+        1871.3
+        >>> trace[-1][100]
+        1562.0
+
+        Read only an interval in a trace:
+        >>> trace[0, 5:10]
+        """
+
+        try:
+            # optimize for the default case when i is a single trace index
+            i = self.wrapindex(i)
+            buf = np.zeros(self.shape, dtype = self.dtype)
+            return self.segyfd.gettr(buf, i, 1, 1, 0, self.shape, 1, self.shape)
+        except TypeError:
+            pass
+
+        try:
+            i, j = i
+        except TypeError:
+            # index is not a tuple. Set j to be a slice that causes the entire
+            # trace to be loaded.
+            j = slice(0, self.shape, 1)
+
+        single = False
+        try:
+            start, stop, step = j.indices(self.shape)
+        except AttributeError:
+            # j is not a slice, set start stop and step so that a single sample
+            # at position j is loaded.
+            start = int(j) % self.shape
+            stop = start + 1
+            step = 1
+            single = True
+
+        n_elements = len(range(start, stop, step))
+
+        try:
+            i = self.wrapindex(i)
+            buf = np.zeros(n_elements, dtype = self.dtype)
+            tr = self.segyfd.gettr(buf, i, 1, 1, start, stop, step, n_elements)
+            return tr[0] if single else tr
+        except TypeError:
+            pass
+
+        try:
+            indices = i.indices(len(self))
+            def gen():
+                # double-buffer the trace. when iterating over a range, we want
+                # to make sure the visible change happens as late as possible,
+                # and that in the case of exception the last valid trace was
+                # untouched. this allows for some fancy control flow, and more
+                # importantly helps debugging because you can fully inspect and
+                # interact with the last good value.
+                x = np.zeros(n_elements, dtype=self.dtype)
+                y = np.zeros(n_elements, dtype=self.dtype)
+
+                for k in range(*indices):
+                    self.segyfd.gettr(x, k, 1, 1, start, stop, step, n_elements)
+                    x, y = y, x
+                    yield y
+
+            return gen()
+        except AttributeError:
+            # At this point we have tried to unpack index as a single int, a
+            # slice and a pair with either element being an int or slice.
+            msg = 'trace indices must be integers or slices, not {}'
+            raise TypeError(msg.format(type(i).__name__))
+
+
+    def __setitem__(self, i, val):
+        """trace[i] = val
+
+        Write the ith trace of the file, starting at 0. It accepts any
+        array_like, but val must be at least as big as the underlying data
+        trace.
+
+        If val is longer than the underlying trace, it is essentially
+        truncated.
+
+        For the best performance, val should be a numpy.ndarray of sufficient
+        size and same dtype as the file. segyio will warn on mismatched types,
+        and attempt a conversion for you.
+
+        Data is written immediately to disk. If writing multiple traces at
+        once, and a write fails partway through, the resulting file is left in
+        an unspecified state.
+
+        Parameters
+        ----------
+        i   : int or slice
+        val : array_like
+
+        Notes
+        -----
+        .. versionadded:: 1.1
+
+        Behaves like [] for lists.
+
+        Examples
+        --------
+        Write a single trace:
+
+        >>> trace[10] = list(range(1000))
+
+        Write multiple traces:
+
+        >>> trace[10:15] = np.array([cube[i] for i in range(5)])
+
+        Write multiple traces with stride:
+
+        >>> trace[10:20:2] = np.array([cube[i] for i in range(5)])
+
+        """
+        if isinstance(i, slice):
+            for j, x in zip(range(*i.indices(len(self))), val):
+                self[j] = x
+
+            return
+
+        xs = castarray(val, self.dtype)
+
+        # TODO:  check if len(xs) > shape, and optionally warn on truncating
+        # writes
+        self.segyfd.puttr(self.wrapindex(i), xs)
+
+    def __repr__(self):
+        return "Trace(traces = {}, samples = {})".format(len(self), self.shape)
+
+    @property
+    def raw(self):
+        """
+        An eager version of Trace
+
+        Returns
+        -------
+        raw : RawTrace
+        """
+        return RawTrace(self.segyfd,
+                        self.dtype,
+                        len(self),
+                        self.shape,
+                        self.readonly,
+                       )
+
+    @property
+    @contextlib.contextmanager
+    def ref(self):
+        """
+        A write-back version of Trace
+
+        Returns
+        -------
+        ref : RefTrace
+            `ref` is returned in a context manager, and must be in a ``with``
+            statement
+
+        Notes
+        -----
+        .. versionadded:: 1.6
+
+        Examples
+        --------
+        >>> with trace.ref as ref:
+        ...     ref[10] += 1.617
+        """
+
+        x = RefTrace(self.segyfd,
+                     self.dtype,
+                     len(self),
+                     self.shape,
+                     self.readonly,
+                    )
+        yield x
+        x.flush()
+
+class RawTrace(Trace):
+    """
+    Behaves exactly like trace, except reads are done eagerly and returned as
+    numpy.ndarray, instead of generators of numpy.ndarray.
+    """
+    def __init__(self, *args):
+        super(RawTrace, self).__init__(*args)
+
+    def __getitem__(self, i):
+        """trace[i]
+
+        Eagerly read the ith trace of the file, starting at 0. trace[i] returns
+        a numpy array, and changes to this array will *not* be reflected on
+        disk.
+
+        When i is a slice, this returns a 2-dimensional numpy.ndarray .
+
+        Parameters
+        ----------
+        i : int or slice
+
+        Returns
+        -------
+        trace : numpy.ndarray of dtype
+
+        Notes
+        -----
+        .. versionadded:: 1.1
+
+        Behaves like [] for lists.
+
+        .. note::
+
+            Reading this way is more efficient if you know you can afford the
+            extra memory usage. It reads the requested traces immediately to
+            memory.
+
+        """
+        try:
+            i = self.wrapindex(i)
+            buf = np.zeros(self.shape, dtype = self.dtype)
+            return self.segyfd.gettr(buf, i, 1, 1, 0, self.shape, 1, self.shape)
+        except TypeError:
+            try:
+                indices = i.indices(len(self))
+            except AttributeError:
+                msg = 'trace indices must be integers or slices, not {}'
+                raise TypeError(msg.format(type(i).__name__))
+            start, _, step = indices
+            length = len(range(*indices))
+            buf = np.empty((length, self.shape), dtype = self.dtype)
+            return self.segyfd.gettr(buf, start, step, length, 0, self.shape, 1, self.shape)
+
+
+def fingerprint(x):
+    return hash(bytes(x.data))
+
+class RefTrace(Trace):
+    """
+    Behaves like trace, except changes to the returned numpy arrays *are*
+    reflected on disk. Operations have to be in-place on the numpy array, so
+    assignment on a trace will not work.
+
+    This feature exists to support code like::
+
+        >>> with ref as r:
+        ...     for x, y in zip(r, src):
+        ...         numpy.copyto(x, y + 10)
+
+    This class is not meant to be instantiated directly, but returned by
+    :attr:`Trace.ref`. This feature requires a context manager, to guarantee
+    modifications are written back to disk.
+    """
+    def __init__(self, *args):
+        super(RefTrace, self).__init__(*args)
+        self.refs = {}
+
+    def flush(self):
+        """
+        Commit cached writes to the file handle. Does not flush libc buffers or
+        notifies the kernel, so these changes may not immediately be visible to
+        other processes.
+
+        Updates the fingerprints whena writes happen, so successive ``flush()``
+        invocations are no-ops.
+
+        It is not necessary to call this method in user code.
+
+        Notes
+        -----
+        .. versionadded:: 1.6
+
+        This method is not intended as user-oriented functionality, but might
+        be useful in certain contexts to provide stronger guarantees.
+        """
+        garbage = []
+        # If there are no external references to the data (so only internal
+        # references remain), the reference count is
+        # - 2 (Python >= 3.14)
+        # - 3 (Python < 3.14)
+        garbage_threshold = 3 if sys.version_info < (3, 14) else 2
+
+        for i, (x, signature) in self.refs.items():
+            if sys.getrefcount(x) == garbage_threshold:
+                garbage.append(i)
+
+            if fingerprint(x) == signature: continue
+
+            self.segyfd.puttr(i, x)
+            signature = fingerprint(x)
+
+
+        # to avoid too many resource leaks, when this dict is the only one
+        # holding references to already-produced traces, clear them
+        for i in garbage:
+            del self.refs[i]
+
+    def fetch(self, i, buf = None):
+        if buf is None:
+            buf = np.zeros(self.shape, dtype = self.dtype)
+
+        try:
+            self.segyfd.gettr(buf, i, 1, 1, 0, self.shape, 1, self.shape)
+        except IOError:
+            if not self.readonly:
+                # if the file is opened read-only and this happens, there's no
+                # way to actually write and the error is an actual error
+                buf.fill(0)
+            else: raise
+
+        return buf
+
+    def __getitem__(self, i):
+        """trace[i]
+
+        Read the ith trace of the file, starting at 0. trace[i] returns a numpy
+        array, but unlike Trace, changes to this array *will* be reflected on
+        disk. The modifications must happen to the actual array (views are ok),
+        so in-place operations work, but assignments will not::
+
+            >>> with ref as ref:
+            ...     x = ref[10]
+            ...     x += 1.617 # in-place, works
+            ...     numpy.copyto(x, x + 10) # works
+            ...     x = x + 10 # re-assignment, won't change the original x
+
+        Works on newly created files that has yet to have any traces written,
+        which opens up a natural way of filling newly created files with data.
+        When getting unwritten traces, a trace filled with zeros is returned.
+
+        Parameters
+        ----------
+        i : int or slice
+
+        Returns
+        -------
+        trace : numpy.ndarray of dtype
+
+        Notes
+        -----
+        .. versionadded:: 1.6
+
+        Behaves like [] for lists.
+
+        Examples
+        --------
+        Merge two files with a binary operation. Relies on python3 iterator
+        zip:
+
+        >>> with ref as ref:
+        ...     for x, lhs, rhs in zip(ref, L, R):
+        ...         numpy.copyto(x, lhs + rhs)
+
+        Create a file and fill with data (the repeated trace index):
+
+        >>> f = create()
+        >>> with f.trace.ref as ref:
+        ...     for i, x in enumerate(ref):
+        ...         x.fill(i)
+        """
+        try:
+            i = self.wrapindex(i)
+
+            # we know this class is only used in context managers, so we know
+            # refs don't escape (with expectation of being written), so
+            # preserve all refs yielded with getitem(int)
+            #
+            # using ref[int] is problematic and pointless, we need to handle
+            # this scenario gracefully:
+            # with f.trace.ref as ref:
+            #     x = ref[10]
+            #     x[5] = 0
+            #     # invalidate other refs
+            #     y = ref[11]
+            #     y[6] = 1.6721
+            #
+            #     # if we don't preserve returned individual getitems, this
+            #     # write is lost
+            #     x[5] = 52
+            #
+            # for slices, we know that references terminate with every
+            # iteration anyway, multiple live references cannot happen
+
+            if i in self.refs:
+                return self.refs[i][0]
+
+            x = self.fetch(i)
+            self.refs[i] = (x, fingerprint(x))
+            return x
+
+        except TypeError:
+            try:
+                indices = i.indices(len(self))
+            except AttributeError:
+                msg = 'trace indices must be integers or slices, not {}'
+                raise TypeError(msg.format(type(i).__name__))
+
+            def gen():
+                x = np.zeros(self.shape, dtype = self.dtype)
+                try:
+                    for j in range(*indices):
+                        x = self.fetch(j, x)
+                        y = fingerprint(x)
+
+                        yield x
+
+                        if not fingerprint(x) == y:
+                            self.segyfd.puttr(j, x)
+
+                finally:
+                    # the last yielded item is available after the loop, so
+                    # preserve it and check if it's been updated on exit
+                    self.refs[j] = (x, y)
+
+            return gen()
+
+class Header(Sequence):
+    """Interact with segy in header mode
+
+    This mode gives access to reading and writing functionality of headers,
+    both in individual (trace) mode and line mode. The returned header
+    implements a dict_like object with a fixed set of keys, given by the SEG-Y
+    standard.
+
+    The Header implements the array interface, where every array element, the
+    data trace, is a numpy.ndarray. As all arrays, it can be random accessed,
+    iterated over, and read strided. Data is read lazily from disk, so
+    iteration does not consume much memory.
+
+    Notes
+    -----
+    .. versionadded:: 1.1
+
+    .. versionchanged:: 1.6
+        common list operations (Sequence)
+
+    """
+    def __init__(self, segyfile):
+        self.segyfile = segyfile
+        super(Header, self).__init__(segyfile.tracecount)
+
+    def __getitem__(self, i):
+        """header[i]
+
+        ith header of the file, starting at 0.
+
+        Parameters
+        ----------
+        i : int or slice
+
+        Returns
+        -------
+        field : Field
+            dict_like header
+
+        Notes
+        -----
+        .. versionadded:: 1.1
+
+        Behaves like [] for lists.
+
+        Examples
+        --------
+        Reading a header:
+
+        >>> header[10]
+
+        Read a field in the first 5 headers:
+
+        >>> [x[25] for x in header[:5]]
+        [1, 2, 3, 4, 5]
+
+        Read a field in every other header:
+
+        >>> [x[37] for x in header[::2]]
+        [1, 3, 1, 3, 1, 3]
+        """
+        try:
+            i = self.wrapindex(i)
+            return Field.trace(traceno = i, traceheader_index = 0, segyfile = self.segyfile)
+
+        except TypeError:
+            try:
+                indices = i.indices(len(self))
+            except AttributeError:
+                msg = 'trace indices must be integers or slices, not {}'
+                raise TypeError(msg.format(type(i).__name__))
+
+            def gen():
+                # double-buffer the header. when iterating over a range, we
+                # want to make sure the visible change happens as late as
+                # possible, and that in the case of exception the last valid
+                # header was untouched. this allows for some fancy control
+                # flow, and more importantly helps debugging because you can
+                # fully inspect and interact with the last good value.
+                x = Field.trace(traceno = None, traceheader_index = 0, segyfile = self.segyfile)
+                buf = bytearray(x.buf)
+                for j in range(*indices):
+                    # skip re-invoking __getitem__, just update the buffer
+                    # directly with fetch, and save some initialisation work
+                    buf = x.fetch(buf, j)
+                    x.buf[:] = buf
+                    x.traceno = j
+                    yield x
+
+            return gen()
+
+    def __setitem__(self, i, val):
+        """header[i] = val
+
+        Write the ith header of the file, starting at 0. Unlike data traces
+        (which return numpy.ndarrays), changes to returned headers being
+        iterated over *will* be reflected on disk.
+
+        Parameters
+        ----------
+        i   : int or slice
+        val : Field or array_like of dict_like
+
+        Notes
+        -----
+        .. versionadded:: 1.1
+
+        Behaves like [] for lists
+
+        Examples
+        --------
+        Copy a header to a different trace:
+
+        >>> header[28] = header[29]
+
+        Write multiple fields in a trace:
+
+        >>> header[10] = { 37: 5, TraceField.INLINE_3D: 2484 }
+
+        Set a fixed set of values in all headers:
+
+        >>> for x in header[:]:
+        ...     x[37] = 1
+        ...     x.update({ TraceField.offset: 1, 2484: 10 })
+
+        Write a field in multiple headers
+
+        >>> for x in header[:10]:
+        ...     x.update({ TraceField.offset : 2 })
+
+        Write a field in every other header:
+
+        >>> for x in header[::2]:
+        ...     x.update({ TraceField.offset : 2 })
+        """
+
+        x = self[i]
+
+        try:
+            x.update(val)
+        except AttributeError:
+            if isinstance(val, Field) or isinstance(val, dict):
+                val = itertools.repeat(val)
+
+            for h, v in zip(x, val):
+                h.update(v)
+
+    @property
+    def iline(self):
+        """
+        Headers, accessed by inline
+
+        Returns
+        -------
+        line : HeaderLine
+        """
+        return HeaderLine(self, self.segyfile.iline, 'inline')
+
+    @iline.setter
+    def iline(self, value):
+        """Write iterables to lines
+
+        Examples:
+            Supports writing to *all* crosslines via assignment, regardless of
+            data source and format. Will respect the sample size and structure
+            of the file being assigned to, so if the argument traces are longer
+            than that of the file being written to the surplus data will be
+            ignored. Uses same rules for writing as `f.iline[i] = x`.
+        """
+        for i, src in zip(self.segyfile.ilines, value):
+            self.iline[i] = src
+
+    @property
+    def xline(self):
+        """
+        Headers, accessed by crossline
+
+        Returns
+        -------
+        line : HeaderLine
+        """
+        return HeaderLine(self, self.segyfile.xline, 'crossline')
+
+    @xline.setter
+    def xline(self, value):
+        """Write iterables to lines
+
+        Examples:
+            Supports writing to *all* crosslines via assignment, regardless of
+            data source and format. Will respect the sample size and structure
+            of the file being assigned to, so if the argument traces are longer
+            than that of the file being written to the surplus data will be
+            ignored. Uses same rules for writing as `f.xline[i] = x`.
+        """
+
+        for i, src in zip(self.segyfile.xlines, value):
+            self.xline[i] = src
+
+
+class FileFieldAccessor(Sequence):
+    """
+    Sequence of rows of trace headers in a SEG-Y file.
+
+    Provides access to all trace headers defined in the SEG-Y file.
+
+    Notes
+    -----
+    .. versionadded:: 2.0
+
+    """
+
+    def __init__(self, segyfile):
+        self.segyfile = segyfile
+        super().__init__(segyfile.tracecount)
+
+    def __getitem__(self, i):
+        """traceheader[i]
+
+        All headers belonging to ith trace, starting at 0.
+
+        Parameters
+        ----------
+        i : int or slice
+
+        Returns
+        -------
+        traceheaders : RowFieldAccessor
+
+        Examples
+        --------
+        Accessing headers in trace 10 (11th in the file):
+
+        >>> traceheader[10]
+        """
+        try:
+            trace_index = self.wrapindex(i)
+            return RowFieldAccessor(segyfile=self.segyfile, trace_index=trace_index)
+
+        except TypeError:
+            try:
+                trace_indices = i.indices(len(self))
+            except AttributeError:
+                msg = 'trace indices must be integers or slices, not {}'
+                raise TypeError(msg.format(type(i).__name__))
+
+            def gen():
+                for trace_index in range(*trace_indices):
+                    yield RowFieldAccessor(segyfile=self.segyfile, trace_index=trace_index)
+
+            return gen()
+
+    def __setitem__(self, i, val):
+        """traceheader[i] = val
+
+        Write the ith header of the file, starting at 0.
+
+        Parameters
+        ----------
+        i   : int or slice
+        val : another FileFieldAccessor or array like
+
+        Examples
+        --------
+        Copy all trace's headers to a different trace:
+
+        >>> traceheader[28] = traceheader[29]
+        """
+        if not isinstance(i, slice):
+            trace_index = self.wrapindex(i)
+            if not isinstance(val, RowFieldAccessor):
+                raise TypeError(
+                    "Unassignable type. f.traceheader[i] can only be assigned f.traceheader[j]")
+            self[trace_index][:] = val
+            return
+
+        trace_indices = range(*i.indices(len(self)))
+        for trace_index, value in zip(trace_indices, val):
+            self[trace_index] = value
+
+
+class RowFieldAccessor(Sequence):
+    """
+    Sequence of trace headers in a single trace (row).
+
+    Provides access to all trace headers defined in the trace.
+
+    Notes
+    -----
+    .. versionadded:: 2.0
+
+    """
+
+    def __init__(self, segyfile, trace_index):
+        self.segyfile = segyfile
+        self.trace_index = trace_index
+        super().__init__(segyfile.traceheader_count)
+
+    def __getitem__(self, i):
+        """traceheader[i]
+
+        ith header of the trace, starting at 0.
+
+        Note that this function loads trace header into memory, so if you wish
+        to access multiple fields, caching the result of this function is more
+        efficient than calling it anew with each of the fields.
+
+        Parameters
+        ----------
+        i : int or slice
+
+        Returns
+        -------
+        field : Field
+            dict_like header
+
+        Examples
+        --------
+        Reading a header:
+
+        >>> traceheader[10]
+
+        Read a field in the first 5 headers:
+
+        >>> [x[25] for x in traceheader[:5]]
+        [1, 2, 3, 4, 5]
+        """
+        try:
+            return HeaderFieldAccessor.trace(
+                traceno=self.trace_index, traceheader_index=self.wrapindex(i), segyfile=self.segyfile
+            )
+
+        except TypeError:
+            try:
+                traceheader_indices = i.indices(len(self))
+            except AttributeError:
+                msg = 'trace header indices must be integers or slices, not {}'
+                raise TypeError(msg.format(type(i).__name__))
+
+            def gen():
+                # see Header.__getitem__ for logic explanation
+                x = HeaderFieldAccessor.trace(
+                    traceno=self.trace_index, traceheader_index=None, segyfile=self.segyfile
+                )
+                buf = bytearray(x.buf)
+                for traceheader_index in range(*traceheader_indices):
+                    buf = x.fetch(buf, self.trace_index, traceheader_index)
+                    x.buf[:] = buf
+                    x.traceheader_index = traceheader_index
+                    traceheader_layout = x.segyfile.tracefield[traceheader_index]
+                    x._keys = [field.offset() for field in traceheader_layout]
+                    yield x
+
+            return gen()
+
+    def __getattr__(self, name):
+        """traceheaders.name
+
+        Header of the trace by name `name`. `name` must be a name defined by
+        the file layouts.
+
+        Wrapper around :meth:`.__getitem__`, so refer to it for more
+        information.
+
+        Parameters
+        ----------
+        name : str
+
+        Returns
+        -------
+        field : Field
+            dict_like header
+
+        Examples
+        --------
+        Reading a header:
+
+        >>> traceheaders.SEG00001
+        """
+        index = self.segyfile._traceheader_names.index(name)
+        return self[index]
+
+    def __setitem__(self, i, val):
+        """traceheader[i] = val
+
+        Write the ith header of the trace, starting at 0.
+
+        Parameters
+        ----------
+        i   : int or slice
+        val : Field or array_like of dict_like
+
+        Examples
+        --------
+        Copy standard header to a different trace:
+
+        >>> f.traceheader[0][0] = f.traceheader[1][0]
+
+        Writing fields via `traceheader[trace_index][traceheader_index] =
+        {(offset: value)}` is not supported. Use :class:`segyio.field.Field`
+        interface instead:
+
+        >>> f.traceheader[0][0].update({ 37: 5, 1: 2484 })
+
+        """
+        if not isinstance(i, slice):
+            traceheader_index = self.wrapindex(i)
+            field_sequence = self[traceheader_index]
+            if isinstance(val, Field):
+                field_sequence.update(val)
+                return
+            raise TypeError(
+                "Unassignable type. f.traceheader[i][j] can only be assigned another Field.")
+
+        traceheader_indices = range(*i.indices(len(self)))
+
+        for traceheader_index, value in zip(traceheader_indices, val):
+            self[traceheader_index] = value
+
+    def __setattr__(self, name, value):
+        """traceheaders.name = value
+
+        Write header of the trace by name `name`. `name` must be a name defined by
+        the file layouts.
+
+        Wrapper around :meth:`.__setitem__`, so refer to it for more
+        information.
+
+        Parameters
+        ----------
+        name : str
+
+        Examples
+        --------
+        Copying a header:
+
+        >>> f.traceheader[0].SEG00001 = f.traceheader[1].SEG00001
+        """
+        if name == "segyfile":
+            super().__setattr__(name, value)
+            return
+
+        try:
+           index = self.segyfile._traceheader_names.index(name)
+           self[index] = value
+        except ValueError:
+            super().__setattr__(name, value)
+
+
+class Attributes(Sequence):
+    """File-wide attribute (header word) reading
+
+    Lazily read a single header word for every trace in the file. The
+    Attributes implement the array interface, and will behave as expected when
+    indexed and sliced.
+
+    Notes
+    -----
+    .. versionadded:: 1.1
+    """
+
+    ENTRY_TYPE_TO_NUMPY = {
+        "int2": np.int16,
+        "int4": np.int32,
+        "int8": np.int64,
+        "uint2": np.uint16,
+        "uint4": np.uint32,
+        "uint8": np.uint64,
+        "ibmfp": np.float32,
+        "ieee32": np.float32,
+        "ieee64": np.float64,
+        "linetrc": np.uint32,
+        "reeltrc": np.uint32,
+        "linetrc8": np.uint64,
+        "reeltrc8": np.uint64,
+        "coor4":    np.int32,
+        "elev4":    np.int32,
+        "time2":    np.int16,
+        "spnum4":   np.int32,
+        # "scale6" unspported, unclear what to do yet
+        "string8":  np.dtype('S8'),
+    }
+
+    def __init__(self, segyfile, field, traceheader_index):
+        super(Attributes, self).__init__(segyfile.tracecount)
+        self.field = field
+        self.traceheader_index = traceheader_index
+        self.segyfd = segyfile.segyfd
+        self.tracecount = segyfile.tracecount
+
+        traceheader_layout = list(segyfile._traceheader_layouts.values())[traceheader_index]
+        entry = traceheader_layout.entry_by_byte(field)
+        self.dtype = Attributes.ENTRY_TYPE_TO_NUMPY[entry.type]
+
+    def __iter__(self):
+        # attributes requires a custom iter, because self[:] returns a numpy
+        # array, which in itself is iterable, but not an iterator
+        return iter(self[:])
+
+    def __getitem__(self, i):
+        """attributes[:]
+
+        Parameters
+        ----------
+        i : int or slice or array_like
+
+        Returns
+        -------
+        attributes : array_like of dtype
+
+        Examples
+        --------
+        Assuming file with default layout mapping, read all unique sweep
+        frequency end:
+
+        >>> end = segyio.TraceField.SweepFrequencyEnd
+        >>> sfe = np.unique(f.attributes( end )[:])
+
+        Discover the first traces of each unique sweep frequency end:
+
+        >>> end = segyio.TraceField.SweepFrequencyEnd
+        >>> attrs = f.attributes(end)
+        >>> sfe, tracenos = np.unique(attrs[:], return_index = True)
+
+        Scatter plot group x/y-coordinates with SFEs (using matplotlib):
+
+        >>> end = segyio.TraceField.SweepFrequencyEnd
+        >>> attrs = f.attributes(end)
+        >>> _, tracenos = np.unique(attrs[:], return_index = True)
+        >>> gx = f.attributes(segyio.TraceField.GroupX)[tracenos]
+        >>> gy = f.attributes(segyio.TraceField.GroupY)[tracenos]
+        >>> scatter(gx, gy)
+        """
+        try:
+            xs = np.asarray(i, dtype=np.int32)
+            xs = xs.astype(dtype=np.int32, order='C', copy=False)
+            attrs = np.empty(len(xs), dtype = self.dtype)
+            return self.segyfd.field_foreach(attrs, self.traceheader_index, xs, self.field)
+
+        except TypeError:
+            try:
+                i = slice(i, i + 1, 1)
+            except TypeError:
+                pass
+
+            traces = self.tracecount
+            segyfd = self.segyfd
+            field = self.field
+
+            start, stop, step = i.indices(traces)
+            indices = range(start, stop, step)
+            attrs = np.empty(len(indices), dtype = self.dtype)
+            return segyfd.field_forall(attrs, self.traceheader_index, start, stop, step, field)
+
+class Text(Sequence):
+    """Interact with segy in text mode
+
+    This mode gives access to reading and writing functionality for textual
+    headers.
+
+    The primary data type is the python string. Reading textual headers is done
+    with [], and writing is done via assignment. No additional structure is
+    built around the textual header, so everything is treated as one long
+    string without line breaks.
+
+    Notes
+    -----
+    .. versionchanged:: 1.7
+        common list operations (Sequence)
+
+    """
+
+    def __init__(self, segyfd, textcount):
+        super(Text, self).__init__(textcount)
+        self.segyfd = segyfd
+
+    def __getitem__(self, i):
+        """text[i]
+
+        Read the text header at i. 0 is the mandatory, main
+
+        Examples
+        --------
+        Print the textual header:
+
+        >>> print(f.text[0])
+
+        Print the first extended textual header:
+
+        >>> print(f.text[1])
+
+        Print a textual header line-by-line:
+
+        >>> # using zip, from the zip documentation
+        >>> text = f.text[0].decode('ascii', errors='replace')
+        >>> lines = map(''.join, zip( *[iter(text)] * 80))
+        >>> for line in lines:
+        ...     print(line)
+        ...
+
+        Or use segyio.tools.wrap:
+        >>> text = segyio.tools.wrap(f.text[0].decode('latin-1'))
+        """
+        try:
+            i = self.wrapindex(i)
+            return self.segyfd.gettext(i)
+
+        except TypeError:
+            try:
+                indices = i.indices(len(self))
+            except AttributeError:
+                msg = 'trace indices must be integers or slices, not {}'
+                raise TypeError(msg.format(type(i).__name__))
+
+            def gen():
+                for j in range(*indices):
+                    yield self.segyfd.gettext(j)
+            return gen()
+
+    def __setitem__(self, i, val):
+        """text[i] = val
+
+        Write the ith text header of the file, starting at 0.
+        If val is instance of Text or iterable of Text,
+        value is set to be the first element of every Text
+
+        Parameters
+        ----------
+        i : int or slice
+        val : str, Text or iterable if i is slice
+
+        Examples
+        --------
+        Write a new textual header:
+
+        >>> f.text[0] = make_new_header()
+        >>> f.text[1:3] = ["new_header1", "new_header_2"]
+
+        Copy a textual header:
+
+        >>> f.text[1] = g.text[0]
+
+        Write a textual header based on Text:
+
+        >>> f.text[1] = g.text
+        >>> assert f.text[1] == g.text[0]
+
+        >>> f.text[1:3] = [g1.text, g2.text]
+        >>> assert f.text[1] == g1.text[0]
+        >>> assert f.text[2] == g2.text[0]
+
+        """
+        if isinstance(val, Text):
+            self[i] = val[0]
+            return
+
+        try:
+            i = self.wrapindex(i)
+            self.segyfd.puttext(i, val)
+
+        except TypeError:
+            try:
+                indices = i.indices(len(self))
+            except AttributeError:
+                msg = 'trace indices must be integers or slices, not {}'
+                raise TypeError(msg.format(type(i).__name__))
+
+            for i, text in zip(range(*indices), val):
+                if isinstance(text, Text):
+                    text = text[0]
+                self.segyfd.puttext(i, text)
+
+
+class Stanza(Sequence):
+    """Access stanza data from extended textual headers.
+
+    Reading stanzas is done with []. Keys are stanza indices, values are raw
+    stanza data as bytes. Stanza name (stanza header) is not included in the
+    return bytes.
+
+    Writing stanzas is not supported.
+
+    Notes
+    -----
+    .. versionadded:: 2.0
+
+    Examples
+    --------
+    Get all stanza names:
+
+    >>> names = f.stanza.names()
+    ... ['OGP:P1/11:text/csv', 'SEG:catalog', 'TROIKA:IMAGEPNG:image/png:51929']
+
+    Access stanza data:
+
+    >>> data = f.stanza[2]
+    """
+
+    def __init__(self, segyfd):
+        self.segyfd = segyfd
+        self._names = self.segyfd.stanza_names()
+        super(Stanza, self).__init__(len(self._names))
+
+    def names(self):
+        """Get all stanza names. Names are the same as they appear in the file.
+
+        Returns
+        -------
+        names : list of str
+            List of all stanza names in the file in order of appearance
+        """
+        return self._names
+
+    def __getitem__(self, key):
+        """Get stanza data by index.
+
+        Parameters
+        ----------
+        key : int or slice
+            Stanza index or indices
+
+        Returns
+        -------
+        data : bytes
+            Stanza data for single stanza, or generator for slice
+
+        Examples
+        --------
+        Access by index:
+
+        >>> data = f.stanza[0]
+
+        Find stanza that fits name pattern:
+
+        >>> for i, name in enumerate(f.stanza.names()):
+        >>>     if name.upper().startswith("SEG:LAYOUT"):
+        >>>         layout_stanza_index = i
+        >>> data = f.stanza[layout_stanza_index]
+        """
+        try:
+            index = self.wrapindex(key)
+            return self.segyfd.getstanza(index)
+        except TypeError:
+            try:
+                indices = key.indices(len(self))
+            except AttributeError:
+                msg = 'stanza indices must be integers, strings, or slices, not {}'
+                raise TypeError(msg.format(type(key).__name__))
+
+            def gen():
+                for j in range(*indices):
+                    yield self.segyfd.getstanza(j)
+            return gen()
+
+
+class RowLayoutEntries(Sequence):
+    """
+    Sequence of trace header layouts in one trace (row).
+
+    Provides access to all trace header layouts defined in the SEG-Y file.
+
+    Notes
+    -----
+    .. versionadded:: 2.0
+    """
+
+    def __init__(self, segyfile):
+        self.segyfile = segyfile
+        self._layouts = segyfile._traceheader_layouts
+        self._layout_names = list(self._layouts.keys())
+
+        super().__init__(segyfile.traceheader_count)
+
+    def __getitem__(self, key):
+        """
+        Get a trace header fields layout by index or slice.
+
+        Parameters
+        ----------
+        key : int or slice
+            Index or range.
+
+        Returns
+        -------
+        HeaderLayoutEntries or generator of HeaderLayoutEntries
+
+        Examples
+        --------
+        Get the layout via [] notation:
+
+        >>> layout = traceheader_layouts[0]
+        """
+        try:
+            traceheader_index = self.wrapindex(key)
+            name = self._layout_names[traceheader_index]
+            layout = self._layouts[name]
+            return HeaderLayoutEntries(self.segyfile, traceheader_index, layout)
+        except TypeError:
+            indices = key.indices(len(self))
+
+            def gen():
+                for traceheader_index in range(*indices):
+                    name = self._layout_names[traceheader_index]
+                    layout = self._layouts[name]
+                    yield HeaderLayoutEntries(self.segyfile, traceheader_index, layout)
+            return gen()
+
+    def __getattr__(self, name):
+        """
+        Get trace header fields layout as an attribute.
+
+        Parameters
+        ----------
+        name : str
+            Name of the layout. Name is case-sensitive.
+
+        Returns
+        -------
+        HeaderLayoutEntries
+
+        Examples
+        --------
+        Get the field layout via . notation:
+
+        >>> layout = traceheader_layouts.SEG00000
+
+        Raises
+        ------
+        AttributeError
+            If the layout does not exist.
+        """
+        if name in self._layouts:
+            traceheader_index = self._layout_names.index(name)
+            return HeaderLayoutEntries(self.segyfile, traceheader_index, self._layouts[name])
+        raise AttributeError(f"No header with name: {name}")
+
+    def names(self):
+        """
+        List all trace header names.
+
+        Returns
+        -------
+        list of str
+            Names of all traceheaders.
+        """
+        return self._layout_names
+
+    def __repr__(self):
+        return f"RowLayoutEntries({self._layout_names})"
+
+
+class HeaderLayoutEntries(Sequence):
+    """
+    Sequence of field layout entries in a trace header.
+
+    Provides access to the individual fields (entries) within a trace header
+    layout.
+
+    Notes
+    -----
+    .. versionadded:: 2.0
+    """
+
+    def __init__(self, segyfile, traceheader_index, layout):
+        self.segyfile = segyfile
+        self._layout = layout
+        self.traceheader_index = traceheader_index
+
+        super().__init__(len(layout))
+
+    def __getitem__(self, key):
+        """
+        Get field entries by index or slice.
+
+        Parameters
+        ----------
+        key : int or slice
+            Index or range.
+
+        Returns
+        -------
+        FieldLayoutEntry or generator of FieldLayoutEntry
+
+        Examples
+        --------
+        Get the entry via [] notation:
+
+        >>> entry = layout[3]
+        """
+        try:
+            entry_index = self.wrapindex(key)
+            entry = self._layout.entries[entry_index]
+            return FieldLayoutEntry(self.segyfile, entry, self.traceheader_index)
+
+        except TypeError:
+            indices = key.indices(len(self))
+
+            def gen():
+                for entry_index in range(*indices):
+                    entry = self._layout.entries[entry_index]
+                    yield FieldLayoutEntry(self.segyfile, entry, self.traceheader_index)
+            return gen()
+
+    def __getattr__(self, name):
+        """
+        Get field entry as an attribute.
+
+        Parameters
+        ----------
+        name : str
+            Name of the field. Name is case-sensitive.
+
+        Returns
+        -------
+        FieldLayoutEntry
+
+        Examples
+        --------
+        Get the entry via . notation:
+
+        >>> entry = layout.iline
+
+        Raises
+        ------
+        AttributeError
+            If the field by that name does not exist.
+        """
+        entry = self._layout.entry_by_name(name)
+        if entry is None:
+            raise AttributeError(f"No field with name: {name}")
+        return FieldLayoutEntry(self.segyfile, entry, self.traceheader_index)
+
+    def names(self):
+        """
+        List all field names in this traceheader layout.
+
+        Returns
+        -------
+        list of str
+            Names of all fields.
+        """
+        return [entry.name for entry in self._layout]
+
+    def index(self):
+        """
+        Get traceheader index of this layout.
+
+        Returns
+        -------
+        int
+            Layout index.
+        """
+        return self.traceheader_index
+
+    def __repr__(self):
+        return f"HeaderLayoutEntries({self.names()})"
+
+
+class FieldLayoutEntry():
+    """
+    Represents a single field entry in a trace header layout.
+
+    Notes
+    -----
+    .. versionadded:: 2.0
+    """
+
+    def __init__(self, segyfile, entry, traceheader_index):
+        self.segyfile = segyfile
+        self.entry = entry
+        self.traceheader_index = traceheader_index
+
+    def name(self):
+        """
+        Get the name of the field as is defined in the layout.
+
+        Returns
+        -------
+        str
+            Name of the field.
+        """
+        return self.entry.name
+
+    def offset(self):
+        """
+        Get the byte offset of this field in the trace header.
+
+        Returns
+        -------
+        int
+            Byte offset of the field.
+        """
+        return self.entry.byte
+
+    def type(self):
+        """
+        Get the data type of the field as defined in the layout.
+
+        Returns
+        -------
+        str
+            Data type of the field.
+        """
+        return self.entry.type
+
+
+    def use_only_if_non_zero(self):
+        """
+        Returns the field property 'if-non-zero' stating if this field could be
+        used only when its value does not equal 0.
+
+        Returns
+        -------
+        bool
+            True if requires non-zero value, False otherwise.
+        """
+        return self.entry.requires_nonzero_value
+
+    def __str__(self):
+        name = self.name()
+        offset = self.offset()
+        type = self.type()
+        non_zero = self.use_only_if_non_zero()
+        return f"{name} (offset={offset}, type={type}, use_only_if_non_zero={non_zero})"
+
+    def __getitem__(self, key):
+        """ tracefield[key]
+
+        Returns values of traces provided in 'key'.
+        Wrapper around :class:`.Attributes`, so refer to it for more
+        information.
+
+        Parameters
+        ----------
+        key : int or slice
+            Index or slice.
+
+        Returns
+        -------
+        array of int, float or bytearray
+
+        Examples
+        --------
+        Get the cdp_x attribute from trace header extension 1 for first 10 traces:
+
+        >>> f.tracefield.SEG00001.cdp_x[0:10]
+        """
+        return Attributes(self.segyfile, self.entry.byte, self.traceheader_index)[key]