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: