Depreciated Loading SEG-Y

Warning

These methods have been depreciated in favour of the direct Xarray backend engine interface. Examples in this documentation have been updated to use the backend engine or consult the Backend Engine reference.

segy_loader(segyfile, cdp=None, iline=None, xline=None, cdp_x=None, cdp_y=None, offset=None, vert_domain='TWT', data_type='AMP', ix_crop=None, cdp_crop=None, xy_crop=None, z_crop=None, return_geometry=False, extra_byte_fields=None, head_df=None, **segyio_kwargs)

Load SEG-Y file into xarray.Dataset

The output dataset has the following structure Dimensions: cdp/iline - CDP or Inline axis xline - Xline axis twt/depth - The vertical axis offset - Offset/Angle Axis Coordinates: iline - The inline numbering xline - The xline numbering cdp_x - Eastings cdp_y - Northings cdp - Trace Number for 2d Variables data - The data volume Attributes: ns - number of samples vertical sample_rate - sample rate in ms/m test - text header measurement_system : m/ft source_file : segy source srd : seismic reference datum percentiles : data amplitude percentiles coord_scalar : from trace headers

Parameters:

Name	Type	Description	Default
segyfile	str	Input segy file path	required
cdp	int	The CDP byte location, usually 21.	None
iline	int	Inline byte location, usually 189	None
xline	int	Cross-line byte location, usually 193	None
cdp_x	int	UTMX byte location, usually 181	None
cdp_y	int	UTMY byte location, usually 185	None
offset	int	Offset/angle byte location	None
vert_domain	str	Vertical sampling domain. One of ['TWT', 'DEPTH']. Defaults to 'TWT'.	'TWT'
data_type	str	Data type ['AMP', 'VEL']. Defaults to 'AMP'.	'AMP'
ix_crop	list	List of minimum and maximum inline and crossline to output. Has the form '[min_il, max_il, min_xl, max_xl]'. Ignored for 2D data.	None
cdp_crop	list	List of minimum and maximum cmp values to output. Has the form '[min_cmp, max_cmp]'. Ignored for 3D data.	None
xy_crop	list	List of minimum and maximum cdp_x and cdp_y to output. Has the form '[min_x, max_x, min_y, max_y]'. Ignored for 2D data.	None
z_crop	list	List of minimum and maximum vertical samples to output. Has the form '[min, max]'.	None
return_geometry	bool	If true returns an xarray.dataset which doesn't contain data but mirrors the input volume header information.	False
extra_byte_fields	list / mapping	A list of int or mapping of byte fields that should be returned as variables in the dataset.	None
head_df	DataFrame	The DataFrame output from segy_header_scrape. This DataFrame can be filtered by the user to load select trace sets. Trace loading is based upon the DataFrame index.	None
**segyio_kwargs		Extra keyword arguments for segyio.open	{}

Returns:

Type	Description
	xarray.Dataset: If ncfile keyword is specified returns open handle to disk netcdf4, otherwise the data in memory. If return_geometry is True does not load trace data and returns headers in geometry.

Source code in segysak/segy/_segy_loader.py

