[change] improved docstrings and testing of utils.py

pylot/core/util/utils.py

@@ -83,8 +83,8 @@ def clims(lim1, lim2):
 
 def demeanTrace(trace, window):
     """
-    returns the DATA where each trace is demean by the average value within
+    takes a trace object and returns the same trace object but with data
-    WINDOW
+    demeaned within a certain time window
     :param trace: waveform trace object
     :type trace: `~obspy.core.stream.Trace`
     :param window:
@@ -101,9 +101,9 @@ def findComboBoxIndex(combo_box, val):
     Function findComboBoxIndex takes a QComboBox object and a string and
     returns either 0 or the index throughout all QComboBox items.
     :param combo_box: Combo box object.
-    :type combo_box: QComboBox
+    :type combo_box: `~QComboBox`
     :param val: Name of a combo box to search for.
-    :type val:
+    :type val: basestring
     :return: index value of item with name val or 0
     """
     return combo_box.findText(val) if combo_box.findText(val) is not -1 else 0
@@ -111,21 +111,35 @@ def findComboBoxIndex(combo_box, val):
 
 def find_nearest(array, value):
     '''
-    Function find_nearest takes an array and a value and returns the
+    function find_nearest takes an array and a value and returns the
-    index of the nearest value found in the array.
+    index of the nearest value found in the array
-    :param array:
+    :param array: array containing values
-    :param value:
+    :type array: `~numpy.ndarray`
-    :return:
+    :param value: number searched for
+    :return: index of the array item being nearest to the value
+
+    >>> a = np.array([ 1.80339578, -0.72546654,  0.95769195, -0.98320759, 0.85922623])
+    >>> find_nearest(a, 1.3)
+    2
+    >>> find_nearest(a, 0)
+    1
+    >>> find_nearest(a, 2)
+    0
+    >>> find_nearest(a, -1)
+    3
+    >>> a = np.array([ 1.1, -0.7,  0.9, -0.9, 0.8])
+    >>> find_nearest(a, 0.849)
+    4
     '''
     return (np.abs(array - value)).argmin()
 
 
 def fnConstructor(s):
     '''
-
+    takes a string and returns a valid filename (especially on windows machines)
-    :param s:
+    :param s: desired filename
-    :type s:
+    :type s: str
-    :return:
+    :return: valid filename
     '''
     if type(s) is str:
         s = s.split(':')[-1]
@@ -143,7 +157,21 @@ def fnConstructor(s):
 
 
 def four_digits(year):
-    if year + 2000 < UTCDateTime.utcnow().year:
+    """
+    takes a two digit year integer and returns the correct four digit equivalent
+    from the last 100 years
+    :param year: two digit year
+    :type year: int
+    :return: four digit year correspondant
+
+    >>> four_digits(20)
+    1920
+    >>> four_digits(16)
+    2016
+    >>> four_digits(00)
+    2000
+    """
+    if year + 2000 <= UTCDateTime.utcnow().year:
         year += 2000
     else:
         year += 1900
@@ -152,10 +180,11 @@ def four_digits(year):
 
 def getGlobalTimes(stream):
     '''
-
+    takes a stream object and returns the latest end and the earliest start
-    :param stream:
+    time of all contained trace objects
-    :type stream
+    :param stream: seismological data stream
-    :return:
+    :type stream: `~obspy.core.stream.Stream`
+    :return: minimum start time and maximum end time
     '''
     min_start = UTCDateTime()
     max_end = None
@@ -169,6 +198,8 @@ def getGlobalTimes(stream):
 
 def getHash(time):
     '''
+    takes a time object and returns the corresponding SHA1 hash of the
+    formatted date string
     :param time: time object for which a hash should be calculated
     :type time: :class: `~obspy.core.utcdatetime.UTCDateTime` object
     :return: str
@@ -180,27 +211,26 @@ def getHash(time):
 
 def getLogin():
     '''
-
+    returns the actual user's login ID
-    :return:
+    :return: login ID
     '''
     return pwd.getpwuid(os.getuid())[0]
 
 
 def getOwner(fn):
     '''
-
+    takes a filename and return the login ID of the actual owner of the file
-    :param fn:
+    :param fn: filename of the file tested
-    :type fn:
+    :type fn: str
-    :return:
+    :return: login ID of the file's owner
     '''
     return pwd.getpwuid(os.stat(fn).st_uid).pw_name
 
 
 def getPatternLine(fn, pattern):
     """
-    Takes a file name and a pattern string to search for in the file and
+    takes a file name and a pattern string to search for in the file and
-    returns the first line which contains the pattern string otherwise None.
+    returns the first line which contains the pattern string otherwise 'None'
-
     :param fn: file name
     :type fn: str
     :param pattern: pattern string to search for
@@ -223,22 +253,52 @@ def getPatternLine(fn, pattern):
 
 def isSorted(iterable):
     '''
-    Takes an iterable and checks if args* are in order.
+    takes an iterable and returns 'True' if the items are in order otherwise
-    :param iterable: any with defined __ls__() and __gs__()
+    'False'
-    :type iterable: list
+    :param iterable: an iterable object
+    :type iterable:
     :return: Boolean
+
+    >>> isSorted(1)
+    Traceback (most recent call last):
+    ...
+    AssertionError: object is not iterable; object: 1
+    >>> isSorted([1,2,3,4])
+    True
+    >>> isSorted('abcd')
+    True
+    >>> isSorted('bcad')
+    False
+    >>> isSorted([2,3,1,4])
+    False
     '''
+    assert isIterable(iterable), 'object is not iterable; object: {' \
+                                 '0}'.format(iterable)
+    if type(iterable) is str:
+        iterable = [s for s in iterable]
     return sorted(iterable) == iterable
 
 
+def isIterable(obj):
+    """
+    takes a python object and returns 'True' is the object is iterable and
+    'False' otherwise
+    :param obj: a python object
+    :return: True of False
+    """
+    try:
+        iterator = iter(obj)
+    except TypeError as te:
+        return False
+    return True
+
 def prepTimeAxis(stime, trace):
     '''
-
+    takes a starttime and a trace object and returns a valid time axis for
-    :param stime:
+    plotting
-    :type stime:
+    :param stime: start time of the actual seismogram as UTCDateTime
-    :param trace:
+    :param trace: seismic trace object
-     :type trace:
+    :return: valid numpy array with time stamps for plotting
-    :return:
     '''
     nsamp = trace.stats.npts
     srate = trace.stats.sampling_rate