CASA History Strategy
---------------------
STM & CB 2008-02-17

It is clear that soon (Patch 2 before summer school) we will need
to make sure that the history files attached to ms and images
uniformly contain the correct information.  This includes:

1. The tasks and tool methods that were run on the relevant file,
   with:
   a) the full inputs (e.g. as in the <task>.last file)
   b) important outputs (WARN,SEVERE,INFO)
   c) values of any return variables (e.g. xstat from imstat)

   It is most important that this be done for any operation that
   changes the file (ms,image) or produces an output ms or image.
   But to be safe, should log in the history any task run.

   We definitely want the history from all successful task/tool runs,
   but for completeness failed ones should go in also.  Thus the
   inputs should be written at the start of execution.

2. Previous history upon import into CASA 

   This includes the AIPS histories (for stuff coming in via
   importuvfits or importfits from AIPS), and any ASDM histories.

3. History should be inherited by any child files, such as:

   a) an image made by an imaging task/tool from one or more ms should
      inherit the histories of al ms(s) that made the image

   b) a split ms or subim should inherit the history of the parent
      ms/im 

   c) a concat ms should inherit histories of all parent ms(s)

   d) upon calibration using a model image, the history of the model
      image should be put in the ms 

   e) an image made for combination of images (e.g. immath) should 
      inherit the parent histories

4. The history block from each task/tool run should include the
   version that was run (e.g. CASA Version 2.0 Rev 4471)

History Format
--------------

A simple linear table with time indexes (as is our current history
table we think) will suffice.  However, a clever hierarchical history
table (database?) might make accessing this later to be easier.  But
the user needs to get readable (and printable) history output somehow.

History and the Logger
----------------------

To make things simple, I propose that all INFO level messages go into
the history (along with SEVERE/WARN).  This means that task/tool
writers should put only important information at INFO priority, that
will be important for "posterity".  Messages of lesser importance,
such as progress indicators, should go at INFO1.  We should then make
the default logger level INFO1 (e.g. casalog.filter('INFO1')).

Task History File
-----------------

We would also like to propose that a taskhistory.saved file be placed
in each ms or image subdirectory that contains the contents of all the
<taskname>.last files, with an additional timecode and version
(e.g. casalog.version() output).  This would make tracing the history
and being able to grab the inputs to rerun things much easier.  These
would follow the inheritance rules given above.  This is written after
(successful) execution along with the .last file, and thus any return
variables will contain the filled output.  Obviously, only tasks will
generate entries in this ascii file.

# CASA Version 2.0 Rev 4471
# Feb 16 15:47 /home/sandrock2/smyers/Testing2/Feb08/polcal.last
taskname           = "polcal"
vis                =  "testpol.cband.ms"
caltable           =  "testpol.cband.pcal"
field              =  "2202+422"
spw                =  ""
selectdata         =  False
timerange          =  ""
uvrange            =  ""
antenna            =  ""
scan               =  ""
msselect           =  ""
solint             =  86400.0
preavg             =  300.0
refant             =  "08"
minsnr             =  3
poltype            =  "Dlin+QU"
append             =  False
gaintable          =  "testpol.cband.fluxscale"
gainfield          =  ['']
interp             =  ['linear']
spwmap             =  []
gaincurve          =  False
opacity            =  0.0
async              =  False
#polcal(vis="testpol.cband.ms",caltable="testpol.cband.pcal",field="2202+422",spw="",selectdata=False,timerange="",uvrange="",antenna="",scan="",msselect="",solint=86400.0,preavg=300.0,refant="08",minsnr=3,poltype="Dlin+QU",append=False,gaintable="testpol.cband.fluxscale",gainfield=[''],interp=['linear'],spwmap=[],gaincurve=False,opacity=0.0,async=False)

# CASA Version 2.0 Rev 4471
# Feb 16 16:00 /home/sandrock2/smyers/Testing2/Feb08/listcal.last
taskname           = "listcal"
vis                =  "testpol.cband.ms"
caltable           =  "testpol.cband.pcal"
field              =  "2202+422"
antenna            =  ""
spw                =  ""
listfile           =  "testpol.cband.pcal.list"
pagerows           =  50
async              =  False
#listcal(vis="testpol.cband.ms",caltable="testpol.cband.pcal",field="2202+422",antenna="",spw="",listfile="testpol.cband.pcal.list",pagerows=50,async=False)

# CASA Version 2.0 Rev 4471
# Feb 16 16:01 /home/sandrock2/smyers/Testing2/Feb08/plotcal.last
sandrock<155>% cat plotcal.last
taskname           = "plotcal"
caltable           =  "testpol.cband.pcal"
xaxis              =  "real"
yaxis              =  "imag"
poln               =  ""
field              =  "2202+422"
antenna            =  ""
spw                =  ""
timerange          =  ""
subplot            =  111
overplot           =  False
clearpanel         =  "auto"
iteration          =  ""
plotrange          =  [-1, -1, -1, -1]
showflags          =  False
plotsymbol         =  "."
plotcolor          =  "darkcyan"
markersize         =  5.0
fontsize           =  10.0
showgui            =  False
figfile            =  "testpol.cband.pcal.plot.png"
#plotcal(caltable="testpol.cband.pcal",xaxis="real",yaxis="imag",poln="",field="2202+422",antenna="",spw="",timerange="",subplot=111,overplot=False,clearpanel="auto",iteration="",plotrange=[-1, -1, -1, -1],showflags=False,plotsymbol=".",plotcolor="darkcyan",markersize=5.0,fontsize=10.0,showgui=False,figfile="testpol.cband.pcal.plot.png")