#
#FitHifiFringe_demo_feb2011.py: instructions to run FitHifiFringe
#    Task.
#
# v0.0 02/Dec/2009 ACAB: created for Caltech group demo
# v0.1 07/Dec/2009 ACAB: adapted for Madrid DPWS Dec 2009
# v0.2 07/Mar/2010 ACAB: adapted to HIPE 3.0, with a different example
# v0.3 03/Apr/2010 ACAB: adapted to HIPE 2.6 for ESTEC DPWS Apr 2010
# v0.4 07/Apr/2010 ACAB: use getObservation
# v0.5 31/Jan/2011 ACAB: adapted to HIPE 5.1, use other data
#

#For most up-to-date information on FitHifiFringe, see 
#Chapter 12 in "The HIFI User's Manual". 
#For background reading on sine wave fitting methods and
#automated line masking, see sections 5.5 and 5.6 
#in the "Herschel Data Analysis Guide".
#Both are accessible from the HIPE "Help Contents" menu.

#load band 3A Pointed LChop observation without sky reference 
#from ~/.hcss/lstore/
#It  has strong, short-period standing waves.
#Such extreme standing waves are expected in LChop mode because
#no sky reference was included in the observation.
#For some science cases, this may be OK.
obs=getObservation("1342180551",poolName="1342180551_point_lchop_3a_noref")

#Click on obs, and on fitHifiFringe under 'Applicable Tasks'.
#Click on Accept button in the GUI with default parameters.
#This will process all available level 2 SpectrumDataSets 
#of product "WBS-H-USB" (in this case only one). It generates 2 plots
#per scan, so don't forget to set plot=0 if the observation
#contains many scans....!

#Notes on the fit:
#
#-A strong 96 MHz standing wave is found, but especially
# near the IF band edges the fit is off. The Chi^2 plot
# does not show additional peaks, but the main peak is rather broad
#  -->increase nfringes
#
#-after subtraction a line is apparent at 835.15 GHz (USB)
# [CH+ 1-0] but because it is weak w.r.t. the waves it is not
# automatically masked (orange line)-->apply usermask option
#
#-the baseline level is negative. Subtract the fit (blue line)
# using sub_base option. If one does not like the baseline,
# reduce/increase curvature by increasing/reducing 
# 'typical period' option. This step may be done by fitting
# polynomials (see FitBaseline demo).

#Note that the input ObservationContext is always "overwritten",
#so to start from scratch for rest of demo, read it again.
obs=getObservation("1342180551",poolName="1342180551_point_lchop_3a_noref")

#to work on command line instead of GUI, copy command from
#console and adapt it
fitHifiFringe(obs1=obs,product="WBS-H-USB",nfringes=8,start_period=20.0,\
end_period=3000.0,typical_period=200.0,plot=1,averscan=False,\
doglue=True,sub_base=False,usermask=[(835.04, 835.24)])

#One can also work on DataSet level. 
#Select  a level 2 spectrumdataset
obs=getObservation("1342180551",poolName="1342180551_point_lchop_3a_noref")
sds_lev2=obs.refs["level2"].product.refs["WBS-H-USB"].product.refs["box_001"].product["0001"]

#Run fitHifiFringe using the GUI that can be opened
#under 'All Tasks'
#Drag sds_lev2 to the sds1 button.

#or on the command line, using default settings
obs=getObservation("1342180551",poolName="1342180551_point_lchop_3a_noref")
fhf = FitHifiFringe()
sds_lev2_out = fhf(sds1=sds_lev2,product="WBS-H-USB",nfringes=1,start_period=20.0,end_period=3000.0,typical_period=150.0,plot=1,averscan=False,doglue=True,sub_base=False)

#Additional notes
#
# -the baseline (blue line) is a smoothed and clipped version of
#  the intensity. All signal deviating from the baseline will
#  be included in the sine wave fit. Control the baseline curvature
#  with the "typical_period" parameter
#
# -if you know the period quite well, narrow the search range
#  using the "start_period" and "end_period" parameters 
#  (speeds up processing in large maps and SScans).
#
# -set "doglue=False" if you like to work on WBS sub-bands.
#  Useful if there are strong WBS sub-band jumps, or getting better
#  solutions for narrow lines.