gio package#

Submodules#

gio.esri module#

Read E00 format DEM (digital elevation model) files.

THIS IS A WORK IN PROGRESS. IT DOES NOT WORK YET.

copyright:

2022 Agile Geoscience

license:

Apache 2.0

gio.esri.read_e00_text(fname)#

Parse a bunch of E00 formatted text and emit a NumPy array.

gio.iesx module#

gio.iesx.check_dialect(fname)#

Decide if IESX file is from Petrel or OpendTect.

gio.iesx.read_iesx_from_petrel(filename, threed=False)#

Read a Petrel IESX file and create a GeoPandas DataFrame.

gio.opendtect module#

I/O for OpendTect horizon formats.

gio.opendtect.df_to_xarray(df, attrs=None, origin=(0, 0), step=(1, 1))#

Convert a DataFrame to a DataArray.

gio.opendtect.get_meta(fname, comment='#')#

Returns a string containing only the lines starting with the specified comment character. Does not read entire file.

gio.opendtect.get_names_from_header(header)#

Get names from header text.

gio.opendtect.read_odt(fname, names=None, usecols=None, na_values=None, origin=(0, 0), step=(1, 1), attrs=None)#

Read an OdT horizon file. (Native format, not IESX.)

Parameters:

  • names (list) –

    The names of the columns in the file. If there’s a header, this is not required. If there is no header, the function will attempt to interpret the columns:

    • If the first two columns are integers, they are interpreted

      as inline and crossline numbers.

    • If the first two columns are floats, and there is only one

      other column, then they are interpreted as (x, y) locations. Inline and crossline numbers will be generated, using origin as starting points.

    • In any other case, the function will throw an error;

      provide names to tell it what the columns are. Use ‘inline’ or ‘iline’ for inlines, ‘xline’ or ‘crossline’ for crosslines, ‘x’ or ‘cdp_x’ for x locations, and ‘y’ or ‘cdp_y’ for y locations. The names of your attributes are up to you.

    If there are 5 columns but you only give 4 names, then only the first 4 columns will be loaded.

  • usecols (list of ints) – The indices of the columns that correspond to the names you’re providing. If you’re loading all the columns, or the N names correspond to the first N columns, then you don’t need to provide this argument.

  • na_values (list of str) – The strings that correspond to missing data. By default, this is [‘1e30’], the deault NULL value in OpendTect. Any values you provide will replace this default and will be used to replace missing data with NaNs.

  • origin (tuple of ints) – If you only have (x, y) locations, then gio will try to construct a grid from them. It probably doesn’t always work. It will assign inline and crossline numbers, which will just be NumPy-like indices by default. If you provide an origin, it will start numbering there; if you provide a step, it will use that to increment the indices.

  • step (tuple of ints) – The step size of the grid (see origin, above).

  • attrs (dict) – The attributes to add to the Dataset; the filename will be added as ‘odt_filename’.

Returns:

Each data column will be a data variable. Inline and

crossline — and cdp_x and cdp_y, if present — will be coordinates.

Return type:

xarray.Dataset

gio.opendtect.read_odt_as_df(fname, names=None, usecols=None, na_values=None, **kwargs)#

Read an OdT file as a Pandas DataFrame.

Parameters:

  • fname (str) – Path to file.

  • names (list) – List of column names.

  • usecols (list) – List of column indices to use.

  • na_values (list) – List of values to treat as NA.

  • pandas.read_csv. (kwargs are passed to) –

Returns:

DataFrame containing the data.

Return type:

df (pandas.DataFrame)

gio.opendtect.regularize_columns(df, mapping=None, snake_case=True)#

Adjust the column names to use segyio / SEGY-SAK standard names. And optionally transform to snake case.

gio.opendtect.sense_types(data)#

Guess the type of some numbers.

gio.opendtect.to_odt(fname, dx, multi=False, twt=None, force_twt=True, name=None, dropna=True, header='multiline', **kwargs)#

Write an OdT horizon file. (Native format, not IESX.)

There is an unhealthy amount of magic in this function.

Parameters:

  • fname (str) – The name of the file to write.

  • dx (xarray.Dataset) – The data to write.

  • multi (bool) – Whether you want a multi-horizon export.

  • twt (str) – The name of the variable containing the two-way time, if not ‘twt’.

  • force_twt (bool) – Whether to force the first variable to be two-way time. If there’s more than one variable, this throws a warning.

  • dropna (bool) – If True, drop any rows with NaNs from the data. This is usual in OpendTect, but it may make the file harder to read by other software.

  • header (str) – The type of header to use. Either ‘multiline’ or ‘singleline’ is recommended, but ‘none’ will omit it entirely.

  • **kwargs – Additional arguments to pass to pandas.DataFrame.to_csv.

Returns:

None

gio.random module#

Random surfaces.

The code in this module was substantially adapted from Pierre Vigier’s code at https://github.com/pvigier/perlin-numpy

gio.random.fractal_noise(shape, res, rng=None, octaves=1, persistence=0.5, lacunarity=2, tileable=(False, False), interpolant=<function interpolant>)#

Generate a 2D numpy array of fractal noise.

