SKYLOOP

Create a map using the " inside-out" algorithm

Description:

This script makes a map from specified raw time-series data using the algorithm described at http://pipelinesandarchives.blogspot.co.uk/2012/10/inside-out-map-making.html. It runs SMURF:MAKEMAP multiple times, performing a single iteration of the Dynamic Iterative Map-Maker algorithm on each invocation, including data from all chunks. Each map created by MAKEMAP is used as the initial sky estimate for the next invocation. MAKEMAP subtracts this initial sky estimate from the time-series data before starting the first (and only) iteration, and then adds the initial sky estimate back on at the end prior to creating the output map.

The script produces several intermediate files: a set of cleaned time-series files that may be 2 to 3 times the size of the entire set of raw data files included in the map, and a 2D map for every iteration. These files are placed in a newly created directory that is normally deleted before the script exits. The files can be retained for debugging purposes if required by running the script with " retain=yes" on the command line.

The temporary files are placed in a directory name " NDG_xxxxx" , located within the directory specified by environment variable STAR_TEMP. If STAR_TEMP is not defined, they are placed in the system s temporary directory (e.g. " /tmp" ).

Usage:

skyloop in out niter pixsize config [itermap] [ref] [mask2] [mask3] [extra] [ipref] [retain] [msg_filter] [ilevel] [glevel] [logfile] [restart]

Parameters:

CHUNKWGT = _LOGICAL (Read)
Controls the weight used for each chunk. If False, then the weights are determined by the value of the CHUNKWGT FITS header in each input time-stream data file (unit weight is used for any data file that has no CHUNKWGT FITS header). If True, the weight for each chunk is based on the normalised map change for each chunk calculated on the previous iteration - the weight for a chunk is the ratio of the mean of all the chunk map changes to the chunk s own map change. Weights above 1.0 are limited to 1.0. [False]
CONFIG = LITERAL (Read)
The MAKEMAP configuration parameter values to use. Additions will be made as follows:
  • First iteration:

    numiter=1
    noi.export=1
    exportNDF=(lut,ext,res,qua)
    noexportsetbad=1
    exportclean=1
    ast.zero_notlast = 0
    flt.zero_notlast = 0
    com.zero_notlast = 0
    pca.zero_notlast = 0
    itermap=0
    shortmap=0
    bolomap=0
    flagmap= <undef >
    sampcube=0
    diag.append=0

  • Subsequent iterations:

    numiter=1
    noi.import=1
    exportNDF=(res,qua)
    doclean=0
    importsky=ref
    importlut=1
    ext.import=1
    ast.zero_notlast = 0
    flt.zero_notlast = 0
    com.zero_notlast = 0
    pca.zero_notlast = 0
    flt.notfirst = 0
    pca.notfirst = 0
    pln.notfirst = 0
    smo.notfirst = 0
    itermap=0
    shortmap=0
    bolomap=0
    flagmap= <undef >
    sampcube=0
    diag.append=1
    downsampscale=0
    downsampfreq=0
    fakemap= <undef >

  • Last iteration:

    numiter=1
    noi.import=1
    doclean=0
    importsky=ref
    importlut=1
    ext.import=1
    ast.zero_notlast = 1
    flt.zero_notlast = 1
    com.zero_notlast = 1
    pca.zero_notlast = 1
    flt.notfirst = 0
    pca.notfirst = 0
    pln.notfirst = 0
    smo.notfirst = 0
    itermap=0
    shortmap=0
    bolomap=0
    flagmap= <undef >
    sampcube=0
    diag.append=1
    downsampscale=0
    downsampfreq=0
    fakemap= <undef >

EXTRA = LITERAL (Read)
A string holding any extra command line options to be passed to MAKEMAP (all invocations). [!]
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. [" ATASK" ]
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.

[" PROGRESS" ]

IN = NDF (Read)
The group of time series NDFs to include in the output map.
IPREF = NDF (Read)
An existing NDF that is to be used to define the correction to be made for instrumental polarisation (IP). It is only accessed if the input data contains POL2 Q or U time-series values, as created by SMURF:CALCQU. No IP correction is made if a null (!) value is supplied. If a non-null value is supplied, it should be an NDF that holds the total intensity (in pW) within the area of sky covered by the output map. The supplied NDF need not be pre-aligned with the output map - the WCS information in the NDF will be used to aligned them. For each Q or U value in the input time-streams, the corresponding total intensity (I) value is found by sampling the supplied IPREF map at the sky position of the Q/U value. This I value is multipled by a factor that depends on elevation and focal plane position, to get the IP correction. These Q and U corrections are rotated so that they use the same reference direction as the input Q/U data, corrected for extinction, and are then subtracted from the input Q or U value before going on to make a map from the corrected values. [!]
ITERMAP = NDF (Write)
A 3D NDF to create holding the maps from all iterations. [!]
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. []
NITER = _INTEGER (Read)
The number of iterations to perform. A positive value specifies a fixed number of iterations to perform. A negative value indicates that iterations should continue until the normalized change in the map between iterations is less than the value of the " maptol" parameter in the configuration supplied by parameter CONFIG (a maptol value of 0.05 is used if CONFIG does not specify maptol). If a value of zero is supplied for NITER, the value used will be read from the " numiter" parameter in the configuration. [0]
MASK2 = NDF (Read)
An existing NDF that can be used to specify a second external mask for use with either the AST, PCA, FLT or COM model. See configuration parameters AST.ZERO_MASK, PCA.ZERO_MASK, FLT.ZERO_MASK and COM.ZERO_MASK. Note, it is assumed that this image is aligned in pixel coordinate with the output map. [!]
MASK3 = NDF (Read)
An existing NDF that can be used to specify a third external mask for use with either the AST, PCA, FLT or COM model. See configuration parameters AST.ZERO_MASK, PCA.ZERO_MASK, FLT.ZERO_MASK and COM.ZERO_MASK. Note, it is assumed that this image is aligned in pixel coordinate with the output map. [!]
MSG_FILTER = LITERAL (Read)
Controls the default level of information reported by Starlink atasks invoked within the executing script. The accepted values are the list defined in SUN/104 (" None" , " Quiet" , " Normal" , " Verbose" , etc). [" Normal" ]
OBSDIR = LITERAL (Read)
The name of a directory in which to put maps made from the individual observations. These are generated on the final iteration. If null is supplied, individual observation maps will not be created. Each map is stored in a file with name <UT >_ <OBS >.sdf. If a single observation is split into multiple chunks, the first chunk will use the above naming scheme but the second and subsequent chunks will have names of the form <UT >_ <OBS >_ <CHUNK >.sdf. [!]
OUT = NDF (Write)
The NDF holding the output map.
PIXSIZE = _REAL (Read)
Pixel dimensions in the output image, in arcsec. The same value will be used for both axes. The default depends on the wavelength of the input data. []
REF = NDF (Read)
An existing NDF that is to be used to define the output grid. If supplied, the output grid will be aligned with the supplied reference NDF. The reference can be either 2D or 3D and the spatial frame will be extracted. If a null (!) value is supplied then the output grid is determined by parameters REFLON, REFLAT, etc. In addition, this NDF can be used to mask the AST, PCA, FLT or COM model. See configuration parameters AST.ZERO_MASK, PCA.ZERO_MASK, FLT.ZERO_MASK and COM.ZERO_MASK.

On the second and subsequent invocations of MAKEMAP, any supplied REF image is replaced by the map created by the previous invocation of MAKEMAP. [!]

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 SKYLOOP. If supplied, execution of skyloop will restart from the point where the previous run finished. This is useful for continuing runs that have been interupted accidentally. 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]