---------------------------------
CDMSBATS
===========
### Table of Contents
1. [Overview]("overview")
2. [Getting Started]("getstart")
   A. [Compiling CDMSBats]("getstart")
   B. [Setting Environment Variables]("env")
3.  Installation
    A. [BatFaker]("faker")
    B. [BatRoot]("batroot")
    C. [BatCalib]("calib")
         i. [Setup]("calibsetup")
	 ii. [Executing BatCalib]("calibexe")
	 iii. [BatCalib Settings](""calibsettings")
	 iv. [Calibration Constants]("calibconst")
	 v. [Additional Notes]("calibnotes")
    D. [BatNoise]("noise")
         i.
    E. BatViewer

### I. Overview <a name="overview"> </a>
This file is intended to serve as a general instructional for using the various components of
CDMSBATS. CDMSBATS is a set of packages used to process and analyze data, designed
with the ability to be used independently; though many configurations will be shared by all,
some will be unique to the program being used. More detailed setup instructions will be
outlined below. First, let's take a brief look at CDMSBATS in general and its functions.
Depending on your desired results, you may wish to utilize:

**BatFaker**: Contains tools designed to produce fake raw data files, primarily for use in data
salting.

**BatRoot**: The first tier of data processing.Takes raw quantities like voltage, current, time,
charge, raw pulse traces and outputs real physics quantities. Uses ROOT rq files for both input
and output (a raw, compressed binary format).

**BatCalib**: The second tier of data processing. Applies calibration constants to generate
rrq's from RQ root files (recall that these are "Refined Reduced Quantities" such as time delay,
or energy and yield).

**BatNoise**: The third tier of data processing. Applies various filtering algorithms to raw data
in order to produce histograms such as Power Spectrum Density (PSD) from selected noise
traces as well as other quantities.

**BatViewer**: A utility which calls on ROOT to display an interactive TCanvas to view a single
raw data file, or series raw data folder.

#### Setting Up Paths and Environment Variables <a name="env"> </a>
CDMSBats requires access number of libraries that are likely to be located in a few places.
It's important to make sure each of these are set appropriately, as little useful information will be given if there is an issue.

CDMSBATSDIR - this is the directory where you checked out "cdmsbats"
i.e. /somedirectory/cdmsbats

BATROOT_NOISEFILES - path to the noise files generated by BatNoise

BATROOT_RAWDATA - where the raw data files (.gz file types) are located.

BATROOT_RQDATA - path to where the output files (end in .root) will be placed. Will be used by BatCalib later

BATROOT_GPIBFILES - path to where the GPIB files are (these files are used for Soudan data only. If not using Soudan data set with a dummy path (i.e. /tom/example))
BATROOT_AUXFILES - path to where the AUX files are (these files are used for Soudan data only. If not using Soudan data set with a dummy path (i.e. /tom/example))

**************
###  II. A simplified makefile system for CDMSBATS <a name="getstart"> </a>
This section describes an *optional* way to compile the packages that reside
within cdmsbats.From this directory,  users may build any or all of the job
stages for raw data processing: BatNoise, BatRoot, or BatCalib, along with the BatCommon library of shared facilities for all three job stages. If you are
looking to install and run the individual packages, please refer to the
documentation specific to BatNoise, BatRoot or BatCalib for full installation
instructions that will get you started.  Each stage of the processing (BatNoise,
BatRoot, and BatCalib) may also be built from within the the package
directory.

*Note that currently,  ROOT v5.xx.xx (including FFTW)  and the BLAS libraries
installed to compile the above executables.*

For users who work with all the stages of processing, or who aren't sure
what they might need to run, everything can be built in one step:
>$make all

If you just need one of the executables, you can simply "make" the directory
for the component you wish to install, for example:
>$make BatRoot

The executables will be put into the directory BUILD/bin.  In your PATH, you
should add the complete directory path to that directory, which you can do
with one of the following commands, depending on your shell:

TCSH: ```setenv PATH ${PATH}:`pwd`/BUILD/bin```
BASH: ```export PATH=${PATH}:`pwd`/BUILD/bin```

------------------------------------------------------------------------------------------------

## BatCalib <a name="calib"></a>

#### SETUP <a name="calibsetup"></a>
BatCalib is the second tier of data processing. To run it, you must have ROOT
(v5.20 or later) properly installed. See the ROOT webpages for install
instruction

Once you have done this, build BatCalib from this directory (or the one above
it) by typing:
>make BatCalib

After successful compilation, you will need to set the following paths so that
BatCalib knows where to find the RQ data  and where to put the output:

BATCALIB_PROC (optional)
an alternate directory where the job-setting files are located,
without specifying this, BatCalib will pick up the default file from:
/somedirectory/cdmsbats/UserSettings/BatCalibSettings/processing

