Merge pull request #16 from JacksonBurns/docs-dev

update dev docs

crow/Crow.py

@@ -32,9 +32,18 @@ class CrowBase(tk.Frame):
     including raw data and input data, as well as holding the notebook
     which containts the 3 tabs (PrePull, Pull, Present)
 
+    Args:
+        tk (tk.Frame): tkinter base window.
     """
 
     def __init__(self, master):
+        """
+        Constructor for the base Crow UI, containing the file selection interface
+        as well as the notbook used to house the tabs.
+
+        Args:
+            master (tk.Tk): tkinter base window
+        """
         # create base window, name it, and size it
         self.master = master
         master.title("Crow")
@@ -74,7 +83,7 @@ def selectrawdatacallback():
             """
             Upon clicking the select data button, open up a file request window
             and set the currently selected files to those which are selected,
-            update the display
+            update the display.
             """
             crow_globals.datafiles = RequestFiles.RequestFiles(
                 "Raw Data", "*.xml", crow_globals.rawdatapath
@@ -90,7 +99,7 @@ def selectrawdatacallback():
         # define excel data callback
         def selectexceldatacallback():
             """
-            Create pop-up file request for ".csv" input data for present
+            Create pop-up file request for ".csv" input data for present.
             """
             crow_globals.datafiles = RequestFiles.RequestFiles(
                 "Processed Data", "*.csv", crow_globals.exportdatapath
@@ -135,7 +144,7 @@ def update_files():
         def searchservercallback():
             """
             Go to given 'server' location and glob for any file matching
-            the given experiment name
+            the given experiment name.
             """
             crow_globals.datafiles = glob.glob(
                 crow_globals.rawdatapath + "*" + self.expname.get() + "*"
@@ -149,6 +158,8 @@ def searchservercallback():
             update_files()
 
         def openconfigcallback():
+            """Opens the configuration file using the system default viewer.
+            """
             webbrowser.open(pkg_resources.resource_filename(
                 __name__, "utils/config.yaml"))
 
@@ -177,8 +188,9 @@ def close_app(self):
             sys.exit(0)
 
 
-# Helpful method for PyPi package console script entry point
 def main():
+    """Helpful method for PyPi package console script entry point
+    """
     # Print a greeting
     print('''
     Thank you for installing Crow!

crow/uitabs/PrePull.py

@@ -13,6 +13,12 @@ class PrePull(tk.Frame):
     """
 
     def __init__(self, name, crow_globals):
+        """Constructor for PrePull frame.
+
+        Args:
+            name (string): Name for the tab. Unpacked from tk calls.
+            crow_globals (crow_globals): Global variables for Crow.
+        """
         # set up as tab
         tk.Frame.__init__(self, width=460, height=450)
         # lists to place collected data and files to get it from

crow/uitabs/Present.py

@@ -24,6 +24,12 @@ class Present(tk.Frame):
     """
 
     def __init__(self, name, crow_globals):
+        """Constructor for Present frame.
+
+        Args:
+            name (string): Name for the tab. Unpacked from tk calls.
+            crow_globals (crow_globals): Global variables for Crow.
+        """
         self._img_filenames = []
         tk.Frame.__init__(self, width=47, height=450)
 
@@ -200,6 +206,15 @@ def presentdatacallback():
                 messagebox.showerror("Error!", "Please select a layout.")
 
         def draw_empty(subplt, row, col, wellnum, e):  # pragma: no cover
+            """Draws an epty pie when an error is encountered.
+
+            Args:
+                subplt (int): matplotlib subplot.
+                row (int): Row number.
+                col (int): Column number.
+                wellnum (int): Index of well.
+                e (exception): exception that was raised to get here.
+            """
             subplt[row, col].pie([0])
             warningmessage = (
                 "Issue displaying well "
@@ -221,6 +236,19 @@ def draw_filled(
             cutoffcolors=None,
             excludeColmax=None,
         ):
+            """Convenience function for drawing a pie.
+
+            Args:
+                totalcolormap (list): List of colors to be used.
+                welldata (list): Values for each pie slice.
+                subplt (int): matplotlib subplot.
+                row (int): Row number.
+                col (int): Column number.
+                datafilter (int, optional): Data filter selected. Defaults to 0.
+                cutoffvalues (list, optional): List of values for groupings. Defaults to None.
+                cutoffcolors (list, optional): Colormap colors for cutoffs. Defaults to None.
+                excludeColmax (float, optional): Value to only plot above. Defaults to None.
+            """
             # handle wells where one or more pie slices are zero
             temp = totalcolormap.copy()
             # iterate through list
@@ -262,18 +290,18 @@ def draw_filled(
 
         def graphic_generator(exceldata, subplotdims, totalcolormap, dims):
             """
