Groundhog GPR Processor Documentation#

Installation#

To install the Groundhog GPR processor:

pip install git+https://github.com/mchristoffersen/groundhog.git

Nominal Workflow#

The usual workflow for processing and interpreting raw Groundhog data looks like this:

Convert raw digitizer files to HDF5 with the ghog_mkh5 command line tool.
```
ghog_mkh5 /path/to/your/files/*.ghog
```

Run a processing script over the HDF5 files.

## Example processing script
import ghog

file = "/your/hdf5/file.h5"

# Load data
data = ghog.load(file)

# Fast time filter (edges in Hz)
data = ghog.filt(data, (0.5e6, 4e6), axis=0)

# NMO correction for 100 meter separation
data = ghog.nmo(data, 100)

# Restack to constant 5 m intervals between traces
data = ghog.restack(data, 5)

# Slow time filter (edges in wavenumber)
data = ghog.filt(data, (1/1000, 1/200), axis=1)

# Stolt migration with default 3.15 dielectric constant
data = ghog.stolt(data)

# Save back to the same HDF5 file in a group named restack
ghog.save(file, data, group="restack")

Use interpretation software, such as RAGU, to pick reflectors in the data.

There are two additional command line tools:

ghog_mkgpkg generates a Geopackage containing the position information of all of the HDF5 files it is directed to. The positionin information in each file is used to create a line object, and each line has the associated HDF5 file name as an attribute.

ghog_mkqlook generates a figure from each HDF5 file it is directed to, saving each figure in the same directory as the accompanying HDF5 file.

Python API#

`ghog.load`(file[, group])	Load a group from a Groundhog HDF5 file into memory.
`ghog.save`(file, data[, group, overwrite])	Save a group to a Groundhog HDF5 file.
`ghog.filt`(data, passband[, axis, order])	Apply a Butterworth filter along a data axis.
`ghog.nmo`(data, sep[, pnmo])	Normal move out and trigger delay correction.
`ghog.restack`(data, interval[, dcut])	Restack traces to constant distance intervals.
`ghog.stolt`(data[, pmig, ntaper, px, pt])	Perform Stolt migration.
`ghog.gain`(data[, tpow])	Apply gain to traces.
`ghog.mute`(data, indices[, axis])	Apply a mute to rows or columns of the data.
`ghog.figure`(data[, file, xunit, yunit, ...])	Generate radargram figure.

HDF5 I/O#

ghog.load(file, group='raw')#

Load a group from a Groundhog HDF5 file into memory.

Parameters:

file – Groundhog HDF5 data file.
group – Group in the HDF5 file to load (default = “raw”).

Returns:

Dictionary containing the 2D data array (rx), numpy structured array with per-column positions and times (gps), and data attributes (attrs).

ghog.save(file, data, group='proc', overwrite=False)#

Save a group to a Groundhog HDF5 file.

Parameters:

file – Groundhog HDF5 data file.
data – Groundhog data dictionary (rx, gps, attrs).
group – Group to save to in the HDF5 file (default = “proc”).
overwrite – Overwrite a group if it already exists in an HDF5 file (default = False).

Processing#

ghog.filt(data, passband, axis=0, order=4)#

Apply a Butterworth filter along a data axis.

Forward and backward for zero phase shift.

Parameters:

data – Groundhog data dictionary (rx, gps, attrs).
passband – (low, high) Tuple giving passband for filter, assumes units of hertz if axis=0, assumes wavenumber if axis=1 and stack_interval exists in attrs, otherwise assumes fraction of nyquist. Use None to denote no filter edge and create a low pass or high pass filter.
axis – Axis to filter along (default = 0).
order – Filter order (default = 4).

Returns:

Dictionary containing the filtered 2D data array (rx), numpy structured array with per-column positions and times (gps), and data attributes (attrs).

ghog.nmo(data, sep, pnmo=3.15)#

Normal move out and trigger delay correction.

Parameters:

data – Groundhog data dictionary (rx, gps, attrs).
sep – Separation between source and receiver in meters.
pnmo – Move out relative permittivity (default = 3.15).

Returns:

Dictionary containing the NMO corrected 2D data array (rx), numpy structured array with per-column positions and times (gps), and data attributes (attrs).

ghog.restack(data, interval, dcut=0)#

Restack traces to constant distance intervals.

Parameters:

data – Groundhog data dictionary (rx, gps, attrs).
interval – Constant distance interval to restack rx to. Must be greater than all original distance intervals in rx (this function does not interpolate).
dcut – Cutoff threshold for no motion between two traces. Distances below this threshold are set to zero for the purpose of restacking. Helpful for noisy position data (default = 0).

Returns:

Dictionary containing the restacked 2D data array (rx), numpy structured array with per-column positions and times (gps), and data attributes (attrs).

ghog.stolt(data, pmig=3.15, ntaper=32, px=None, pt=None)#

Perform Stolt migration.

This function performs Stolt migration.

Parameters:

data – Groundhog data dictionary (rx, gps, attrs).
pmig – Migration relative permittivity (default = 3.15).
ntaper – Taper width in pixels, applied to all sides of image (default = 32).
pt – Zero padding along time axis (default = 10x length of time axis).
px – Zero padding along distance axis (default = 1x length of distance axis).

Returns:

Dictionary containing the migrated 2D data array (rx), numpy structured array with per-column positions and times (gps), and data attributes (attrs)

ghog.gain(data, tpow=1)#

Apply gain to traces.

Parameters:

data – Groundhog data dictionary (rx, gps, attrs).
tpow – Power of time gain to apply to each trace (default = 1 : linear gain).

Returns:

Dictionary containing the gained 2D data array (rx), numpy structured array with per-column positions and times (gps), and data attributes (attrs).

ghog.mute(data, indices, axis=0)#

Apply a mute to rows or columns of the data.

Parameters:

data – Groundhog data dictionary (rx, gps, attrs).
indices – Indices of the rows or columns to mute.
axis – Axis on which to apply the mute (default = 0 : mute columns).

Returns:

Dictionary containing the muted 2D data array (rx), numpy structured array with per-column positions and times (gps), and data attributes (attrs).

Visualization#

ghog.figure(data, file='radargram.png', xunit='distance', yunit='time', title=None, pdepth=3.15, figsize=(8, 4), pclip=1, tpow=0, cmap='seismic', show=False)#

Generate radargram figure.

Parameters:

data – Groundhog data dictionary (rx, gps, attrs).
file – File name to save figure at. To not save an image use filename=None (default = “radargram.png”).
xunit – Unit for x axis, valid options are [“index”, “distance”] (default = “distance”).
yunit – Unit for y axis, valid options are [“index”, “time”, “depth”] if “depth” is chosen the pdepth argument is used to convert time to depth (default = “time”).
title – Title for the figure (default = None).
pdepth – Relative permittivity for y axis depth conversion (default = 3.15).
figsize – Figure dimension (x, y) in inches (default = (8, 4)).
pclip – Linear scaling clip percent, between 0 and 50 (default = 1).
tpow – Power of time exponential gain (default = 0 : no gain).
cmap – Matplotlib colormap to use (default = “seismic”).
show – Show figure in desktop window (default = False).

Command Line Tools#

ghog_mkh5#

Convert Groundhog digitizer files to HDF5.

usage: ghog_mkh5 [-h] [-o OUTPUT] [-v] files [files ...]

Positional Arguments#

files: Digitizer file(s) (X.ghog) to convert to HDF5. Should be in same directory as acompanying GPS files (X.txt).

Named Arguments#

-o, --output

Directory to write Groundhog HDF5 files to (default = ./).

Default: “.”

-v, --verbose

Verbose output

Default: False

ghog_mkgpkg#

Generate Geopackage containing trajectories from Groundhog HDF5 files.

usage: ghog_mkgpkg [-h] [-g GROUP] [-o OUTPUT] [-v] files [files ...]

Positional Arguments#

files: Groundhog HDF5 file(s)

Named Arguments#

-g, --group

Group to load from HDF5 file (default = raw)

Default: “raw”

-o, --output

Output Geopackage file (default = ghog_tracks.gpkg)

Default: “ghog_tracks.gpkg”

-v, --verbose

Verbose output

Default: False

ghog_mkqlook#

Generate quicklook figures of Groundhog HDF5 files.

usage: ghog_mkqlook [-h] [-g GROUP] [-v] files [files ...]

Positional Arguments#

files: Groundhog HDF5 file(s) to generate quicklooks from.

Named Arguments#

-g, --group

Group to load from HDF5 file (default = raw).

Default: “raw”

-v, --verbose

Verbose output

Default: False