def segy_loader(
    segyfile,
    cdp=None,
    iline=None,
    xline=None,
    cdp_x=None,
    cdp_y=None,
    offset=None,
    vert_domain="TWT",
    data_type="AMP",
    ix_crop=None,
    cdp_crop=None,
    xy_crop=None,
    z_crop=None,
    return_geometry=False,
    extra_byte_fields=None,
    head_df=None,
    **segyio_kwargs,
):
    """Load SEG-Y file into xarray.Dataset

    The output dataset has the following structure
        Dimensions:
            cdp/iline - CDP or Inline axis
            xline - Xline axis
            twt/depth - The vertical axis
            offset - Offset/Angle Axis
        Coordinates:
            iline - The inline numbering
            xline - The xline numbering
            cdp_x - Eastings
            cdp_y - Northings
            cdp - Trace Number for 2d
        Variables
            data - The data volume
        Attributes:
            ns - number of samples vertical
            sample_rate - sample rate in ms/m
            test - text header
            measurement_system : m/ft
            source_file : segy source
            srd : seismic reference datum
            percentiles : data amplitude percentiles
            coord_scalar : from trace headers

    Args:
        segyfile (str): Input segy file path
        cdp (int, optional): The CDP byte location, usually 21.
        iline (int, optional): Inline byte location, usually 189
        xline (int, optional): Cross-line byte location, usually 193
        cdp_x (int, optional): UTMX byte location, usually 181
        cdp_y (int, optional): UTMY byte location, usually 185
        offset (int, optional): Offset/angle byte location
        vert_domain (str, optional): Vertical sampling domain. One of ['TWT', 'DEPTH']. Defaults to 'TWT'.
        data_type (str, optional): Data type ['AMP', 'VEL']. Defaults to 'AMP'.
        ix_crop (list, optional): List of minimum and maximum inline and crossline to output.
            Has the form '[min_il, max_il, min_xl, max_xl]'. Ignored for 2D data.
        cdp_crop (list, optional): List of minimum and maximum cmp values to output.
            Has the form '[min_cmp, max_cmp]'. Ignored for 3D data.
        xy_crop (list, optional): List of minimum and maximum cdp_x and cdp_y to output.
            Has the form '[min_x, max_x, min_y, max_y]'. Ignored for 2D data.
        z_crop (list, optional): List of minimum and maximum vertical samples to output.
            Has the form '[min, max]'.
        return_geometry (bool, optional): If true returns an xarray.dataset which doesn't contain data but mirrors
            the input volume header information.
        extra_byte_fields (list/mapping): A list of int or mapping of byte fields that should be returned as variables in the dataset.
        head_df (pandas.DataFrame): The DataFrame output from `segy_header_scrape`. This DataFrame can be filtered by the user
            to load select trace sets. Trace loading is based upon the DataFrame index.
        **segyio_kwargs: Extra keyword arguments for segyio.open

    Returns:
        xarray.Dataset: If ncfile keyword is specified returns open handle to disk netcdf4,
            otherwise the data in memory. If return_geometry is True does not load trace data and
            returns headers in geometry.
    """
    warn(
        "segy_loader will be removed in v0.6, please use the Xarray engine ds = xr.open_dataset(segy_file) method instead.",
        DeprecationWarning,
        stacklevel=2,
    )

    extra_byte_fields = _loader_converter_checks(cdp, iline, xline, extra_byte_fields)

    head_df, head_bin, head_loc = _loader_converter_header_handling(
        segyfile,
        cdp=cdp,
        iline=iline,
        xline=xline,
        cdp_x=cdp_x,
        cdp_y=cdp_y,
        offset=offset,
        vert_domain=vert_domain,
        data_type=data_type,
        ix_crop=ix_crop,
        cdp_crop=cdp_crop,
        xy_crop=xy_crop,
        z_crop=z_crop,
        return_geometry=return_geometry,
        silent=Progress.silent(),
        extra_byte_fields=extra_byte_fields,
        head_df=head_df,
        **segyio_kwargs,
    )

    byte_loc = [
        bytel
        for bytel in [cdp, iline, xline, cdp_x, cdp_y, offset]
        if bytel is not None
    ]
    check_tracefield(byte_loc)

    common_args = (segyfile, head_df, head_bin, head_loc)

    common_kwargs = dict(
        zcrop=z_crop,
        vert_domain=vert_domain,
        data_type=data_type,
        return_geometry=return_geometry,
        silent=Progress.silent(),
    )

    # 3d data needs iline and xline
    if all(v is not None for v in (head_loc.iline, head_loc.xline)):
        print("Loading as 3D")
        ds = _3dsegy_loader(
            *common_args,
            **common_kwargs,
            **segyio_kwargs,
        )
        indexer = ["il_index", "xl_index"]
        dims = (
            DimensionKeyField.threed_head
            if offset is None
            else DimensionKeyField.threed_ps_head
        )
        is3d2d = True

    # 2d data
    elif head_loc.cdp is not None:
        print("Loading as 2D")
        ds = _2dsegy_loader(*common_args, **common_kwargs, **segyio_kwargs)
        indexer = ["cdp_index"]
        dims = (
            DimensionKeyField.twod_head
            if offset is None
            else DimensionKeyField.twod_ps_head
        )
        is3d2d = True

    # fallbak to just a 2d array of traces
    else:
        ds = _2dsegy_loader(*common_args, **common_kwargs, **segyio_kwargs)
        indexer = []
        dims = DimensionKeyField.cdp_2d
        is3d2d = False

    indexer = indexer + ["off_index"] if offset is not None else indexer

    ds = _loader_converter_write_headers(
        ds, head_df, indexer, dims, extra_byte_fields, is3d2d=is3d2d
    )

    # ds.seis.get_corner_points()
    return ds

