adding user-specified lower velocity for pause detection

CHANGES.md

@@ -2,6 +2,7 @@
 
 ## changes since 0.0.20
 - changed file naming convention (outfile parameter is no longer clobbered by the naming function)
+- changed main python function to accept user-specified velocity threshold for pause correction function call
 
 ## changes since 0.0.19
 - added support for the "42000S" antenna name ([#34](https://github.com/iannesbitt/readgssi/issues/34) from [@GGDRriedel](https://github.com/GGDRriedel))

docs/processing.rst

@@ -163,8 +163,8 @@ This example distance normalizes and displays the X-axis in meters. Note the cha
 .. code-block:: python
 
     readgssi.readgssi(infile='DZT__001.DZT', outfile='2c.png', frmt=None,
-                      zero=[233], plot=5, stack='auto', gain=60,
-                      normalize=True, x='m')
+                      zero=[233], plotting=True, figsize=5, stack='auto',
+                      gain=60, normalize=True, x='m')
 
 .. code-block:: bash
 
@@ -203,7 +203,9 @@ of "paused" epochs from subsequent :code:`GSSIS` trace numbers in the DZG file.
 
 Additionally, all corrected GPS epochs will be written to a CSV file for easy integration into a GIS environment.
 
-The function can be implemented using the :code:`-P` flag in command line usage alongside distance normalization.
+The function can be implemented using the :code:`-P` flag in command line usage alongside distance normalization,
+or by specifying :code:`pausecorrect=True` in a :py:mod:`readgssi.readgssi` function call. To change the minimum pause
+detection velocity, specify a positive float value; for example :code:`pausecorrect=0.075`.
 
 .. warning:: This function will identify and remove ALL pauses longer than 3 epochs and renumber the traces accordingly.
     Obviously this can have unintended consequences if the radar controller remains collecting data during these periods.

readgssi/_version.py

@@ -1 +1 @@
-version = "0.0.20"
+version = "0.0.21"

readgssi/gps.py

@@ -248,7 +248,7 @@ def readdzg(fi, frmt, header, verbose=False):
 
 
 
-def pause_correct(header, dzg_file, threshold=0.25, verbose=False):
+def pause_correct(header, dzg_file, verbose=False, **kwargs):
     '''
     This is a streamlined way of removing pauses from DZG files and re-assigning trace values.
     GSSI controllers have a bug in which GPS sentences are collected with increasing trace numbers even though radar trace collection is stopped.
@@ -281,6 +281,14 @@ def pause_correct(header, dzg_file, threshold=0.25, verbose=False):
                 fx.printmsg('found backed up DZG file %s' % (backup_file))
         dzg_file = backup_file              # we always want to draw from the backup and write to the main DZG file
 
+        # threshold default
+        threshold = 0.25
+        # get threshold value from kwargs if it exists
+        for arg in kwargs:
+            if arg == "threshold":
+                if (type(kwargs[arg]) == float) or (type(kwargs[arg]) == int):
+                    threshold = float(kwargs[arg])
+
         # pandas ninja maneuvers to get a list of pause boundaries
         orig_gps = readdzg(fi=backup_file, frmt='dzg', header=header, verbose=False)    # get original GPS values
         orig_gps['groups'] = pd.cut(orig_gps.velocity,[-1,threshold,100000])            # segment file into groups based on velocity

readgssi/readgssi.py

@@ -76,7 +76,7 @@ def readgssi(infile, outfile=None, verbose=False, antfreq=None, frmt='python',
     :param bool title: Whether to display descriptive titles on plots. Defaults to :py:data:`True`.
     :param list[int,int,int,int] zoom: Zoom extents to set programmatically for matplotlib plots. Must pass a list of four integers: :py:data:`[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.
     :rtype: header (:py:class:`dict`), radar array (:py:class:`numpy.ndarray`), gps (False or :py:class:`pandas.DataFrame`)
-    :param bool pausecorrect: If :py:data:`True`, search the DZG file for pauses, where GPS keeps recording but radar unit does not, and correct them if necessary. Defaults to :py:data:`False`.
+    :param bool pausecorrect: If :py:data:`True` or minimum speed given as :py:data:`+float`, search the DZG file for pauses, where GPS keeps recording but radar unit does not, and correct them if necessary. Defaults to :py:data:`False`. Minimum speed defaults to 0.25 m/s.
     :param bool showmarks: If :py:data:`True`, display mark locations in plot. Defaults to :py:data:`False`.
     """
 
@@ -127,8 +127,14 @@ def readgssi(infile, outfile=None, verbose=False, antfreq=None, frmt='python',
     outfiles = {}
 
     if (pausecorrect) and (not gps.empty):
+        kwargs = {}
         fx.printmsg('correcting GPS errors created by user-initiated recording pauses...')
-        gps = pause_correct(header=header, dzg_file=os.path.splitext(infile)[0] + ".DZG", verbose=verbose)
+        if (type(pausecorrect) == float) or (type(pausecorrect) == int):
+            kwargs['threshold'] = pausecorrect
+            fx.printmsg('pause velocity threshold is %s m/s (user-specified)' % (kwargs['threshold']))
+        else:
+            fx.printmsg('pause velocity threshold is 0.25 m/s (default)')
+        gps = pause_correct(header=header, dzg_file=os.path.splitext(infile)[0] + ".DZG", verbose=verbose, **kwargs)
     elif (pausecorrect) and (gps.empty):
         fx.printmsg("can't correct pauses without a valid DZG file to look for. are you sure the DZG has the same name as the DZT file?")