Improved the help strings across files in NDH_Tools (ended at read_gpx)

Author: nholschuh

add_arrow.py

@@ -3,14 +3,27 @@
 
 def add_arrow(lines, position=None, direction='forward', size=15, color='black'):
     """
-    add an arrow to a line.
+    % (C) Nick Holschuh - Amherst College -- 2022 ([email protected])
+    %
+    % This function adds an arrow to a line. Adapted from:
+    % https://stackoverflow.com/questions/34017866/arrow-on-a-line-plot
+    %
+    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+    % The inputs are:
+    %     line:       Line2D object or list of lines
+    %     position:   x-position of the arrow. If None, mean of xdata is taken
+    %     direction:  'left' or 'right'
+    %     size:       size of the arrow in fontsize points
+    %     color:      if None, line color is taken.
+    %
+    %%%%%%%%%%%%%%%
+    % The outputs are:
+    %
+    %      N/A
+    %
+    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+    """    
 
-    line:       Line2D object or list of lines
-    position:   x-position of the arrow. If None, mean of xdata is taken
-    direction:  'left' or 'right'
-    size:       size of the arrow in fontsize points
-    color:      if None, line color is taken.
-    """
     if isinstance(lines,type([])) == 0:
         lines = [lines]
 

add_datavariable_xr.py

@@ -5,16 +5,21 @@ def add_datavariable_xr(xarray_dataset,new_datavariable,varname,coordinate_names
     """
     % (C) Nick Holschuh - Amherst College -- 2022 ([email protected])
     %
-    % This function uses xarray to construct a netcdf
+    % This function takes an existing xarray dataset and adds a new datavariable
+    % to the existing coordinate axes (assumed to be y and x)
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are:
-    %
+    %      xarray_dataset -- the existing xarray dataset to be added to
+    %      new_datavariable -- the array containing the new data to be added
+    %      varname -- the name for the new datavariable
+    %      coordinate_names -- default: ['y','x'], the names and order of 
+    %                          coordinate variables to assign to the dimensions
     %
     %%%%%%%%%%%%%%%
     % The outputs are:
     %
-    %
+    %      The updated xarray dataset
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     """    

box_from_corners.py

@@ -1,21 +1,22 @@
 import numpy as np
 
-
 def box_from_corners(xs,ys):
     """
     % (C) Nick Holschuh - Amherst College -- 2022 ([email protected])
     %
-    % This function prints out the minimum and maximum values of an array
+    % This function takes x and y edge values for a rectangle, and produces a
+    % 5x2 array of corner points that trace out the rectangle (for use in plotting)
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are:
     %
-    %     input_array -- array of data to analyze
+    %     xs - 2 value array contaiining the x edges of the rectangle
+    %     ys - 2 value array contaiining the y edges of the rectangle
     %
     %%%%%%%%%%%%%%%
     % The outputs are:
     %
-    %      output -- the min and max in a 1x2 array
+    %      box -- the 5x2 array containing the corner points for the rectangle
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     """ 

calculate_flowlines.py

@@ -20,17 +20,36 @@ def calculate_flowlines(input_xr,seed_points,uv_varnames=['u','v'],xy_varnames=[
     """
     % (C) Nick Holschuh - Amherst College -- 2022 ([email protected])
     %
-    % This function prints out the minimum and maximum values of an array
+    % This function takes a vector field described in an xarray dataset, an
+    % array of points, and calculates flowlines that pass through the array
+    % points following the vector field.
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are:
     %