segy_freeloader(segyfile, vert_domain='TWT', data_type='AMP', return_geometry=False, extra_byte_fields=None, head_df=None, segyio_kwargs=None, **dim_kwargs)

Freeform loader for SEG-Y data. This loader allows you to load SEG-Y into an xarray.Dataset using an arbitrary number of header locations to create othogonal dimensions. This is an eager loader and will transfer the entire SEG-Y and requested header information to memory.

From the dimension header locations specified the freeloader will try to create a Dataset where each trace is assigned to a dimension.

Parameters:

Name	Type	Description	Default
segyfile	string	The SEG-Y file/path.	required
vert_domain	str	One of ('TWT', 'DEPTH'). Defaults to 'TWT'.	'TWT'
data_type	str	Defaults to "AMP".	'AMP'
return_geometry	bool	If true, just returned the empty dataset based upon the calcuated header geometry. Defaults to False.	False
extra_byte_fields	dict	Additional header information to load into the Dataset. Defaults to None.	None
head_df	DataFrame	The DataFrame output from segy_header_scrape. This DataFrame can be filtered by the user to load select trace sets. Trace loading is based upon the DataFrame index.	None
segyio_kwargs	dict	Extra keyword arguments for segyio.open	None
**dim_kwargs		Dimension names and byte location pairs.	{}

Source code in segysak/segy/_segy_loader.py