By Pierre Vigier https://github.com/pvigier/perlin-numpy Licence: MIT

Parameters:

  • shape – The shape of the generated array (tuple of two ints). This must be a multiple of lacunarity**(octaves-1)*res.

  • res – The number of periods of noise to generate along each axis (tuple of two ints). Note shape must be a multiple of (lacunarity**(octaves-1)*res).

  • octaves – The number of octaves in the noise. Defaults to 1.

  • persistence – The scaling factor between two octaves.

  • lacunarity – The frequency factor between two octaves.

  • tileable – If the noise should be tileable along each axis (tuple of two bools). Defaults to (False, False).

  • interpolant – The, interpolation function, defaults to t*t*t*(t*(t*6 - 15) + 10).

Returns:

A numpy array of fractal noise and of shape shape generated by combining several octaves of perlin noise.

Raises:

ValueError – If shape is not a multiple of lacunarity**(octaves-1)*res.

gio.random.generate_random_surface(size, res=2, octaves=2, lacunarity=2, persistence=0.5, random_seed=None, name=None, coords='i,j')#

Make a square grid of at least the given size (length of side), with the given parameters. Size must be a multiple of lacunarity**(octaves-1)*res so the smallest possible size greater than the one provided is used.

Parameters:

  • size (int or tuple) – minimum length of side of the grid.

  • res (int or tuple) – number of periods of noise to generate along each axis.

  • octaves (int) – number of octaves of noise (bandwidth).

  • lacunarity (float) – lacunarity of the noise (frequency factor between octaves). Default: 2.

  • persistence (float) – persistence of the noise (amplitude factor between octaves). Default: 0.5.

  • random_seed (int) – random seed.

  • name (str) – name of the resulting array, optional. Default: None.

  • coords (str) – names of spatial coordinates, separated by commas. Default: i and j.

Returns:

the grid.

Return type:

xarray.DataArray

gio.random.interpolant(t)#

By Pierre Vigier https://github.com/pvigier/perlin-numpy Licence: MIT

gio.random.perlin_noise(shape, res, rng=None, tileable=(False, False), interpolant=<function interpolant>)#

Generate a 2D numpy array of perlin noise.

By Pierre Vigier https://github.com/pvigier/perlin-numpy Licence: MIT

Parameters:

  • shape – The shape of the generated array (tuple of two ints). This must be a multple of res.

  • res – The number of periods of noise to generate along each axis (tuple of two ints). Note shape must be a multiple of res.

  • tileable – If the noise should be tileable along each axis (tuple of two bools). Defaults to (False, False).

  • interpolant – The interpolation function, defaults to t*t*t*(t*(t*6 - 15) + 10).

Returns:

A numpy array of shape shape with the generated noise.

Raises:

ValueError – If shape is not a multiple of res.

gio.surfer module#

Read 2D ASCII/binary Surfer grid files.

copyright:

2022 Agile Geoscience (this adaptation)

license:

Apache 2.0

Adapted from Seequent’s steno3d_surfer: https://pypi.org/project/steno3d_surfer

copyright:

2018 Seequent

license:

MIT

MIT License Copyright (c) 2018 Seequent Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

gio.surfer.read_grd(fname)#
gio.surfer.read_surfer(fname)#

Reader for Surfer .grd files, supporting both Surfer 6 binary & ASCII files, and Surfer 7 binary files. Only (x, y)-orthogonal grids are supported.

Parameters:

fname (str) – The filename of the Surfer .grd file.

Returns:

The grid data.

Return type:

xarray.DataArray

gio.unmap module#

gio.unmap.unmap_to_dataarray(arr, cmap, extent=None, dims=None, **kwargs)#

Unmap data, via a colourmap, from an image. Reverse false-colouring.

Parameters:

  • arr – NumPy array of image data.

  • cmap – Either another array, or pixel extent of colourbar in image, or name of mpl colourbar or if None, just use lightness (say) If get pixels and they’re a few wide, then average them along short axis? Again, depends on scatter.

  • extent – The extent of the image, as a tuple (left, right, bottom, top), giving the real-world coordinates.

  • dims (tuple) – The dimensions of the image, as a tuple e.g. (‘x’, ‘y’) or (‘Lon’, ‘Lat’)).

  • **kwargs – Passed to unmap.unmap.

Returns:

An xarray.DataArray of the same shape as the input image, with the colourmap removed.

gio.xarray module#

xarray convenience class and accessor.

class gio.xarray.GridInfo(xmin: float, ymin: float, xmax: float, ymax: float, data: numpy.ndarray, dims: tuple = ('i', 'j'), source: str = '', fname: str = '')#

Bases: object

data: ndarray#
dims: tuple = ('i', 'j')#
fname: str = ''#
source: str = ''#
to_xarray()#

Convert to xarray.DataArray. Only (x, y)-orthogonal grids are supported.

xmax: float#
xmin: float#
ymax: float#
ymin: float#
class gio.xarray.SurfaceAccessor(xarray_obj)#

Bases: object

to_zmap(fname, coords=None, comment_attr='comment', add_comment='File created by gio.to_zmap xarray accessory', nodes_per_line=6, field_width=12, precision=3, null_value=-999.25)#

