POL2SIM

Create simulated POL2 data from known I, Q and U maps

Description:

This script creates simulated POL2 time-series data, using a supplied real POL2 observation as a template. The maps containing the artificial I, Q and U values at each point on the sky can be created automatically, or can be supplied by the user (see parameters ARTI, ARTQ and ARTU).

There are two basic modes of operation, selected by the parameter ADDON:

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).

Usage:

pol2sim in out newart arti artq artu

Parameters:

ADDON = _LOGICAL (Read)
If True, the output time-stream data consists of the sum of the artificial time-stream data (generated by sampling the maps given by parameters ARTI, ARTQ and ARTU) and the real time-stream data (given by parameter IN). If False, the output time-stream data consists just of the artificial data. [False]
AMP2 = _DOUBLE (Read)
Controls the amplitude of the 2 Hz signal. It gives the amplitude of the 2 Hz signal as a fraction of the total intensity. See also " PHASE2" . Only used if ADDON is False. [0.0003]
AMP4 = _DOUBLE (Read)
Controls the amplitude of the 4 Hz signal. It gives the amplitude of the 4 Hz signal as a fraction of the total intensity. See also " PHASE4" . Only used if ADDON is False. [0.009]
AMP16 = _DOUBLE (Read)
Controls the amplitude of the 16 Hz signal. It gives the amplitude of the 16 Hz signal as a fraction of the total intensity. See also " PHASE16" . Only used if ADDON is False. [0.0008]
ARTFORM = _INTEGER (Read)
Indicates the form of polarisation pattern created if parameter NEWART is set True:

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]

ARTI = NDF (Read or write)
A 2D NDF holding the artificial total intensity map from which the returned time-stream data is derived. If the NEWART parameter is True, then a new artificial I map is created and stored in a new NDF with name specified by ARTI. If NEWART is False, then ARTI should specify an existing NDF on entry, which is used as the artificial I map. The values in this NDF include the effects of the degradation caused by placing POL2 into the beam, (a factor of 1.35).
ARTQ = NDF (Read or write)
A 2D NDF holding the artificial Q map from which the returned time-stream data is derived. If the NEWART parameter is True, then a new artificial Q map is created and stored in a new NDF with name specified by ARTQ. If NEWART is False, then ARTQ should specify an existing NDF on entry, which is used as the artificial Q map. The values in this NDF include the effects of the degradation caused by placing POL2 into the beam, (a factor of 1.35).
ARTU = NDF (Read or write)
A 2D NDF holding the artificial U map from which the returned time-stream data is derived. If the NEWART parameter is True, then a new artificial U map is created and stored in a new NDF with name specified by ARTU. If NEWART is False, then ARTU should specify an existing NDF on entry, which is used as the artificial U map. The values in this NDF include the effects of the degradation caused by placing POL2 into the beam, (a factor of 1.35).
CFACTOR = _DOUBLE (Read)
A factor by which to expand the COM model values derived from the supplied INCOM data. The expansion is centred on the mean value. Real POL2 data seems to have a much flatter common-mode than real non-POL2 data, so the default flattens the common-mode to some extent. Only used if ADDON is False. [0.2]
COMVAL1 = _DOUBLE (Read)
Only used if ADDON is False and INCOM is null (!). If supplied,

COMVAL1 should be a constant sky emission value in pW seen by all

bolometers and time slices. The total common-mode signal added to the simulated data is the sum of COMVAL1 and COMVAL2, but only COMVAL1 is considered when determing the Q and U values caused by Instrumental Polarisation. Supplying null (!) is equivalent to supplying zero. [0.0] COMVAL2 = _DOUBLE (Read) Only used if ADDON is False and INCOM is null (!). If supplied,

COMVAL2 should be a constant offset to add to all bolometers and

time slices representing an offset in the electronics (i.e. not caused by sky emission). The total common-mode signal added to the simulated data is the sum of COMVAL1 and COMVAL2, but only COMVAL1 is considered when determing the Q and U values caused by Instrumental Polarisation. Supplying null (!) is equivalent to supplying zero. [0.0] GFACTOR = _DOUBLE (Read) A factor by which to expand the GAI model values derived from the supplied time-series data. The expansion is centred on the value 1.0. No GAI model is used if GFACTOR is zero. Only used if ADDON is False and INCOM is not null (!). [1.0] GLEVEL = LITERAL (Read) Controls the level of information to write to a text log file. Allowed values are as for " 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):

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]