/**
\mainpage Plug Strip Software
\addindex Plug Strip Software

\author
<A HREF="mailto:benn@physics.ucla.edu">Benn Tannenbaum</A> 

\date 15 May 2001
\date updated 16 May 2002

<h2>Description</h2>

Implementation of Plug Strip reconstruction code. This package consists of
three modules which perform \ref corrections (PesDtoEModule), \ref cluster 
(PlugStripClusterModule) and \ref save to PADs (PESQ_Module).<p>

<h2>Input data</h2>
The input to the correction software are PESD banks:<p>
<pre>
#include "RawDataBanks/PESD_StorableBank.hh"
AbsEnv* pEnv = AbsEnv::instance( );//get pointer to event
Handle<PlugStripColl> hPlugStripColl(new PlugStripColl);
for (EventRecord::ConstIterator iPESD(anEvent,"PESD_StorableBank"); 
     iPESD.is_valid(); ++iPESD) {
  ConstHandle<PESD_StorableBank> aPESD(iPESD);
  hPlugStripColl = doStrips.doPlugStrips(_nevt,aPESD, _paramSet.storeHist());
  if ((anEvent->append(hPlugStripColl)).is_null() ) {
    cerr<<"PesDtoEModule::event: Cannot add PlugStripColl to event\n";
  }
}
</pre>


<h2>Deliverables</h2>

Output data are the corrected strips (PlugStrip), clusters (Pes2dCluster) and
PADs (PESQ). All are appended to the event. They are accessed as follows:<p>

<pre>
#include "CalorObjects/PlugStripColl.hh"
  AbsEnv* pEnv = AbsEnv::instance();
  Handle<PesClusterColl> pesClusterCollH(new PesClusterColl());
  for (EventRecord::ConstIterator iPSC(anEvent,"PlugStripColl"); 
       iPSC.is_valid(); ++iPSC) {
    ConstHandle<PlugStripColl> aPSC(iPSC);
    vector<PlugStrip> thePlugStrips = aPSC->contents();
  }
</pre>

Similarly for the Pes2dCluster and the PESQ.

See the individual data classes for details about what can be accessed.</p>

A ROOT ntuple is created when the module Pesana_test is run, as shown below. the
output is in a file named showermax.root in the user's /cdf/scratch/ directory.
It contains an ntuple with most of the variables available to users of the PES
code. Additionally, there are several histograms which display the occupancy and
average energy of the detector, viewed by eta versus phi, x verus y, and as a
function of the strip number, octant, layer, and plug.

Other histograms are created through the PesValidation module. These histograms
are available on fcdflnx3.fnal.gov in /cdf/scratch/cdfprod0/.

\section modules Module details
\subsection corrections Corrections to raw strips

The Plug Shower Maximum detector is installed at roughly the location of the
maximum energy deposit for EM showers in the plug EM calorimeter. There is one
in each endplug, each divided into eight 45-degree octants and 2 layers. Each
layer in each octant consists of 200 scintillator strips. For the \e u layer
(closer to the interaction region), the strips are oriented -22.5 degrees away
from being radial and for the \e v layer (futher from the interaction region),
the strips are oriented +22.5 degrees away from being radial. Additionally, the
strips are segmented such that the strips numbered 1-170 are in the low eta
region (1.13 \< eta \< 2.60) and the strips numbered 171-200 are the high
eta region (2.6 \< eta \< 3.50). Embedded in each strip is a wave length
shifting fiber which goes to a single pixel of a 16-channel multi-anode
photomultiplier tube. The tubes which read out the high-eta region are run at a
lower gain than those tubes which read out the low-eta region.

The phototubes used for this detector are somewhat nonlinear in the region of
interest, and can have substantial pixel to pixel gain variations. To remove
these effects we must perform corrections to the data from this detector. This
is done in the PesDtoEModule.

The PesDtoE module loops over all PESD_StorableBanks in the event and passes
the contents to the PlugStripMaker. The PlugStripMaker corrects for
non-linearity and pixel-to-pixel and tube-to-tube gain variations. It then
places the endplug, octant, layer, strip, and corrected and uncorrected energies
into a PlugStrip. The PlugStrip is placed in a collection of PlugStrips, a
PlugStripColl. The PlugStripColl is returned the the PesDtoEModule
where it is appended to the event.

The factors used for correcting the raw PESD information are stored in the
database. At beginRun this information is retrieved from the database and stored
in an array of PesConstants. At present there are \b no automatically run
calibrations for the PES. The software for the sourcing (to measure
pixel-to-pixel changes and changes in the attenuation length of the WLS fiber)
is being written, and the hardware and software for the laser calibration (to
measure tube-to tube drift and, potentially, changes in the linearity) are in
progress.

\subsection cluster Clustering strips

No object passing through the detector deposits energy in a single strip. Thus,
to get an accurate measure of the position of the particle passing through the
detector, we must cluster strips together. There are two steps to this. First,
we must cluster the strips in a given layer. Next, we must associate the clusters in the \e u layer
with the proper clusters in the \e v layer. This is done in
PlugStripClusterModule. Once we have a 2-dimensional cluster, we can
calculate the eta and phi of the cluster and associate it with an energy deposit
in the calorimeter.

At present we use a seed/shoulder clustering algorithm for the 1-dimensional
clustering. The module searches through all PlugStrips in an event. Strips with
energy greater than the seed value are used as cluster seeds, and all
neighboring strips with energy greater than the shoulder threshold are added to
the cluster. 

\date 1 October 2001 <em>done</em> Need to add a new clustering method that
simply takes all strips in a window of a user-defined size. This is desirable
as the current clustering technique fails when there are dead strips. Also, the
current clustering software is a bit of a jumble. It needs to be separated into
a Maker and a Module section; Jay Hauser is working on that.

The current 2-dimensional clustering algorithm simple associates all possible
combinations in a given octant, checking only to be sure they are fiducial. It
does not check for any possible ghost combinations.

\attention Need to add a track-based clustering algorithm. This has been done by
David Waters and needs documentation. Also need to add an EM tower based
clustering algorithm (i.e. for photons).

\subsection save Saving corrected strips

This module takes the output from PesDtoEModule and saves it to a PAD. The input
is a collection of PlugStrip and the output is a collection of PESQ. All
PlugStrip over the threshold saveThrs (as set in the talk-to) are saved.

\date 10 February 2002 <em>Done</em> Need to add bank compression. I have an
idea how to do that, losslessly, that will result in almost a factor of two
saving.

<h3>Parameters</h3>

All parameters are set via talk-tos. They are all documented in their respective
module files. I list them here for completeness.
\htmlonly
<table BORDER WIDTH="100%" NOSAVE >
<tr NOSAVE> 
<th>Module</td>
 <th NOSAVE>Name</td>
 <th>Type</td>
 <th>Function</td>
 <th>Default</td>
</tr>
<tr><td>PESQ_Module</td>
<td>  saveThrs </td>
<td> double</td>
<td> Set the minimum energy of a saved strip</td>
<td>0</td>
</tr>
<tr><td>PesDtoEModule</td>
<td>      readWrite</td>
<td>bool</td>
<td> save to or read from the database</td>
<td>false [read]</td>
</tr>
<tr><td>PesDtoEModule</td>
<td>DBversion</td>
<td> int</td>
<td> Database version number</td> 
<td> 0 [auto-increment on write]</td>
</tr>
<tr><td>PesDtoEModule</td>
<td>      storeHist</td>
<td>bool</td>
<td>store or not store histograms </td>
<td> false [no save]
</tr>
<tr><td>PlugStripClusterModule</td>
<td> seedThrs</td>
<td>double</td>
<td>        define the seedThreshold</td>   
<td>1050</td>
</tr>
<tr><td>PlugStripClusterModule</td>
<td>shoulderThrs </td>
<td>double</td>
<td>define the shoulderThreshold</td>
<td>1000</td>
</tr>
<tr><td>PlugStripClusterModule</td>
<td>   printClInfo</td>
<td>bool</td>
<td>     print out clustering info</td>
<td>false</td>
</tr>
<tr><td>PlugStripClusterModule</td>
<td>printStripInfo</td>
<td>bool</td>
<td>print out strip info</td>
<td>false</td>
</tr>
<tr><td>PlugStripClusterModule</td>
<td>printBnkInfo</td>
<td>bool</td>
<td>print out bank info</td>
<td>false</td>
</tr>
<tr><td>PlugStripClusterModule</td>
<td>storeHist</td>
<td>bool</td>
<td>save histograms</td>
<td>false</td>
</tr>
<tr><td>PlugStripClusterModule</td>
<td>histPrEvery</td>
<td>int</td>
<td>how often to make entries in histogram</td>
<td>10</td>
</tr>
<tr>
<td>PlugStripClusterModule</td>
<td>histPrMax</td>
<td>int</td>
<td>maxiumum entries per histogram</td>
<td>10000</td>
</tr>


</table>

\endhtmlonly


<h2>Example</h2>
Here is an example of using this code:
\include Pesana_test.cc


*/