Open and create¶

open(filename, mode='r', iline=189, xline=193, strict=True, ignore_geometry=False, endian='big')¶

Open a segy file.

Opens a segy file and tries to figure out its sorting, inline numbers, crossline numbers, and offsets, and enables reading and writing to this file in a simple manner.

For reading, the access mode r is preferred. All write operations will raise an exception. For writing, the mode r+ is preferred (as rw would truncate the file). Any mode with w will raise an error. The modes used are standard C file modes; please refer to that documentation for a complete reference.

Open should be used together with python’s with statement. Please refer to the examples. When the with statement is used the file will automatically be closed when the routine completes or an exception is raised.

By default, segyio tries to open in strict mode. This means the file will be assumed to represent a geometry with consistent inline, crosslines and offsets. If strict is False, segyio will still try to establish a geometry, but it won’t abort if it fails. When in non-strict mode is opened, geometry-dependent modes such as iline will raise an error.

If ignore_geometry=True, segyio will not try to build iline/xline or other geometry related structures, which leads to faster opens. This is essentially the same as using strict=False on a file that has no geometry.

Parameters:	filename (str) – Path to file to open mode ({'r', 'r+'}) – File access mode, read-only (‘r’, default) or read-write (‘r+’) iline (int or segyio.TraceField) – Inline number field in the trace headers. Defaults to 189 as per the SEG-Y rev1 specification xline (int or segyio.TraceField) – Crossline number field in the trace headers. Defaults to 193 as per the SEG-Y rev1 specification strict (bool, optional) – Abort if a geometry cannot be inferred. Defaults to True. ignore_geometry (bool, optional) – Opt out on building geometry information, useful for e.g. shot organised files. Defaults to False. endian ({'big', 'msb', 'little', 'lsb'}) – File endianness, big/msb (default) or little/lsb
Returns:	file – An open segyio file handle
Return type:	segyio.SegyFile
Raises:	`ValueError` – If the mode string contains ‘w’, as it would truncate the file

Notes

New in version 1.1.

Changed in version 1.8: endian argument

When a file is opened non-strict, only raw traces access is allowed, and using modes such as iline raise an error.

Examples

Open a file in read-only mode:

>>> with segyio.open(path, "r") as f:
...     print(f.ilines)
...
[1, 2, 3, 4, 5]

Open a file in read-write mode:

>>> with segyio.open(path, "r+") as f:
...     f.trace = np.arange(100)

Open two files at once:

>>> with segyio.open(src_path) as src, segyio.open(dst_path, "r+") as dst:
...     dst.trace = src.trace # copy all traces from src to dst

Open a file little-endian file:

>>> with segyio.open(path, endian = 'little') as f:
...     f.trace[0]

open(filename, mode='r', iline=189, xline=193, strict=True, ignore_geometry=False, endian='big')¶

Open a seismic unix file.

Behaves identically to open(), except it expects the seismic unix format, not SEG-Y.

Parameters:	filename (str) – Path to file to open mode ({'r', 'r+'}) – File access mode, read-only (‘r’, default) or read-write (‘r+’) iline (int or segyio.TraceField) – Inline number field in the trace headers. Defaults to 189 as per the SEG-Y rev1 specification xline (int or segyio.TraceField) – Crossline number field in the trace headers. Defaults to 193 as per the SEG-Y rev1 specification strict (bool, optional) – Abort if a geometry cannot be inferred. Defaults to True. ignore_geometry (bool, optional) – Opt out on building geometry information, useful for e.g. shot organised files. Defaults to False. endian ({'big', 'msb', 'little', 'lsb'}) – File endianness, big/msb (default) or little/lsb
Returns:	file – An open seismic unix file handle
Return type:	segyio.su.file
Raises:	`ValueError` – If the mode string contains ‘w’, as it would truncate the file

See also

segyio.open(): SEG-Y open

Notes

New in version 1.8.

create(filename, spec)¶

Create a new segy file.

Create a new segy file with the geometry and properties given by spec. This enables creating SEGY files from your data. The created file supports all segyio modes, but has an emphasis on writing. The spec must be complete, otherwise an exception will be raised. A default, empty spec can be created with segyio.spec().

Very little data is written to the file, so just calling create is not sufficient to re-read the file with segyio. Rather, every trace header and trace must be written to the file to be considered complete.

Create should be used together with python’s with statement. This ensure the data is written. Please refer to the examples.

The segyio.spec() function will default sorting, offsets and everything in the mandatory group, except format and samples, and requires the caller to fill in all the fields in either of the exclusive groups.

If any field is missing from the first exclusive group, and the tracecount is set, the resulting file will be considered unstructured. If the tracecount is set, and all fields of the first exclusive group are specified, the file is considered structured and the tracecount is inferred from the xlines/ilines/offsets. The offsets are defaulted to [1] by segyio.spec().

Parameters:	filename (str) – Path to file to create spec (segyio.spec) – Structure of the segy file
Returns:	file – An open segyio file handle, similar to that returned by segyio.open
Return type:	segyio.SegyFile

See also

segyio.spec(): template for the spec argument

Notes

New in version 1.1.

Changed in version 1.4: Support for creating unstructured files

Changed in version 1.8: Support for creating lsb files

The spec is any object that has the following attributes

Mandatory:

iline   : int or segyio.BinField
xline   : int or segyio.BinField
samples : array of int
format  : { 1, 5 }
    1 = IBM float, 5 = IEEE float

Exclusive:

ilines  : array_like of int
xlines  : array_like of int
offsets : array_like of int
sorting : int or segyio.TraceSortingFormat

OR

tracecount : int

Optional:

ext_headers : int
endian : str { 'big', 'msb', 'little', 'lsb' }
    defaults to 'big'

Examples

Create a file:

>>> spec = segyio.spec()
>>> spec.ilines  = [1, 2, 3, 4]
>>> spec.xlines  = [11, 12, 13]
>>> spec.samples = list(range(50))
>>> spec.sorting = 2
>>> spec.format  = 1
>>> with segyio.create(path, spec) as f:
...     ## fill the file with data
...     pass
...

Copy a file, but shorten all traces by 50 samples:

>>> with segyio.open(srcpath) as src:
...     spec = segyio.spec()
...     spec.sorting = src.sorting
...     spec.format = src.format
...     spec.samples = src.samples[:len(src.samples) - 50]
...     spec.ilines = src.ilines
...     spec.xline = src.xlines
...     with segyio.create(dstpath, spec) as dst:
...         dst.text[0] = src.text[0]
...         dst.bin = src.bin
...         dst.header = src.header
...         dst.trace = src.trace

Copy a file, but shift samples time by 50:

>>> with segyio.open(srcpath) as src:
...     delrt = 50
...     spec = segyio.spec()
...     spec.samples = src.samples + delrt
...     spec.ilines = src.ilines
...     spec.xline = src.xlines
...     with segyio.create(dstpath, spec) as dst:
...         dst.text[0] = src.text[0]
...         dst.bin = src.bin
...         dst.header = src.header
...         dst.header = { TraceField.DelayRecordingTime: delrt }
...         dst.trace = src.trace

