-
Notifications
You must be signed in to change notification settings - Fork 24
RMsynth3D
The 3D RM synthesis tool is used for performing RM synthesis on image-frequency cubes. This tool is currently somewhat less developed than the 1D RM synthesis in terms of additional features, but basic functionality is complete. Specific behaviour of this tool may change in future versions (or users may be requested changes).
If RMtools has been installed with terminal commands, then RMSynth3D can be invoked from the command line as rmsynth3d <Stokes Q cube> <Stokes U cube> <frequencies file> <options>, otherwise it must be invoked as a Python script as python <RMtools directory>/RMtools_3D/do_RMsynth_3D.py <Stokes Q cube> <Stokes U cube> <frequencies file> <options>.
Invoking with the -h flag set will produce the help text with the list of option flags.
RMsynth3D takes two input FITS files, and an ASCII file containing a list of channel frequencies. The FITS files are assumed to have a frequency axis and 1 or 2 non-degenerate position axes (which allows support for HEALPIX files), and any number of degenerate axes (axes of size 1). In principle, the axis ordering shouldn't matter, but not all edge cases have been tested. Each of the two input FITS files is assumed to contain one Stokes parameter; RM-tools does not currently support inputs with a non-degenerate Stokes axis.
The channel frequencies ASCII file is expected to contain one entry per line, with a frequency in Hz, and a number of lines equal to the number of frequencies in the input FITS files. The reason that RMsynth3D pulls the frequencies from a text file instead of from the FITS headers is to allow users to run RM synthesis on non-continuous blocks of frequencies (e.g., combining observations at different bands). This can be done by concatenating all the channels into a single cube, but this cannot be recorded properly in the FITS header so a separate file is used. Users trying this are warned to be very careful constructing such concatenated non-contiguous FITS cubes, as their headers can be very misleading to others if not carefully documented.
RMsynth3D produces the following output files:
- FDF_dirty.fits: a FITS file of the dirty FDF. Contains three cubes (as separate FITS extensions): the real component (Stokes Q), the imaginary component (Stokes U), and the amplitude (polarized intensity). Dimensions and axis ordering of the cubes is the same as the inputs, except that the frequency axis is swapped for the Faraday depth axis. Degenerate axes are removed.
- RMSF.fits: a FITS file similar to FDF, but containing the RMSF. Has the same structure as the FDF, but with twice as many planes in Faraday depth. In addition to the 3 cubes, it also contains as the 4th extension a map of the FWHM of the RMSF. This has the same dimensions as the dirty FDF, but without the Faraday depth axis.
- FDF_maxPI.fits: a FITS file containing a map of the maximum polarized intensity in each FDF (ie, for each pixel). Has the same dimensions as the dirty FDF, but without the Faraday depth axis.
- FDF_peakRM.fits: a FITS file containing a map of the Faraday depth containing the maximum polarized intensity in each FDF.
The _maxPI and _peakRM maps are calculated from the Faraday depth values sampled by the FDF; no interpolation or peak fitting is done. This functionality will be developed as an additional tool in the near future.
-h Print the help documentation to the terminal.
-i FITSI Supply a FITS cube of Stokes I values (either data or modelled) that will be used to normalize the input Stokes Q and U values to be fractional polarizations. If not supplied, then the Q and U flux values are used.
-n NOISEFILE Supply a 1D FITS file with noise values for each channel, which can be used to set the weighting scheme. Support for 2D or 3D noise is not yet implemented, but can be added if requested. Requires that -w flag to be set to have any effect. If no noise file is supplied then all channels are assumed to have equal weight.
-w WEIGHTTYPE Supply the name of the weighting scheme to be used. Currently the only options are 'uniform' (default, all channels treated equally), or 'variance' (each channel weighted by the inverse square of the noise). Additional weightings can be added if requested.
-t Fit a Gaussian to the RMSF [False]. By default, the RMSF is determined by measuring the width of the half power level in the RMSF. This option will fit a Gaussian to the main lobe, and derive the FWHM from the Gaussian fit.
-l PHIMAX Supply a number to set the range of Faraday depths over which to calculate the FDF. The resulting FDF will go from -PHIMAX rad/m^2 to +PHIMAX rad/m^2. By default, RMtools will calculate the 50% bandwidth depolarization threshold (using the equation from Brentjens & de Bruyn 2005) and will set the PHIMAX to the larger of this value or 600 rad/m^2.
-d DPHI Supply a number to set the sample spacing in Faraday depth, in rad/m^2. The FDF will be calculated in steps of this size, symmetrically around zero out to +/-PHIMAX. If PHIMAX is not a multiple of DPHI then PHIMAX will be decreased to the nearest multiple. The default value is determined by the -s flag below.
-s NSAMPLES Supply a number to set the sample spacing DPHI to correspond to NSAMPLES points per RMSF FWHM. This value will be ignored if the -d flag is used to manually set the sample spacing. The default behaviour is to have 10 samples across the FWHM (a high oversampling ratio).
-o PREFIXOUT Supply the filename prefix that the output files should have. This will be prepended to all the files saved (as described in Outputs).
-f Separate the Stokes Q/U/P outputs into individual files. Currently the default is to combine these as multiple extensions in a single FITS file. With this flag selected 3 FITS files are written for each output: _real_ (Stokes Q), _im_ (Stokes U), _tot_ (P, polarized intensity).
-v Activate verbose messaging (including progress bar to indicate progress towards completion).
-R Set to skip the calculation of the RMSF. By default the RMSF cube is calculated along with the dirty FDF, but this can be suppressed with this flag in order to reduce computational load.
The memory requirements for RMsynth3D can be quite large, especially for larger input and output cubes. If the required memory exceeds the available RAM, then most systems will begin using swap memory which is considerably slower. To avoid this, we are developing tools to allow users to break up large files into smaller chunks, run each chunk through RMsynth3D, then reassemble the output products. This tools are not extensively tested yet, but are available to users for testing. Inside the RM-tools package, RMtools_3D/create_chunks.py will create smaller pieces of a large file, while RMtools_3D/assemble_chunks.py will put them back together again. These tools both have -h flags to explain their use, and will eventually be documented on the Additional Tools page.
Not yet determined, sorry!