Tools

The following tools are also present in RM-Tools. Each has a corresponding terminal command to make it easier to access. All of the tools have built-in help that can be accessed with the -h flag; information on the specific flags that can be used with each tool can be found there.

1D additional tools

rmtools_calcRMSF: Estimates the RMSF properties for a given frequency sampling. The frequency sampling can be input in two forms:

1. an ASCII file with each row containing a frequency (in Hz) and optionally a channel weight. Alternatively, a second file containing a weight value in each row can be supplied. If no weights are supplied in the file, uniform weighting is used.
2. using the -f flag and supplying the lowest frequency, highest frequency, and channel width (all in Hz). Uniform channel spacing and weighting are assumed.
   Flags can be used to set the maximum Faraday depth and the Faraday depth spacing respectively, otherwise they default to 10x and 1/10th the theoretical FWHM. The RMSF shape is plotted for the user, and key values are printed to the plot and the terminal. Flags can be used to automatically save this plot.

rmtools_testdata1D: Creates an example/test dataset for 1D RM-synthesis and QU-fitting, given an RM catalog. Example RM catalogs are supplied in the RMtools_1D/cats/ directory. Flags can be used to adjust the frequency channels of the example data, and to adjust the noise level. Example datasets generated from this tool are already included in the RMtools_1D/data/ directory.

---

3D chunk manipulation tools

Since the memory footprint of 3D RM synthesis can be quite large, it can be the case that trying to run rmsynth3d and rmclean3d on very large cubes can overfill the available RAM, forcing the system to use swap memory (hard disk) which is considerably slower. Since each pixel is effectively processed independently, it can be better to break large files into smaller chunks (with a smaller number of image-plane pixels), running RM synthesis on each chunk, and assembling the output products back into larger files.

We have written two convenience scripts for this task: RMtools_3D/create_chunks.py and RMtools_3D/assemble_chunks.py.

rmtools_createchunks: Creates smaller files from a large FITS files, breaking the image plane into small pieces. Does not delete the large file (so additional disk storage is needed for the chunks).
Inputs:
filename, the name of the large FITS file to be broken up.
N_pixels, the number of image-plane pixels per chunk. Can take any value; is not fixed to any fraction/multiple of the image dimensions. The number of chunks created will be ceil(X_dim x Y_dim / N_pixels), where X_dim/Y_dim are the X and Y pixel dimensions of the input image.
-p Prefix, the prefix to be prepended to each filename. Defaults to the name of the input file.

Running this task will create a number of files, all named with the prefix specified by the -p parameter (or the default), a .C<i>, where <i> is the number of the chunk from 1..N, and .fits. From there, these files can be individually run through 3D RM synthesis and/or 3D RM clean.

Note that the default behaviour of RMsynth3d is to produces files with the default filenames (e.g., FDF_tot_dirty.fits). Thus, the chunk number is removed from the filename. To prevent this, use the -o PREFIXOUT parameter in RMsynth3D to ensure each output is saved with a unique file name. To use the assemble_chunks script, each file must have a .C<i>present in the filename to allow re-assembly.

rmtools_assemblechunks: Assembles chunks into larger files.
Inputs:
filename: one of the chunks to be assembled. The others must have the same filename, and will be identified by the .C<i> part of the filename. -f _Output name>: the name of the output file. If not supplied, it will the same as the input filename but with the .C<i> portion removed. -o: Overwrite existing file if present?

The dimensions of the original image are stored in the FITS header of the chunks and used to reassemble the chunks to the original (image-plane) dimensions. The script will fail if not all chunks are present; it can only assemble the entire image plane together.

---

3D additional tools

rmtools_freqfile: makes a frequency file from a FITS file, assuming that the channels are equally spaced and described accurately by the FITS header. This frequency file can be directly used by RMsynth3D.

rmtools_fitIcube: Fits Stokes I models per pixel to a Stokes I cube. Applies the Stokes I fitting routines from the 1D tools pixel-wise to a 3D cube. Supports both polynomial and log-polynomial/power law functions, with fixed or dynamic polynomial order. Also estimates the noise per-channel in the Stokes I images (iteratively using clipping to remove bright pixels), which will be saved to a file for optional channel weighting in the RM synthesis step. If the apply_mask flag is set, spectra are only fit to pixels above some cutoff threshold (absolute or a multiple of the noise); otherwise all pixels are fit. Outputs a cube containing model values at the same frequencies, a channel noise file, and sky masks of the pixels used in the noise estimation and the fitting, and maps of the fit parameters. The Stokes I model cube can be supplied to rmsynth3d to normalize the polarized spectra.

rmtools_peakfitcube: Applies the 1D RM spectrum characterization and peak-fitting methods pixel-wise to a 3D Faraday depth cube. Each of the resulting parameters/measurements is converted into a 2D map. By default only the most commonly interesting maps are saved, but all properties can be saved if desired. The names and meanings of the outputs match up with the 1D RM synthesis outputs, found here.

rmtools_3DIrescale: Rescales Stokes I model parameters to a new reference frequency. Useful for converting Stokes I models to the same frequency as the polarization results (from 3D RM-synthesis/clean), or to a single user-selected reference frequency.

rmtools_testdata3D: Creates a sample/test dataset suitable for rmsynth3d. Takes an input catalog of sources, such as present in RMtools_1D/cats/. Most parameters governing the resulting frequency cubes are hardcoded; look inside RMtools_3D/mk_test_cube_data.py to modify.

rmtools_extractregion: Cuts out a small (image-plane) region of a cube. Region can be selected in either pixel or sky coordinates. Cutting on the 3rd axis can also be applied (but only in pixel coordinates).