BATCALIB_CONST (optional)
an alternate directory where the calibration constants files are located,
without specifying this, BatCalib will pick up the default file from:
/somedirectory/cdmsbats/UserSettings/BatCalibSettings/calibration

BATCALIB_RQDATA
this is the directory where the rq data files are (these end in .root)

BATCALIB_RRQDATA
this is the directory where you want to put the output root files.

The make command places the executable into the BUILD/bin directory
(see cdmsbats/README).  To run without having to specify the full path
to this directory, you may set your path to point to this directory:

TCSH: ```setenv PATH ${PATH}:$CDMSBATSDIR/BUILD/bin```
BASH: ```export PATH=${PATH}:$CDMSBATSDIR/BUILD/bin```

In addition to the environmental variables, set the file prefixes in the
UserSettings/BatCalibSettings/processing/optionsXXXXData.Default file (where XXXX corresponds to the location of your experiment).  You must set both RQ_DATA_PREFIX and
RRQ_DATA_PREFIX.  These will look for and write out files with the prefixes
that you specified.  Don't use the same prefix for both!  Otherwise BatCalib
will try to write output data to the input file.

-----------------------------------------
#### EXECUTING BATCALIB
<a name="calibexe"></a>
Once you have properly set the above, run BatCalib (in BUILD/bin) by typing:

BatCalib series# dump# maxEvents(optional) processingFile(optional) calibrationFile(optional)

For example, if you want to process 10 events from an RQ file myfile_170319_1616_F0002.root type:

BatCalib 170319_1616 2 10

(inside your options file, RQ_DATA_PREFIX should be set to "myfile")

* Note that this command is intended to process one file per raw data file.
  If you want to run on a merged rq file as we did for production in 2010,
  then you can specify this by changing the flag "USE_MERGED_RQ = 1" in the
  options configuration file.  For this, then subsitute the word "merged" in
  place of the dump#.  This change was made to facilite automated processing
  of files at Soudan and also at the test facilities.
----
#### SETTINGS
<a name="calibsettings"></a>
In the directory $CDMSBATSDIR/UserSettings/BatCalibSettings/processing, there are various files that begin
with the prefix "options" and end with ".Default".  These are text files
that tell BatCalib what processing configuration to run in.  Most of the
setting are fairly self explanatory.  Examples of things you can control
include which pulse analyzing algorithms are run (for example Optimal Filter
and PipeFitter).  You can also turn the processing on and off for specific
detectors or components of the experiment.  For example, you can turn off
calibration of all zips except zip17.  Look in the file and follow the
examples.  If is fairly self explanatory and the format is flexible.  You DO
NOT need to RECOMPILE BatCalib for these settings to be picked up!  BatCalib
will automatically detect which experimental location your data comes from
(i.e Soudan, or UCB or SUF) and it will load the relevant processing
configuration for that dataset.

Alternately, you can force BatCalib to read a different processing
configuration file then the one that has the .Default extension by passing
it in the full pathname as a third argument to the BatCalib command (see
above).

NOTE: The calibration algorithms should match the RQ's that exist in your
file.  If you did not run Pipefitter in BatRoot when you generated your RQ
file, then do not run PipeFitter in BatCalib when processing that file.  If
you forget this step, then BatCalib will not allow you to process the data
until you fix your configuration file.

*****

#### CALIBRATION CONSTANTS <a name="calibconst"></a>
In the directory $CDMSBATSDIR/UserSettings/BatCalibSettings/calibration, is
another set of configuration files.  These contain all the parameters and
calibration constants that are used by the various calibration algorithms.
You can modify these parameters by changing the values in these files.
Again you do no need to recompile for BatCalib to pick up a new value and
you can also force BatCalib to read a different file by passing in the full
directory path as a fourth argument to the BatCalib command.

*****

#### NOTES:
<a name="calibnotes"></a>
Feb. 2011: Significant reorganization was done to accommodate the growing
number of detector types and degenerate number of calculations for similar
quantities.  Each detector type now has its own "GenRRQDataXXX" class.  The
original version of BatCalib is preserved in the GenRRQDataCDMSII class,
which works up through Soudan R131 data.  At the same time we streamlined
the naming convention for rq's and rrq's, so some long-standing names become
obsolte.  In particular, we renamed phonon optimal filter rq's from P*eV to
P*amps.  The ConstFreqRTFTWalk quantities were renamed from P*CFr% to P*WKr%
and correspondingly the VarFreqRTFTwalk was renamed from P*r% to P*VWKr%.
At the same time we standarized all phonon rrq quantities to begin with "p"
and all charge rrq quantities to begin with "q". [LLH]

----