-
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.
There are several additional tools to support 3D RM synthesis. If the cubes are too large to process efficiently, they can be divided into small chunks and reassembled after RM synthesis. If normalization by a Stokes I spectrum is desired, there is a tool for generating model spectra. For analysis of Faraday depth cubes, there is a pixel-wise peak-fitting script.
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 model values 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. Note that Stokes I should NOT be used here, as it is very noisy and will introduces significant errors into the RM synthesis. Stokes I model cubes can be generated using the fitIcube tool.
-n NOISEFILE Supply an ASCII file with noise values for each channel (same format as the frequency file), 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 Store different Stokes as FITS extensions. Normally, 3 FITS files are written for each output: _real_ (Stokes Q), _im_ (Stokes U), _tot_ (P, polarized intensity). If this flag is activated then these will be combined into a single FITS file with multiple extensions.
-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!
RM-tools RM synthesis uses a non-gridded discrete Fourier transform to compute the FDF. The advantage of this is that it automatically handles non-uniform sampling in wavelength^2 (which occurs because sampling is usually uniform in frequency) as well as gaps in sampling (which can come from combining data at different bands) without any artifacts introduced by re-gridding the data. The cost of this is that FFT algorithms cannot be used, making the computation somewhat more expensive.
Weighting of the input data can be applied, with two options being available currently: uniform and inverse variance. Uniform weighting (or no weights) treats every channel equally. This gives the smallest RMSF possible with a given set of data, at the cost of producing slightly noisier FDFs. Inverse variance weighting down-weights noisy channels, producing FDFs with lower noise at the cost of RMSF width. Inverse variance also requires that the noise be estimated accurately in order to produce optimum results. If all channels have the same noise levels then this is equivalent to uniform weighting.
Since the FDF is computed at discrete values, the spacing between computed samples and the distance in Faraday depth over which to sample must be defined. The default values for the maximum Faraday depth and Faraday depth sampling are calculated from Equations 61 and 63 of Brentjens & de Bruyn (2005) which give simple predictions for the FWHM of the RMSF, and the Faraday depth at which bandwidth depolarization become significant. The FWHM of the RMSF is estimated to be approximately 2*sqrt(3)/(wavelength^2_max - wavelength^2_min), using the maximum and minimum wavelengths of the input data. If a sampling size is not set by the user (with the -d flag), it then it will default to a fraction of the estimated FWHM; specifically it is set to FWHM/NSAMPLES, where NSAMPLES is the value set by the -s flag (defaults to 5).
It should be noted that currently the weighting is only per-frequency, and is calculated the same for every pixel, but any position-dependence in missing or flagged out channels is correctly accounted for. This leads to a pixel-dependent RMSF, which is why the RMSF is also kept as a cube.