Copy a file, but shorten all traces by 50 samples (since v1.4):

>>> with segyio.open(srcpath) as src:
...     spec = segyio.tools.metadata(src)
...     spec.samples = spec.samples[:len(spec.samples) - 50]
...     with segyio.create(dstpath, spec) as dst:
...         dst.text[0] = src.text[0]
...         dst.bin = src.bin
...         dst.header = src.header
...         dst.trace = src.trace

File handle¶

class SegyFile¶

This class is not meant to be instantiated directly, but rather obtained from segyio.open or segyio.create.

attributes(field)¶

File-wide attribute (header word) reading

Lazily gather a single header word for every trace in the file. The array can be sliced, supports index lookup, and numpy-style list-of-indices.

Parameters:	field (int or segyio.TraceField) – field
Returns:	attrs – A sliceable array_like of header words
Return type:	Attributes

Notes

New in version 1.1.

close()¶

Close the file

This method is mostly useful for testing.

It is not necessary to call this method if you’re using the with statement, which will close the file for you. Calling methods on a previously-closed file will raise IOError.

Notes

New in version 1.1.

flush()¶

Flush the file

Write the library buffers to disk, like C’s fflush. This method is mostly useful for testing.

It is not necessary to call this method unless you want to observe your changes on-disk while the file is still open. The file will automatically be flushed for you if you use the with statement when your routine is completed.

Notes

New in version 1.1.

Warning

This is not guaranteed to actually write changes to disk, it only flushes the library buffers. Your kernel is free to defer writing changes to disk until a later time.

Examples

Flush:

>>> with segyio.open(path) as f:
...     # write something to f
...     f.flush()

group(word)¶

Get groups of traces matching a key

This feature is experimental, and there are no guarantees code using this will work in the future.

Walks the headers and groups traces into buckets, where all traces in a bucket have the same value for the given set of words. It is particularly useful for pre-stack files, gathering traces belonging to the same gather or shot.

Parameters:	word (segyio.TraceField or iterable of segyio.TraceField) – The set of words belonging to the same bucket
Returns:	groups
Return type:	segyio.gather.Groups

Notes

This feature is experimental, but you are encouraged to try it out. Bug reports and suggestions for improvement are welcomed, but no guarantees are made that the interface will remain as it is in the future.

interpret(ilines, xlines, offsets=None, sorting=2)¶

(Re-)interpret structure on top of a file

(Re-)interpret the structure of the file given the new sorting, ilines, xlines and offset indices. Note that file itself is not changed in any way, it is only segyio’s interpretation of the file that changes. It’s a way of telling segyio that a file is laid out in a particular way, even though the header fields say otherwise.

interpret expect that the ilines-, xlines- and offsets-indices are unique. It also expect the dimensions of ilines, xlines and offset to match the tracecount.

Parameters:	f (SegyFile) – ilines (array_like) – ilines indices in new structure xlines (array_like) – xlines indices in new structure offsets (array_like) – offset indices in new structure sorting (int, string or TraceSortingFormat) – Sorting in new structure

Notes

New in version 1.8.

Examples

(Re)interpret the structure of the file:

>>> ilines = [10, 11, 12, 13]
>>> xlines = [20, 21, 22, 23, 24]
>>> with segyio.open(file, ignore_geometry=True) as f:
... f.interpret(ilines, xlines)

mmap()¶

Memory map the file

Memory map the file. This is an advanced feature for speed and optimization; however, it is no silver bullet. If your file is smaller than the memory available on your system this will likely result in faster reads and writes, especially for line modes. However, if the file is very large, or memory is very pressured, this optimization might cause overall system slowdowns. However, if you’re opening the same file from many different instances of segyio then memory mapping may significantly reduce the memory pressure.

If this call returns true, the file is memory mapped. If memory mapping was build-time disabled or is not available for your platform this call always return false. If the memory mapping is unsuccessful you can keep using segyio - reading and writing falls back on non-memory mapped features.

Returns:	success – Returns True if the file was successfully memory mapped, False if not
Return type:	bool

Notes

New in version 1.1.

Examples

Memory map:

>>> mapped = f.mmap()
>>> if mapped: print( "File is memory mapped!" )
File is memory mapped!
>>> pass # keep using segyio as per usual
>>> print( f.trace[10][7] )
1.02548

bin¶

Interact with segy in binary mode

This mode gives access to reading and writing functionality for the binary header. Please note that using numeric binary offsets uses the offset numbers from the specification, i.e. the first field of the binary header starts at 3201, not 1. If you’re using the enumerations this is handled for you.

Returns:	binary
Return type:	Field

Notes

New in version 1.1.

depth_slice¶

Interact with segy in depth slice mode (fixed z-coordinate)

Returns:	depth
Return type:	Depth

Notes

New in version 1.1.

Changed in version 1.7.1: enabled for unstructured files

dtype¶

The data type object of the traces. This is the format most accurate and efficient to exchange with the underlying file, and the data type you will find the data traces.

Returns:	dtype
Return type:	numpy.dtype

Notes

New in version 1.6.

ext_headers¶

Extra text headers

The number of extra text headers, given by the ExtendedHeaders field in the binary header.

Returns:	headers – Number of extra text headers
Return type:	int

fast¶

Access the ‘fast’ dimension

This mode yields iline or xline mode, depending on which one is laid out faster, i.e. the line with linear disk layout. Use this mode if the inline/crossline distinction isn’t as interesting as traversing in a fast manner (typically when you want to apply a function to the whole file, line-by-line).

Returns:	fast – line addressing mode
Return type:	Line

Notes

New in version 1.1.

gather¶

Interact with segy in gather mode

Returns:	gather
Return type:	Gather

header¶

Interact with segy in header mode

Returns:	header
Return type:	Header

Notes

New in version 1.1.

iline¶

Interact with segy in inline mode

Returns:	iline
Return type:	Line or None
Raises:	`ValueError` – If the file is unstructured

Notes

New in version 1.1.

ilines¶

Inline labels

The inline labels in this file, if structured, else None

Returns:	inlines
Return type:	array_like of int or None

offsets¶

Return the array of offset names. For post-stack data, this array has a length of 1

Returns:	offsets
Return type:	numpy.ndarray of int

readonly¶

File is read-only

Returns:	readonly – True if this file is read-only
Return type:	bool

Notes

New in version 1.6.

samples¶

Return the array of samples with appropriate intervals.

Returns:	samples
Return type:	numpy.ndarray of int

Notes

It holds that len(f.samples) == len(f.trace[0])

slow¶

Access the ‘slow’ dimension

This mode yields iline or xline mode, depending on which one is laid out slower, i.e. the line with strided disk layout. Use this mode if the inline/crossline distinction isn’t as interesting as traversing in the slower direction.

Returns:	slow – line addressing mode
Return type:	Line

Notes

New in version 1.1.

sorting¶: Inline or crossline sorting, or Falsey (None or 0) if unstructured. :returns: sorting :rtype: int

