Merge pull request #4 from maclariz/maclariz-patch-3

Update digital_dark_field.py

py4DSTEM/process/diffraction/digital_dark_field.py

@@ -117,8 +117,6 @@ def aperture_array_generator(
         (N,2) array containing the aperture positions in a centered coordinate system.
     fig, ax:
         Figure and axes handles for plot.
-
-
     """
 
     V, H = shape[0], shape[1]
@@ -232,6 +230,32 @@ def aperture_array_subtract(
     """
     This function takes in a set of aperture positions, and removes apertures within
     the user-specified tolerance from aperture_array_delete.
+    
+    Parameters
+    ----------
+    aperture_positions: tuple, list, np.array
+        2-element vector(s) of the diffraction space shape of positions of apertures
+    aperture_positions: tuple, list, np.array
+        2-element vector(s) of the diffraction space shape of positions of apertures to remove from the list
+    tol: float
+        a single number giving the tolerance for a maximum distance between aperture positions in the two lists to still be considered a match
+    plot_result: bool
+        Plot the aperture array
+    plot_marker_size: float
+        Marker size in points (standard matplotlib)
+    plot_marker_radius_pixels: float
+        Marker radius in pixels.
+    figsize: (float, float)
+        Figure size.
+    returnfig: bool
+        Set to true to return the figure handles.
+
+    Returns
+    ----------
+    aperture_positions:
+        (N,2) array containing the aperture positions in the image coordinate system.    
+    fig, ax:
+        Figure and axes handles for plot.
     """
 
     # Determine which apertures to keep
@@ -287,16 +311,23 @@ def pointlist_to_array(
     This function turns the py4dstem pointslist object to a simple numpy array that is more
     convenient for rapid array processing in numpy
 
-    idim and jdim are the dimensions in the Rx and Ry directions
+    idim and jdim are the dimensions in the Rx and Ry directions and are determined from the input
+   
+    Parameters
+    ----------
+    bplist: pointslist
+        py4dstem pointslist
 
-    returns an array called points_array
-        This will be an 2D numpy array of n points x 5 columns:
+    Returns
+    ----------
+    points_array: numpy array
+         This will be an 2D numpy array of n points x 5 columns:
             qx
             qy
             I
             Rx
             Ry
-    """
+   """
     for i, j in tqdmnd(bplist.Rshape[0], bplist.Rshape[1]):
         if i == j == 0:
             points_array = np.array(
@@ -324,10 +355,20 @@ def pointlist_to_array(
 
 def pointlist_differences(aperture_position, points_array):
     """
-    calculates differences between a specific aperture position
-    and a whole list of detected points for a dataset (as an array)
+    calculates Euclidean distances between a specific aperture position
+    and a whole list of detected points for a dataset
+
+    Parameters
+    ----------
+    aperture_position: tuple
+        2-element vector of the diffraction space shape of a position of an aperture
+    points_array: numpy array
+        as produced by pointlist_to_array and defined in docstring for that function
 
-    returns the Euclidean distances as a 1D numpy array
+    Returns
+    ----------
+    diff: numpy array
+        the Euclidean distances as a 1D numpy array
     """
     subtractor = np.array(
         [[aperture_position[0], aperture_position[1]] * points_array.shape[0]]
@@ -338,19 +379,26 @@ def pointlist_differences(aperture_position, points_array):
 
 def DDFimage(points_array, aperture_positions, Rshape=None, tol=1):
     """
-    points_array is an array of points as calculated by pointlist_to_array
-
-    aperture_positions is a numpy.array of aperture centers generated by aperture_array_generator,
-    with dimensions 2xN for N apertures.
-
-    Rshape is a 2 element vector giving the real space dimensions.  If not specified, we
-    take these value from the max along points_array.
-
-    tol is the tolerance for a displacement between points and centers (in pixels)
+    Calculates a Digital Dark Field image from a list of detected diffraction peak positions in a points_array and a list of aperture_positions, within a defined matching tolerance
+    
+    This does rely on the pointslist_differences function for the calculation
 
-    this does rely on the pointslist_differences function
+    Parameters
+    ----------
+    points_array: numpy array
+        as produced by pointlist_to_array and defined in docstring for that function
+    aperture_positions: tuple, list, np.array
+        2-element vector(s) of the diffraction space shape of positions of apertures
+    Rshape: tuple, list, array
+        a 2 element vector giving the real space dimensions.  If not specified, this is determined from the max along points_array
+    tol: float
+        the tolerance in pixels or calibrated units for a point in the points_array to be considered to match to an aperture position in the aperture_positions array
 
-    returns a the DDF image as a 2D numpy array
+    Returns
+    ----------
+    image: numpy array
+        2D numpy array with dimensions determined by Rshape
+    
     """
 
     if Rshape is None: