seisio.tools API documentation
Description: Tools to handle seismic trace headers as Numpy structured arrays.

# Module `seisio.tools`

Tools to handle seismic trace headers as Numpy structured arrays.

## Functions

`def add_mnemonic(headers, names=None, data=None, dtypes=None)`

  Add mnemonic(s) to structured array.

  This function can be used to add, for instance, a trace header mnemonic to the corresponding Numpy structured array.

  ## Parameters

  `headers` :`Numpy structured array`
    The header structure (e.g., trace headers).
  `names` :`str` or `list` of `str`
    The trace header mnemonics to add.
  `data` :`value` or `list` of `values, array` or `list` of `arrays, None`
    The data with which to fill the new header slots. If None, then the entries will be filled with zeros. If a single value is given, or a list of values where the length of the list corresponds to the number of mnemonics to add, each value will be used to initialize the corresponding new header slots. If an array is given where the length of the array corresponds to the number of traces in the header array, or a list of arrays where each individual array's length equals the number of traces, then each array will be used to initialize the corresponding new header slots.
  `dtypes` :`data type` or `list` of `data types`
    The data types for the new header mnemonics. If only a single data type is given but multiple mnemonics are added, then the single data type will be used for all new mnemonics.

  ## Returns

  `Numpy structured array`
    The original header array with the new mnemonics added and initialized.
`def ensemble2cube(ensemble, idef='xline', jdef='iline', is_sorted=False, header_trid='trid')`

  Convert a 2D ensemble to a 3D cube.

  The cube's dimensions are defined by the header mnemonics 'idef' and 'jdef' (plus the vertical axis, usually time or depth). This function will pad traces as required to form a regular cube. This can (and definitely will) happen when your data cover an area of non-rectangular shape, or in case your data coverage has holes. Keep in mind that for strangely shaped areas a lot of padding can occur. It is assumed that there are no duplicate trace positions in the input data, i.e., each idef/jdef position has only one trace.

  ## Parameters

  `ensemble` :`Numpy structured array`
    The 2D ensemble to reshape into a cube.
  `idef` :`str`, optional `(default: 'xline')`
    The header mnemonic present in the ensemble's trace headers that remains constant along the i-axis.
  `jdef` :`str`, optional `(default: 'iline')`
    The header mnemonic present in the ensemble's trace headers that remains constant along the j-axis.
  `is_sorted` :`bool`, optional `(default: False)`
    If the ensemble is already sorted by order=[idef, jdef], set this parameter to True to avoid an additional sort (copy). There is no check performed whether the ensemble is sorted correctly.
  `header_trid` :`str`, optional `(default: 'trid')`
    Trace header mnemonic to use in order to flag padded traces. If set to None, padded traces won't be flagged, otherwise the trace identification is set to 3 ('dummy').

  ## Returns

  `Numpy structured array`
    The data reshaped and possibly padded. If requested, padded traces have a trace identification of 3; they contain NaN as data values. The cube's dimensions ('idef', 'jdef') will be in ascending order.
`def remove_mnemonic(headers, names=None, allzero=False)`

  Remove mnemonic(s) from structured array.

  This function can be used to remove, for instance, a trace header mnemonic from the corresponding Numpy structured array. If you remove the "data" mnemonic, you end up with just the trace headers but no data values anymore.

  ## Parameters

  `headers` :`Numpy structured array`
    The header structure (e.g., trace headers).
  `names` :`str` or `list` of `str (default: None)`
    The trace header mnemonics to remove.
  `allzero` :`bool (default: False)`
    If True, all mnemonics that contain only zeros will be removed, possibly in addition to the mnemonics specified via 'names'.

  ## Returns

  `Numpy structured array`
    The original header array with the specified mnemonics removed.
`def rename_mnemonic(headers, mapping=None)`

  Rename mnemonic(s) in structured array.

  This function can be used to rename, for instance, a trace header mnemonic in the corresponding Numpy structured array.

  ## Parameters

  `headers` :`Numpy structured array`
    The header structure (e.g., trace headers).
  `namemap` :`dict`
    Dictionary mapping old name(s) to new name(s).

  ## Returns

  `Numpy structured array`
    The original header array with the specified mnemonics renamed.