text¶

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.

Returns:	text
Return type:	Text

See also

segyio.tools.wrap: line-wrap a text header

Notes

New in version 1.1.

trace¶

Interact with segy in trace mode.

Returns:	trace
Return type:	Trace

Notes

New in version 1.1.

tracecount¶

Number of traces in this file

Equivalent to len(f.trace)

Returns:	count – Number of traces in this file
Return type:	int

unstructured¶

If the file is unstructured, sophisticated addressing modes that require the file to represent a proper cube won’t work, and only raw data reading and writing is supported.

Returns:	unstructured – `True` if this file is unstructured, `False` if not
Return type:	bool

xline¶

Interact with segy in crossline mode

Returns:	xline
Return type:	Line or None
Raises:	`ValueError` – If the file is unstructured

Notes

New in version 1.1.

xlines¶

Crossline labels

The crosslane labels in this file, if structured, else None

Returns:	crosslines
Return type:	array_like of int or None

Addressing¶

Data trace¶

class Trace¶

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

New in version 1.1.

Changed in version 1.6: common list operations (collections.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

__getitem__(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
Return type:	numpy.ndarray of dtype or generator of numpy.ndarray of dtype

Notes

New in version 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]

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

__setitem__(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

New in version 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)])

count(value) → integer -- return number of occurrences of value¶

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

raw¶

An eager version of Trace

Returns:	raw
Return type:	RawTrace

ref¶

A write-back version of Trace

Returns:	ref – ref is returned in a context manager, and must be in a `with` statement
Return type:	RefTrace

Notes

New in version 1.6.

Examples

>>> with trace.ref as ref:
...     ref[10] += 1.617

class RawTrace¶

Behaves exactly like trace, except reads are done eagerly and returned as numpy.ndarray, instead of generators of numpy.ndarray.

__getitem__(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
Return type:	numpy.ndarray of dtype

Notes

New in version 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.

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

__setitem__(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

New in version 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)])

count(value) → integer -- return number of occurrences of value¶

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

raw¶

An eager version of Trace

Returns:	raw
Return type:	RawTrace

ref¶

A write-back version of Trace

Returns:	ref – ref is returned in a context manager, and must be in a `with` statement
Return type:	RefTrace

Notes

New in version 1.6.

Examples

>>> with trace.ref as ref:
...     ref[10] += 1.617

class RefTrace¶

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 Trace.ref. This feature requires a context manager, to guarantee modifications are written back to disk.

__getitem__(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
Return type:	numpy.ndarray of dtype

Notes

New in version 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)

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

__setitem__(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

New in version 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)])

count(value) → integer -- return number of occurrences of value¶

flush()¶

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

New in version 1.6.

This method is not intended as user-oriented functionality, but might be useful in certain contexts to provide stronger guarantees.

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

raw¶

An eager version of Trace

Returns:	raw
Return type:	RawTrace

ref¶

A write-back version of Trace

Returns:	ref – ref is returned in a context manager, and must be in a `with` statement
Return type:	RefTrace

Notes

New in version 1.6.

Examples

>>> with trace.ref as ref:
...     ref[10] += 1.617

Trace header and attributes¶

class Header¶

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

New in version 1.1.

Changed in version 1.6: common list operations (collections.Sequence)

__getitem__(i)¶

header[i]

ith header of the file, starting at 0.

Parameters:	i (int or slice) –
Returns:	field – dict_like header
Return type:	Field

Notes

New in version 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]

Read a field in every other header:

>>> [x[37] for x in header[::2]]
[1, 3, 1, 3, 1, 3]

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

__setitem__(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

New in version 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 })

count(value) → integer -- return number of occurrences of value¶

iline¶

Headers, accessed by inline

Returns:	line
Return type:	HeaderLine

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

xline¶

Headers, accessed by crossline

Returns:	line
Return type:	HeaderLine

class Attributes¶

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

New in version 1.1.

__getitem__(i)¶

attributes[:]

Parameters:	i (int or slice or array_like) –
Returns:	attributes
Return type:	array_like of dtype

Examples

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)

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

count(value) → integer -- return number of occurrences of value¶

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

Data line¶

class Line¶

The Line implements the dict interface, with a fixed set of int_like keys, the line numbers/labels. Data is read lazily from disk, so iteration does not consume much memory, and are returned as numpy.ndarrays.

It provides a convenient interface for reading data in a cartesian grid system, provided one exists and is detectable by segyio.

Lines can be accessed individually or with slices, and writing is done via assignment. Note that accessing lines uses the line numbers, not their position, so if a files has lines [2400..2500], accessing line [0..100] will be an error. Note that since each line is returned as a numpy.ndarray, meaning accessing the intersections of the inline and crossline is 0-indexed - orthogonal labels are not preserved.

Additionally, the line has a concept of offsets, which is useful when dealing with prestack files. Offsets are accessed via sub indexing, meaning iline[10, 4] will give you line 10 at offset 4. Please note that offset, like lines, are accessed via their labels, not their indices. If your file has the offsets [150, 250, 350, 450] and the lines [2400..2500], you can access the third offset with [2403, 350]. Please refer to the examples for more details. If no offset is specified, segyio will give you the first.

Notes

New in version 1.1.

Changed in version 1.6: common dict operations (collections.Mapping)

__contains__(key)¶: x.__contains__(y) <==> y in x

__getitem__(index)¶

line[i] or line[i, o]

The line i, or the line i at a specific offset o. line[i] returns a numpy array, and changes to this array will not be reflected on disk.

The i and o are keys, and should correspond to the line- and offset labels in your file, and in the ilines, xlines, and offsets attributes.

Slices can contain lines and offsets not in the file, and like with list slicing, these are handled gracefully and ignored.

When i or o is a slice, a generator of numpy arrays is returned. If the slice is defaulted (:), segyio knows enough about the structure to give you all of the respective labels.

When both i and o are slices, only one generator is returned, and the lines are yielded offsets-first, roughly equivalent to the double for loop:

>>> for line in lines:
...     for off in offsets:
...         yield line[line, off]
...

Parameters:	i (int or slice) – o (int or slice) –
Returns:	line
Return type:	numpy.ndarray of dtype or generator of numpy.ndarray of dtype
Raises:	`KeyError` – If i or o don’t exist

Notes

New in version 1.1.

Examples

Read an inline:

>>> x = line[2400]

Copy every inline into a list:

>>> l = [numpy.copy(x) for x in iline[:]]

Numpy operations on every other inline:

>>> for line in line[::2]:
...     line = line * 2
...     avg = np.average(line)

Read lines up to 2430:

>>> for line in line[:2430]:
...     line.mean()

Copy all lines at all offsets:

>>> l = [numpy.copy(x) for x in line[:,:]]

Copy all offsets of a line:

>>> x = numpy.copy(iline[10,:])

Copy all lines at a fixed offset:

>>> x = numpy.copy(iline[:, 120])

Copy every other line and offset:

>>> map(numpy.copy, line[::2, ::2])

