load.py documentation improvement

Params class still needs better documentation, probably on a centralized document in sphinx so that the other routines reference it instead of having the dicitonary tables on every single page

bifacial_radiance/load.py

@@ -1,72 +1,65 @@
 # -*- coding: utf-8 -*-
 """
-Created on Tue Feb 19 08:38:45 2019
-
-@author: cdeline, sayala
-
-load.py - load bifacial_radiance results. Module to load and clean 
-bifacial_radiance irradiance result files, csv format, usually stored in RadianceScene\results folder.
-
-Introduced in bifacial_radiance v0.2.4
+Module providing routines for loading and cleaning results from bifacial_radiance.
+Bifacial_radiance results are .csv format files stored in a results folder
+autogenerated in the location where the RadianceObj was set to build its scene.
+If no path was provided for the RadianceObj to build its scene, it defaults to
+TEMP folder in bifacial_radiance > bifacial_radiance
+"""
 
-functions: 
-    load_inputvariablesfile(inputfile)
-        loads a .py file which has all of the input variables required for a simulation.
-        Everything is loaded into a dictionary
-    
-    loadRadianceObj(savefile)
-        unpickle a RadianceObj saved with RadianceObj.save()    
-    
-    resultsdf = read1Result(csvfile)
-        read in a csv file
-        Returns: resultsDF
-    
-    cleanResult(resultsDF, matchers=None)
-        replace irradiance values with NaN's when the scan intersects ground, sky, or anything in `matchers`.
-        Returns: resultsDF
-    
-    deepcleanResult(resultsDF, sensorsy, numpanels, azimuth, automatic=True)
-        
-        Returns: resultsDF
-    
-    loadTrackerDict(trackerdict, fileprefix=None)
-        load all csv files in a \results\ folder matching timestamps in trackerdict
-        Intended to be called from RadianceObj.loadTrackerDict()
+# #DocumentationCheck : Introduced in bifacial_radiance v0.2.4 -- added load.py routines
 
-"""
-
-
-
 def load_inputvariablesfile(intputfile):
-    '''
-    Description
-    -----------
-    load_inputvariablesfile(inputfile)
+    """
     Loads inputfile which must be in the bifacial_radiance directory,
     and must be a *.py file with all the variables, and organizes the variables
     into dictionaries that it returns
 
     Parameters
     ----------
-    inputfile:    string of a *.py file in the bifacial_radiance directory.
+    inputfile : str
+        String of a *.py file in the bifacial_radiance directory.
 
-    Returns (Dictionaries)
+    Returns
     -------
-    simulationParamsDict          testfolder, weatherfile, getEPW, simulationname, 
-                                  moduletype, rewritemodule,
-                                  rcellLevelmodule, axisofrotationtorquetube, 
-                                  torqueTube, hpc, tracking, cumulativesky,
-                                  daydateSimulation, timestampRangeSimulation
-    sceneParamsDict:              gcrorpitch, gcr, pitch, albedo, nMods, nRows, 
-                                  hub_height, clearance_height, azimuth, hub_height, axis_Azimuth
-    timeControlParamsDict:        hourstart, hourend, daystart, dayend, monthstart, monthend,
-                                  timestampstart, timestampend, 
-    moduleParamsDict:             numpanels, x, y, bifi, xgap, ygap, zgap
-    cellLevelModuleParamsDict:    numcellsx, numcellsy, xcell, ycell, xcellgap, ycellgap
-    trackingParamsDict:           backtrack, limit_angle,angle_delta
-    torquetubeParamsDict:         diameter, tubetype, torqueTubeMaterial
-    analysisParamsDict:           sensorsy, modWanted, rowWanted
-    '''
+    simulationParamsDict : Dictionary
+        Dictionary containing the parameters for performing the simulation,
+        including simulation names, and types of sky, fixed or tracked systems:
+            ========================  =======  =============================
+            variable                   type         Description
+            ========================  =======  =============================
+            testfolder                str      Path to testfolder
+            weatherfile               str      File (with path) to weatherfile
+            getEPW                    bool     
+            simulationname            str      Name for simulation
+            moduletype                str      Module name as is / or will be defined in JSON
+            rewritemodule             bool     If moduletype exists in JSON, True will rewrite with new parameters
+            cellLevelmodule           bool        
+            axisofrotationtorquetube  bool
+            torqueTube                bool
+            hpc                       bool
+            tracking                  bool
+            cumulativesky             bool
+            daydateSimulation         bool
+            timestampRangeSimulation  bool
+            ========================  =======  =============================
+    sceneParamsDict : Dictionary 
+        gcrorpitch, gcr, pitch, albedo, nMods, nRows, 
+        hub_height, clearance_height, azimuth, hub_height, axis_Azimuth
+    timeControlParamsDict : Dictionary      
+        hourstart, hourend, daystart, dayend, monthstart, monthend,
+        timestampstart, timestampend, 
+    moduleParamsDict : Dictionary
+        numpanels, x, y, bifi, xgap, ygap, zgap
+    cellLevelModuleParamsDict : Dictionary
+        numcellsx, numcellsy, xcell, ycell, xcellgap, ycellgap
+    trackingParamsDict : Dictionary
+        backtrack, limit_angle,angle_delta
+    torquetubeParamsDict : Dictionary
+         diameter, tubetype, torqueTubeMaterial
+    analysisParamsDict : Dictionary
+        sensorsy, modWanted, rowWanted
+    """
 
     import inputfile as ibf
 
@@ -127,7 +120,7 @@ def load_inputvariablesfile(intputfile):
 
 
 def loadRadianceObj(savefile=None):
-    '''
+    """
     Load the pickled radiance object for further use
     usage: (once you're in the correct local directory)
       demo = bifacial_radiance.loadRadianceObj(savefile)
@@ -136,7 +129,7 @@ def loadRadianceObj(savefile=None):
     ----------
     savefile :   optional savefile.  Otherwise default to save.pickle
             
-    '''
+    """
     import pickle
 
     if savefile is None:
@@ -162,17 +155,31 @@ def read1Result(selectfile):
 # End read1Result subroutine
 
 def cleanResult(resultsDF, matchers=None):
-    '''
-    cleanResult(resultsDF, matchers=None)
-    check for 'sky' or 'tube' or 'pole' or 'ground in the front or back material 
-    and substitute NaN in Wm2Front and Wm2Back
+    """
+    Replace irradiance values with NaN's when the scan intersects ground, 
+    sky, or anything in `matchers`.
     
-    matchers 3267 and 1540 is to get rid of inner-sides of the module.
+    Matchers are words in the dataframe like  'sky' or 'tube' 
+    in the front or back material description column that 
+    get substituted by NaN in Wm2Front and Wm2Back
+    There are default matchers established in this routine but other matchers
+    can be passed.
+    Default matchers: 'sky', 'tube', 'pole', 'ground', '3267', '1540'.
+    Matchers 3267 and 1540 is to get rid of inner-sides of the module.
     
-    Parameters:
-        resultsDF:  pandas dataframe read from read1Result
+    Parameters
+    ----------
+    resultsDF : DataFrame
+        DataFrame of results from bifacial_radiance, for example read 
+        from :py:class:`~bifacial_radiance.load.read1Result`
+    
+    Returns
+    --------
+    resultsDF : DataFrame
+        Updated resultsDF 
+    
+    """
 
-    '''
     import numpy as np
 
     if matchers is None:
@@ -189,26 +196,33 @@ def cleanResult(resultsDF, matchers=None):
 
 
 def loadTrackerDict(trackerdict, fileprefix=None):
-    '''
-    Load a trackerdict by reading all files in the \results\ directory.
-    fileprefix is used to select only certain matching files in \results\
+    """
+    Load a trackerdict by reading all files in the `\\results\\` directory.
+    fileprefix is used to select only certain matching files in `\\results\\`
    
     It will then save the Wm2Back, Wm2Front and backRatio by reading in all valid files in the
-    \results\ directory.  Note: it will match any file ending in '_key.csv'
+    \\results\\ directory.  Note: it will match any file ending in '_key.csv'
     
     Parameters
-    --------------
-    trackerdict:    You need to pass in a valid trackerdict with correct keys from RadianceObj.set1axis()
-    fileprefix:     (None): optional parameter to specify the initial part of the savefile prior to '_key.csv'
+    ----------
+    trackerdict : 
+        You need to pass in a valid trackerdict with correct keys from 
+        :py:class:`~bifacial_radiance.RadianceObj.set1axis`
+    fileprefix : str
+        Optional parameter to specify the initial part of the savefile prior 
+        to '_key.csv'
     
     Returns
     -------------
-    trackerdict:    dictionary with additional ['Wm2Back'], ['Wm2Front'], ['backRatio']
-    totaldict:      totalized dictionary with ['Wm2Back'], ['Wm2Front']. 
-                    Also ['numfiles'] (number of csv files loaded) and 
-                    ['finalkey'] (last index file in directory)
+    trackerdict : Dictionary
+        Dictionary with additional keys ``Wm2Back``, ``Wm2Front``, ``backRatio``
+    totaldict : Dictionary
+        totalized dictionary with ``Wm2Back``, ``Wm2Front``. 
+        Also ``numfiles`` (number of csv files loaded) and 
+        ``finalkey`` (last index file in directory)
 
-    '''        
+    """
+
     import re, os
     import numpy as np
 
@@ -282,30 +296,33 @@ def exportTrackerDict(trackerdict, savefile, reindex):
 
 
 def deepcleanResult(resultsDict, sensorsy, numpanels, automatic=True):
-    '''
-    cleanResults(resultsDict, sensorsy, numpanels, azimuth) 
-    @author: SAyala
-    
-    cleans results read by read1Result specifically for 1 UP and 2UP configurations in v0.2.4
+    """    
+    Cleans results read by read1Result specifically for 1 UP and 2UP configurations in v0.2.4
     Asks user to select material of the module (usually the one with the most results) 
     and removes sky, ground, and other materials (side of module, for example)
     
