===========================================================
How to construct and the subtract ground templates from TOD
===========================================================

The ground code is largely contained in :mod:`cbasspy.groundpy.newGtCode`.
There are two convenient wrappers, one for constructing ground tempaltes and one for subtracting them from TOD.
They are both passed an options .ini file as input.

You will need to run the code independently for each elevation.
Typically you will run the ground subtraction first on elevation 37 data, before using that as an input model sky when constructing higher elevation templates.

Constructing ground templates
-----------------------------
The wrapper for constructing ground templates from TOD is located here:
cbass_analysis/cbasspy/groundpy/makeGroundTemplates.py 

It is called from the command line by passing it an options ini file, which is discussed below.
It is called as follows::

    python cbass_analysis/cbasspy/groundpy/makeGroundTemplates.py groundOptions.ini

Subtracting ground templates
----------------------------
The wrapper for sutbracting ground templates from TOD is located here:
cbass_analysis/cbasspy/groundpy/loadAndSubtractGroundTemplates.py

It is called from the command line by passing it an options ini file AND telling it whether it is being run under mpi.
It is called as follows::

    python cbass_analysis/cbasspy/groundpy/loadAndSubtractGroundTemplates.py groundOptions.ini False

To run this code in the Glamdring queue, you need to put it in a .scr file and set the MPI option to True.
e.g. put the following line into a file like run_ground_removal.scr::

    python cbass_analysis/cbasspy/groundpy/loadAndSubtractGroundTemplates.py groundOptions.ini True

Then from the command line::

    addqueue -q W -n X -m Y -c 'Z' run_ground_removal.scr

where W is the queue, X is the number of cores, Y is the memory per core and Z is a comment.

Options file
------------
The input options are all passed using an .ini file.
This has several benefits;
firstly it means that there is a permanent record of exactly what was done to the data stored in the file,
secondly it means that to change the parameters in the ground subtrction routine we don't have to edit the ground code.

A typical options file will look like the following::

    [dateOptions]
    # Period over which to produce ground templates
    startDate : 20-Jan-2014
    endDate : 20-Jun-2014
    # How much data should go into each template, in days
    temporalBinWidth : 5.
    
    [maskOptions]
    maskFileNameI : /users/luke/CBASS/cbass_analysis/constants/karen_newmask.fits
    maskFileNameQ : /users/luke/CBASS/cbass_analysis/constants/karen_newmask.fits
    maskFileNameU : /users/luke/CBASS/cbass_analysis/constants/karen_newmask.fits

    [azBinOptions]
    # Width of azimuth bins, in degrees
    azBinWidth : 1.0
    
    [detrendingOptions]
    # A reference azimuth is needed for detrending.
    # Give an azimuth range (in degrees) to average data together over.
    refAzMin : 358.0
    refAzMax : 2.0
    
    [files]
    # File list
    fitsFileList : /stegodon/Reductions/v28/v28_tod/v28_ungroundsubtracted_goodground_goodels_fullpath.txt
    # Cut extension name
    cutName : NIGHT
    # Elevation, in degrees
    targetEl : 37
    # Elevation tolerance, in degrees
    targetElTol : 2
    
    [outputOptions]
    # Where to save the templates
    outDir : ./testOut/
    # Output string to attach to file names
    outString : 5d_37
    # save templates in the old school format - not yet opperational
    saveOldSchool : False
    # Where to save the ground subtracted TOD
    outFitsDir : ./testGsTod/
    
    [modelSkyOptions]
    # Use a model sky when subtracting drifts
    useModelSky : False
    modelSkyName :


Hopefully the meaning of the input options is fairly obvious.
The same options file can be passed to both loadAndSubtractGroundTemplates.py and loadAndSubtractGroundTemplates.py,
or separate options files if, for example, you only want to subtract the ground from a subset of the files.