Copy all offsets [200, 250, 300, 350, …] in the range [200, 800) for all lines [2420,2460):

>>> l = [numpy.copy(x) for x in line[2420:2460, 200:800:50]]

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

__setitem__(index, val)¶

line[i] = val or line[i, o] = val

Follows the same rules for indexing and slicing as line[i].

In either case, if the val iterable is exhausted before the line(s), assignment stops with whatever is written so far. If val is longer than an individual line, it’s essentially truncated.

Parameters:	i (int or slice) – offset (int or slice) – val (array_like) –
Raises:	`KeyError` – If i or o don’t exist

Notes

New in version 1.1.

Examples

Copy a full line:

>>> line[2400] = other[2834]

Copy first half of the inlines from g to f:

>>> line[:] = other[:labels[len(labels) / 2]]

Copy every other line consecutively:

>>> line[:] = other[::2]

Copy every third offset:

>>> line[:,:] = other[:,::3]

Copy a line into a set line and offset:

>>> line[12, 200] = other[21]

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

items()¶: D.values() -> generator of D’s (key,values), as 2-tuples

keys() → a set-like object providing a view on D's keys¶

values() → generator of D's values¶

Line header¶

class HeaderLine¶

The Line implements the dict interface, with a fixed set of int_like keys, the line numbers/labels. The values are iterables of Field objects.

Notes

New in version 1.1.

Changed in version 1.6: common dict operations (collections.Mapping)

__contains__(key)¶: x.__contains__(y) <==> y in x

__getitem__(index)¶

line[i] or line[i, o]

The line i, or the line i at a specific offset o. line[i] returns an iterable of Field objects, and changes to these will be reflected on disk.

The i and o are keys, and should correspond to the line- and offset labels in your file, and in the ilines, xlines, and offsets attributes.

Slices can contain lines and offsets not in the file, and like with list slicing, these are handled gracefully and ignored.

When i or o is a slice, a generator of iterables of headers are returned.

When both i and o are slices, one generator is returned for the product i and o, and the lines are yielded offsets-first, roughly equivalent to the double for loop:

>>> for line in lines:
...     for off in offsets:
...         yield line[line, off]
...

Parameters:	i (int or slice) – o (int or slice) –
Returns:	line
Return type:	iterable of Field or generator of iterator of Field
Raises:	`KeyError` – If i or o don’t exist

Notes

New in version 1.1.

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

__setitem__(index, val)¶

line[i] = val or line[i, o] = val

Follows the same rules for indexing and slicing as line[i]. If i is an int, and val is a dict or Field, that value is replicated and assigned to every trace header in the line, otherwise it’s treated as an iterable, and each trace in the line is assigned the next() yielded value.

If i or o is a slice, val must be an iterable.

In either case, if the val iterable is exhausted before the line(s), assignment stops with whatever is written so far.

Parameters:	i (int or slice) – offset (int or slice) – val (dict_like or iterable of dict_like) –
Raises:	`KeyError` – If i or o don’t exist

Notes

New in version 1.1.

Examples

Rename the iline 3 to 4:

>>> line[3] = { TraceField.INLINE_3D: 4 }
>>> # please note that rewriting the header won't update the
>>> # file's interpretation of the file until you reload it, so
>>> # the new iline 4 will be considered iline 3 until the file
>>> # is reloaded

Set offset line 3 offset 3 to 5:

>>> line[3, 3] = { TraceField.offset: 5 }

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

items()¶: D.values() -> generator of D’s (key,values), as 2-tuples

keys() → a set-like object providing a view on D's keys¶

values() → generator of D's values¶

Gather¶

class Gather¶

A gather is in this context the intersection of lines in a cube, i.e. all the offsets at some inline/crossline intersection. The primary data type is numpy.ndarray, with dimensions depending on the range of offsets specified.

Implements a dict_like lookup with the line and offset numbers (labels), not 0-based indices.

Notes

New in version 1.1.

__getitem__(index)¶

gather[i, x, o], gather[:,:,:]

Get the gather or range of gathers, defined as offsets intersection between an in- and a crossline. Also works on post-stack files (with only 1 offset), although it is less useful in those cases.

If offsets are omitted, the default is all offsets.

A group of offsets is always returned as an offset-by-samples numpy.ndarray. If either inline, crossline, or both, are slices, a generator of such ndarrays are returned.

If the slice of offsets misses all offsets, a special, empty ndarray is returned.

Parameters:	i (int or slice) – inline x (int or slice) – crossline o (int or slice) – offsets (default is :)
Returns:	gather
Return type:	numpy.ndarray or generator of numpy.ndarray

Notes

New in version 1.1.

Examples

Read one offset at an intersection:

>>> gather[200, 241, 25] # returns same shape as trace

Read all offsets at an intersection:

>>> gather[200, 241, :] # returns offsets x samples ndarray
>>> # If no offset is specified, this is implicitly (:)
>>> gather[200, 241, :] == gather[200, 241]

All offsets for a set of ilines, intersecting one crossline:

>>> gather[200:300, 241, :] == gather[200:300, 241]

Some offsets for a set of ilines, interescting one crossline:

>>> gather[200:300, 241, 10:25:5]

Some offsets for a set of ilines and xlines. This effectively yields a subcube:

>>> f.gather[200:300, 241:248, 1:10]

Depth¶

class Depth¶

The Depth implements the array interface, where every array element, the depth, is a numpy.ndarray of a horizontal cut of the volume. As all arrays it can be random accessed, iterated over, and read strided. Please note that SEG-Y data is laid out trace-by-trace on disk, so accessing horizontal cuts (fixed z-coordinates in a cartesian grid) is very inefficient.

This mode works even on unstructured files, because it is not reliant on in/crosslines to be sensible. Please note that in the case of unstructured depth slicing, the array shape == tracecount.

Notes

New in version 1.1.

Changed in version 1.6: common list operations (collections.Sequence)

Changed in version 1.7.1: enabled for unstructured files

Warning

Accessing the file by depth (fixed z-coordinate) is inefficient because of poor locality and many reads. If you read more than a handful depths, consider using a faster mode.

__getitem__(i)¶

depth[i]

ith depth, a horizontal cross-section of the file, starting at 0. depth[i] returns a numpy.ndarray, and changes to this array will not be reflected on disk.

When i is a slice, a generator of numpy.ndarray is returned.

The depth slices are returned as a fast-by-slow shaped array, i.e. an inline sorted file with 10 inlines and 5 crosslines has the shape (10,5). If the file is unsorted, the array shape == tracecount.

Be aware that this interface uses zero-based indices (like traces) and not keys (like ilines), so you can not use the values file.samples as indices.

Parameters:	i (int or slice) –
Returns:	depth
Return type:	numpy.ndarray of dtype or generator of numpy.ndarray of dtype

Notes

New in version 1.1.

Warning

The segyio 1.5 and 1.6 series, and 1.7.0, would return the depth_slice in the wrong shape for most files. Since segyio 1.7.1, the arrays have the correct shape, i.e. fast-by-slow. The underlying data was always fast-by-slow, so a numpy array reshape can fix programs using the 1.5 and 1.6 series.