Write a DataArray to a ZMAP file.

Parameters:

  • fname (str) – path to ZMAP file.

  • coords (list or None) – list of coordinate names to use for the X and Y axes. If None, use the first two dimensions of the DataArray.

  • comment_attr (str or None) – name of the DataArray attribute to use as a comment in the file. If None, no comment is added.

  • add_comment (str or list or None) – comment to add to the end of any comments found in the DataArray. If None, no comment is added.

  • nodes_per_line (int) – number of values to write per line.

  • field_width (int) – character width of each value field.

  • precision (int) – number of decimal places to write.

  • null_value (float) – value to use for NaN values.

Returns:

None

gio.xy_to_grid module#

Special case: binning data with only (x, y) coords.

copyright:

2022 Agile Geoscience

license:

Apache 2.0

gio.xy_to_grid.get_intervals(x)#

From an unsorted and possibly sparse collection of 1D coordinates, compute the number of bins and the distance between bin centres.

Default is nearest-metre precision, which should be fine for most seismic surveys.

gio.xy_to_grid.nearest_neighbours(x, y, precision=5)#

Vector between 2 closest points. If there’s a tie (there likely will be), then we get the first point with a minimally nearest neighbour (and its first such neighbour).

The precision cut-off is needed to deal with floating-point imprecision.

gio.xy_to_grid.parabolic(f, x)#

Quadratic interpolation for estimating the true position of an inter-sample maximum when nearby samples are known.

f is a vector and x is an index for that vector.

Returns (vx, vy), the coordinates of the vertex of a parabola that goes through point x and its two neighbors.

Example: Defining a vector f with a local maximum at index 3 (= 6), find local maximum if points 2, 3, and 4 actually defined a parabola.

>>> import numpy as np
>>> f = [2, 3, 1, 6, 4, 2, 3, 1]
>>> parabolic(f, np.argmax(f))
(3.2142857142857144, 6.1607142857142856)
gio.xy_to_grid.rectify(X, vector)#

Rotate the geometry X, which should have columns (x, y, data). Data can be anything, just ones if you only have points to transform.

gio.xy_to_grid.xy_to_grid(x, y, data, compute_array=False)#

Bin a bunch of unsorted (x, y) datapoints into a regular grid.

Returns:

  • arr (ndarray): The binned data.

  • (dx, dy): The spacing between bins in the x and y directions.

  • (addx, addy): The destination of each data point into the grid;

    n.b. this is given in NumPy (row, col) format.

Return type:

tuple

gio.zmap module#

I/O for ZMAP grid formats.

gio.zmap.array_to_zmap(fname, arr, extent=None, comment='File created by gio.array_to_zmap', nodes_per_line=6, field_width=12, precision=3, null_value=-999.25, name='Z')#

Write a NumPy array as a ZMAP dat file.

Parameters:

  • fname (str) – path to output file.

  • arr (np.ndarray) – 2D array to write.

  • extent (None or list) – if not None, should be a list of 4 numbers representing the extent of the array in real-world coordinates, in the order [min_x, max_x, min_y, max_y].

  • comment (str or list) – comment to add to the file.

  • nodes_per_line (int) – number of values to write per line.

  • field_width (int) – character width of each value field.

  • precision (int) – number of decimal places to write.

  • null_value (float) – value to use for NaN values.

  • name (str) – name of the variable in the file.

Returns:

None

gio.zmap.dataarray_to_zmap(fname, da, coords=None, comment_attr='comments', add_comment='File created by gio.dataarray_to_zmap', nodes_per_line=6, field_width=12, precision=3, null_value=-999.25)#

Write an xarray.DataArray as a ZMAP dat file. For now we assume that dx is a DataArray.

Parameters:

  • fname (str) – path to output file.

  • da (xarray.DataArray) – 2D array to write.

  • coords (None or str) – If coords is None, then the first two coordinates are assumed to represent x and y respectively. If this is not the case, pass a single string with a comma separating the names of the coordinates to use, eg “UTMx,UTMy”. Note that the order of the coordinates might be different from the order of the dimensions in the DataArray (which is often y, x).

  • comment_attr (str or None) – the name of the DataArray attribute to use as a comment in the file, if any. If None, no comments are passed from the DataArray to the file.

  • add_comment (str or list or None) – comment to add to the end of any comments found in the DataArray. If None, no comment is added.

  • nodes_per_line (int) – number of values to write per line.

  • field_width (int) – character width of each value field.

  • precision (int) – number of decimal places to write.

  • null_value (float) – value to use for NaN values.

Returns:

None

gio.zmap.read_zmap(fname, add_attrs=True, add_comment='File read by gio.read_zmap')#

Read a ZMAP file and return an xarray.DataArray.

Parameters:

  • fname (str) – path to ZMAP file.

  • add_attrs (bool) – if True, add the ZMAP file’s metadata as attributes on the DataArray.

  • add_comment (str or None) – if not None, add this comment to the DataArray’s comment attribute (after any found in the ZMAP file).

Returns:

xarray.DataArray

Module contents#