def segy_freeloader(
    segyfile,
    vert_domain="TWT",
    data_type="AMP",
    return_geometry=False,
    extra_byte_fields=None,
    head_df=None,
    segyio_kwargs=None,
    **dim_kwargs,
):
    """Freeform loader for SEG-Y data. This loader allows you to load SEG-Y into
    an xarray.Dataset using an arbitrary number of header locations to create
    othogonal dimensions. This is an eager loader and will transfer the entire
    SEG-Y and requested header information to memory.

    From the dimension header locations specified the freeloader will try to
    create a Dataset where each trace is assigned to a dimension.

    Args:
        segyfile (string): The SEG-Y file/path.
        vert_domain (str, optional): One of ('TWT', 'DEPTH'). Defaults to 'TWT'.
        data_type (str, optional): Defaults to "AMP".
        return_geometry (bool, optional): If true, just returned the empty
            dataset based upon the calcuated header geometry. Defaults to False.
        extra_byte_fields (dict, optional): Additional header information to
            load into the Dataset. Defaults to None.
        head_df (pandas.DataFrame): The DataFrame output from `segy_header_scrape`.
            This DataFrame can be filtered by the user
            to load select trace sets. Trace loading is based upon the DataFrame index.
        segyio_kwargs (dict, optional): Extra keyword arguments for segyio.open
        **dim_kwargs: Dimension names and byte location pairs.
    """
    warn(
        "segy_loader will be removed in v0.6, please use the Xarray engine ds = xr.open_dataset(segy_file) method instead.",
        DeprecationWarning,
        stacklevel=2,
    )
    if segyio_kwargs is None:
        segyio_kwargs = dict()

    if head_df is None:
        # Start by scraping the headers.
        head_df = segy_header_scrape(segyfile, **segyio_kwargs)

    head_bin = segy_bin_scrape(segyfile, **segyio_kwargs)

    # get vertical sample ranges
    n0 = 0
    nsamp = head_bin["Samples"]
    ns0 = head_df.DelayRecordingTime.min()

    # binary header translation
    nsamp = head_bin["Samples"]
    sample_rate = head_bin["Interval"] / 1000.0
    msys = _SEGY_MEASUREMENT_SYSTEM[head_bin["MeasurementSystem"]]
    vert_samples = np.arange(ns0, ns0 + sample_rate * nsamp, sample_rate, dtype=int)

    # creating dimensions and new dataset
    dims = dict()
    dim_index_names = list()
    dim_fields = list()
    for dim in dim_kwargs:
        trace_field = str(segyio.TraceField(dim_kwargs[dim]))
        if trace_field == "Unknown Enum":
            raise ValueError(f"{dim}:{dim_kwargs[dim]} was not a valid byte header")
        dim_fields.append(trace_field)
        as_unique = head_df[trace_field].unique()
        dims[dim] = np.sort(as_unique)
        d_map = {dval: i for i, dval in enumerate(as_unique)}
        index_name = f"{dim}_index"
        dim_index_names.append(index_name)
        head_df.loc[:, index_name] = head_df[trace_field].map(d_map)

    if (
        head_df[dim_index_names].shape
        != head_df[dim_index_names].drop_duplicates().shape
    ):
        raise ValueError(
            "The selected dimensions results in multiple traces per "
            "dimension location, add additional dimensions or use "
            "trace numbering to load as 2D."
        )

    builder, domain = _dataset_coordinate_helper(vert_samples, vert_domain, **dims)
    ds = create_seismic_dataset(**builder)

    # getting attributes
    text = get_segy_texthead(segyfile, **segyio_kwargs)
    ds.attrs[AttrKeyField.text] = text
    ds.attrs[AttrKeyField.source_file] = pathlib.Path(segyfile).name
    ds.attrs[AttrKeyField.measurement_system] = msys
    ds.attrs[AttrKeyField.sample_rate] = sample_rate

    # map extra byte fields into ds
    if extra_byte_fields is not None:
        to_add = list()
        for name, byte in extra_byte_fields.items():
            trace_field = str(segyio.TraceField(byte))
            if trace_field == "Unknown Enum":
                raise ValueError(f"{name}:{byte} was not a valid byte header")
            to_add.append(trace_field)
        to_add = to_add + dim_fields
        extras = head_df[to_add].set_index(dim_fields).to_xarray()
        extras = extras.rename_dims(
            {b: a for a, b in zip(dim_kwargs, dim_fields) if a != b}
        )
        for name, xtr in zip(extra_byte_fields, to_add):
            ds[name] = extras[xtr]

    if return_geometry:
        # return geometry -> e.g. don't process segy traces
        return ds

    segyio_kwargs.update(dict(ignore_geometry=True))

    with segyio.open(segyfile, "r", **segyio_kwargs) as segyf:

        segyf.mmap()
        shape = [ds.sizes[d] for d in dim_kwargs] + [vert_samples.size]
        volume = np.zeros(shape, dtype=np.float32)

        # this can probably be done as a block - leaving for now just incase sorting becomes an issue
        indexes = tuple([head_df[idx].values for idx in dim_index_names])
        volume[indexes] = segyf.trace.raw[:][head_df.index.values]

    percentiles = np.percentile(volume, PERCENTILES)
    ds[VariableKeyField.data] = (
        list(dim_kwargs) + [VerticalKeyDim[domain]],
        volume,
    )
    ds.attrs[AttrKeyField.percentiles] = list(percentiles)

    return ds

segy_converter(segyfile, ncfile, cdp=None, iline=None, xline=None, cdp_x=None, cdp_y=None, offset=None, vert_domain='TWT', data_type='AMP', ix_crop=None, cdp_crop=None, xy_crop=None, z_crop=None, return_geometry=False, extra_byte_fields=None, **segyio_kwargs)

Convert SEG-Y data to NetCDF4 File

The output ncfile has the following structure Dimensions: cdp/iline - CDP or Inline axis xline - Xline axis twt/depth - The vertical axis offset - Offset/Angle Axis Coordinates: iline - The inline numbering xline - The xline numbering cdp_x - Eastings cdp_y - Northings cdp - Trace Number for 2d Variables data - The data volume Attributes: ns - number of samples vertical sample_rate - sample rate in ms/m test - text header measurement_system : m/ft source_file : segy source srd : seismic reference datum percentiles : data amplitude percentiles coord_scalar : from trace headers

Parameters:

Name	Type	Description	Default
segyfile	str	Input segy file path	required
ncfile	str	Output SEISNC file path. If none the loaded data will be returned in memory as an xarray.Dataset.	required
cdp	int	The CDP byte location, usually 21.	None
iline	int	Inline byte location, usually 189	None
xline	int	Cross-line byte location, usually 193	None
cdp_x	int	UTMX byte location, usually 181	None
cdp_y	int	UTMY byte location, usually 185	None
offset	int	Offset/angle byte location	None
vert_domain	str	Vertical sampling domain. One of ['TWT', 'DEPTH']. Defaults to 'TWT'.	'TWT'
data_type	str	Data type ['AMP', 'VEL']. Defaults to 'AMP'.	'AMP'
ix_crop	list	List of minimum and maximum inline and crossline to output. Has the form '[min_il, max_il, min_xl, max_xl]'. Ignored for 2D data.	None
cdp_crop	list	List of minimum and maximum cmp values to output. Has the form '[min_cmp, max_cmp]'. Ignored for 3D data.	None
xy_crop	list	List of minimum and maximum cdp_x and cdp_y to output. Has the form '[min_x, max_x, min_y, max_y]'. Ignored for 2D data.	None
z_crop	list	List of minimum and maximum vertical samples to output. Has the form '[min, max]'.	None
return_geometry	bool	If true returns an xarray.dataset which doesn't contain data but mirrors the input volume header information.	False
silent	bool	Disable progress bar.	required
extra_byte_fields	list / mapping	A list of int or mapping of byte fields that should be returned as variables in the dataset.a	None
**segyio_kwargs		Extra keyword arguments for segyio.open	{}

Source code in segysak/segy/_segy_loader.py

def segy_converter(
    segyfile,
    ncfile,
    cdp=None,
    iline=None,
    xline=None,
    cdp_x=None,
    cdp_y=None,
    offset=None,
    vert_domain="TWT",
    data_type="AMP",
    ix_crop=None,
    cdp_crop=None,
    xy_crop=None,
    z_crop=None,
    return_geometry=False,
    extra_byte_fields=None,
    **segyio_kwargs,
):
    """Convert SEG-Y data to NetCDF4 File

    The output ncfile has the following structure
        Dimensions:
            cdp/iline - CDP or Inline axis
            xline - Xline axis
            twt/depth - The vertical axis
            offset - Offset/Angle Axis
        Coordinates:
            iline - The inline numbering
            xline - The xline numbering
            cdp_x - Eastings
            cdp_y - Northings
            cdp - Trace Number for 2d
        Variables
            data - The data volume
        Attributes:
            ns - number of samples vertical
            sample_rate - sample rate in ms/m
            test - text header
            measurement_system : m/ft
            source_file : segy source
            srd : seismic reference datum
            percentiles : data amplitude percentiles
            coord_scalar : from trace headers

    Args:
        segyfile (str): Input segy file path
        ncfile (str): Output SEISNC file path. If none the loaded data will be
            returned in memory as an xarray.Dataset.
        cdp (int, optional): The CDP byte location, usually 21.
        iline (int, optional): Inline byte location, usually 189
        xline (int, optional): Cross-line byte location, usually 193
        cdp_x (int, optional): UTMX byte location, usually 181
        cdp_y (int, optional): UTMY byte location, usually 185
        offset (int, optional): Offset/angle byte location
        vert_domain (str, optional): Vertical sampling domain. One of ['TWT', 'DEPTH']. Defaults to 'TWT'.
        data_type (str, optional): Data type ['AMP', 'VEL']. Defaults to 'AMP'.
        ix_crop (list, optional): List of minimum and maximum inline and crossline to output.
            Has the form '[min_il, max_il, min_xl, max_xl]'. Ignored for 2D data.
        cdp_crop (list, optional): List of minimum and maximum cmp values to output.
            Has the form '[min_cmp, max_cmp]'. Ignored for 3D data.
        xy_crop (list, optional): List of minimum and maximum cdp_x and cdp_y to output.
            Has the form '[min_x, max_x, min_y, max_y]'. Ignored for 2D data.
        z_crop (list, optional): List of minimum and maximum vertical samples to output.
            Has the form '[min, max]'.
        return_geometry (bool, optional): If true returns an xarray.dataset which doesn't contain data but mirrors
            the input volume header information.
        silent (bool): Disable progress bar.
        extra_byte_fields (list/mapping): A list of int or mapping of byte fields that should be returned as variables in the dataset.a
        **segyio_kwargs: Extra keyword arguments for segyio.open

    """
    warn(
        "segy_converter will be removed in v0.6, please use Xarray engine ds = xr.open_dataset(file) and then accessor ds.seisio.to_segy method instead.",
        DeprecationWarning,
        stacklevel=2,
    )
    # Input sanity checks
    extra_byte_fields = _loader_converter_checks(cdp, iline, xline, extra_byte_fields)
    byte_loc = [
        bytel
        for bytel in [cdp, iline, xline, cdp_x, cdp_y, offset]
        if bytel is not None
    ]
    check_tracefield(byte_loc)

    head_df, head_bin, head_loc = _loader_converter_header_handling(
        segyfile,
        cdp=cdp,
        iline=iline,
        xline=xline,
        cdp_x=cdp_x,
        cdp_y=cdp_y,
        offset=offset,
        vert_domain=vert_domain,
        data_type=data_type,
        ix_crop=ix_crop,
        cdp_crop=cdp_crop,
        xy_crop=xy_crop,
        z_crop=z_crop,
        return_geometry=return_geometry,
        silent=Progress.silent(),
        extra_byte_fields=extra_byte_fields,
        optimised_load=True,
        **segyio_kwargs,
    )
    print("header_loaded")
    common_args = (segyfile, head_df, head_bin, head_loc)

    common_kwargs = dict(
        zcrop=z_crop,
        ncfile=ncfile,
        vert_domain=vert_domain,
        data_type=data_type,
        return_geometry=return_geometry,
        silent=Progress.silent(),
    )

    # 3d data needs iline and xline
    if iline is not None and xline is not None:

        print("is_3d")
        ds = _3dsegy_loader(
            *common_args,
            **common_kwargs,
            **segyio_kwargs,
        )
        indexer = ["il_index", "xl_index"]
        dims = (
            DimensionKeyField.threed_head
            if offset is None
            else DimensionKeyField.threed_ps_head
        )
        is3d2d = True

    # 2d data
    elif cdp is not None:
        ds = _2dsegy_loader(*common_args, **common_kwargs, **segyio_kwargs)
        indexer = ["cdp_index"]
        dims = (
            DimensionKeyField.twod_head
            if offset is None
            else DimensionKeyField.twod_ps_head
        )
        is3d2d = True

    # fallbak to just a 2d array of traces
    else:
        ds = _2dsegy_loader(*common_args, **common_kwargs, **segyio_kwargs)
        indexer = []
        dims = DimensionKeyField.cdp_2d
        is3d2d = False

    indexer = indexer + ["off_index"] if offset is not None else indexer

    ds = _loader_converter_write_headers(
        ds, head_df, indexer, dims, extra_byte_fields, is3d2d=is3d2d
    )
    new_vars = {key: ds[key] for key in extra_byte_fields}
    ds.close()
    del ds

    with h5netcdf.File(ncfile, "a") as seisnc:
        for var, darray in new_vars.items():
            seisnc_var = seisnc.create_variable(
                var, dimensions=darray.dims, dtype=darray.dtype
            )
            seisnc_var[...] = darray[...]
            seisnc.flush()

    return None

well_known_byte_locs(name)

Return common bytes position kwargs_dict for segy_loader and segy_converter.

Returns a dict containing the byte locations for well known SEG-Y variants in the wild.

Parameters:

Name	Type	Description	Default
name	str	Takes one of keys from KNOWN_BYTES	required

Returns:

Name	Type	Description
dict		A dictionary of SEG-Y byte positions.

Example:

Use the output of this function to unpack arguments into segy_loader

seismic = segy_loader(filepath, **well_known_byte_locs('petrel_3d'))

Source code in segysak/segy/_segy_loader.py

def well_known_byte_locs(name):
    """Return common bytes position kwargs_dict for segy_loader and segy_converter.

    Returns a dict containing the byte locations for well known SEG-Y variants in the wild.

    Args:
        name (str): Takes one of keys from KNOWN_BYTES

    Returns:
        dict: A dictionary of SEG-Y byte positions.

    Example:

    Use the output of this function to unpack arguments into ``segy_loader``

    >>> seismic = segy_loader(filepath, **well_known_byte_locs('petrel_3d'))

    """
    try:
        return KNOWN_BYTES[name]
    except KeyError:
        raise ValueError(
            f"No byte locatons for {name}, select from {list(KNOWN_BYTES.keys())}"
        )