Behaves like [] for lists.

Examples

Read a single cut (one sample per trace):

>>> x = f.depth_slice[199]

Copy every depth slice into a list:

>>> l = [numpy.copy(x) for x in depth[:]

Every third depth:

>>> for d in depth[::3]:
...     (d * 6).mean()

Read up to 250:

>>> for d in depth[:250]:
...     d.mean()

>>> len(ilines), len(xlines)
(1, 6)
>>> f.depth_slice[0]
array([[0.  , 0.01, 0.02, 0.03, 0.04, 0.05]], dtype=float32)

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

__setitem__(depth, val)¶

depth[i] = val

Write the ith depth, a horizontal cross-section, of the file, starting at 0. It accepts any array_like, but val must be at least as big as the underlying data slice.

If val is longer than the underlying trace, val is essentially truncated.

Parameters:	i (int or slice) – val (array_like) –

Notes

New in version 1.1.

Behaves like [] for lists.

Examples

Copy a depth:

>>> depth[4] = other[19]

Copy consecutive depths, and assign to a sub volume (inject a sub cube into the larger volume):

>>> depth[10:50] = other[:]

Copy into every other depth from an iterable:

>>> depth[::2] = other

count(value) → integer -- return number of occurrences of value¶

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

Text¶

class Text¶

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

Changed in version 1.7: common list operations (collections.Sequence)

__getitem__(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 = str(f.text[0])
>>> lines = map(''.join, zip( *[iter(text)] * 80))
>>> for line in lines:
...     print(line)
...

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

__setitem__(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]

count(value) → integer -- return number of occurrences of value¶

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

Trace and binary header¶

class Field¶

The Field implements the dict interface, with a fixed set of keys. It’s used for both binary- and trace headers. Any modifications to this dict_like object will be reflected on disk.

The keys can be integers, int_likes, or enumerations such as BinField, TraceField, and su. If raw, numerical offsets are used they must align with the defined byte offsets by the SEGY specification.

Notes

New in version 1.1.

Changed in version 1.3: common dict operations (update, keys, values)

Changed in version 1.6: more common dict operations (collections.MutableMapping)

__delitem__(key)¶

del d[key]

‘Delete’ the key by setting value to zero. Equivalent to d[key] = 0.

Notes

New in version 1.6.

__getitem__(key)¶

d[key]

Read the associated value of key.

key can be any iterable, to retrieve multiple keys at once. In this case, a mapping of key -> value is returned.

Parameters:	key (int, or iterable of int) –
Returns:	value
Return type:	int or dict_like

Notes

New in version 1.1.

Note

Since version 1.6, KeyError is appropriately raised on key misses, whereas IndexError was raised before. This is an old bug, since header types were documented to be dict-like. If you rely on catching key-miss errors in your code, you might want to handle both IndexError and KeyError for multi-version robustness.

Warning

segyio considers reads/writes full headers, not individual fields, and does the read from disk when this class is constructed. If the file is updated through some other handle, including a secondary access via f.header, this cache might be out-of-date.

Examples

Read a single value:

>>> d[3213]
15000

Read multiple values at once:

>>> d[37, 189]
{ 37: 5, 189: 2484 }
>>> d[37, TraceField.INLINE_3D]
{ 37: 5, 189: 2484 }

__iter__() <==> iter(x)¶

__len__() <==> len(x)¶

__setitem__(key, val)¶

d[key] = val

Set d[key] to val. Setting keys commits changes to disk, although the changes may not be visible until the kernel schedules the write.

Unlike d[key], this method does not support assigning multiple values at once. To set multiple values at once, use the update method.

Parameters:	key (int_like) – val (int_like) –
Returns:	val – The value set
Return type:	int

Notes

New in version 1.1.

Note

Since version 1.6, KeyError is appropriately raised on key misses, whereas IndexError was raised before. This is an old bug, since header types were documented to be dict-like. If you rely on catching key-miss errors in your code, you might want to handle both IndexError and KeyError for multi-version robustness.

Warning

segyio considers reads/writes full headers, not individual fields, and does the read from disk when this class is constructed. If the file is updated through some other handle, including a secondary access via f.header, this cache might be out-of-date. That means writing an individual field will write the full header to disk, possibly overwriting previously set values.

Examples

Set a value and keep in a variable:

>>> x = header[189] = 5
>>> x
5

clear() → None. Remove all items from D.¶

fetch(buf=None, traceno=None)¶

Fetch the header from disk

This object will read header when it is constructed, which means it might be out-of-date if the file is updated through some other handle. This method is largely meant for internal use - if you need to reload disk contents, use reload.

Fetch does not update any internal state (unless buf is None on a trace header, and the read succeeds), but returns the fetched header contents.

This method can be used to reposition the trace header, which is useful for constructing generators.

If this is called on a writable, new file, and this header has not yet been written to, it will successfully return an empty buffer that, when written to, will be reflected on disk.

Parameters:	buf (bytearray) – buffer to read into instead of `self.buf` traceno (int) –
Returns:	buf
Return type:	bytearray

Notes

New in version 1.6.

This method is not intended as user-oriented functionality, but might be useful in high-performance code.

flush()¶

Commit backing storage to disk

This method is largely internal, and it is not necessary to call this from user code. It should not be explicitly invoked and may be removed in future versions.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.¶

items() → a set-like object providing a view on D's items¶

keys() → a set-like object providing a view on D's keys¶

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair¶: as a 2-tuple; but raise KeyError if D is empty.

reload()¶

This object will read header when it is constructed, which means it might be out-of-date if the file is updated through some other handle.

It’s rarely required to call this method, and it’s a symptom of fragile code. However, if you have multiple handles to the same header, it might be necessary. Consider the following example:

>>> x = f.header[10]
>>> y = f.header[10]
>>> x[1, 5]
{ 1: 5, 5: 10 }
>>> y[1, 5]
{ 1: 5, 5: 10 }
>>> x[1] = 6
>>> x[1], y[1] # write to x[1] is invisible to y
6, 5
>>> y.reload()
>>> x[1], y[1]
6, 6
>>> x[1] = 5
>>> x[1], y[1]
5, 6
>>> y[5] = 1
>>> x.reload()
>>> x[1], y[1, 5] # the write to x[1] is lost
6, { 1: 6; 5: 1 }

In segyio, headers writes are atomic, and the write to disk writes the full cache. If this cache is out of date, some writes might get lost, even though the updates are compatible.

The fix to this issue is either to use reload and maintain buffer consistency, or simply don’t let header handles alias and overlap in lifetime.

Notes

New in version 1.6.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶

update([E, ]**F) → None. Update D from mapping/iterable E and F.¶

Overwrite the values in d with the keys from E and F. If any key in value is invalid in d, KeyError is raised.

This method is atomic - either all values in value are set in d, or none are. update does not commit a partially-updated version to disk.

For kwargs, Seismic Unix-style names are supported. BinField and TraceField are not, because there are name collisions between them, although this restriction may be lifted in the future.

Notes

Changed in version 1.3: Support for common dict operations (update, keys, values)

Changed in version 1.6: Atomicity guarantee

Changed in version 1.6: **kwargs support

Examples

>>> e = { 1: 10, 9: 5 }
>>> d.update(e)
>>> l = [ (105, 11), (169, 4) ]
>>> d.update(l)
>>> d.update(e, iline=189, xline=193, hour=5)
>>> d.update(sx=7)

values() → an object providing a view on D's values¶

Tools¶

collect(itr)¶

Collect traces or lines into one ndarray

Eagerly copy a series of traces, lines or depths into one numpy ndarray. If collecting traces or fast-direction over a post-stacked file, reshaping the resulting array is equivalent to calling segyio.tools.cube.

Parameters:	itr (iterable of numpy.ndarray) –
Returns:	data
Return type:	numpy.ndarray

Notes

New in version 1.1.

Examples

collect-cube identity:

>>> with segyio.open('post-stack.sgy') as f:
>>>     x = segyio.tools.collect(f.trace[:])
>>>     x = x.reshape((len(f.ilines), len(f.xlines), f.samples))
>>>     numpy.all(x == segyio.tools.cube(f))

create_text_header(lines)¶

Format textual header

Create a “correct” SEG-Y textual header. Every line will be prefixed with C## and there are 40 lines. The input must be a dictionary with the line number[1-40] as a key. The value for each key should be up to 76 character long string.

Parameters:

lines (dict) –

lines dictionary with fields:

no : line number (int)
line : line (str)

Returns: text

Return type: str

cube(f)¶

Read a full cube from a file

Takes an open segy file (created with segyio.open) or a file name.

If the file is a prestack file, the cube returned has the dimensions (fast, slow, offset, sample). If it is post-stack (only the one offset), the dimensions are normalised to (fast, slow, sample)

Parameters:	f (str or segyio.SegyFile) –
Returns:	cube
Return type:	numpy.ndarray

Notes

New in version 1.1.

dt(f, fallback_dt=4000.0)¶

Delta-time

Infer a dt, the sample rate, from the file. If none is found, use the fallback.

Parameters:	f (segyio.SegyFile) – fallback_dt (float) – delta-time to fall back to, in microseconds
Returns:	dt
Return type:	float

Notes

New in version 1.1.

from_array(filename, data, iline=189, xline=193, format=1, dt=4000, delrt=0)¶

Create a new SEGY file from an n-dimentional array. Create a structured SEGY file with defaulted headers from a 2-, 3- or 4-dimensional array. ilines, xlines, offsets and samples are inferred from the size of the array. Please refer to the documentation for functions from_array2D, from_array3D and from_array4D to see how the arrays are interpreted.

Structure-defining fields in the binary header and in the traceheaders are set accordingly. Such fields include, but are not limited to iline, xline and offset. The file also contains a defaulted textual header.

Parameters:

filename (string-like) – Path to new file
data (2-,3- or 4-dimensional array-like) –
iline (int or segyio.TraceField) – Inline number field in the trace headers. Defaults to 189 as per the SEG-Y rev1 specification
xline (int or segyio.TraceField) – Crossline number field in the trace headers. Defaults to 193 as per the SEG-Y rev1 specification
format (int or segyio.SegySampleFormat) – Sample format field in the trace header. Defaults to IBM float 4 byte
dt (int-like) – sample interval
delrt (int-like) –

Notes

New in version 1.8.

Examples

Create a file from a 3D array, open it and read an iline:

>>> segyio.tools.from_array(path, array3d)
>>> segyio.open(path, mode) as f:
...     iline = f.iline[0]
...

from_array2D(filename, data, iline=189, xline=193, format=1, dt=4000, delrt=0)¶

Create a new SEGY file from a 2D array Create an structured SEGY file with defaulted headers from a 2-dimensional array. The file is inline-sorted and structured as a slice, i.e. it has one iline and the xlinecount equals the tracecount. The tracecount and samplecount are inferred from the size of the array. Structure-defining fields in the binary header and in the traceheaders are set accordingly. Such fields include, but are not limited to iline, xline and offset. The file also contains a defaulted textual header.

The 2 dimensional array is interpreted as:

               samples
         --------------------
trace 0 | s0 | s1 | ... | sn |
         --------------------
trace 1 | s0 | s1 | ... | sn |
         --------------------
                  .
                  .
         --------------------
trace n | s0 | s1 | ... | sn |
         --------------------

traces = [0, len(axis(0)] samples = [0, len(axis(1)]

Parameters:

filename (string-like) – Path to new file
data (2-dimensional array-like) –
iline (int or segyio.TraceField) – Inline number field in the trace headers. Defaults to 189 as per the SEG-Y rev1 specification
xline (int or segyio.TraceField) – Crossline number field in the trace headers. Defaults to 193 as per the SEG-Y rev1 specification
format (int or segyio.SegySampleFormat) – Sample format field in the trace header. Defaults to IBM float 4 byte
dt (int-like) – sample interval
delrt (int-like) –

Notes

New in version 1.8.

Examples

Create a file from a 2D array, open it and read a trace:

>>> segyio.tools.from_array2D(path, array2d)
>>> segyio.open(path, mode, strict=False) as f:
...     tr = f.trace[0]

from_array3D(filename, data, iline=189, xline=193, format=1, dt=4000, delrt=0)¶

Create a new SEGY file from a 3D array Create an structured SEGY file with defaulted headers from a 3-dimensional array. The file is inline-sorted. ilines, xlines and samples are inferred from the array. Structure-defining fields in the binary header and in the traceheaders are set accordingly. Such fields include, but are not limited to iline, xline and offset. The file also contains a defaulted textual header.

The 3-dimensional array is interpreted as:

      xl0   xl1   xl2
     -----------------
  / | tr0 | tr1 | tr2 | il0
    -----------------
| / | tr3 | tr4 | tr5 | il1
     -----------------
| / | tr6 | tr7 | tr8 | il2
     -----------------
| /      /     /     / n-samples
  ------------------

ilines = [1, len(axis(0) + 1] xlines = [1, len(axis(1) + 1] samples = [0, len(axis(2)]

Parameters:

filename (string-like) – Path to new file
data (3-dimensional array-like) –
iline (int or segyio.TraceField) – Inline number field in the trace headers. Defaults to 189 as per the SEG-Y rev1 specification
xline (int or segyio.TraceField) – Crossline number field in the trace headers. Defaults to 193 as per the SEG-Y rev1 specification
format (int or segyio.SegySampleFormat) – Sample format field in the trace header. Defaults to IBM float 4 byte
dt (int-like) – sample interval
delrt (int-like) –

Notes

New in version 1.8.

Examples

Create a file from a 3D array, open it and read an iline:

>>> segyio.tools.from_array3D(path, array3d)
>>> segyio.open(path, mode) as f:
...     iline = f.iline[0]
...

from_array4D(filename, data, iline=189, xline=193, format=1, dt=4000, delrt=0)¶

Create a new SEGY file from a 4D array Create an structured SEGY file with defaulted headers from a 4-dimensional array. The file is inline-sorted. ilines, xlines, offsets and samples are inferred from the array. Structure-defining fields in the binary header and in the traceheaders are set accordingly. Such fields include, but are not limited to iline, xline and offset. The file also contains a defaulted textual header.

The 4D array is interpreted:

ilines = [1, len(axis(0) + 1] xlines = [1, len(axis(1) + 1] offsets = [1, len(axis(2) + 1] samples = [0, len(axis(3)]

Parameters:

filename (string-like) – Path to new file
data (4-dimensional array-like) –
iline (int or segyio.TraceField) – Inline number field in the trace headers. Defaults to 189 as per the SEG-Y rev1 specification
xline (int or segyio.TraceField) – Crossline number field in the trace headers. Defaults to 193 as per the SEG-Y rev1 specification
format (int or segyio.SegySampleFormat) – Sample format field in the trace header. Defaults to IBM float 4 byte
dt (int-like) – sample interval
delrt (int-like) –

Notes

New in version 1.8.

Examples

Create a file from a 3D array, open it and read an iline:

>>> segyio.tools.create_from_array4D(path, array4d)
>>> segyio.open(path, mode) as f:
...     iline = f.iline[0]
...

metadata(f)¶

Get survey structural properties and metadata

Create a description object that, when passed to segyio.create(), would create a new file with the same structure, dimensions, and metadata as f.

Takes an open segy file (created with segyio.open) or a file name.

Parameters:	f (str or segyio.SegyFile) –
Returns:	spec
Return type:	segyio.spec

Notes

New in version 1.4.

native(data, format=1, copy=True)¶

Convert numpy array to native float

Converts a numpy array from raw segy trace data to native floats. Works for numpy ndarrays.

Parameters:	data (numpy.ndarray) – format (int or segyio.SegySampleFormat) – copy (bool) – If True, convert on a copy, and leave the input array unmodified
Returns:	data
Return type:	numpy.ndarray

Notes

New in version 1.1.

Examples

Convert mmap’d trace to native float:

>>> d = np.memmap('file.sgy', offset = 3600, dtype = np.uintc)
>>> samples = 1500
>>> trace = segyio.tools.native(d[240:240+samples])

resample(f, rate=None, delay=None, micro=False, trace=True, binary=True)¶

Resample a file

Resample all data traces, and update the file handle to reflect the new sample rate. No actual samples (data traces) are modified, only the header fields and interpretation.

By default, the rate and the delay are in millseconds - if you need higher resolution, passing micro=True interprets rate as microseconds (as it is represented in the file). Delay is always milliseconds.

By default, both the global binary header and the trace headers are updated to reflect this. If preserving either the trace header interval field or the binary header interval field is important, pass trace=False and binary=False respectively, to not have that field updated. This only apply to sample rates - the recording delay is only found in trace headers and will be written unconditionally, if delay is not None.

Warning

This function requires an open file handle and is DESTRUCTIVE. It will modify the file, and if an exception is raised then partial writes might have happened and the file might be corrupted.

This function assumes all traces have uniform delays and frequencies.

Parameters:	f (SegyFile) – rate (int) – delay (int) – micro (bool) – if True, interpret rate as microseconds trace (bool) – Update the trace header if True binary (bool) – Update the binary header if True

Notes

New in version 1.4.

rotation(f, line='fast')¶

Find rotation of the survey

Find the clock-wise rotation and origin of line as (rot, cdpx, cdpy)

The clock-wise rotation is defined as the angle in radians between line given by the first and last trace of the first line and the axis that gives increasing CDP-Y, in the direction that gives increasing CDP-X.

By default, the first line is the ‘fast’ direction, which is inlines if the file is inline sorted, and crossline if it’s crossline sorted.

Parameters:

f (SegyFile) –
line ({ 'fast', 'slow', 'iline', 'xline' }) –

Returns:

rotation (float)
cdpx (int)
cdpy (int)

Notes

New in version 1.2.

sample_indexes(segyfile, t0=0.0, dt_override=None)¶

Creates a list of values representing the samples in a trace at depth or time. The list starts at t0 and is incremented with am*dt* for the number of samples. If a dt_override is not provided it will try to find a dt in the file.

Parameters:	segyfile (segyio.SegyFile) – t0 (float) – initial sample, or delay-recording-time dt_override (float or None) –
Returns:	samples
Return type:	array_like of float

Notes

New in version 1.1.

wrap(s, width=80)¶

Formats the text input with newlines given the user specified width for each line.

Parameters:	s (str) – width (int) –
Returns:	text
Return type:	str

Notes

New in version 1.1.

Constants¶

Trace header keys¶

class TraceField(enum_value)¶

Trace header field enumerator

See also

segyio.su: Seismic unix aliases for header fields

TRACE_SEQUENCE_LINE = 1¶

TRACE_SEQUENCE_FILE = 5¶

FieldRecord = 9¶

TraceNumber = 13¶

EnergySourcePoint = 17¶

CDP = 21¶

CDP_TRACE = 25¶

TraceIdentificationCode = 29¶

NSummedTraces = 31¶

NStackedTraces = 33¶

DataUse = 35¶

offset = 37¶

ReceiverGroupElevation = 41¶

SourceSurfaceElevation = 45¶

SourceDepth = 49¶

ReceiverDatumElevation = 53¶

SourceDatumElevation = 57¶

SourceWaterDepth = 61¶

GroupWaterDepth = 65¶

ElevationScalar = 69¶

SourceGroupScalar = 71¶

SourceX = 73¶

SourceY = 77¶

GroupX = 81¶

GroupY = 85¶

CoordinateUnits = 89¶

WeatheringVelocity = 91¶

SubWeatheringVelocity = 93¶

SourceUpholeTime = 95¶

GroupUpholeTime = 97¶

SourceStaticCorrection = 99¶

GroupStaticCorrection = 101¶

TotalStaticApplied = 103¶

LagTimeA = 105¶

LagTimeB = 107¶

DelayRecordingTime = 109¶

MuteTimeStart = 111¶

MuteTimeEND = 113¶

TRACE_SAMPLE_COUNT = 115¶

TRACE_SAMPLE_INTERVAL = 117¶

GainType = 119¶

InstrumentGainConstant = 121¶

InstrumentInitialGain = 123¶

Correlated = 125¶

SweepFrequencyStart = 127¶

SweepFrequencyEnd = 129¶

SweepLength = 131¶

SweepType = 133¶

SweepTraceTaperLengthStart = 135¶

SweepTraceTaperLengthEnd = 137¶

TaperType = 139¶

AliasFilterFrequency = 141¶

AliasFilterSlope = 143¶

NotchFilterFrequency = 145¶

NotchFilterSlope = 147¶

LowCutFrequency = 149¶

HighCutFrequency = 151¶

LowCutSlope = 153¶

HighCutSlope = 155¶

YearDataRecorded = 157¶

DayOfYear = 159¶

HourOfDay = 161¶

MinuteOfHour = 163¶

SecondOfMinute = 165¶

TimeBaseCode = 167¶

TraceWeightingFactor = 169¶

GeophoneGroupNumberRoll1 = 171¶

GeophoneGroupNumberFirstTraceOrigField = 173¶

GeophoneGroupNumberLastTraceOrigField = 175¶

GapSize = 177¶

OverTravel = 179¶

CDP_X = 181¶

CDP_Y = 185¶

INLINE_3D = 189¶

CROSSLINE_3D = 193¶

ShotPoint = 197¶

ShotPointScalar = 201¶

TraceValueMeasurementUnit = 203¶

TransductionConstantMantissa = 205¶

TransductionConstantPower = 209¶

TransductionUnit = 211¶

TraceIdentifier = 213¶

ScalarTraceHeader = 215¶

SourceType = 217¶

SourceEnergyDirectionMantissa = 219¶

SourceEnergyDirectionExponent = 223¶

SourceMeasurementMantissa = 225¶

SourceMeasurementExponent = 229¶

SourceMeasurementUnit = 231¶

UnassignedInt1 = 233¶

UnassignedInt2 = 237¶

classmethod enums()¶

Binary header keys¶

class BinField(enum_value)¶

Trace header field enumerator

See also

segyio.su: Seismic unix aliases for header fields

JobID = 3201¶

LineNumber = 3205¶

ReelNumber = 3209¶

Traces = 3213¶

AuxTraces = 3215¶

Interval = 3217¶

IntervalOriginal = 3219¶

Samples = 3221¶

SamplesOriginal = 3223¶

Format = 3225¶

EnsembleFold = 3227¶

SortingCode = 3229¶

VerticalSum = 3231¶

SweepFrequencyStart = 3233¶

SweepFrequencyEnd = 3235¶

SweepLength = 3237¶

Sweep = 3239¶

SweepChannel = 3241¶

SweepTaperStart = 3243¶

SweepTaperEnd = 3245¶

Taper = 3247¶

CorrelatedTraces = 3249¶

BinaryGainRecovery = 3251¶

AmplitudeRecovery = 3253¶

MeasurementSystem = 3255¶

ImpulseSignalPolarity = 3257¶

VibratoryPolarity = 3259¶

Unassigned1 = 3261¶

SEGYRevision = 3501¶

TraceFlag = 3503¶

ExtendedHeaders = 3505¶

Unassigned2 = 3507¶

classmethod enums()¶

Seismic Unix keys¶

Seismic Unix aliases

Seismic Unix style aliases for binary and trace header fields.

Notes

Seismic Unix does not have names for all possible fields, as it came around during an early revision of SEG-Y, and names for these fields are created by segyio in their absence. If Seismic Unix starts providing names for these fields, they will be added to these alies, and in conflicts take presedence after some time. If there are no conflicts, segyio names are considered for deprecation on a case-by-case basis, but will most likely be supported along with the Seismic Unix name.

tracl = 1¶

tracr = 5¶

fldr = 9¶

tracf = 13¶

ep = 17¶

cdp = 21¶

cdpt = 25¶

trid = 29¶

nvs = 31¶

nhs = 33¶

duse = 35¶

offset = 37¶

gelev = 41¶

selev = 45¶

sdepth = 49¶

gdel = 53¶

sdel = 57¶

swdep = 61¶

gwdep = 65¶

scalel = 69¶

scalco = 71¶

sx = 73¶

sy = 77¶

gx = 81¶

gy = 85¶

counit = 89¶

wevel = 91¶

swevel = 93¶

sut = 95¶

gut = 97¶

sstat = 99¶

gstat = 101¶

tstat = 103¶

laga = 105¶

lagb = 107¶

delrt = 109¶

muts = 111¶

mute = 113¶

ns = 115¶

dt = 117¶

gain = 119¶

igc = 121¶

igi = 123¶

corr = 125¶

sfs = 127¶

sfe = 129¶

slen = 131¶

styp = 133¶

stat = 135¶

stae = 137¶

tatyp = 139¶

afilf = 141¶

afils = 143¶

nofilf = 145¶

nofils = 147¶

lcf = 149¶

hcf = 151¶

lcs = 153¶

hcs = 155¶

year = 157¶

day = 159¶

hour = 161¶

minute = 163¶

sec = 165¶

timbas = 167¶

trwf = 169¶

grnors = 171¶

grnofr = 173¶

grnlof = 175¶

gaps = 177¶

otrav = 179¶

cdpx = 181¶

cdpy = 185¶

iline = 189¶

xline = 193¶

sp = 197¶

scalsp = 201¶

trunit = 203¶

tdcm = 205¶

tdcp = 209¶

tdunit = 211¶

triden = 213¶

sctrh = 215¶

stype = 217¶

sedm = 219¶

sede = 223¶

smm = 225¶

sme = 229¶

smunit = 231¶

uint1 = 233¶

uint2 = 237¶

jobid = 3201¶

lino = 3205¶

reno = 3209¶

ntrpr = 3213¶

nart = 3215¶

hdt = 3217¶

dto = 3219¶

hns = 3221¶

nso = 3223¶

format = 3225¶

fold = 3227¶

tsort = 3229¶

vscode = 3231¶

hsfs = 3233¶

hsfe = 3235¶

hslen = 3237¶

hstyp = 3239¶

schn = 3241¶

hstas = 3243¶

hstae = 3245¶

htatyp = 3247¶

hcorr = 3249¶

bgrcv = 3251¶

rcvm = 3253¶

mfeet = 3255¶

polyt = 3257¶

vpol = 3259¶

unas1 = 3261¶

rev = 3501¶

trflag = 3503¶

exth = 3505¶

unas2 = 3507¶

Sorting and formats¶

class TraceSortingFormat(enum_value)¶

UNKNOWN_SORTING = 0¶

CROSSLINE_SORTING = 1¶

INLINE_SORTING = 2¶

classmethod enums()¶

class SegySampleFormat(enum_value)¶

IBM_FLOAT_4_BYTE = 1¶

SIGNED_INTEGER_4_BYTE = 2¶

SIGNED_SHORT_2_BYTE = 3¶

FIXED_POINT_WITH_GAIN_4_BYTE = 4¶

IEEE_FLOAT_4_BYTE = 5¶

IEEE_FLOAT_8_BYTE = 6¶

SIGNED_CHAR_3_BYTE = 7¶

SIGNED_CHAR_1_BYTE = 8¶

SIGNED_INTEGER_8_BYTE = 9¶

UNSIGNED_INTEGER_4_BYTE = 10¶

UNSIGNED_SHORT_2_BYTE = 11¶

UNSIGNED_INTEGER_8_BYTE = 12¶

UNSIGNED_INTEGER_3_BYTE = 15¶

UNSIGNED_CHAR_1_BYTE = 16¶

NOT_IN_USE_1 = 19¶

NOT_IN_USE_2 = 20¶

classmethod enums()¶