updated functions documentation

Author: dantecn

OceanLab/utils.py

@@ -12,14 +12,15 @@
 def parallel_client(cpu_params=dict(tpw=2,nw=4,ml=7.5)):
     """
     Create client kernel for parallel computing
-
+    ====================================================
     INPUT:
         -> cpu_params: dict containing floats with keys
             -> tpw: threads_per_worker
             -> nw: n_workers
             -> ml: memory_limit per worker [GB]
     OUTPUT:
         -> client: configuration of parallel computing
+    ====================================================
     """
 
     client = Client(threads_per_worker=cpu_params['tpw'], 
@@ -33,19 +34,21 @@ def parallel_client(cpu_params=dict(tpw=2,nw=4,ml=7.5)):
 #=============================================================================
 def argdistnear(x,y,xi,yi):
     '''
-    This function finds the index to nearest points in (xi,yi) from (x,y).
-    
-    usage:
+    This function finds the index to nearest points in (xi,yi) from (x,y)
+    ======================================================================
+
+    USAGE:
     x,y = [5,1,10],[2,6,3]
     xi,yi = np.linspace(0,19,20),np.linspace(-5,30,20)
     ind = argdistnear(x,y,xi,yi)
 
     INPUT:
-    --> (x,y): points [list]
-    --> (xi,yi): series to search nearest point [list]
-    
-    Iury T.Simões-Sousa
-    (IO-USP/ UMass-Dartmouth)
+       (x,y)   = points [list]
+       (xi,yi) = series to search nearest point [list]
+
+    OUTPUT:
+       ind     = index of the nearest points
+    ======================================================================
     '''
 
     idxs = [np.argmin(np.sqrt((xi-xx)**2 + (yi-yy)**2)) for xx,yy in zip(x,y)]
@@ -59,36 +62,39 @@ def argdistnear(x,y,xi,yi):
 def meaneddy(prop,days=60,ndim=1,DataArray=False,timedim=None):
 
     """
-    Apply a low-pass filter (scipy.signal.butter) to 'prop' and obtain the mean and eddy components.
-    
-    usage [1]:
-    Velocity = np.random.randn(365,17,13) # one year, 17 lat x 13 lon domain
-    Filtered, Residual = meaneddy(Velocity, days=10, ndim=3, DataArray=False,timedim=None)
+    Apply a low-pass filter (scipy.signal.butter) to 'prop' and obtain the 
+     mean and eddy components.
+    ==========================================================================
+
+    USAGE [1]:
+    # np.array() one year, 17 lat x 13 lon domain
+    Velocity = np.random.randn(365,17,13)
+    Filtered, Residual = meaneddy(Velocity, days=10, ndim=3,
+                                   DataArray=False,timedim=None)
     
-    usage [2]:
-    Velocity = xr.DataArray(data=np.random.randn(365,17,13), dims=["time","lat","lon"],
-coords=dict(time=(["time"],range(0,365)), lat=(["lat"],np.arange(-4,4.5,0.5)), lon=(["lon"],np.arange(1,7.5,0.5)))) # one year, 17 lat x 13 lon domain
-    Filtered, Residual = meaneddy(Velocity, days=10, DataArray=True,timedim=["time"])
-
+    USAGE [2]:
+    # xr.DataArray() one year, 17 lat x 13 lon domain
+    Velocity = xr.DataArray(data=np.random.randn(365,17,13),
+                             dims=["time","lat","lon"],
+                             coords=dict(time=(["time"],range(0,365)),
+                             lat=(["lat"],np.arange(-4,4.5,0.5)),
+                             lon=(["lon"],np.arange(1,7.5,0.5))))
+    Filtered, Residual = meaneddy(Velocity, days=10,
+                                   DataArray=True,timedim=["time"])
     
     INPUT:
-       -> prop: 1, 2 or 3D array to filter
-       -> days: number of days to set up the filter
-       -> ndim: number of dimensions of the data [only used for DataArray=False, max:3]
-       -> DataArray: True if prop is in xr.DataArray format
-       -> dim: name of time dimension to filter (only used for DataArray=True)
+       prop      = 1, 2 or 3D array to be filtered
+       days      = number of days to set up the filter
+       ndim      = number of dimensions of the data
+                    [only used for DataArray=False, max:3]
+       DataArray = True if prop is in xr.DataArray format
+       dim       = name of time dimension to filter
+                    [only used for DataArray=True]
    
     OUTPUT:
-       -> m_prop: mean (filtered) part of the property
-       -> p_prop: prime part of the property, essentially prop - m_prop
-    
-    v1 (February 2018)
-    Cesar B. Rocha
-    Dante C. Napolitano ([email protected])
-    
-    v2 (December 2020)
-    Dante C. Napolitano ([email protected])
-    Mariana M. Lage ([email protected])
+       m_prop    = mean (filtered) part of the property
+       p_prop    = prime part of the property, essentially prop - m_prop
+    ==========================================================================
    """
 
     # creating filter