-    %     input_xr -- xarray dataarray that has the gradient objects in it
+    %     input_xr -- this must be an xarray dataset with two dataarrays, represting
+    %                 the x components and the y components of a vector field. The data
+    %                 variables and the coordinate variables that describe them can have
+    %                 any name, but the defaults are 'u','v','x','y'.
+    %     seed_points -- this should be an nx2 array containing x/y pairs for seed points
+    %                    used to constrain the calculated flowlines
+    %     uv_varnames -- default=['u','v'], these are the datavariable names for the
+    %                    vector field components.
+    %     xy_varnames -- default=['x','y'], these are the coordinate variable names 
+    %                    describing the columns and rows of the vector field arrays
+    %     steps -- default=20000, this is the number of steps to take away from the seed
+    %               in either the forward or backward direction
+    %     ds -- default=2, this is the step-size to take when propagating the flowline away
+    %           from the seedpoint (in the same units as the coordinate variables
+    %     forward0_both1_backward2 -- default=1, this sets whether or not you want 
+    %                                 the flowlines to extend down-vector, up-vector, or
+    %                                 both from the seed point.
     %
     %%%%%%%%%%%%%%%
     % The outputs are:
     %
-    %      output -- the min and max in a 1x2 array
+    %      output -- a list of nx2 arrays containing the flowlines associated with
+    %                each seed point
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     """ 

clipped_colorbar.py

@@ -5,9 +5,9 @@ def clipped_colorbar(CS, **kwargs):
     """
     % (C) Nick Holschuh - Amherst College - 2022 ([email protected])
     % This function restricts the colorbar to the vmin/vmax values, so that 
-    % there aren't large chunks of the colorbar that are a single value. The
-    % default behavior is make a colorbar that spans the min value to max value,
-    % not the vmin/vmax. 
+    % there aren't large chunks of the colorbar that are a single value. This
+    % oposes Matplotlib's default behavior, which is to make a colorbar that 
+    % spans the min value to max value, not the vmin/vmax. 
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are as follows:
     %

cmap_data.py

@@ -1,11 +1,10 @@
 import matplotlib
 
-
 def cmap_data(colormapname):
     """
     % (C) Nick Holschuh - Amherst College -- 2022 ([email protected])
     %
-    % This function gets the colormap object for value extraction
+    % This function gets the colormap object from matplotlib for value extraction
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are:

compare_list.py

@@ -4,7 +4,10 @@ def compare_list(list1,list2):
     """
     % (C) Nick Holschuh - Amherst College -- 2022 ([email protected])
     %
-    % This function tests the equality of every item in a list
+    % This function compares entire lists, and spits out two comparative statistics:
+    %    1 -- Are all items across both lists both the same shape and same value
+    %    2 -- Are all items across both lists the same value
+    %    3 -- Are all items across both lists the same shape
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are:
@@ -13,9 +16,11 @@ def compare_list(list1,list2):
     %     list2 -- second list to compare
     %
     %%%%%%%%%%%%%%%
-    % The outputs are:
+    % The outputs, following the structure in the headline description:
     %
-    %      true/false
+    %      1: true/false
+    %      2: true/false
+    %      3: true/false
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     """ 

cresis_season.py

@@ -13,11 +13,11 @@ def cresis_season(y,m=0,d=0,ant1_gre2=1):
     """
     % (C) Nick Holschuh - Amherst College -- 2022 ([email protected])
     %
-    %     This function finds the season name associated with a flight day
-    % There are a small number of flight days in which both campaigns
+    %     This function finds the season name associated with a flight day.
+    % There are a small number of flight days in which two campaigns
     % were running apparently. By default, this code will assume you want
-    % the Antarctic Season. If you would prefer it prompt you to ask for
-    % a selection, chanage the value to zero.  
+    % the Antarctic Season. You can force it to take the greenland season using
+    % the given flag.
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are:

crop_image.py

@@ -4,13 +4,14 @@
 def crop_image(inimage,outimage,margin=0):
     """
     % (C) Nick Holschuh - Penn State University - 2015 ([email protected])
-    % This function takes an image file and removes the solid white margins.
+    % This function takes an image file and removes solid white margins.
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are as follows:
     %
-    % inimage -- the filename for the video to crop
-    % outimage -- the filename to write the cropped video to
-    % margin=0 -- the number of additional rows/columns to add as buffer
+    % inimage -- the filename for the image to crop
+    % outimage -- the filename to write the cropped image to
+    % margin=0 -- the number of additional rows/columns to add as buffer.
+    %             higher numbers here increases the addition of white margin
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The outputs are as follows:
@@ -23,7 +24,9 @@ def crop_image(inimage,outimage,margin=0):
 
     frame_aggregate = imageio.imread(inimage)
 
+    ######### Find the rows that are solid white
     row_margin = np.where(np.mean(frame_aggregate,0) == 255)[0]
+    ######### Find where the indeces of those rows jumps (as in, where the image is)
     middle = np.where(np.diff(row_margin) > 1)[0]
     x = row_margin[middle[0]]-margin
     w = row_margin[middle[-1]+1]-row_margin[middle[0]]+2*margin

crop_video.py

@@ -11,7 +11,8 @@ def crop_video(invideo,outvideo,margin=0):
     %
     % invideo -- the filename for the video to crop
     % outvideo -- the filename to write the cropped video to
-    % margin=0 -- the number of additional rows/columns to add as buffer
+    % margin=0 -- the number of additional rows/columns to add as buffer.
+    %             higher numbers here increases the addition of white margin
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The outputs are as follows:

crossovers.py

@@ -2,7 +2,25 @@
 
 
 def crossovers(line1,line2):
-
+    """
+    % (C) Nick Holschuh - Amherst College -- 2024 ([email protected])
+    % This function takes two lines and calculates any crossover points they may have
+    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+    % The inputs are as follows:
+    %
+    % line1 -- this takes an nx2 array with x and y coordinates for the first line
+    % line2 -- this takes an nx2 array with x and y coordinates for the second line
+    %
+    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+    % The outputs are as follows:
+    %
+    % crossover_dictionary -- the outpuut is a dictionary containing two things:
+    %       1: The indecies in line1 and line 2 that are nearest to the crossover
+    %       2: The position of the true crossover coordinates
+    %
+    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+    %%
+    """
     import numpy.core.umath_tests as ut
 
     x_down = line1[:,0]

depth_shift.py

@@ -34,7 +34,7 @@ def depth_shift(data,time,surface,elevation,bed=[],disp_flag=0):
     %%
     """
 
-    if np.nanmin(np.mod(surface,1)) == 0:
+    if np.nanmax(np.mod(surface,1)) == 0:
         ind_flag = 1;
     else:
         ind_flag = 0;

edgetrim_mask.py

@@ -9,12 +9,19 @@ def edgetrim_mask(edge_trim_array, debug_flag=0, start_trim=0, end_trim=0, addit
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are:
-    %
+    %      edge_trim_array -- this is typically a 64xn array, with values only
+    %                         where edge trim values have been identified.
+    %                         These typically are the 8th entry in the 'y' object 
+    %                         of a CSARP_surf file
+    %      debug_flag=0 -- this will produce a plot at the end showing the edge mask
+    %      start_trim=0 -- this removes additional columns at the front of the mask
+    %      end_trim=0 -- this removes additional columns from the end of the mask
+    %      additional_narrowing=0 -- this takes from both sides relative to the edge trim
     %
     %%%%%%%%%%%%%%%
     % The outputs are:
     %
-    %
+    %      mask -- a 64xn array of zeros and ones defined by the trim values
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % the edge trim array is typically surf_data['surf']['y'][7]
@@ -59,7 +66,7 @@ def edgetrim_mask(edge_trim_array, debug_flag=0, start_trim=0, end_trim=0, addit
 
 
     if debug_flag:
-        import matplotlib.pyplot as pltdd
+        import matplotlib.pyplot as plt
         plt.imshow(mask)
         plt.plot(et_col,et_row,'o',c='red')
         plt.plot(col_opts,left_row,'-',c='black')

elevation_shift.py

@@ -34,7 +34,7 @@ def elevation_shift(data,time,surface,elevation,bed,disp_flag=0):
     %%
     """
 
-    if np.nanmin(np.mod(surface,1)) == 0:
+    if np.nanmax(np.mod(surface,1)) == 0:
         ind_flag = 1;
     else:
         ind_flag = 0;

find_COPdem_fn.py

@@ -7,9 +7,24 @@
 
 def find_COPdem_fn(lat,lon):
     """
-    This is a function that outputs the filename associated wtih the desired latitude & longitude 
-    """
-    
+    % (C) Nick Holschuh - Amherst College -- 2022 ([email protected])
+    %
+    %     This is a function that outputs the filename associated wtih the 
+    %     desired latitude & longitude of the COPdem
+    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+    % The inputs are:
+    %
+    %     lat -- individual latitude value to use for search
+    %     lon -- individual longitude value to use for search
+    %
+    %%%%%%%%%%%%%%%
+    % The outputs are:
+    %
+    %      file_info -- the filename for the COPDem tile that you want
+    %
+    %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+    """ 
+
     from NDH_Tools import find_nearest_xy
     from NDH_Tools import loadmat
 

find_cresisfiles.py

@@ -9,7 +9,7 @@
 ################################################################################################
 
 
-def find_cresisfiles(y,m=0,d=0,seg=0,frame=0):
+def find_cresisfiles(y,m=0,d=0,seg=0,frm=0):
     """
     % (C) Nick Holschuh - Amherst College -- 2022 ([email protected])
     %
@@ -21,7 +21,8 @@ def find_cresisfiles(y,m=0,d=0,seg=0,frame=0):
     %     y - either the year, or a string for the filename you want the season for
     %     m - the month
     %     d - the day
-    %     ant1_gre2 - force a particular continent for days where there are surveys in both places
+    %     seg - the segment number
+    %     frm - the frame number
     %
     %%%%%%%%%%%%%%%
     % The outputs are:

find_nearest.py

@@ -1,28 +1,28 @@
 import numpy as np
 
-def find_nearest(vector_2_search,value,how_many=1):
+def find_nearest(vector_2_search,value):
     """
     % (C) Nick Holschuh - Penn State University - 2013 ([email protected])
     % In the way that the find commands finds values in a matrix identical to
     % the search vector, this command finds the nearest entry.
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     % The inputs are:
     %
-    % vector_2_search = The set of data that you want to search. Each entry
-    %                   should be a row. This also works with a n x m x 2
-    %                   matrix to search, with x y pairs in the 3rd dimension.
-    % value = The value you want to find within "vector_2_search" (row vector)
-    % how_many = The function will find the x nearest values to "value", where
-    %               x is an integer defined by "how_many"
-    %
+    % vector_2_search = The set of data that you want to search. Should be a 
+    %                   0 or 1 dimensional array (I don't get zero dimensional arrays)
+    % value = The value you want to find within "vector_2_search". Can be
+    %         a single value or an array of values.
     %
     %%%%%%%%%%%%%%%
-    % The outputs are:
+    % The output is a dictionary containing:
+    %
+    %       index = the index values for the location within "vector_2_search" where
+    %               the nearest possible values are stored.
     %
-    % index = the index values for the location within "vector_2_search" where
-    % the nearest possible values are stored.
+    %       distance = the distance between the values and their nearest point within
+    %                  the vector_2_search
     %
-    % results = the values themselves within the vector.
+    %       results = the values themselves within the vector.
     %
     %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     """