readgssi.readgssi (main module)

readgssi.readgssi.main()

This function gathers and parses command line arguments with which to create function calls. It is not for use from the python console.

readgssi.readgssi.readgssi(infile, outfile=None, verbose=False, antfreq=None, frmt='python', plotting=False, figsize=7, dpi=150, stack=1, x='seconds', z='nanoseconds', histogram=False, colormap='gray', colorbar=False, zero=[None, None, None, None], gain=1, freqmin=None, freqmax=None, reverse=False, bgr=False, win=0, dewow=False, absval=False, normalize=False, specgram=False, noshow=False, spm=None, start_scan=0, num_scans=-1, epsr=None, title=True, zoom=[0, 0, 0, 0], pausecorrect=False, showmarks=False)

This is the primary directive function. It coordinates calls to reading, filtering, translation, and plotting functions, and should be used as the overarching processing function in most cases.

Parameters

  • infile (str) – Input DZT data file

  • outfile (str) – Base output file name for plots, CSVs, and other products. Defaults to None, which will cause the output filename to take a form similar to the input. The default will let the file be named via the descriptive naming function readgssi.functions.naming().

  • verbose (bool) – Whether or not to display (a lot of) information about the workings of the program. Defaults to False. Can be helpful for debugging but also to see various header values and processes taking place.

  • antfreq (int) – User setting for antenna frequency. Defaults to None, which will cause the program to try to determine the frequency from the antenna name in the header of the input file. If the antenna name is not in the dictionary readgssi.constants.ANT, the function will try to determine the frequency by decoding integers in the antenna name string.

  • frmt (str) – The output format to be passed to readgssi.translate. Defaults to None. Presently, this can be set to frmt='dzt', frmt='csv', 'numpy', 'gprpy', or 'object' (which will return the header dictionary, the image arrays, and the gps coordinates as objects). Plotting will not interfere with output (i.e. you can output to CSV and plot a PNG in the same command).

  • plotting (bool) – Whether to plot the radargram using readgssi.plot.radargram(). Defaults to False.

  • figsize (int) – Plot size in inches to be passed to readgssi.plot.radargram().

  • dpi (int) – Dots per inch (DPI) for figure creation.

  • stack (int) – Number of consecutive traces to stack (horizontally) using readgssi.arrayops.stack(). Defaults to 1 (no stacking). Especially good for handling long radar lines. Algorithm combines consecutive traces together using addition, which reduces noise and enhances signal. The more stacking is done, generally the clearer signal will become. The tradeoff is that you will reduce the length of the X-axis. Sometimes this is desirable (i.e. for long survey lines).

  • x (str) – The units to display on the x-axis during plotting. Defaults to x='seconds'. Acceptable values are x='distance' (which sets to meters), 'km', 'm', 'cm', 'mm', 'kilometers', 'meters', etc., for distance; 'seconds', 's', 'temporal' or 'time' for seconds, and 'traces', 'samples', 'pulses', or 'columns' for traces.

  • z (str) – The units to display on the z-axis during plotting. Defaults to z='nanoseconds'. Acceptable values are z='depth' (which sets to meters), 'm', 'cm', 'mm', 'meters', etc., for depth; 'nanoseconds', 'ns', 'temporal' or 'time' for seconds, and 'samples' or 'rows' for samples.

  • histogram (bool) – Whether to plot a histogram of array values at plot time.

  • colormap (str or matplotlib.colors.Colormap) – Plot using a Matplotlib colormap. Defaults to gray which is colorblind-friendly and behaves similarly to the RADAN default, but seismic is a favorite of many due to its diverging nature.

  • colorbar (bool) – Whether to display a graded color bar at plot time.

  • zero (list[int,int,int,int]) – A list of values representing the amount of samples to slice off each channel. Defaults to None for all channels, which will end up being set by the rh_zero variable in readgssi.dzt.readdzt().

  • gain (int) – The amount of gain applied to plots. Defaults to 1. Gain is applied as a ratio of the standard deviation of radargram values to the value set here.

  • freqmin (int) – Minimum frequency value to feed to the vertical triangular FIR bandpass filter readgssi.filtering.triangular(). Defaults to None (no filter).

  • freqmax (int) – Maximum frequency value to feed to the vertical triangular FIR bandpass filter readgssi.filtering.triangular(). Defaults to None (no filter).

  • reverse (bool) – Whether to read the array backwards (i.e. flip horizontally; readgssi.arrayops.flip()). Defaults to False. Useful for lining up travel directions of files run opposite each other.

  • bgr (int) – Background removal filter applied after stacking (readgssi.filtering.bgr()). Defaults to False (off). bgr=True must be accompanied by a valid value for win.

  • win (int) – Window size for background removal filter (readgssi.filtering.bgr()). If bgr=True and win=0, the full-width row average will be subtracted from each row. If bgr=True and win=50, a moving window will calculate the average of 25 cells on either side of the current cell, and subtract that average from the cell value, using scipy.ndimage.uniform_filter1d() with mode='constant' and cval=0. This is useful for removing non-uniform horizontal average, but the tradeoff is that it creates ghost data half the window size away from vertical figures, and that a window size set too low will obscure any horizontal layering longer than the window size.

  • dewow (bool) – Whether to apply a vertical dewow filter (experimental). See readgssi.filtering.dewow().

  • absval (bool) – If True, displays the absolute value of the vertical gradient of the array when plotting. Good for displaying faint array features.

  • normalize (bool) – Distance normalization (readgssi.arrayops.distance_normalize()). Defaults to False.

  • specgram (bool) – Produce a spectrogram of a trace in the array using readgssi.plot.spectrogram(). Defaults to False (if True, defaults to a trace roughly halfway across the profile). This is mostly for debugging and is not currently accessible from the command line.

  • noshow (bool) – If True, this will suppress the matplotlib interactive window and simply save a file. This is useful for processing many files in a folder without user input.

  • spm (float) – User-set samples per meter. This overrides the value read from the header, and typically doesn’t need to be set if the samples per meter value was set correctly at survey time. This value does not need to be set if GPS input (DZG file) is present and the user sets normalize=True.

  • start_scan (int) – zero based start scan to read data from. Defaults to zero.

  • num_scans (int) – number of scans to read from the file, Defaults to -1, which reads from start_scan to end of file.

  • epsr (float) – Epsilon_r, otherwise known as relative permittivity, or dielectric constant. This determines the speed at which waves travel through the first medium they encounter. It is used to calculate the profile depth if depth units are specified on the Z-axis of plots.

  • title (bool) – Whether to display descriptive titles on plots. Defaults to True.

  • zoom (list[int,int,int,int]) – Zoom extents to set programmatically for matplotlib plots. Must pass a list of four integers: [left, right, up, down]. Since the z-axis begins at the top, the “up” value is actually the one that displays lower on the page. All four values are axis units, so if you are working in nanoseconds, 10 will set a limit 10 nanoseconds down. If your x-axis is in seconds, 6 will set a limit 6 seconds from the start of the survey. It may be helpful to display the matplotlib interactive window at full extents first, to determine appropriate extents to set for this parameter. If extents are set outside the boundaries of the image, they will be set back to the boundaries. If two extents on the same axis are the same, the program will default to plotting full extents for that axis.

  • pausecorrect (bool) – If True or minimum speed given as +float, search the DZG file for pauses, where GPS keeps recording but radar unit does not, and correct them if necessary. Defaults to False. Minimum speed defaults to 0.25 m/s.

  • showmarks (bool) – If True, display mark locations in plot. Defaults to False.

Return type

header (dict), radar arrays by channel dict {0: numpy.ndarray, 1: numpy.ndarray, etc.}, gps (False or pandas.DataFrame)