From a453c9fdb810dd2673a9ce6d4b2dc752809c733b Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Fri, 22 Jun 2018 17:52:25 +0200
Subject: [PATCH 01/14] Add man page for gemTreeDrawWrapper.py

Currently only Synopsis and Description
---
 doc/conf.py                    |  2 ++
 doc/macros.rst                 |  8 ++++----
 doc/man/gemTreeDrawWrapper.rst |  4 ++++
 macros/gemTreeDrawWrapper.py   | 31 ++++++++++++++++++++++++++++---
 4 files changed, 38 insertions(+), 7 deletions(-)
 create mode 100644 doc/man/gemTreeDrawWrapper.rst

diff --git a/doc/conf.py b/doc/conf.py
index b0a64aba..4274cfe0 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -222,6 +222,8 @@
      [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
     ('man/gemPlotter', 'gemPlotter.py', u'Plot time evolution of scan results',
      [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
+    ('man/gemTreeDrawWrapper', 'gemTreeDrawWrapper.py', u'Make X-Y plots for each scan date',
+     [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
 ]
 
 # If true, show URL addresses after external links.
diff --git a/doc/macros.rst b/doc/macros.rst
index b724f586..25c30948 100644
--- a/doc/macros.rst
+++ b/doc/macros.rst
@@ -46,10 +46,10 @@ Macros
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: gemTreeDrawWrapper
-    :members:
-    :undoc-members:
-    :show-inheritance:
+.. toctree::
+    :maxdepth: 1
+
+    man/gemTreeDrawWrapper
 
 .. automodule:: packageFiles4Docker
     :members:
diff --git a/doc/man/gemTreeDrawWrapper.rst b/doc/man/gemTreeDrawWrapper.rst
new file mode 100644
index 00000000..684dce92
--- /dev/null
+++ b/doc/man/gemTreeDrawWrapper.rst
@@ -0,0 +1,4 @@
+.. automodule:: gemTreeDrawWrapper
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/macros/gemTreeDrawWrapper.py b/macros/gemTreeDrawWrapper.py
index 0422785c..aa42259a 100755
--- a/macros/gemTreeDrawWrapper.py
+++ b/macros/gemTreeDrawWrapper.py
@@ -1,8 +1,33 @@
 #!/bin/env python
 
-"""
-gemTreeDrawWrapper
-==================
+r"""
+``gemTreeDrawWrapper.py`` --- Make X-Y plots for each scan date
+===============================================================
+
+Synopsis
+--------
+
+**gemTreeDrawWrapper.py** :token:`--anaType` <*ANALYSIS TYPE*> :token:`--treeExpress` <*EXPRESSION*> :token:`-i` <*INPUT FILE*> [*OPTIONS*]
+
+Description
+-----------
+
+The :program:`gemTreeDrawWrapper.py` tool is for making a given 'Y vs. X' plot
+for each scandate of interest. Here Y and X are quantities stored in
+``TBranches`` of one of the ``TTree`` objects produced by the (ana-) ultra scan
+scripts. This is designed to complement :program:`gemPlotter.py` and should
+speed up plotting in general. This tool is essesntially a wrapper for the
+``TTree::Draw()`` method. To make full use of this tool you should familiarize
+yourself with the ``TTree::Draw()`` `documentation`_.
+
+.. _documentation: https://root.cern.ch/doc/master/classTTree.html#a73450649dc6e54b5b94516c468523e45
+
+Additionally :program:`gemTreeDrawWrapper.py` can also fit produced plots with a
+function defined at runtime through the command line arguments.
+
+Each plot produced will be stored as an output ``*.png`` file. Additionally an
+output ``TFile`` will be produced which will contain each of the plots, stored
+as ``TGraph`` objects, canvases, and fits produced.
 """
 
 def getPlotFromTree(filename, treeName, expression, selection=""):

From 70e2350bb3e18d6fe5c978ffef8884982422cf4f Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Fri, 22 Jun 2018 18:09:52 +0200
Subject: [PATCH 02/14] Document arguments of gemTreeDrawWrapper.py

---
 macros/gemTreeDrawWrapper.py | 108 +++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)

diff --git a/macros/gemTreeDrawWrapper.py b/macros/gemTreeDrawWrapper.py
index aa42259a..01392e33 100755
--- a/macros/gemTreeDrawWrapper.py
+++ b/macros/gemTreeDrawWrapper.py
@@ -28,6 +28,114 @@
 Each plot produced will be stored as an output ``*.png`` file. Additionally an
 output ``TFile`` will be produced which will contain each of the plots, stored
 as ``TGraph`` objects, canvases, and fits produced.
+
+Mandatory arguments
+-------------------
+
+The following list shows the mandatory inputs that must be supplied to execute
+the script.
+
+.. program:: gemTreeDrawWrapper.py
+
+.. option:: --anaType <ANALYSIS TYPE>
+
+    Analysis type to be executed, see :any:`utils.anaInfo.tree_names` for
+    possible inputs.
+
+.. option:: --treeExpress <EXPRESSION>
+
+    Expression to be drawn, corresponds to the ``varexp`` argument of
+    ``TTree::Draw()``.
+
+.. option:: -i, --infilename <FILE NAME>
+
+    Physical filename of the input file to be passed to
+    :program:`gemPlotter.py`. See :any:`Two Column Format` for details on the
+    format and contents of this file.
+
+Note for those :option:`--anaType` values which have the substring ``Ana`` in
+their names it is expected that the user has already run :program:`ana_scans.py`
+on the corresponding ``scandate`` to produce the necessary input file for
+:program:`gemPlotter.py`.
+
+Optional arguments
+------------------
+
+.. option:: --axisMaxX <NUMBER>
+
+    Maximum value for X-axis range.
+
+.. option:: --axisMinX <NUMBER
+
+    Minimum value for X-axis range, note this parameter will default to 0
+    :option:`--axisMaxX` is given.
+
+.. option:: --axisMaxY <NUMBER>
+
+    Maximum value for Y-axis range.
+
+.. option:: --axisMinY <NUMBER>
+
+    Minimum value for Y-axis range, note this parameter will default to 0
+    :option:`--axisMaxY` is given.
+
+.. option:: --drawLeg
+
+    When used with :option:`--summary` option draws a ``TLegend`` on the output
+    plot.
+
+.. option:: --fitFunc <EXPRESSION>
+
+    Expression following the `TFormula syntax`_ for defining a ``TF1`` to be
+    fitted to the plot.
+
+    .. _TFormula syntax: https://root.cern.ch/doc/master/classTFormula.html
+
+.. option:: --fitGuess <COMMA-SEPARATED LIST OF NUMBERS>
+
+    Initial guess for fit parameters defined in :option:`--fitFunc`. Note, order
+    of params here should match that of :option:`--fitFunc`.
+
+.. option:: --fitOpt <OPTION>
+
+    Option to be used when fitting, a complete list can be found `here`_.
+
+    .. _here: https://root.cern.ch/doc/master/classTH1.html#a7e7d34c91d5ebab4fc9bba3ca47dabdd
+
+.. option:: --fitRange <COMMA-SEPARATED LIST OF NUMBERS>
+
+    Defines the range the fit function is valid on.
+
+.. option:: --rootOpt <OPTION>
+
+    Option for creating the output ``TFile``, e.g. ``RECREATE`` or ``UPDATE``
+
+.. option:: --showStat
+
+    Causes the statistics box to be drawn on created plots.
+
+.. option:: --summary
+
+    Make a summary canvas with all created plots drawn on it.
+
+.. option:: --treeSel <EXPRESSION>
+
+    Selection to be used when making the plot, corresponds to the selection
+    argument of `TTree::Draw()`_.
+
+    .. _TTree::Draw(): https://root.cern.ch/doc/master/classTTree.html#a73450649dc6e54b5b94516c468523e45
+
+.. option:: --treeDrawOpt <OPTION>
+
+    Draw option to be used for the procued plots.
+
+.. option:: --ztrim <NUMBER>
+
+    The ztrim value that was used when running the scans listed in
+    :option:`--infilename`
+
+Internals
+---------
 """
 
 def getPlotFromTree(filename, treeName, expression, selection=""):

From 1c6352fb88e67e617fc007d883e8a82ce06f8f61 Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Fri, 22 Jun 2018 18:10:52 +0200
Subject: [PATCH 03/14] Fix copy-paste error

---
 macros/gemTreeDrawWrapper.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/macros/gemTreeDrawWrapper.py b/macros/gemTreeDrawWrapper.py
index 01392e33..35cd5f94 100755
--- a/macros/gemTreeDrawWrapper.py
+++ b/macros/gemTreeDrawWrapper.py
@@ -56,7 +56,7 @@
 Note for those :option:`--anaType` values which have the substring ``Ana`` in
 their names it is expected that the user has already run :program:`ana_scans.py`
 on the corresponding ``scandate`` to produce the necessary input file for
-:program:`gemPlotter.py`.
+:program:`gemTreeDrawWrapper.py`.
 
 Optional arguments
 ------------------

From 80c9b54b32173fdacf42dffd0f72d6e4fcb4a78e Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Fri, 22 Jun 2018 18:23:39 +0200
Subject: [PATCH 04/14] Add examples and env docs for gemTreeDrawWrapper.py

---
 macros/gemTreeDrawWrapper.py | 52 ++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/macros/gemTreeDrawWrapper.py b/macros/gemTreeDrawWrapper.py
index 35cd5f94..683ea385 100755
--- a/macros/gemTreeDrawWrapper.py
+++ b/macros/gemTreeDrawWrapper.py
@@ -134,6 +134,58 @@
     The ztrim value that was used when running the scans listed in
     :option:`--infilename`
 
+Examples
+--------
+
+Making a Plot
+.............
+
+For example to make a plot from a latency scan, ``Nhits`` vs. ``lat`` for
+VFAT12, use the following command:
+
+.. code-block:: bash
+
+    gemTreeDrawWrapper.py -ilistOfScanDates_TreeDraw.txt --anaType=latency --summary --treeExpress="Nhits:lat" --treeDrawOpt=APE1 --treeSel="vfatN==12" --axisMaxY=1000 --axisMinX=39 --axisMaxX=49 --drawLeg
+
+This will produce one ``Nhits`` vs. ``lat`` plot for VFAT12 for each
+``(ChamberName,scandate)`` pair found in ``listOfScanDates_TreeDraw.txt``.
+Additionally it will make one summary plot with a legend drawn which contains
+all of the produced plots.
+
+Fitting a Plot
+..............
+
+For example to plot and fit an scurve from an scurve scan, ``Nhits`` vs
+``vcal``, for VFAT12 channel 45, use the following command:
+
+.. code-block:: bash
+
+    gemTreeDrawWrapper.py -ilistOfScanDates_TreeDraw.txt --anaType=scurve --treeExpress="Nhits:vcal" --treeDrawOpt=APE1 --treeSel="vfatN==12 && vfatCH==45" --fitFunc="500*TMath::Erf((TMath::Max([2],x)-[0])/(TMath::Sqrt(2)*[1]))+500" --fitRange=70,150 --fitOpt="RM" --fitGuess=110,10,10
+
+Here the fit that will be applied will be equivalent too:
+
+.. code-block:: python
+
+    myFunc = r.TF1(strName,"500*TMath::Erf((TMath::Max([2],x)-[0])/(TMath::Sqrt(2)*[1]))+500",70,150)
+    myFunc.SetParameter(0,110)
+    myFunc.SetParameter(0,10)
+    myFunc.SetParameter(0,10)
+
+The fit option that will be used will be ``RM``. This fit will be applied to the
+scurve generated from VFAT12 channel 45 for each ``(ChamberName,scandate)`` pair
+found in ``listOfScanDates_TreeDraw.txt``.
+
+Environment
+-----------
+
+.. glossary::
+
+    :envvar:`DATA_PATH`
+        The location of input data
+
+    :envvar:`ELOG_PATH`
+        Results are written in the directory pointed to by this variable
+
 Internals
 ---------
 """

From b8321442bc1797abc61be6c91441dc6c1d249b50 Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Fri, 22 Jun 2018 18:31:34 +0200
Subject: [PATCH 05/14] Convert gemTreeDrawWrapper.py's internal docs to rst

---
 macros/gemTreeDrawWrapper.py | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/macros/gemTreeDrawWrapper.py b/macros/gemTreeDrawWrapper.py
index 683ea385..5a877330 100755
--- a/macros/gemTreeDrawWrapper.py
+++ b/macros/gemTreeDrawWrapper.py
@@ -192,15 +192,21 @@
 
 def getPlotFromTree(filename, treeName, expression, selection=""):
     """
-    Returns the type of TObject returned by TTree::Draw(expression, selection, drawOpt)
+    Returns the type of ``TObject`` returned by
+    ``TTree::Draw(expression, selection, drawOpt)``. See `the documentation`_
+    for ``TTree::Draw()`` details.
 
-    filename - string, physical filename of the input TFile
-    treeName - string, name of the TTree found in filename
+    .. _the documentation: https://root.cern.ch/doc/master/classTTree.html#a73450649dc6e54b5b94516c468523e45
 
-    See https://root.cern.ch/doc/master/classTTree.html#a73450649dc6e54b5b94516c468523e45 for TTree::Draw() documentation
+    Args:
+        filename (string): Physical filename of the input ``TFile``
 
-    expression - string, the "varexp" argument passed to TTree::Draw()
-    selection - string, the "selection" argument passed to TTree::Draw()
+        treeName (string): Name of the ``TTree`` found in ``filename``
+
+        expression (string): The ``varexp`` argument passed to ``TTree::Draw()``
+
+        selection (string): The ``selection`` argument passed to
+            ``TTree::Draw()``
     """
   
     from gempython.gemplotting.utils.anautilities import filePathExists, getStringNoSpecials, getDirByAnaType

From 663825c848038f1984fd6deee4ed91170c996d9b Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Fri, 22 Jun 2018 22:26:27 +0200
Subject: [PATCH 06/14] Add man page for packageFiles4Docker

---
 doc/conf.py                     |   2 +
 doc/macros.rst                  |   6 +-
 doc/man/packageFiles4Docker.rst |   4 ++
 packageFiles4Docker.py          | 113 +++++++++++++++++++++++++++++---
 4 files changed, 110 insertions(+), 15 deletions(-)
 create mode 100644 doc/man/packageFiles4Docker.rst

diff --git a/doc/conf.py b/doc/conf.py
index 4274cfe0..b3939bae 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -224,6 +224,8 @@
      [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
     ('man/gemTreeDrawWrapper', 'gemTreeDrawWrapper.py', u'Make X-Y plots for each scan date',
      [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
+    ('man/packageFiles4Docker', 'packageFiles4Docker.py', u'Creates a tarball containing data',
+     [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
 ]
 
 # If true, show URL addresses after external links.
diff --git a/doc/macros.rst b/doc/macros.rst
index 25c30948..e06fda7d 100644
--- a/doc/macros.rst
+++ b/doc/macros.rst
@@ -50,11 +50,7 @@ Macros
     :maxdepth: 1
 
     man/gemTreeDrawWrapper
-
-.. automodule:: packageFiles4Docker
-    :members:
-    :undoc-members:
-    :show-inheritance:
+    man/packageFiles4Docker
 
 .. automodule:: plotSCurveFitResults
     :members:
diff --git a/doc/man/packageFiles4Docker.rst b/doc/man/packageFiles4Docker.rst
new file mode 100644
index 00000000..bfaf7450
--- /dev/null
+++ b/doc/man/packageFiles4Docker.rst
@@ -0,0 +1,4 @@
+.. automodule:: packageFiles4Docker
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/packageFiles4Docker.py b/packageFiles4Docker.py
index 7b4cef31..615cc3ae 100755
--- a/packageFiles4Docker.py
+++ b/packageFiles4Docker.py
@@ -1,18 +1,114 @@
 #!/bin/env python
 
-"""
-packageFiles4Docker
-===================
+r"""
+``packageFiles4Docker.py`` --- Creates a tarball containing data
+================================================================
+
+Synopsis
+--------
+
+**packageFiles4Docker.py** [*OPTIONS*]
+
+Description
+-----------
+
+You may occasionally need to update the travis CI docker which checks the code
+quality or you may want to transfer a number of files corresponding to a series
+of scandates from the P5 machine to another area. The
+:program:`packageFiles4Docker.py` tool enables you to do this. The output of :program:`packageFiles4Docker.py` will be a ``*.tar`` file that:
+
+* mimics the file structure of ``$DATA_PATH``, and
+* contains each of the input ``listOfScandates.txt`` files supplied at runtime,
+  and
+* a temorary ``chamberInfo.py`` file which can be placed in the docker for
+  testing.
+
+Arguments
+---------
+
+.. program:: packageFiles4Docker.py
+
+.. option:: --fileListLat <FILE>
+
+    Specify Input Filename for list of scandates for latency files.
+
+.. option:: --fileListScurve <FILE>
+
+    Specify Input Filename for list of scandates for scurve files.
+
+.. option:: --fileListThresh <FILE>
+
+    Specify Input Filename for list of scandates for threshold files.
+
+.. option:: --fileListTrim <FILE>
+
+    Specify Input Filename for list of scandates for trim files.
+
+.. option:: --ignoreFailedReads
+
+    Ignores failed read errors in tarball creation, useful for ignoring scans
+    that did not finish successfully.
+
+.. option:: --onlyRawData
+
+    Files produced by ``anaUltra*.py`` scripts will not be included.
+
+.. option:: --tarBallName <FILE>
+
+    Specify the name of the output tarball.
+
+.. option:: --ztrim <NUMBER>
+
+    The ztrim value of interest for scandates given in --fileListTrim.
+
+.. option:: -d, --debug
+
+    Prints the commands that would be exectuted but does not call them.
+
+Please note that multiple :token:`--fileListX` arguments can be supplied at
+runtime, but at least one must be supplied.
+
+Each of the :token:`--fileListX` arguments can be supplied with a
+``listOfScanDates.txt`` file that follows either the :any:`Two Column Format` or
+the :any:`Three Column Format`.
+
+Example
+-------
+
+To make a tarball of containing scurve scandates defined in
+``listOfScanDates.txt`` for ``GEMINIm01L1`` execute:
+
+.. code-block:: bash
+
+    packageFiles4Docker.py --ignoreFailedReads --fileListScurve=$DATA_PATH/GEMINIm01L1/scurve/listOfScanDates.txt --tarBallName=GEMINIm01L1_scurves.tar --ztrim=4 --onlyRawData
+
+In this case failed read errors in the tar command will be ignored and only the
+raw data, e.g. ``SCurveData.root`` files, will be stored in the tarball
+following the appropriate file structure.
+
+Environment
+-----------
+
+.. glossary::
+
+    :envvar:`DATA_PATH`
+        The location of input data
+
+Internals
+---------
 """
 
 def getListOfCmdTuples(filename, anaType):
     """
     Returns a list of tuples where each element is:
-        (anaType, cName, scandate)
+    ``(anaType, cName, scandate)``
+
+    Args:
+        filename (string): Physical filename of input file, see
+            :any:`parseListOfScanDatesFile` for details on expected format
 
-    filename - physical filename of input file, see parseListOfScanDatesFile 
-               for details on expected format
-    anaType - string matching a key in ana_config of anaInfo.py
+        anaType (string): String matching a key in
+            :any:`utils.anaInfo.ana_config`
     """
 
     from gempython.gemplotting.utils.anaInfo import ana_config
@@ -35,9 +131,6 @@ def getListOfCmdTuples(filename, anaType):
     return ret_list_cmd_tuples
 
 if __name__ == '__main__':
-    """
-    Creates a tar ball to be used with the docker for unit tests with travis
-    """
     from gempython.gemplotting.utils.anaInfo import tree_names
     from gempython.gemplotting.utils.anautilities import getDirByAnaType
     from gempython.utils.wrappers import runCommand

From 15b1295afb68be1dba12e211e7d5c61436beea10 Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Tue, 3 Jul 2018 15:04:37 +0200
Subject: [PATCH 07/14] Document DeadChannelFinder

See PR #123
---
 fitting/fitScanData.py | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/fitting/fitScanData.py b/fitting/fitScanData.py
index 222b7ee7..1a1c567b 100644
--- a/fitting/fitScanData.py
+++ b/fitting/fitScanData.py
@@ -1,17 +1,40 @@
-"""
-``fitScanData`` --- S-curves fits
----------------------------------
-"""
-
 import numpy as np
 import ROOT as r
 from gempython.gemplotting.utils.anaInfo import dict_calSF
 
 class DeadChannelFinder(object):
+    r"""
+    Finds channels that returned no data during an S-curve scan ("dead"
+    channels).
+
+    This class has only one function, :py:meth:`feed`, that takes an entry from
+    the S-curve tree and updates the results.
+
+    Attributes:
+        isDead (numpy.array): 2D array of ``bool``s, indexed as
+            ``[vfat][channel]``. Each entry is ``True`` if the channel is
+            dead, ``False`` otherwise.
+
+    Example:
+        Typical usage:
+
+        .. code-block:: python
+
+            finder = DeadChannelFinder()
+            for event in file.scurveTree:
+                finder.feed(event)
+                pass
+            # Use the results...
+
+    """
     def __init__(self):
         self.isDead = [ np.ones(128, dtype=bool) for i in range(24) ]
 
     def feed(self, event):
+        """
+        Takes an entry from the S-curve tree and updates the results
+        accordingly.
+        """
         self.isDead[event.vfatN][event.vfatCH] = False
 
 class ScanDataFitter(DeadChannelFinder):

From 582984693b3dc415647bf1b81f1123fba5a9885f Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Sat, 23 Jun 2018 03:43:43 +0200
Subject: [PATCH 08/14] Include sphinx.ext.pngmath for maths in docs

---
 doc/conf.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/doc/conf.py b/doc/conf.py
index b3939bae..ce3a0797 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -26,7 +26,14 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.napoleon', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinxcontrib.napoleon',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.coverage',
+    'sphinx.ext.pngmath',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode']
 
 # Disable numpy docstrings for Napoleon, because they eat headers such as
 # "Examples"

From ffb51e6ec5d1b78cee300bd7f5f20f763695f637 Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Sat, 23 Jun 2018 03:45:21 +0200
Subject: [PATCH 09/14] Fix typos in DeadChannelFinder docs

---
 fitting/fitScanData.py | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/fitting/fitScanData.py b/fitting/fitScanData.py
index 1a1c567b..d0a6013c 100644
--- a/fitting/fitScanData.py
+++ b/fitting/fitScanData.py
@@ -10,11 +10,6 @@ class DeadChannelFinder(object):
     This class has only one function, :py:meth:`feed`, that takes an entry from
     the S-curve tree and updates the results.
 
-    Attributes:
-        isDead (numpy.array): 2D array of ``bool``s, indexed as
-            ``[vfat][channel]``. Each entry is ``True`` if the channel is
-            dead, ``False`` otherwise.
-
     Example:
         Typical usage:
 
@@ -26,6 +21,10 @@ class DeadChannelFinder(object):
                 pass
             # Use the results...
 
+    Attributes:
+        isDead (numpy.ndarray): 2D array of ``bool``, indexed as
+            ``[vfat][channel]``. Each entry is ``True`` if the channel is
+            dead, ``False`` otherwise.
     """
     def __init__(self):
         self.isDead = [ np.ones(128, dtype=bool) for i in range(24) ]

From e83c92dd3c9eca84e5ca8fe10607b919c91ffb7a Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Sat, 23 Jun 2018 03:45:45 +0200
Subject: [PATCH 10/14] Document ScanDataFitter and fitScanData

---
 fitting/fitScanData.py | 137 +++++++++++++++++++++++++++++++++--------
 1 file changed, 113 insertions(+), 24 deletions(-)

diff --git a/fitting/fitScanData.py b/fitting/fitScanData.py
index d0a6013c..342eb9f1 100644
--- a/fitting/fitScanData.py
+++ b/fitting/fitScanData.py
@@ -37,13 +37,87 @@ def feed(self, event):
         self.isDead[event.vfatN][event.vfatCH] = False
 
 class ScanDataFitter(DeadChannelFinder):
-    def __init__(self, calDAC2Q_m=None, calDAC2Q_b=None, isVFAT3=False):
-        """
-        calDAC2Q_m - list of slope values for "fC = m * cal_dac + b" equation, ordered by vfat position
-        calDAC2Q_b - as calDAC2Q_m but for intercept b
-        isVFAT3 - if using VFAT3
-        """
+    r"""
+    Fits S-curves.
+
+    This class is used in two steps:
+
+    #. The data to fit is passed to the object using :py:meth:`feedHisto`,
+       :py:meth:`readFile` or repeated calls to :py:meth:`feed`.
+    #. The fit is performed by calling :py:meth:`fit`.
+
+    One cannot count on all attributes being present before calling
+    :py:meth:`fit`.
+
+    .. note::
+
+        If the :py:attr:`calDAC2Q_m` and :py:attr:`calDAC2Q_b` were supplied at
+        construction time, values will be in charge units instead of DAC units.
+
+    See :program:`anaUltraScurve.py` for example usage.
+
+    Attributes:
+        Nev (ndict): 2D array of ``int``, indexed as ``[vfat][channel]``.
+
+        scanFuncs (ndict): 2D array of ``TF1``, indexed as ``[vfat][channel]``.
+            After fitting, each entry contains the fit function for the
+            corresponding channel. The functions are color-coded:
+
+            ======= =====================================
+            Color   Meaning
+            ======= =====================================
+            Black   Default
+            Blue    Fit Converged
+            Gray    Dead channel or empty input histogram
+            Orange  Fit result is empty
+            ======= =====================================
+
+        scanHistos (ndict): 2D array of ``TH1``, indexed as
+            ``[vfat][channel]``, that contain the S-curve results (number of
+            events vs charge)
+
+        scanCount (ndict): 2D array of ``int``, indexed as ``[vfat][channel]``.
+            Each entry contains the total number of events for the corresponding
+            channel.
+
+        scanFitResults (ndict): 3D array of ``float``, indexed as
+            ``[idx][vfat][channel]``, that contain the fit results. ``idx`` has
+            the following meaning:
+
+            0. S-curve mean in either DAC units or charge (threshold of
+               comparator)
+            1. S-curve width in either DAC units or charge (noise seen by
+               comparator)
+            2. S-curve pedestal in hits (e.g. at 0 VCAL this is the
+               noise)
+            3. :math:`\chi^2` of the fit
+            4. Same as ``self.scanCount[vfat][channel]``
+            5. Number of degrees of freedom (NDF) of the fit
+
+        calDAC2Q_m (numpy.ndarray): Calibration of ``calDAC`` to charge for each
+            VFAT. This corresponds to :math:`m` in
+
+            .. math::
 
+                Q = m * \mathtt{calDAC} + b
+
+            If no value was given at construction time, this is an arrays of
+            ones.
+
+        calDAC2Q_b (numpy.ndarray): Calibration of ``calDAC`` to charge for each
+            VFAT. This corresponds to :math:`b` in
+
+            .. math::
+
+                Q = m * \mathtt{calDAC} + b
+
+            If no value was given at construction time, this is an arrays of
+            zeros.
+
+        isVFAT3 (bool): Whether the detector under consideration uses VFAT3
+    """
+
+    def __init__(self, calDAC2Q_m=None, calDAC2Q_b=None, isVFAT3=False):
         super(ScanDataFitter, self).__init__()
 
         from gempython.utils.nesteddict import nesteddict as ndict
@@ -96,6 +170,7 @@ def __init__(self, calDAC2Q_m=None, calDAC2Q_b=None, isVFAT3=False):
         return
 
     def feed(self, event):
+        # Docs inherited from parent class
         super(ScanDataFitter, self).feed(event)
 
         charge = self.calDAC2Q_m[event.vfatN]*event.vcal+self.calDAC2Q_b[event.vfatN]
@@ -125,6 +200,16 @@ def feed(self, event):
         return
 
     def feedHisto(self, vfatN, vfatCH, histo, nEvts=None):
+        """
+        Feed the fitter with data stored in an histogram.
+
+        Args:
+            vfatN (int): The VFAT under consideration
+            vfatCH (int): The channel under consideration
+            histo (int): The data for the channel under consideration
+            nEvts (int): Override :py:attr`Nev` for the channel under
+                consideration (else the maximum value in the histogram is used)
+        """
         self.scanHistos[vfatN][vfatCH] = histo
         self.isDead[vfatN][vfatCH] = False
         if nEvts is None:
@@ -137,25 +222,10 @@ def feedHisto(self, vfatN, vfatCH, histo, nEvts=None):
 
     def fit(self, debug=False):
         """
-        Iteratively fits all scurves
-        Note:   if the user supplied calDAC2Q_m and calDAC2Q_b at
-                construction then output container will have relevant
-                parameters in charge units instead of DAC units
+        Iteratively fits all scurves, and populates the relevant class
+        attributes.
 
-        Returns self.scanFitResults
-            
-                 [0][vfat][ch] = scurve mean in either DAC units or charge (threshold of comparator)
-                 [1][vfat][ch] = scurve width in either DAC units or charge (noise seen by comparator)
-                 [2][vfat][ch] = scurve pedestal in hits (e.g. at 0 VCAL this is the noise)
-                 [3][vfat][ch] = fitChi2
-                 [4][vfat][ch] = self.scanCount[vfat][ch]
-                 [5][vfat][ch] = fitNDF
-
-        The TF1 is color coded:
-            Black - Default
-            Blue - Fit Converged 
-            Gray - Dead channel or empty input histogram
-            Orange - Fit result is empty
+        Returns: The filled :py:attr:`scanFitResults`
         """
 
         r.gROOT.SetBatch(True)
@@ -310,15 +380,34 @@ def fit(self, debug=False):
         return self.scanFitResults
     
     def getFunc(self, vfat, ch):
+        """Returns the fit function for the given VFAT and channel"""
         return self.scanFuncs[vfat][ch]
 
     def readFile(self, treeFileName):
+        """
+        Reads data from an ``scurveData.root`` file produced by
+        ``ultraScurve.py``.
+        """
         inF = r.TFile(treeFileName)
         for event in inF.scurveTree :
             self.feed(event)
         return
 
 def fitScanData(treeFileName, isVFAT3=False, calFileName=None):
+    """
+    Helper function to fit scan data. Creates a :py:class:`ScanDataFitter`,
+    loads the data and returns the results of :py:meth:`ScanDataFitter.fit`.
+
+    Args:
+        treeFileName (string): Path to the ``TFile`` that contains the scan data
+        isVFAT3 (bool): Whether the detector uses VFAT3
+        calFileName (string): Path to the file that contains calibration data
+
+    .. seealso::
+
+        :py:func:`gempython.gemplotting.utils.anautilities.parseCalFile` for the
+        format of the calibration file.
+    """
     from gempython.gemplotting.utils.anautilities import parseCalFile
     
     # Get the fitter

From 2115d058ff8e65f1c720281eb4cb6afa65810ad3 Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Sat, 23 Jun 2018 03:54:57 +0200
Subject: [PATCH 11/14] Add a short intro to fitting.rst

---
 doc/fitting.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/doc/fitting.rst b/doc/fitting.rst
index 013664ba..790a30dc 100644
--- a/doc/fitting.rst
+++ b/doc/fitting.rst
@@ -1,6 +1,10 @@
 ``gempython.gemplotting.fitting`` --- Fitting tools
 ===================================================
 
+This package contains only one module,
+:py:mod:`gempython.gemplotting.fitting.fitScanData`, that provides functions to
+fit S-curve data.
+
 .. automodule:: gempython.gemplotting.fitting.fitScanData
     :members:
     :undoc-members:

From fc01c1cb22de03d489871e435efa2b87b67d2dcd Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Fri, 22 Jun 2018 22:35:42 +0200
Subject: [PATCH 12/14] Update Sphinx configuration file

* Don't duplicate the author list everywhere
* Don't hard-code the copyright date
* Add a description to the texinfo page
---
 doc/conf.py | 25 ++++++++++++++++++-------
 1 file changed, 18 insertions(+), 7 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index ce3a0797..3ce160e2 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -12,6 +12,8 @@
 # serve to show the default.
 
 import sys, os
+import datetime
+import string
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -21,6 +23,15 @@
 
 # -- General configuration -----------------------------------------------------
 
+# List all authors here
+authors = [
+    'Cameron Bravo',
+    'Mykhailo Dalchenko',
+    'Brian Dorney',
+    'Louis Moureaux',
+    'Jared Sturdy',
+]
+
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
@@ -53,7 +64,7 @@
 
 # General information about the project.
 project = u'gempython.gemplotting'
-copyright = u'2018, Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'
+copyright = '%d %s' % (datetime.date.today().year, string.join(authors, ', '))
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -196,7 +207,7 @@
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
   ('index', 'gemplotting.tex', u'gemplotting Documentation',
-   u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy', 'manual'),
+   string.join(authors, ', '), 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -226,13 +237,13 @@
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'gemplotting', u'gemplotting Documentation',
-     [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
+     authors, 1),
     ('man/gemPlotter', 'gemPlotter.py', u'Plot time evolution of scan results',
-     [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
+     authors, 1),
     ('man/gemTreeDrawWrapper', 'gemTreeDrawWrapper.py', u'Make X-Y plots for each scan date',
-     [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
+     authors, 1),
     ('man/packageFiles4Docker', 'packageFiles4Docker.py', u'Creates a tarball containing data',
-     [u'Cameron Bravo, Mykhailo Dalchenko, Brian Dorney, Louis Moureaux, Jared Sturdy'], 1),
+     authors, 1),
 ]
 
 # If true, show URL addresses after external links.
@@ -246,7 +257,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'gemplotting', u'gemplotting Documentation',
-   u'Mykhailo Dalchenko, Evaldas Juska, RobertKing, Andrew Peck, Jared Sturdy', 'gemplotting', 'One line description of project.',
+   string.join(authors, ', '), 'gemplotting', 'GEM commissioning plotting tools.',
    'Miscellaneous'),
 ]
 

From d0f80a4cdb48cb808710908ad07e73bdc5632bfd Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Tue, 3 Jul 2018 15:09:22 +0200
Subject: [PATCH 13/14] Add man page for clusterAnaScurve.py

See PR #123
---
 doc/conf.py                  |   2 +
 doc/macros.rst               |   6 +-
 doc/man/clusterAnaScurve.rst |   4 +
 macros/clusterAnaScurve.py   | 270 +++++++++++++++++++++++++++++++++--
 mapping/chamberInfo.py       |   1 +
 5 files changed, 269 insertions(+), 14 deletions(-)
 create mode 100644 doc/man/clusterAnaScurve.rst

diff --git a/doc/conf.py b/doc/conf.py
index 3ce160e2..aa656fe0 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -244,6 +244,8 @@
      authors, 1),
     ('man/packageFiles4Docker', 'packageFiles4Docker.py', u'Creates a tarball containing data',
      authors, 1),
+    ('man/clusterAnaScurve', 'clusterAnaScurve.py', u'Analyze S-curves using the LSF cluster',
+     authors, 1),
 ]
 
 # If true, show URL addresses after external links.
diff --git a/doc/macros.rst b/doc/macros.rst
index e06fda7d..4de7f2a9 100644
--- a/doc/macros.rst
+++ b/doc/macros.rst
@@ -31,14 +31,10 @@ Macros
     :undoc-members:
     :show-inheritance:
 
-.. automodule:: clusterAnaScurve
-    :members:
-    :undoc-members:
-    :show-inheritance:
-
 .. toctree::
     :maxdepth: 1
 
+    man/clusterAnaScurve
     man/gemPlotter
 
 .. automodule:: gemSCurveAnaToolkit
diff --git a/doc/man/clusterAnaScurve.rst b/doc/man/clusterAnaScurve.rst
new file mode 100644
index 00000000..a2cebc4b
--- /dev/null
+++ b/doc/man/clusterAnaScurve.rst
@@ -0,0 +1,4 @@
+.. automodule:: clusterAnaScurve
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/macros/clusterAnaScurve.py b/macros/clusterAnaScurve.py
index a2764888..5bc167d5 100755
--- a/macros/clusterAnaScurve.py
+++ b/macros/clusterAnaScurve.py
@@ -1,17 +1,269 @@
 #!/bin/env python
 
-"""
-clusterAnaScurve
-================
+r"""
+``clusterAnaScurve.py`` --- Analyze S-curves using the LSF cluster
+==================================================================
+
+Synopsis
+--------
+
+**clusterAnaScurve.py** :token:`-q` <*QUEUE*> :token:`-t` *long|short* :token:`--anaType` *scurve|trim* (:token:`--chamberName` <*NAME*> | :token:`-i` <*FILE*>)
+
+Description
+-----------
+
+This tool will allow you to re-analyze the scurve data in a straightforward way
+without the time consuming process of launching it by hand. Takes a list of
+scandates file in the :any:`Two Columns Format`, and launches a job for each
+``(chamberName, scandate)`` pair. Each job will launch
+:program:`anaUltraScurve.py`.
+
+Mandatory arguments
+-------------------
+
+The following list shows the mandatory inputs that must be supplied to execute
+the script.
+
+.. program:: clusterAnaScurve.py
+
+.. option:: --anaType scurve|trim
+
+    Analysis type to be executed.
+
+.. option:: --chamberName <CHAMBER NAME>
+
+    Name of detector to be analyzed, from the values in
+    :py:data:`gempython.gemplotting.mapping.chamberInfo.chamber_config`. Either
+    this option or :option:`--infilename` must be supplied.
+
+.. option:: -i, --infilename <FILE>
+
+    Physical file name of the input file. The format of this input file should
+    follow the :any:`Two Column Format`. Either this option or
+    :option:`--chamberName` must be supplied.
+
+.. option:: -q, --queue <QUEUE>
+
+    Queue to submit your jobs to. Suggested options are ``8nm``, ``1nh`` and
+    ``1nd``.
+
+.. option:: -t, --type long|short
+
+    Specify GEB/detector type.
+
+Optional arguments
+------------------
+
+.. option:: --calFile <FILE>
+
+    File specifying CAL_DAC/VCAL to fC equations per VFAT. If this is not
+    provided the analysis will default to hardcoded conversion for VFAT2. See
+    :py:class:`gempython.gemplotting.fitting.fitScanData.ScanDataFitter` for
+    more information.
+
+.. option:: -c, --channels
+
+    Output plots will be made vs VFAT channel instead of ROB strip.
+
+.. option:: -d, --debug
+
+    If provided all cluster files will be created for inspection, and job
+    submission commands printed to terminal, but no jobs will be submitted to
+    the cluster. Using this option before submitting a large number of jobs is
+    strongly recommended.
+
+.. option:: --endDate <YYYY.MM.DD>
+
+    If :option:`--infilename` is not supplied this is the ending scandate, in
+    ``YYYY.MM.DD`` format, to be considered for job submission. The default is
+    whatever ``datetime.today()`` evaluates to.
+
+.. option:: --extChanMapping <FILE>
+
+    Physical file name of a custom, non-default, channel mapping file. If not
+    provided the default slice test ROB strip to VFAT channel mapping will be
+    used.
+
+.. option:: -f, --fit
+
+    Fit S-curves and save fit information to output ``TFile``.
+
+.. option:: -p, --panasonic
+
+    Output plots will be made vs Panasonic pins instead of ROB strip.
+
+.. option:: --startDate <YYYY.MM.DD>
+
+    If :option:`--infilename` is not supplied this is the starting scandate, in
+    YYYY.MM.DD format, to be considered for job submission. Default is
+    ``2017.01.01`` so the start of the slice test will be used.
+
+.. option:: --zscore <NUMBER>
+
+    Z-Score for Outlier Identification in the MAD Algorithm. For details see
+    talks by `B. Dorney`_ or `L. Moureaux`_.
+
+    .. _B. Dorney: https://indico.cern.ch/event/638404/contributions/2643292/attachments/1483873/2302543/BDorney_OpsMtg_20170627.pdf
+
+    .. _L. Moureaux: https://indico.cern.ch/event/659794/contributions/2691237/attachments/1508531/2351619/UpdateOnHotChannelIdentificationAlgo.pdf
+
+.. option:: --ztrim <NUMBER>
+
+    Specify the :math:`P`-value of the trim in the quantity:
+    ``scurve_mean - ztrim * scurve_sigma``
+
+Finally :program:`clusterAnaScurve.py` can also be passed the cut values used in
+assigning a ``maskReason`` described at
+:any:`Providing Cuts for ``maskReason`` at Runtime`.
+
+Full Example For P5 S-Curve Data
+--------------------------------
+
+Before you start due to space limitations on AFS it is strongly recommended that
+your :envvar:`DATA_PATH` variable on lxplus point to the work area rather than
+the user area, e.g.:
+
+.. code-block:: bash
+
+    export DATA_PATH=/afs/cern.ch/work/<first-letter-of-your-username>/<your-user-name>/<somepath>
+
+In your work area you can have up to 100GB of space. If this is your first time
+using ``lxplus`` you may want to increase your storage quota by following
+instructions `here`_.
+
+.. _here: https://resources.web.cern.ch/resources/Help/?kbid=067040
+
+Now connect to the P5 ``dqm`` machine. Then if you are interested in a chamber
+``ChamberName`` execute:
+
+.. code-block:: bash
+
+    cd $HOME
+    plotTimeSeries.py --listOfScanDatesOnly --startDate=2017.01.01
+    packageFiles4Docker.py --ignoreFailedReads --fileListScurve=/gemdata/<ChamberName>/scurve/listOfScanDates.txt --tarBallName=<ChamberName>_scurves.tar --ztrim=4 --onlyRawData
+
+Then connect to ``lxplus``, and after setting up the env execute:
+
+.. code-block:: bash
+
+    cd $DATA_PATH
+    scp <your-user-name>@cmsusr.cms:/nfshome0/<your-user-name>/<ChamberName>_scurves.tar .
+    tar -xf <ChamberName>_scurves.tar
+    mv gemdata/<ChamberName> .
+    clusterAnaScurve.py -i <ChamberName>/scurve/listOfScanDates.txt --anaType=scurve -f -q 1nh
+
+It may take some time to finish the job submission. Please pay attention to the
+output at the end of the :program:`clusterAnaScurve.py` command as it provides
+helpful information for managing jobs and understanding what comes next. Once
+your jobs are complete you should check that they all finished successfully. One
+way to do this is to check if any of them exited with status ``Exited`` and
+check for the exit code. To do this execute:
+
+.. code-block:: bash
+
+    grep -R "exit code" <ChamberName>/scurve/*/stdout/jobOut.txt --color
+
+This will print a single line from all files where the string exit code appears.
+For example:
+
+    GEMINIm01L1/scurve/2017.04.10.20.33/stdout/jobOut.txt:Exited with exit code 255.
+    GEMINIm01L1/scurve/2017.04.26.12.25/stdout/jobOut.txt:Exited with exit code 255.
+    GEMINIm01L1/scurve/2017.04.27.13.27/stdout/jobOut.txt:Exited with exit code 255.
+    GEMINIm01L1/scurve/2017.06.07.12.17/stdout/jobOut.txt:Exited with exit code 255.
+    GEMINIm01L1/scurve/2017.07.18.11.09/stdout/jobOut.txt:Exited with exit code 255.
+    GEMINIm01L1/scurve/2017.07.18.18.34/stdout/jobOut.txt:Exited with exit code 255.
+
+For those lines that appear in the grep output command you will need to check
+the standard err of the job which can be found in:
+
+.. code-block:: bash
+
+    <ChamberName>/scurve/<scandate>/stderr/jobErr.txt
+
+Note since some scans at P5 may have failed to complete successfully some jobs
+may intrinsically fail and be non-recoverable. If you have questions about a
+particular job you can try to search in the e-log around the scandate in time to
+see if anything occurred around this time that might cause problems for the
+scan. If you would like to re-analyze a failed job you can do so by calling:
+
+.. code-block:: bash
+
+    $DATA_PATH/<ChamberName>/scurve/<scandate>/clusterJob.sh
+
+If a large number of jobs have failed you should spend some time trying to
+understand why, and then re-submit to the cluster, rather than attempting to
+analyze them all by hand.
+
+Finally after you are satisfied that all the jobs that could complete
+successfully have completed you can:
+
+#. Re-package the re-analyzed data into a tarball, and/or
+#. Create time series plots to summarize the entire dataset.
+
+For case 1, re-packaging the re-analyzed files into a tarball, execute:
+
+.. code-block:: bash
+
+    packageFiles4Docker.py --ignoreFailedReads --fileListScurve=<ChamberName>/scurve/listOfScanDates.txt --tarBallName=<ChamberName>_scurves_reanalyzed.tar --ztrim=4
+    mv <ChamberName>_scurves_reanalyzed.tar $HOME/public
+    chmod 755 $HOME/public/<ChamberName>_scurves_reanalyzed.tar
+    echo $HOME/public/<ChamberName>_scurves_reanalyzed.tar
+
+Then provide the terminal output of this last command to one of the GEM DAQ
+Experts for mass-storage.
+
+For case 2, create time series plots to summarize the entire dataset, execute:
+
+.. code-block:: bash
+
+    <editor of your choice> $VIRTUAL_ENV/lib/python2.7/site-packages/gempython/gemplotting/mapping/chamberInfo.py
+
+And ensure the only uncommented entries of the ``chamber_config`` dictionary
+match the set of ChamberName's that you have submitted jobs for. Then execute:
+
+.. code-block:: bash
+
+    plotTimeSeries.py --startDate=2017.01.01 --anaType=scurve
+
+Please note the above command may take some time to process depending on the
+number of detectors worth of data you are trying to analyze. Then a series of
+output ``*.png`` and ``*.root`` files will be found at:
+
+.. code-block:: bash
+
+    $ELOG_PATH/timeSeriesPlots/<ChamberName>/vt1bump0/
+
+If you would prefer to analyze ChamberName's one at a time, or to have an output
+``*.png`` file for each VFAT, you can produce time series plots individually by
+executing the :program:`gemPlotter.py` commands provided at the end of the
+:program:`clusterAnaScurve.py` output. This might be preferred as when analyzing
+a large period of time the 3-by-8 grid plots that :program:`plotTimeSeries.py`
+will produce for you may be hard to read. In either case
+:program:`gemPlotter.py` or :program:`plotTimeSeries.py` will produce a
+``TFile`` for you in which the plots at the per VFAT level are stored for you to
+later investigate.
+
+If you encounter issues in this procedure please spend some time trying to
+figure out what wrong on your side first. If after studying the documentation
+and reviewing the commands you have exeuted you still do not understand the
+failure please ask on the ``Software`` channel of the CMS GEM Ops Mattermost
+team or submit an issue to the `github page`_.
+
+.. _github page: https://github.com/cms-gem-daq-project/gem-plotting-tools/issues/new
+
+Environment
+-----------
+
+.. glossary::
+
+    :envvar:`DATA_PATH`
+        The location of input data
+
+    :envvar:`ELOG_PATH`
+        Results are written in the directory pointed to by this variable
 """
 
 if __name__ == '__main__':
-    """
-    Takes a list of scandates file, see parseListOfScanDatesFile(...) documentation,
-    and launches a job for each (chamberName, scandate) pair.  Each job will 
-    launch anaUltraScurve.py
-    """
-    
     from optparse import OptionParser, OptionGroup
     parser = OptionParser()
     parser.add_option("--anaType", type="string", dest="anaType",
diff --git a/mapping/chamberInfo.py b/mapping/chamberInfo.py
index 51dcfefe..d6403c86 100644
--- a/mapping/chamberInfo.py
+++ b/mapping/chamberInfo.py
@@ -3,6 +3,7 @@
 --------------------------------------------------------
 """
 
+#: Available chambers
 chamber_config = {
     #Coffin Setup
     #0:"GE11-VI-L-CERN-0002"

From a7ff0255eb30168e73f439d666873bbb4f8720ca Mon Sep 17 00:00:00 2001
From: Louis Moureaux <lmoureau@ulb.ac.be>
Date: Tue, 3 Jul 2018 15:52:32 +0200
Subject: [PATCH 14/14] Add undocumented options of clusterAnaScurve.py

--maxEffPedPercent
--highNoiseCut
--deadChanCutLow
--deadChanCutHigh

See PR #123
---
 macros/clusterAnaScurve.py | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/macros/clusterAnaScurve.py b/macros/clusterAnaScurve.py
index 5bc167d5..be098c19 100755
--- a/macros/clusterAnaScurve.py
+++ b/macros/clusterAnaScurve.py
@@ -112,9 +112,32 @@
     Specify the :math:`P`-value of the trim in the quantity:
     ``scurve_mean - ztrim * scurve_sigma``
 
-Finally :program:`clusterAnaScurve.py` can also be passed the cut values used in
-assigning a ``maskReason`` described at
-:any:`Providing Cuts for ``maskReason`` at Runtime`.
+Parameters which specify how Dead, Noisy, and High Pedestal Channels are
+characterized:
+
+.. option:: --maxEffPedPercent <PERCENTS>
+
+    Threshold for setting the ``HighEffPed`` mask reason, if channel
+    (``effPed > maxEffPedPercent * nevts``) then
+    :py:data:`gempython.gemplotting.utils.anaInfo.MaskReason.HighEffPed` is set.
+
+.. option:: --highNoiseCut <CHARGE>
+
+    Threshold for setting the ``HighNoise`` ``maskReason``, if channel
+    (``scurve_sigma > highNoiseCut``) then
+    :py:data:`gempython.gemplotting.utils.anaInfo.MaskReason.HighNoise` is set.
+
+.. option:: --deadChanCutLow <CHARGE>
+
+    If channel (``deadChanCutLow < scurve_sigma < deadChanCutHigh``) then
+    :py:data:`gempython.gemplotting.utils.anaInfo.MaskReason.DeadChannel` is
+    set.
+
+.. option:: --deadChanCutHigh <CHARGE>
+
+    If channel (``deadChanCutHigh < scurve_sigma < deadChanCutHigh``) then
+    :py:data:`gempython.gemplotting.utils.anaInfo.MaskReason.DeadChannel` is
+    set.
 
 Full Example For P5 S-Curve Data
 --------------------------------