Create simulated POL2 data from known I, Q and U maps
There are two basic modes of operation, selected by the parameter ADDON:
If ADDON is True, noise-free artificial POL2 time-stream data is generated by sampling supplied I, Q and U maps at the position of each bolometer value in the supplied real POL2 observation, and the artificial time-stream data is then added onto the real time-stream data to generate the output time-streams. In this mode, no artificial noise components are added into the artificial time-stream data. Instead, the noise in the output time-streams is inherited from the noise in the input real POL2 time-streams
If ADDON is False, artificial POL2 time-stream data is generated in the same way, but is then used directly as the output time-sreams without first adding on the real time-stream data. In this mode, artificial noise components are added into the artificial time-stream data as follows (NOTE - this mode takes a very long time to run !!):
o A time-varying unpolarised sky brightness is added onto the I values amapled from the supplied ARTI map. The sky brightness is common to all bolometers, and is derived from the time-series data for a a real scan map (see parameter INCOM). For some unknown reason, the common-mode for real POL2 data seems to be much flatter than the common-mode for real non-POL2 data. For this reason, there is an option to flatten the common-mode before using it in the simulation (see parameter CFACTOR). o 2, 4 and 16 Hz signals proportional to the total intensity (including sky brightness) in included in the simulated POL2 data. o Each bolometer has a separate gain, which is allowed to vary over time (like the GAI model used by smurf:makemap). The GAI values are derived from the template POL2 data supplied for parameter IN. The extent to which the GAI values vary with time is controlled by parameter GFACTOR o Random Gaussian noise is added to the returned time-stream data.
In both modes, instrumental polarisation is included in the artificial time-stream data (see parameter
IPFORM). Three forms of instrumental polarisation can be used: the Johnstone/Kennedy IPDATA
model, the simplified planetary data "
PL1"
model, or an arbitrary user-define IP model (see
parameters IPMAX, IPMIN and IPTHETA).
"
PHASE2"
. Only used if ADDON is False. [0.0003] "
PHASE4"
. Only used if
ADDON is False. [0.009] "
PHASE16"
. Only used if ADDON is False. [0.0008] 0 - A single Gaussian source centred at pixel coordinates given by parameters XC and YC (default is (0,0)), with peak total intensity given by parameter IPEAK and width given by parameter IFWHM. The polarisation vectors are tangential, centred on the source. The fractional polarisation is constant at the value given by POL.
1 - Exactly like "
1"
except that the vectors are parallel across the whole Gaussian blob, rather than
being tangential. The vectors are parallel to the Y pixel axis.
[0]
"
ILEVEL"
. The log file to create is specified via parameter "
LOGFILE. In adition,
the glevel value can be changed by assigning a new integer value (one of starutil.NONE,
starutil.CRITICAL, starutil.PROGRESS, starutil.ATASK or starutil.DEBUG) to the module variable
starutil.glevel. ["
ATASK"
] IFWHM = _DOUBLE (Read) FWHM of Gaussian source for new
artificial total instensity map, in pixels. [8] ILEVEL = LITERAL (Read) Controls the level of
information displayed on the screen by the script. It can take any of the following values (note,
these values are purposefully different to the SUN/104 values to avoid confusion in their
effects):
"
NONE"
: No screen output is created
"
CRITICAL"
: Only critical messages are displayed such as warnings.
"
PROGRESS"
: Extra messages indicating script progress are also displayed.
"
ATASK"
: Extra messages are also displayed describing each atask invocation. Lines starting with "
>>>"
indicate the command name and parameter values, and subsequent lines hold the screen output
generated by the command.
"
DEBUG"
: Extra messages are also displayed containing unspecified debugging information. In
addition scatter plots showing how each Q and U image compares to the mean Q and U image are
displayed at this ILEVEL.
In adition, the glevel value can be changed by assigning a new integer value (one of starutil.NONE,
starutil.CRITICAL, starutil.PROGRESS, starutil.ATASK or starutil.DEBUG) to the module variable
starutil.glevel. ["
PROGRESS"
] IN = NDF (Read) A group of POL2 time series NDFs. INCOM = NDF
(Read) A group of non-POL2 time series NDFs that are used to define the common-mode (i.e. the sky
brightness) to include in the simulated POL2 data. The number of NDFs supplied for INCOM must
equal the number supplied for IN. Each INCOM file must be at least as long (in time) as the
corresponding IN file. If null (!) is supplied, the common-mode is defined by parameters COMVAL1
and COMVAL2 instead. Only used if ADDON is False. [!] IPFORM = LITERAL (Read) The form
of instrumental polarisation to use. Can be "
JK"
for the Johnstone/Kennedy model, "
PL1"
, "
PL2"
or "
PL3"
for one of the simplified planetary data models, "
User"
for a
user-defined model (see parameters IPMAX, IPMIN and IPTHETA), or "
None"
if no instrumental
polarisation is to be added to the simulated data. ["
PL3"
] IPEAK = _DOUBLE (Read) Peak
intensity for new artificial total instensity map, in pW. [0.08] IPMIN = _DOUBLE (Read) The
minimum instrumental polarisation within the focal plane, expressed as a fraction. The
IP varies linearly across each array from IPMIN to IPMAX. The IP is fixed in focal plane
coordinates over all stare positions. This parameter is only accessed if IPFORM is set to
"
User"
. [0.0004] IPMAX = _DOUBLE (Read) The maximum instrumental polarisation
within the focal plane, expressed as a fraction. The IP varies linearly across each array from
IPMIN to IPMAX. The IP is fixed in focal plane coordinates over all stare positions. This
parameter is only accessed if IPFORM is set to "
User"
. [0.0008] IPTHETA = _DOUBLE
(Read) The angle from the focal plane Y axis to the instrumental polarisation vectors, in
degrees. This parameter is only accessed if IPFORM is set to "
User"
. [15] LOGFILE =
LITERAL (Read) The name of the log file to create if GLEVEL is not NONE. The default is "
<command>.log"
, where <command>
is the name of the executing script (minus any trailing "
.py"
suffix), and will be created in the current
directory. Any file with the same name is over-written. The script can change the logfile if necessary
by assign the new log file path to the module variable "
starutil.logfile"
. Any old log file will be closed
befopre the new one is opened. [] MSG_FILTER = LITERAL (Read) Controls the default level of
information reported by Starlink atasks invoked within the executing script. This default can be
over-ridden by including a value for the msg_filter parameter within the command string passed to
the "
invoke"
function. The accepted values are the list defined in SUN/104 ("
None"
, "
Quiet"
, "
Normal"
, "
Verbose"
, etc). ["
Normal"
] NEWART = _LOGICAL (Read) Indicates if new artificial I, Q
and U maps should be created. These are the maps from which the returned time-stream data are
derived.
If NEWART is False, then existing 2D NDFs holding the artificial I, Q and U data to be used should be
specified via parameter ARTI, ARTQ and ARTU. These maps should have WCS that is
consistent with the supplied template time-stream data (parameter IN). The data values are
assumed to be in units of "
pW"
. The Y pixel axis is assumed to be the polarimetric reference
direction.
If NEWART is True, then new artificial I, Q and U data is created containing data of the form indicated
by parameter ARTFORM. The Y pixel axis is reference direction (suitable POLANAL Frames are
included in the WCS to indicate this, as required by POLPACK). OUT = NDF (Write) A
group of output NDFs to hold the simulated POL2 time series data. Equal in number to
the files in "
IN"
. PERROR = _DOUBLE (Read) Standard deviation of pointing errors to
include in the simulated data, in arc-seconds. [0.0] PHASE2 = _DOUBLE (Read) The phase
offset to apply to the 2 Hz signal specified via parameter AMP2, in degrees. Only used if
ADDON is False. [0.0] PHASE4 = _DOUBLE (Read) The phase offset to apply to the 4 Hz
signal specified via parameter AMP4, in degrees. Only used if ADDON is False. [-30.0]
PHASE16 = _DOUBLE (Read) The phase offset to apply to the 16 Hz signal specified via
parameter AMP16, in degrees. Only used if ADDON is False. [0.0] POL = _DOUBLE (Read) The
fractional polarisation for new artificial Q and U maps. [0.05] RESTART = LITERAL (Read) If
a value is assigned to this parameter, it should be the path to a directory containing the
intermediate files created by a previous run of POL2SIM (it is necessry to run POL2SIM with
RETAIN=YES otherwise the directory is deleted after POL2SIM terminates). If supplied, any files
which can be re-used from the supplied directory are re-used, thus speeding things up.
The path to the intermediate files can be found by examining the log file created by the
previous run. [!] RETAIN = _LOGICAL (Read) Should the temporary directory containing the
intermediate files created by this script be retained? If not, it will be deleted before the
script exits. If retained, a message will be displayed at the end specifying the path to the
directory. [FALSE] SIGMA = _DOUBLE (Read) Gaussian noise level (in pW) to add to
the final data. Only used if ADDON is False. [0.004] XC = _DOUBLE (Read) The X pixel
coordinate at which to place the artificial blob if NEWART is YES. [0.0] YC = _DOUBLE
(Read) The Y pixel coordinate at which to place the artificial blob if NEWART is YES. [0.0]