-    TODO: add automatization of panel select.
-    
-    PARAMETERS
+    Parameters
     -----------
-    sensorsy     For the interpolation routine. Can be more than original sensory or same value.
-    numpanels    1 or 2
-    azimuth   of the tracker for the results generated. So that it knows if sensors 
-                   should be flipped or not. Particular crucial for 2 UP configurations.
-    automatic      Automaticatlly detects module and ignores Ground, torque tube and sky values. If set to off, user gets queried about the right surfaces.
+    sensorsy : int
+        For the interpolation routine. Can be more than original sensory or same value.
+    numpanels : int
+        Options are 1 or 2 panels for this function.
+    automatic : bool
+        Default True. Automaticatlly detects module and ignores Ground, torque tube and 
+        sky values. If set to off, user gets queried about the right surfaces.
     
     Returns
     -------
-    Frontresults, Backresults;     dataframe with only values of the material selected, 
-                                   length is the number of sensors desired.
+    Frontresults : DataFrame
+        Dataframe with only front-irradiance values for the module material selected, 
+        length is the number of sensors desired.
+    Backresults : DataFrame
+        Dataframe with only rear-irradiance values for the module material selected, 
+        length is the number of sensors desired.
+    """
+
+    # #TODO: add automatization of panel select.
 
-    '''
     import numpy as np
     #from scipy.interpolate import interp1d
 
@@ -419,30 +436,34 @@ def interp_sub(panelDict, sensorsy, frontbackkey):
         Frontresults=interp_sub(panelB,sensorsy,'Wm2Front')
         Backresults=interp_sub(panelB,sensorsy,'Wm2Back')
 
-            
+
     return Frontresults, Backresults;    # End Deep clean Result subroutine.
 
 def readconfigurationinputfile(inifile=None):
     """
-    readconfigurationinputfile(inifile=None)
-    
-    input:      inifile (string):  .ini filename to read in
+    Function to read configurationinput file for a bifacial_radiance simulation.
     
-    returns:    simulationParamsDict, 
-                sceneParamsDict, 
-                timeControlParamsDict, 
-                moduleParamsDict, 
-                trackingParamsDict, 
-                torquetubeParamsDict, 
-                analysisParamsDict, 
-                cellLevelModuleParamsDict;
-
-    @author: sayala
+    Parameters
+    ----------
+    input : str
+      Filename with extension .ini to read in
     
-    #TODO: check if modulename exists on jason and rewrite is set to false, then
-    don't save moduleParamsDict? Discuss.
+    Returns
+    -------
+    simulationParamsDict : Dictionary
+    sceneParamsDict : Dictionary
+    timeControlParamsDict : Dictionary 
+    moduleParamsDict : Dictionary
+    trackingParamsDict : Dictionary
+    torquetubeParamsDict : Dictionary
+    analysisParamsDict : Dictionary
+    cellLevelModuleParamsDict : Dictionary
 
     """
+
+    ## #TODO: check if modulename exists on jason and rewrite is set to false, then
+    #don't save moduleParamsDict? Discuss.
+
     import configparser
     import os
 
@@ -826,9 +847,32 @@ def boolConvert(d):
 
 
 def savedictionariestoConfigurationIniFile(simulationParamsDict, sceneParamsDict, timeControlParamsDict=None, moduleParamsDict=None, trackingParamsDict=None, torquetubeParamsDict=None, analysisParamsDict=None, cellLevelModuleParamsDict=None, inifilename=None):
-    '''
-    inifilename = 'example.ini'
-    '''
+    """
+    Saves dictionaries from working memory into a Configuration File
+    with extension format .ini.
+    
+    Parameters
+    ----------
+    simulationParamsDict
+    sceneParamsDict
+    timeControlParamsDict 
+        Default None
+    moduleParamsDict
+        Default None
+    trackingParamsDict
+        Default None 
+    torquetubeParamsDict
+        Default None 
+    analysisParamsDict
+        Default None, 
+    cellLevelModuleParamsDict
+        Default None    
+    
+    Returns
+    -------
+    Writes output into inifilename passed (default if inifilename=None is 
+    'example.ini')
+    """
 
     import configparser
 
@@ -871,9 +915,10 @@ def savedictionariestoConfigurationIniFile(simulationParamsDict, sceneParamsDict
 
 class Params():
     """
-
-    model configuration parameters. Including the following:
+    Model configuration parameters. Including the following:
     
+    Parameters
+    ----------
     simulationParams          testfolder, weatherfile, getEPW, simulationname, 
                                   moduletype, rewritemodule,
                                   rcellLevelmodule, axisofrotationtorquetube, 
@@ -890,7 +935,8 @@ class Params():
     analysisParams:           sensorsy, modWanted, rowWanted
     
     """
-    #    cdeline 5/9/19:  new class to try to make some sense of these model parameters?
+    # #DocumentationCheck : add to updates
+    # cdeline 5/9/19:  new class to try to make some sense of these model parameters?
 
 
     def __init__(self, simulationParams=None, sceneParams=None,