Extraction of Spectra, Images and Cubelets ========================================== This page describes the way spectral and image data products can be extracted for each detected source. Using these tools, the user can get integrated spectra, noise spectra, moment maps, and cube cutouts for each (or a selection) of the detected sources. For all cases, the image products that are created (be they spectra, 2D images or 3D cubelets) are written to either CASA or FITS format images. This is selectable using the **imagetype** parameter for each section - this can take the value **casa** (the default) or **fits**. Spectral Extraction ------------------- This set of parameters allows, for each detected source, the extraction of spectra at the corresponding position in a spectral cube. Typical use cases include: * Extracting full-Stokes spectra from a continuum cube for a source detected in a taylor.0 MFS image. * Extracting an integrated or peak spectrum of a spectral-line source (eg. an HI detection). In this case the spectral cube is the same dataset as that used for the source detection. *Note*: At this point the pixel coordinates are used to get the location in the spectral cube, so the detection image and the spectral cube should have the same WCS. This will be updated as needed in future releases. The initial use case follows the specification provided by POSSUM. The user provides a spectral cube, a list of polarisations to be extracted, and a box width. The spectrum is summed in each channel within this box, centred on the peak (or centroid or average) position of the detected object. This spectrum can optionally be scaled by the response of the beam over the same box, such that the resulting spectrum gives the flux of a point source at that location. The beam used defaults to the beam from the image header, although a 'beam log' (produced by either :doc:`../calim/simager` or the :doc:`../calim/makecube` utility) can be provided so that each channel is scaled by the appropriate restoring beam. The beam log should have columns: index | major axis [arcsec] | minor axis [arcsec] | position angle [deg]. Here is an example of the start of a beam log: :: #Channel BMAJ[arcsec] BMIN[arcsec] BPA[deg] 0 65.7623 36.4139 -54.7139 1 65.7981 36.4222 -54.7605 2 65.8365 36.4324 -54.7985 3 65.8733 36.4413 -54.845 4 65.9082 36.4512 -54.8919 At present, the decision to scale by the beam is made at the parset input stage, but future versions of the algorithm could make this a dynamic choice based on the source in question. The user can select which polarisations / Stokes parameters should be included in the output spectra. There are three options here for the case of multiple polarisations, with **polarisation="IQUV"** * The user provides a single spectral cube that has all polarisations listed: **spectralCube=image.iquv.cube** * The user provides a list of spectral cubes that have all the polarisations requested. The list is provided as a comma-separated list enclosed in square brackets: **spectralCube=[image.i.cube,image.q.cube,image.u.cube,image.v.cube]** * The user provides a single filename that uses a "%p" wildcard in place of the polarisation name (in lower case): **spectralCube=image.%p.cube** The second use case is triggered by setting **extractSpectra.useDetectedPixels=true**. This results in the spectrum being summed over all spatial pixels in which the object in question was detected. If **extractSpectra.scaleSpectraByBeam=true**, then the spectrum is scaled by the area of the beam (in the same way the integrated flux of a Duchamp detection is scaled by the beam). Additionally, Selavy inherits Duchamp's ability to save the spectra to an ASCII text file. This is controlled by the parameters **flagTextSpectra** and **spectraTextFile**. You can select particular objects for spectral extraction, either to images or ASCII text, by using the **objectList** parameter and providing a comma-separated list of object IDs. Parameters for spectral extraction ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |*Parameter* |*Type* |*Default* |*Explanation* | +==================================+================+===================+====================================================================================================+ |extractSpectra |bool |false |Whether to extract spectra for each detected source | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.imagetype |string |casa |Type of image to create when extracting. Can be either "casa" or "fits" - anything else will throw | | | | |an error. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.usefitstable |bool |false |If imagetype is "fits" and this flag is set then the extacted spectra are written to a fits binary | | | | |table. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.spectralCube |vector |[] |A set of input spectral cubes from which the spectra will be extracted, given as a comma-separated | | | | |list within square brackets. If just one cube is required, the square brackets are optional. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.spectralOutputBase |string |"" |The base used for the output spectra. The filename for a given source will be this string appended | | | | |with "_ID", where ID is the source's ID number from the results list. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.polarisation |vector |I |The set of Stokes parameters for which spectra should be extracted. Multiple polarisations can be | | | | |provided in a number of ways: "IQUV", ["I","Q","U","V"] etc. See text for requirements. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.spectralBoxWidth |int |5 |The width of the box to be applied in the extraction. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.pixelCentre |string |peak |Which object location to use. Can be "peak", "centroid", or "average", in the same way as the | | | | |standard Duchamp input parameter pixelCentre. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.useDetectedPixels |bool |false |Whether to use all detected pixels of the object, and integrating over them, rather than applying a | | | | |box. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.scaleSpectraByBeam |bool |true |Whether to scale the resulting spectra by the beam extracted over the same box, or, in the case of | | | | |useDetectedPixels=true, by the area of the beam (using the same correction as in Duchamp). | | | | | | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |extractSpectra.beamLog |string |"" |The name of a 'beam log' produced by :doc:`../calim/makecube`. If provided (and if the | | | | |scaleSpectraByBeam flag is set), each channel is independently corrected by the relevant restoring | | | | |beam. If not provided, the beam from the image header is used instead. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |flagTextSpectra |bool |false |Produce a file with text-based values of the spectra of each detection. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |spectraTextFile |string |selavy-spectra.txt |The file containing ascii spectra of each detection. | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ |objectList |string |*no default* |A comma-separated list of objects that will be used for the post-processing. This is inherited from | | | | |Duchamp, where it can be used to only plot a selection of sources. This is most useful for | | | | |re-running with a previously-obtained catalogue. In Selavy, this will only be applied to the | | | | |spectraTextFile and spectral extraction options. If not provided, all objects will be processed. | | | | | | +----------------------------------+----------------+-------------------+----------------------------------------------------------------------------------------------------+ Noise spectra ------------- The same algorithms can be applied to extract noise spectra for each object. In this case, the box used is defined by a multiple of beam areas (defaulting to 50, as per the POSSUM specification). The box is taken to be a square box with the same area as requested. For each channel, the noise rms level is measured within that box to produce the noise spectrum. As for the source spectrum, a polarisation can be indicated as the Stokes parameter from which to measure the noise. Only one Stokes parameter is used - if more than one is provided, only the first is used. The same rules for accessing the spectral cube are applied as described above. The **objectList** parameter applies to the noise spectra as well. Parameters for noise spectra extraction ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------+---------------+------------+---------------------------------------------------+ |*Parameter* |*Type* |*Default* |*Explanation* | +=======================================+===============+============+===================================================+ |extractNoiseSpectra |bool |false |Whether to extract a noise spectrum from around | | | | |each detected source | +---------------------------------------+---------------+------------+---------------------------------------------------+ |extractNoiseSpectra.imagetype |string |casa |Type of image to create when extracting. Can be | | | | |either "casa" or "fits" - anything else will throw | | | | |an error. | +---------------------------------------+---------------+------------+---------------------------------------------------+ |extractNoiseSpectra.usefitstable |bool |false |If imagetype is "fits" and this flag is set then | | | | |the extracted noise spectra are written to a fits | | | | |binary table. | +---------------------------------------+---------------+------------+---------------------------------------------------+ |extractNoiseSpectra.spectralCube |vector |[] |As above. If more than one cube is given, only the | | | | |first is used. | +---------------------------------------+---------------+------------+---------------------------------------------------+ |extractNoiseSpectra.spectralOutputBase |string |"" |As above. | +---------------------------------------+---------------+------------+---------------------------------------------------+ |extractNoiseSpectra.polarisation |vector |I |As above. If more than one is provided, only the | | | | |first is used. | +---------------------------------------+---------------+------------+---------------------------------------------------+ |extractNoiseSpectra.noiseArea |float |50.0 |The number of beam areas over which to measure the | | | | |noise. | +---------------------------------------+---------------+------------+---------------------------------------------------+ |extractNoiseSpectra.robust |bool |true |Whether to use robust methods to estimate the | | | | |noise. | +---------------------------------------+---------------+------------+---------------------------------------------------+ Moment-map extraction --------------------- Similar facilities exist for creating and extracting moment maps for spectral-line detections. This is capable of creating the total intensity (moment-0) map, the intensity-weighted mean velocity field (moment-1 map) and the intensity-weighted velocity dispersion (moment-2 map). The default behaviour is to produce all three, although one may use the **moments** parameter to select individual maps (e.g. **moments=[0,1]** to select just the total intensity and mean velocity field maps). There is one key choice to be made that affects the appearance of these maps, and that is what voxels to include in the calculations. By setting **useDetectedPixels=true**, the only pixels included in the calculations will be those that actually form part of the detected object. Pixels that do not form part of the object are masked in the final images. If **useDetectedPixels=false**, then the moment maps will be made with all pixels within the channel range of the detected object, whether or now they formed part of that object. The spatial size of the maps is determined in one of two ways. If **spatialMethod=box**, then the spatial size is at least the size of the detected object, padded out on each side by a given number of pixels if desired (by using the **padSize** parameter). If **spatialMethod=fullfield**, then the full spatial size of the input cube is used. The output filenames can be specified using a special wildcard: '%m' will be replaced with the moment number, so that if one provides **momentOutputBase=myImage_mom%m**, then the first object's moment-0 map will go into myImage_mom0_1 and its moment-1 map will go to myImage_mom1_1. As above, the object ID is appended to the base name in the form "_ID". Parameters for moment-map extraction ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |*Parameter* |*Type* |*Default* |*Explanation* | +=======================================+===============+============+================================================================+ |extractMomentMap |bool |false |Whether to extract moment maps. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractMomentMap.imagetype |string |casa | Type of image to create when extracting. Can be either "casa" | | | | | or "fits" - anything else will throw an error | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractMomentMap.spectralCube |vector |[] |As above. If more than one cube is given, only the first is | | | | |used. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractMomentMap.momentOutputBase |string |"" |Base name for the moment maps. If more than one moment is being | | | | |used, use '%m' to represent the moment number. The name is | | | | |appended with "_ID", where ID is the object ID number. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractMomentMap.moments |vector |[0] |Which moment maps to create. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractMomentMap.spatialMethod |string |box |Either "box" (cutout is restricted to the immediate vicinity of | | | | |the detection, padded by **padSize**), or "fullfield" (the | | | | |entire spatial size of the input cube). | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractMomentMap.padSize |int |5 |When using **spatialMethod=box**, a border of this many pixels | | | | |is added to the edges of the image, surrounding the spatial | | | | |extent of the detection. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractMomentMap.useDetectedPixels |bool |true |Whether to just use the detected pixels in calculating the | | | | |moment maps (**true**) or to use all pixels within the detected | | | | |object's spectral range. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ Cubelet extraction ------------------ The final form of data product extraction is to extract 'cubelets' - cutout cubes surrounding the detected object. These have no processing applied to them other than the trimming, and so provide a way of looking at the data directly relevant to the detected object without having to load the entire input image cube. The cubelet size is taken from the outer dimensions of the detected object, and can be padded by a certain number of pixels in the spatial and spectral directions. To specify the padding amount, use the **padSize** parameter, giving a vector with two elements. The first is the pad size used in the spatial direction, the second is for the spectral direction. If only one value is given it is applied to both directions. The input data need not be a cube, of course - it is possible to run this on a continuum image and it will work in the same way. Parameters for cubelet extraction ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |*Parameter* |*Type* |*Default* |*Explanation* | +=======================================+===============+============+================================================================+ |extractCubelet |bool |false |Whether to extract cubelets. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractCubelet.imagetype |string |casa | Type of image to create when extracting. Can be either "casa" | | | | | or "fits" - anything else will throw an error. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractCubelet.spectralCube |vector |[] |As above. If more than one cube is given, only the first is | | | | |used. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractCubelet.cubeletOutputBase |string |"" |Base name for the cubelet files. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+ |extractCubelet.padSize |vector |[5,5] |Number of pixels to add to the edge of the detection in the | | | | |spatial and spectral directions respectively. If a single | | | | |integer is provided, this is applied to both spatial and | | | | |spectral directions. | +---------------------------------------+---------------+------------+----------------------------------------------------------------+