.help osopha Aug 99 ftools.oso8
.ih
NAME
osopha --  Osopha creates (by default) a non-background-subtracted
lightcurve and 1-63 channel PHA spectrum from OSO-8 B/C detector data
for a selected X-ray source.  
.ih
USAGE
equinox ra dec rootname detector rawlist  fov_check cont_srcelist
ch_start ch_end integ_time int_low (ph_restriction) period ephemeris
phase_st phase_sp int_high lchan_min lchan_max hchan_min hchan_max
strtdate strtime enddate endtime (bg) (bgl) (bgh) (tchat) (lchat)
(clobber) (mode) 
.ih
DESCRIPTION

Osopha generates a broad-band lightcurve and a 1-63 channel PHA spectrum
(neither one background-subtracted) from either the B or C detector,
for a single source position. 
The user may select hard and soft channel boundaries for the lightcurve
processing. The soft, hard, total counts  + the hardness ratio are 
then included in the output lightcurve. The user may also select :
(i)  to restrict the source data to within a certain phase 
(ii) to perform a check for possible contaminating sources in the detector FOV.


Note: 

* The output lightcurve and spectrum are normalized by 2/pi. 

* If the user inputs previously determined background levels 
(for the broad, soft, hard energy bands) OSOPHA can produce a  
background-subtracted lightcurve (but NOT a background-subtracted PHA
spectrum). 


Determining the appropriate background correction -

The background default values for broad, soft, hard energy bands are
0.0 (set as hidden parameters). However if the user wishes to produce
a  background-subtracted, broad-band lightcurve for a selected X-ray
source, they must first: 

(i) obtain a NEARBY position, which has also been observed CLOSE IN
TIME to the selected X-ray source. This is done by examining the OSO-8
lightcurve database for the B/C detectors located in the HEASARC
OSO8BCLC archive. 

(ii) Once suitable positions have been found, a check on their
lightcurve profiles should reveal a `no source' candidate (a
lightcurve which has a low, flat count-rate). This candidate may be
used as the background source. 

(iii) Run the perl script OSOFINDFAST for these `background' coords to
determine the days when the `background' is the the detector FOV (the `good' 
observing days for the background). Also an ASCII file must be
created containing  a list of all raw PHA files pertaining to the
`good' observing days for the background.

(iv) Run OSOPHA using the ASCII filelist of raw PHA data files and
input the `background' coordinates.

(v) OSOPHA will produce the output lightcurve for the `background'
and from this data up to 3 integral values (c/s) for the background
may be determined: a mean broad band level; a mean soft band level and
a mean hard band level. The 3 bands are bounded by channel boundaries
which MUST be the same as those to be set for the selected X-ray 
source. 

The above integral values may then be entered into OSOPHA (during the 
run for the selected X-ray source) as the values for the bg, bgl, bgh
parameters respectively.


.ih
PARAMETERS
.ls equinox [real]
 The input value for the equinox (default value 1950)
.le
.ls ra [character string]
 The source R.A. given in hh mm ss.s or degrees
.le
.ls dec [character string]
 The source Declination given in dd mm ss.s or degrees
.le
.ls rootname [character string]
 The rootname for the generated lightcurve and PHA spectrum output.
.le
.ls detector [integer]
 The detector of interest (1=B,2=C).
.le
.ls rawlist [character string]
 The name of the file containing the list of raw pha data files.
 The raw data files correspond to the mission days when the source was most
 likely to have been in the detector FOV. 
.le
.ls (ph_restriction=no) [boolean]
 Logical flag to indicate whether user wishes to restriction the phase of the
 data (yes/no). If yes, then the user will be prompted for the period
 and ephemeris of the phase restriction as well as the start and stop
 phase. These parameters are skipped otherwise.
.le
.ls period [double precision]
 The period (secs) for phase restriction.
.le
.ls ephemeris [double precision]
 The ephemeris (MJD) for phase restriction.
.le
.ls phase_st [real]
 Phase start (0.0 - 1.0) for phase restriction.
.le
.ls phase_sp [real]
 Phase stop (0.0 - 1.0) for phase restriction.
.le
.ls fov_check [boolean]
 Logical flag to indicate whether user wishes to check for contaminating
 sources in the detector FOV (yes/no). If yes then the user will be
 prompted for the file containing the list of coordinates and epochs of
 contaminating sources. This parameter will be skipped otherwise.
.le
.ls cont_srcelist [character string]
 The name of the file listing coordinates and epochs
 for possible contaminating sources (max number allowed in list = 10).
.le
.ls ch_start [integer]
 Start PHA channel for broad-band lightcurve (default = 1).
.le
.ls ch_end [integer]
 End PHA channel for broad-band lightcurve (default = 63).
.le
.ls integ_time [integer]
 Number of raw data records for integration 
 (default = 1 so B=40.96s ; C=12.98s).
.le
.ls int_low [integer]
 Low Intensity Threshold for lightcurve (c/s) (default = -10000)
.le
.ls int_high [integer]
 High Intensity Threshold for lightcurve (c/s) (default = 10000)
.le
.ls lchan_min [integer]
 Channel Boundary - low channel (soft-band) min [1-63] (default = 5).
.le
.ls lchan_max [integer]
 Channel Boundary - low channel (soft-band) max [1-63] (default = 14).
.le
.ls hchan_min [integer]
 Channel Boundary - high channel (hard-band) min [1-63] (default = 15).
.le
.ls lchan_min [integer]
 Channel Boundary - high channel (hard-band) max [1-63] (default = 63).
.le
.ls strtdate [character string]
 The observation start date (dd/mm/yy).
.le
.ls strtime [character string]
 The observation start time (hh:mm:ss).
.le
.ls enddate [character string]
 The observation end date (dd/mm/yy).
.le
.ls endtime[character string]
 The observation end time (hh:mm:ss).
.le
.ls (bg = 0.0) [real]
 Mean background level (c/s) for broad band (ch_start-ch_end).
.le
.ls (bgl = 0.0) [real]
 Mean background level (c/s) for soft band (lchan_min-lchan_max).
.le
.ls (bgh = 0.0) [real]
 Mean background level (c/s) for hard band (hchan_min-hchan_max).
.le
.ls (tchat = 10) [integer]
 Flag to indicate how chatty the task is at execution. A value of 10 is the
 default, with lower/higher values producing quieter/verbose output 
 respectively. This is for TERMINAL chattiness.
.ls (lchat = 10) [integer] 
  Same as above but for the level of chattiness to the output log file.
.le
.ls (clobber=no) [boolean] 
  Flag to overwrite lightcurve if it already exists.
.le
.ls (mode = "ql") [character string]
  
.le 

           

.ih
BUGS
None known


.endhelp