-            general purpose, abstract function for the generation of hte
-            diagrams
-            first check for which data filter has been selected, then
+            General purpose, abstract function for the generation of hte
+            diagrams first check for which data filter has been selected, then
             moves on to plotting.
 
-            exceldata: numpy array-type of the values to be plotted
-            subplotdims: array of ints containing length and width of the
-                            experiment
-            totalcolormap: array of floats containing colors to be used in the
-                            diagram
-            dims: tuple, immutable version of the dimensions of the subplot
-                            in the order required by matplotlib
+            Args:
+                exceldata (list): numpy array-type of the values to be plotted
+                subplotdims (list(ints)): array of ints containing length and
+                                          width of the experiment
+                totalcolormap (list): array of floats containing colors to be used in the
+                                      diagram
+                dims (tuple): immutable version of the dimensions of the subplot
+                              in the order required by matplotlib
             """
             # Check for which filter the user has requested, and call the
             # appropriate pop-up window
@@ -429,6 +457,18 @@ def graphic_generator(exceldata, subplotdims, totalcolormap, dims):
                 plot.show()
 
         def pickcolor(colormap, cutoffcol, cutoffvalues, cutoffcolors, currentwell):  # pragma: no cover
+            """Based on user inputs, choose which color the well should be.
+
+            Args:
+                colormap (list): Overall set of colors.
+                cutoffcol (int): Column on which to base decision.
+                cutoffvalues (list): Floats for deciding column grouping.
+                cutoffcolors (list): Colors for cutoffs.
+                currentwell (int): Index of current well.
+
+            Returns:
+                list: Colors to use.
+            """
             for i in range(0, len(cutoffvalues) - 1):
                 if (currentwell[cutoffcol] > cutoffvalues[i]) & (
                     currentwell[cutoffcol] <= cutoffvalues[i + 1]

crow/uitabs/Pull.py

@@ -9,10 +9,22 @@
 class Pull(tk.Frame):
     """
     Tab of the GC window responsible for pulling data from the entered
-    xml files based on the indicated retention times and variability
+    xml files based on the indicated retention times and variability.
+
+    Args:
+        tk (tk.Frame): Notebook for tab to be placed in.
+
+    Returns:
+        tk.Tk: tkinter master frame after closing.
     """
 
     def __init__(self, name, crow_globals):
+        """Constructor for Pull frame.
+
+        Args:
+            name (string): Name for the tab. Unpacked from tk calls.
+            crow_globals (crow_globals): Global variables for Crow.
+        """
         tk.Frame.__init__(self, width=47, height=450)
         # make place for collected retention times and tolerances to go
         # before being written
@@ -28,6 +40,12 @@ def clearentriescallback():
             self.entryreadorclear("clear")
 
         def pulldatacallback():
+            """Callback for the pull data button, which executes the following:
+            1. Ensure data files have been selected.
+            2. Check that retention times and tolerances are (a) present and (b) compatible.
+            3. Retrieves the data according to user settings.
+            4. Writes the data to a file.
+            """
             # gather the values in the entry boxes
             self.entryreadorclear("read")
             # check for wrong type of data file
@@ -242,8 +260,10 @@ def pulldatacallback():
         self.expname.place(x=170, y=280)
 
         def add_entry_fields():
+            """Convenience function for entry fields.
+            """
             tk.Label(self, text="Retention Time (minutes)").place(x=40, y=40)
-            # assigning and placing have to be on seperate lines because place returns nothing
+            # assigning and placing have to be on seperate lines because place returns None
             self.rt1 = tk.Entry(self)
             self.rt1.place(x=40, y=65)
             self.rt2 = tk.Entry(self)
@@ -279,6 +299,11 @@ def add_entry_fields():
         add_entry_fields()
 
     def entryreadorclear(self, readorclear):
+        """Internal use function for reading or clearing data from entry fields.
+
+        Args:
+            readorclear (string): either read or clear to do that action.
+        """
         if readorclear == "clear":
             self.rt1.delete(0, tk.END)
             self.tol1.delete(0, tk.END)
@@ -334,6 +359,11 @@ def entryreadorclear(self, readorclear):
                 )
 
     def isthereoverlap(self):
+        """Check for overlap in retention times and their tolerances.
+
+        Returns:
+            bool: True or False for overlap or no overlap.
+        """
         if len(self.rettimes) == 1:
             return False
         else:

crow/utils/ParseXML.py

@@ -2,11 +2,13 @@
 
 
 def ParseXML(filename):
-    """
-    One line passthrough to xml element tree, returns root of tree
+    """One line passthrough to xml element tree.
+
+    Args:
+        filename (string): the absolute or relative path to an xml file
 
-    filename: string which gives either the absolute or relative path
-                to an xml file
+    Returns:
+        etree: root of tree
     """
     tree = ET.parse(filename)
     root = tree.getroot()

