POFF: Planck On Flight Forecaster
NAME:
POFF
CATEGORY:
Tool for point sources
AUTHORS:
Marcella Massardi & Carlo Burigana
PURPOSE:
The Planck On-Flight Forecaster (POFF) calculates when a position in the sky is observed
according to the preprogrammed Planck scanning strategy (i.e. the PPL, Planned Pointing List).
It has been thought to help planning ground based follow-up of point sources, verifying
that the real scan follows the nominal one, supporting the people that look for variable
objects (e.g. the QdS people) to predict when a candidate variable will be observable and
plan their activity. If the actual pointing positions (i.e. the pointings of the TODs)
are given as input instead of the nominal scanning strategy it allows to verify when a
position has been observed: that can help to select the moments of the data stream to
be extracted to study the signal in selected sky positions. The input is a (list of)
position(s) to be searched. Each position is associated, for each horn,
to the time when the position falls within a beam unit from the receiver scan tracks.
Several output options are available, to cope with the various uses the code is suited for.
By combining the spin axis position at every pointing in the PPL with the angle of each
receiver with respect to the spin axis given by the SIAM (Spacecraft/Instrument Alignment
Matrix) it is possible to identify the region of the sky swept by each receiver.
We fixed that the width of each region is within a circle of nsigma beamwidth radii
(nsigma*s=nsigma*FWHM/sqrt(8ln(2)) at each frequency, where nsigma is an optional multiplying
factor, set to 1 as default.
We used as FWHM the values 33, 27, 13, 9.5, 7.1 arcmin respectively for 30, 44, 70, 100,
and 143 and 5 arcmin for all the channels between 217 and 857 GHz.
In this way we can simply define that a source is observable by a receiver if it is within
nsigma beam units strip during the full rotation of the satellite around its spin axis.
For this reason the minimum time bin for which we could define the observability of an object
is equal to the minimum separation between two consecutive positions in the PPL file (roughly
1 hour).
The user provides the list of coordinates, the code transforms them into Ecliptic, if
necessary, and feeds them to a routine that reads the released version of the PPL and of the SIAM
files. For each input couple of coordinates and for each Planck frequency channel (an option
allow to investigate each receiver) the program verifies if it falls within the observable
region during a whole rotation of the satellite around its spin axis for each PPL position.
This routine generates a matrix of size (if the option /horn is not set)
[# of sources, # of frequency channels, # of PPL positions]:
an element [s, f, p] of this matrix is equal to 1 if the source s is observable in the channel f
at the PPL position p, 0 otherwise.
If the option "/horn" is set the matrix size is
[# of sources, # of receivers, # of PPL positions]
and the information about observability by each (selected) receiver is provided as output.
The PPL position corresponds to an exact epoch during the satellite scan: this allows
to date the observability. The matrix, the IDs of the positions and the epochs associated with
each PPL position are saved into a '.save' file: in this way it is possible to restore the
observation matrix for the same input source positions, SIAM and PPL files, and selection
between horn or frequency information in any future use, simply changing the output requests.
The matrix and the epochs associated with each PPL position are in fact given to a part of the
code that produces the output according to the user requests. The user can select the frequency
channels (default is all the channels), or (a list of) selected horn(s) (default is no
information on single horns), define a time range for the output epoch and a binning
of the time to be printed (default is 1 day). According to the aim for which the code is used,
different sets of output may be of use.
The user can decide to list the output by epoch of observations or following the order of the
input positions as they have been provided at the beginning.
In both the case the results may be ordered according to the frequency.
FEEDBACK FROM USERS:
For any feedback/request please e-mail to:
massardi@ira.inaf.it
and
burigana@iasfbo.inaf.it
ACKNOWLEDGEMENTS TO THE CODE:
You can acknowledge the use of this code with the sentence
"This research has made use of the Planck On-Flight Forecaster code by
M. Massardi and C. Burigana (Massardi and Burigana, in preparation)."
TO RESTORE:
Save the poff.sav on your machine. Type on your idl command line
restore, '_path_poff.sav'
where _path_ is the path your operative system requires to reach the folder
where poff.sav is. Notice that the .sav extension should automatically compile
the restored routines: hence, once restored, you are ready to run POFF.
Remember to download the last released version of the PPL and SIAM files.
PPL files can be downloaded from the Planck Livelink document portal:
http://www.rssd.esa.int/llink/livelink?func=ll&objId=2810263&objAction=browse&sort=name&viewType=1
PPL and SIAM files can be downloaded from the Planck ESA webpage:
http://www.rssd.esa.int/index.php?project=PLANCK&page=Pointing
CALLING SEQUENCE:
poff, outpath, pplfile=pplfile, siamfile=siamfile, filein=filein, mat=mat, $
colpos=colpos, colid=colid, posarray=posarray, $
gal=gal, ecl=ecl, hour=hour, $
timerange=timerange, dt=dt, freq=freq, $
sxd=sxd, oxf=oxf, horn=horn, man=man
INPUT:
The (list of) position(s) for which the user wants to know when they will be observable
by Planck according to the nominal scanning strategy defined by the PPL.
The PPL file as can be downloaded from the Planck Livelink and from the ESA website.
The SIAM file as can be downloaded from the ESA website.
OUTPUT:
A file outpath+'_outcat.dat' that lists the observed positions according to the sorting
options that have been set.
A file outpath+'_matrix.save' that collects the information about the observability of
the given list of positions in the required timerange at all the frequencies.
It allows to make future runs of the program with the /mat keyword set modifying only
the output options.
INPUT KEYWORDS:
pplfile : the PPL file downloadable from the Planck livelink or from the ESA website.
No default.
siamfile : the SIAM file downloadable from the ESA website. No default.
filein : name of the input file. It can be a text file (with read permissions) that lists
the positions and/or the IDs of the sources or a .save file previously generated by
this program, if the /mat keyword is set.
Coordinates should be in degrees if keyword /hour is not set. (See also posarray)
IDs are not necessary.
Blanck spaces are considered column separators: hence no blanck space is allowed within
a value to be read (i.e. names like 'PKS 1921-293' are not allowed, 'PKS1921-293' is
a valid name, but ra and dec can be separated by a blank space).
mat : set this keyword if the filein is a .save file generated by the program in a previous
run. This keyword is useless if the filein keyword is not set.
posarray : array of coordinates in the format'[[a0,b0],[a1,b1],...]' where 'ai' is the i-th first
coordinate (i.e. RA or longitude), and 'bi' is the i-th second coordinate of the positions
(i.e. declination or latitude).
If also filein is set the posarray will be concatenated at the end of the array of
position read in filein. Coordinates should be in degrees if keyword /hour is not set.
Notice that one among posarray or filein 'must' be set. It is useless if /mat is set.
No ID can be given to these positions. If tehre is no filein, or if IDs are set in the
filein, the sequential order of each position in the given posarray is used as its ID,
otherwise, if filein is set but no ID is given, the sequential order in the concatenated
list is used for every position in the list.
colpos : 2-d array '[a,b]' where 'a' is the index of the column of filein that lists the
first coordinate of the positions (i.e. RA or longitude), and 'b' is the index of the
column of filein that lists the second coordinate of the positions (i.e. declination or
latitude). The index of the first column is '1'.
Default is [1, 2]. It is useless if /mat is set.
colid : the index of the column of filein that lists the identification of the positions
It is useless if the mat keyword is set.
If not set, the sequential number of the source in the 'filein' (or in the posarray)
is used as ID
gal : set this keyword if the positions are given in J2000 Galactic coordinates.
If unset J2000 Equatorial coordinates are assumed.
ecl : set this keyword if the positions are given in J2000 Ecliptic coordinates.
If unset J2000 Equatorial coordinates are assumed.
hour : set this keyword if the first coordinate of the positions (i.e. RA or longitude)
is given in hour. If unset the first coordinate is assumed to be in degrees.
man : if this keyword is set, the calling sequence is written to help the user. Execution is halted.
OUTPUT KEYWORDS:
outpath : path to generate the output files
timerange: 2-d array '[a,b]' where 'a' is the beginning and 'b' the end of the time range for
which the program verifies the observability of the positions.
Required format is [YYYYMMDDHH, YYYYMMDDHH]. Default is '[2009010100, 2015010100].
dt : time bin (in days) required for the output. The timerange is binned in intervals of width
equal to dT and for each position observability is verified within each bin.
Default is 1 (i.e. one day). Range of allowance is [0.041, 183]
(i.e. about [1 hour, 6 months]).
freq : n-d array listing the frequency channels required for output (dimension up to n=9).
Allowed values are 30, 44, 70, 100, 143, 217, 353, 545, 857. Default is all the channels.
horn : this keyword allows to retrieve the information about single receivers. If set it
will select all the horns observing at the frequencies given through the keyword freq
(i.e. if freq is not set it means "all the receivers").
It can be set to a n-d array (dimension up to n=47) listing the name of the requested horn.
Allowed values are: 'lfi27','lfi28','lfi24','lfi25','lfi26','lfi18','lfi19','lfi20',
'lfi21','lfi22','lfi23', '100_1','100_2','100_3','100_4',
'143_1','143_2','143_2','143_4','143_5','143_6','143_7','143_8',
'217_1','217_2','217_2','217_4','217_5','217_6','217_7','217_8',
'353_1','353_2','353_2','353_4','353_5','353_6','353_7','353_8',
'545_1','545_2','545_3','545_4','857_1','857_2','857_3','857_4'.
If freq is not set and horn is set to an array, only the selected horns will be
considered for the output. Default is no information on single receivers.
If this keyword is set the observational matrix stored in the .save output file
will have [# source, 47, #PPL positions], so it can be restored only to provide
informations on single receivers (but they can be different from the case when the
matrix has been generated).
nsigma : multiplying factor to modify the size of the observable region for each horn.
Default is 1, which means that the observable size is 1 beamwidth.
sxd : if set, sorts the observations by dT and then according to the sequence of input list of
positions. If not set, default is to list all the observations for each position sorted
by dT.
oxf : if set, sorts the observations for each position (or those for each dT if sxd is set) by
frequency as first criterion.
SIDE EFFECTS:
None
EXAMPLES:
a) Verifying observability for the positions [RA, dec]=[79., -45.],[RA, dec]=[80., -45],
[RA, dec]=[79., -46] in August and September 2009 at 30 GHz.
Save the results in files with path='poff\test\src_Aug'.
Use the PPL stored in the file 'may09.PPL' and the siamfile in 'esa.SIAM'
Calling sequence:
>POFF, 'poff\test\src_Aug', pplfile='poff\ppl\aug.PPL', siamfile='esa.SIAM', $
posarray=[[79., -45.],[80., -45],[79., -46]],timerange=[2009080100, 2009093000], freq=[30]
Results
% SAVE: Portable (XDR) SAVE/RESTORE file.
% SAVE: Saved variable: MATRIX.
% SAVE: Saved variable: JULIAN_DATES.
% SAVE: Saved variable: LON.
% SAVE: Saved variable: LAT.
End
In the file 'poff\test\picA_Aug_outcat.dat':
#Observations of each position ordered by date and by frequency
#RA[hr] Declination Ecl_lon Ecl_lat YYYYMMDDHH.h Freq IDs
5.2666669 -45.0000000 69.2204285 -67.6473999 2009082212.0 30 0
5.2666669 -45.0000000 69.2204285 -67.6473999 2009082312.0 30 0
5.3333335 -45.0000038 71.0507660 -67.7825699 2009082312.0 30 1
5.3333335 -45.0000038 71.0507660 -67.7825699 2009082412.0 30 1
5.2666664 -45.9999962 68.6728363 -68.6263962 2009082112.0 30 2
5.2666664 -45.9999962 68.6728363 -68.6263962 2009082212.0 30 2
Also a poff\test\src_Aug_matrix.save file is generated
b) Add the source [RA, Dec]=[13.33,-40.0] to the positions listed in the 2nd and 3rd column
of the file 'poff\test\test_ecl.dat' in Equatorial coordinates with RA in hours,
and verify their observability on August the 4th 2009 at all the frequencies.
Names of the sources are in column 1.
Save the results in files with path='poff\test\test_4Aug'.
Use the PPL stored in the file 'may09.PPL' and the siamfile in 'esa.SIAM'
Calling sequence:
>POFF, 'poff\test\test_4Aug', pplfile='may09.PPL',siamfile='esa.SIAM', filein='poff\test\test.dat', colpos=[2,3], $
posarray=[13.33,-40.0], timerange=[2009080400, 2009080500], /hour
The filein appears as
src1 5.33 -60.0
src2 6.66 -70.0
src3 7.33 -70.0
src4 8.66 -70.0
src5 12.00 -60.0
Results
% SAVE: Portable (XDR) SAVE/RESTORE file.
% SAVE: Saved variable: MATRIX.
% SAVE: Saved variable: JULIAN_DATES.
% SAVE: Saved variable: LON.
% SAVE: Saved variable: LAT.
End
In the file 'poff\test\test_4Aug_outcat.dat'
#Observations of each position ordered by date and by frequency
#RA[hr] Declination Ecl_lon Ecl_lat YYYYMMDDHH.h Freq IDs
5.3299999 -60.0000000 50.8610916 -82.0543213 2009080412.0 30 src1
5.3299999 -60.0000000 50.8610916 -82.0543213 2009080412.0 44 src1
6.6599998 -70.0000000 227.7175140 -84.9858093 2009080412.0 217 src2
7.3300009 -70.0000000 214.0365448 -81.9045258 2009080412.0 70 src3
8.6599998 -70.0000000 211.2357788 -75.1326065 2009080412.0 70 src4
12.0000000 -60.0000038 214.5656891 -52.6139793 2009080412.0 70 src5
13.3299999 -40.0000000 214.5323486 -29.0634155 2009080412.0 30 0
13.3299999 -40.0000000 214.5323486 -29.0634155 2009080412.0 44 0
Also a poff\test\test_4Aug_matrix.save file is generated
c) Upload the sav file generated in the example b) and set also /oxf selecting only
the frequencies at 30 and 44 GHz on August the 4th and 5th 2009
(notice that you can change the timerange you require as output just loading the matrix file!).
Save the results in files with path='poff\test\test_5Aug'.
Calling sequence:
>POFF, 'poff\test\test_5Aug', filein='poff\test\test_4Aug.save', /mat, freq=[30, 44], $
timerange=[2009080400, 2009080600], /oxf
Results
% RESTORE: Portable (XDR) SAVE/RESTORE file.
% RESTORE: Save file written by user@PC-USER, Tue Mar 17 15:40:40 2009.
% RESTORE: IDL version 5.5 (Win32, x86).
% RESTORE: Restored variable: MATRIX.
% RESTORE: Restored variable: JULIAN_DATES.
% RESTORE: Restored variable: LON.
% RESTORE: Restored variable: LAT.
End
In the file 'poff\test\test_5Aug_outcat.dat'
#Observations of each position ordered by frequency and by date
#RA[hr] Declination Ecl_lon Ecl_lat YYYYMMDDHH.h Freq IDs
5.3299999 -60.0000000 50.8610916 -82.0543213 2009080412.0 30 src1
5.3299999 -60.0000000 50.8610916 -82.0543213 2009080512.0 30 src1
13.3299999 -40.0000000 214.5323486 -29.0634155 2009080412.0 30 0
5.3299999 -60.0000000 50.8610916 -82.0543213 2009080412.0 44 src1
5.3299999 -60.0000000 50.8610916 -82.0543213 2009080512.0 44 src1
13.3299999 -40.0000000 214.5323486 -29.0634155 2009080412.0 44 0
RESTRICTIONS:
None
SOFTWARE USED:
IDL 5.5 and IDL 7.0
REVISION HISTORY:
Version for second release v2.0. Marcella Massardi & Carlo Burigana 23/Sept/2009
Added /nsigma option. MM and CB 23/Sept/2009
Added /horn option. Marcella Massardi 22/Sep/2009
Added reading SIAM file. Marcella Massardi 22/Sep/2009
Small bug in outcat fixed. Marcella Massardi 13/Aug/2009
Added SIAM.v7 info. Marcella Massardi 01/Jun/2009
Version for first release. Marcella Massardi 26/May/2009
Added colid by Marcella Massardi 10/May/2009
Version 1.0 completed 01/Feb/2009
Created by Marcella Massardi and Carlo Burigana 10/Dic/2008