diff --git a/crow/Crow.py b/crow/Crow.py index 8bd31e1..bc866fa 100644 --- a/crow/Crow.py +++ b/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! diff --git a/crow/uitabs/PrePull.py b/crow/uitabs/PrePull.py index 9d8a9c0..2d5e6ea 100644 --- a/crow/uitabs/PrePull.py +++ b/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 diff --git a/crow/uitabs/Present.py b/crow/uitabs/Present.py index 9388682..24528fd 100644 --- a/crow/uitabs/Present.py +++ b/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] diff --git a/crow/uitabs/Pull.py b/crow/uitabs/Pull.py index e7841bf..54bfe28 100644 --- a/crow/uitabs/Pull.py +++ b/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: diff --git a/crow/utils/ParseXML.py b/crow/utils/ParseXML.py index 198972f..d3b938b 100644 --- a/crow/utils/ParseXML.py +++ b/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() diff --git a/crow/utils/RequestFiles.py b/crow/utils/RequestFiles.py index 89f1105..423e094 100644 --- a/crow/utils/RequestFiles.py +++ b/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() diff --git a/crow/utils/crow_globals.py b/crow/utils/crow_globals.py index 6555838..2c7abf6 100644 --- a/crow/utils/crow_globals.py +++ b/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( diff --git a/crow/utils/logger.py b/crow/utils/logger.py index 8121770..a48c838 100644 --- a/crow/utils/logger.py +++ b/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") diff --git a/crow/utils/popupwindows/cutoff.py b/crow/utils/popupwindows/cutoff.py index c57be25..36875c9 100644 --- a/crow/utils/popupwindows/cutoff.py +++ b/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() diff --git a/crow/utils/popupwindows/exclude.py b/crow/utils/popupwindows/exclude.py index 6adb1d1..4dbaa23 100644 --- a/crow/utils/popupwindows/exclude.py +++ b/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() diff --git a/crow/utils/popupwindows/numberofcutoffs.py b/crow/utils/popupwindows/numberofcutoffs.py index f7f2bca..1a07965 100644 --- a/crow/utils/popupwindows/numberofcutoffs.py +++ b/crow/utils/popupwindows/numberofcutoffs.py @@ -3,11 +3,19 @@ class numberofcutoffsPopup(object): """ - Asks user for both the column to base the groupign on and - the number of groups to generate + Asks user for both the column to base the grouping on and + the number of groups to generate. + + 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="Number of groups:").place(x=0, y=0) self.numgroups = tk.Entry(top) @@ -19,6 +27,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.numgroups = self.numgroups.get() self.cutoffcol = self.cutoffcol.get() self.top.destroy() diff --git a/crow/utils/popupwindows/shadebyyield.py b/crow/utils/popupwindows/shadebyyield.py index 9582604..2daf68e 100644 --- a/crow/utils/popupwindows/shadebyyield.py +++ b/crow/utils/popupwindows/shadebyyield.py @@ -2,11 +2,18 @@ class shadebyyieldPopup(object): - """ - Asks for which column to base the shading preference + """GUI popup to ask for which column to base the shading. + + 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 base shading on:").place(x=0, y=0) self.shadecol = tk.Entry(top) @@ -15,5 +22,7 @@ def __init__(self, master): self.closebutton.place(x=0, y=50) def close(self): + """Pack value into an attribute and then destroy the window. + """ self.shadecol = self.shadecol.get() self.top.destroy()