crow/utils/RequestFiles.py

@@ -7,9 +7,13 @@ def RequestFiles(file_desc, file_ext, path):
     to retrieve a file of type file_ext (described by file_desc),
     path specifies starting directory
 
-    file_desc: string containing a description of the file to be chosen, ex. "Text Document"
-    file_ext: string of OS file extension, filetype ex. ".txt"
-    path: string giving location to start at with the file doalog, ex. "/usr/jackson/Desktop"
+    Args:
+        file_desc (string): description of the file to be chosen, ex. "Text Document"
+        file_ext (string): OS file extension, filetype ex. ".txt"
+        path (string): location to start at with the file doalog, ex. "/usr/jackson/Desktop"
+
+    Returns:
+        list(string): List of files selected by the user.
     """
     root = Tk()
     root.withdraw()

crow/utils/crow_globals.py

@@ -10,11 +10,17 @@
 
 class crow_globals():
     """
-    variables which are used by all tabs in the window, such as the path to
-    the server of raw data.
+    Class which initializes itself using the `config.yaml` file, making
+    variables which are used by all tabs of crow accesible in the 'global'
+    namespace (but without using global variables).
     """
 
     def __init__(self, config="config.yaml"):
+        """Opens the configuration file and reads the contents into attritbutes.
+
+        Args:
+            config (str, optional): Configuration file. Defaults to "config.yaml".
+        """
         # open the config file
         if config == "config.yaml":
             resource_path = pkg_resources.resource_filename(

crow/utils/logger.py

@@ -3,10 +3,10 @@
 
 
 def mylog(e):
-    """
-    General purpose function for writing errors to an external .txt file
+    """General purpose function for writing errors to an external .txt file.
 
-    e: exception raised by Crow
+    Args:
+        e (exception): exception raised by Crow
     """
     debugfile = open("debug.txt", "a")
     debugfile.write("\n")

crow/utils/popupwindows/cutoff.py

@@ -3,11 +3,19 @@
 
 class cutoffPopup(object):
     """
-    enable the user to make custom cutoff colors, useful for grouping wells
+    Enable the user to make custom cutoff colors, useful for grouping wells
     by selectivity or yield
+
+    Args:
+        object (tk.Top): Base window over which to draw this pop-up.
     """
 
     def __init__(self, master):
+        """Constructor for GUI.
+
+        Args:
+            master (tk.Tk): tkinter UI window.
+        """
         top = self.top = tk.Toplevel(master)
         tk.Label(top, text="For wells below this value:").place(x=0, y=0)
         self.cutoffval = tk.Entry(top)
@@ -20,6 +28,8 @@ def __init__(self, master):
         self.closebutton.place(x=0, y=100)
 
     def close(self):
+        """Pack values into attributes and then destroy the window.
+        """
         self.cutoffval = self.cutoffval.get()
         self.cutoffcolor = self.cutoffcolor.get()
         self.top.destroy()

crow/utils/popupwindows/exclude.py

@@ -8,9 +8,17 @@ class excludePopup(object):
 
     Ex. Creating a selectivity chart, but not displaying wells where the
     yield is vanishingly small.
+
+    Args:
+        object (tk.Top): Base window over which to draw this pop-up.
     """
 
     def __init__(self, master):
+        """Constructor for GUI.
+
+        Args:
+            master (tk.Tk): tkinter UI window.
+        """
         top = self.top = tk.Toplevel(master)
         tk.Label(top, text="Column to filter by:").place(x=0, y=0)
         self.excludecol = tk.Entry(top)
@@ -22,6 +30,8 @@ def __init__(self, master):
         self.closebutton.place(x=0, y=100)
 
     def close(self):
+        """Pack values into attributes and then destroy the window.
+        """
         self.excludecol = self.excludecol.get()
         self.excludeval = self.excludeval.get()
         self.top.destroy()