Correct tools

Functions for applying ionospheric Faraday rotation corrections to images and image cubes. This file contains the functions needed to apply the correction to data cubes (either in memory, or in FITS files.)

The complex polarization (Q + iU) is divided by the predicted ionospheric modulation to produce corrected values that should have the effect of the ionosphere removed. These can then be saved to new Stokes Q and U FITS files.

The main functions below do not do anything specific to handle very large FITS files gracefully. It may not perform efficiently when file sizes are comparable to the amount of available RAM. An alternative mode, apply_correction_large_cube(), has been developed to reduce the memory footprint required.

FRion.correct.apply_correction_to_files(Qfile, Ufile, predictionfile, Qoutfile, Uoutfile, overwrite=False)

This function combines all the individual steps needed to apply a correction to a set of Q and U FITS cubes and save the results. The user should supply the paths to all the files as specified.

Parameters:

  • Qfile (str) – filename of uncorrected Stokes Q FITS cube

  • Ufile (str) – filename of uncorrected Stokes U FITS cube

  • predictionfile (str) – path to ionospheric modulation prediction (from predict tools)

  • Qoutfile (str) – filename for corrected Stokes Q FITS cube.

  • Uoutfile (str) – filename for corrected Stokes U FITS cube.

  • overwrite (bool) – overwrite Stokes Q/U files if they already exist? [False]

FRion.correct.read_prediction(filename)

Read in frequencies and ionospheric predictions from text file.

Returns:

tuple containing

-frequencies (array): frequencies of each channel (Hz);

-theta (array): ionospheric modulation for each channel

FRion.correct.find_freq_axis(header)

Finds the frequency axis in a FITS header. Input: header: a Pyfits header object. Returns the axis number (as recorded in the FITS file, NOT in numpy ordering.) Returns 0 if the frequency axis cannot be found.

FRion.correct.readData(Qfilename, Ufilename)

Open the Stokes Q and U input cubes (from the supplied file names) and return data-access variables and the header. Axes are re-ordered so that frequency is first, beyond that the number and ordering of axes doesn’t matter. Uses the memmap functionality so that data isn’t read into data; variables are just handles to access the data on disk. Returns the header from the Q file, the U file’s header is ignored.

FRion.correct.write_corrected_cubes(Qoutputname, Uoutputname, Qcorr, Ucorr, Qheader, Uheader, overwrite=False)

Write the corrected Q and U data to FITS files. Copies the supplied header, adding a note to the history saying that the correction was applied.

Inputs:

Qoutputname (str): filename to write corrected Stoke Q data to. Uoutputname (str): filename to write corrected Stoke U data to. Qcorr (array): corrected Stokes Q data Ucorr (array): corrected Stokes U data [Q/U]header: Astropy FITS header objects that describes the data overwrite (bool): overwrite Stokes Q/U files if they already exist? [False]

FRion.correct.correct_cubes(Qdata, Udata, theta)

Applies the ionospheric Faraday rotation correction to the Stokes Q/U data, derotating the polarization angle and renormalizing to remove depolarization. Note that this will amplify the noise present in the data, particularly if the depolarization is large (|theta| is small).

Inputs:

Qdata (array): uncorrected Stokes Q data, frequency axis first Udata (array): uncorrected Stokes U data, frequency axis first theta (1D array): ionospheric modulation, per frequency

Returns:

corrected Stokes Q data, same axis ordering Ucorr (array): corrected Stokes U data, same axis ordering

Return type:

Qcorr (array)

FRion.correct.progress(width, percent)

Print a progress bar to the terminal. Stolen from Mike Bell.

FRion.correct.apply_correction_large_cube(Qfile, Ufile, predictionfile, Qoutfile, Uoutfile, overwrite=False)

Functions as apply_correction_to_files, but for files too large to hold in memory. Combines the correct_cubes() and write_corrected_cubes() steps into a single function so that it can operate on smaller pieces of data at one time.

This function combines all the individual steps needed to apply a correction to a set of Q and U FITS cubes and save the results. The user should supply the paths to all the files as specified. This function is less flexible in terms of axis ordering: it assumes two spatial axes, and a frequency axis in position 3 or 4.

Parameters:

  • Qfile (str) – filename of uncorrected Stokes Q FITS cube

  • Ufile (str) – filename of uncorrected Stokes U FITS cube

  • predictionfile (str) – path to ionospheric modulation prediction (from predict tools)

  • Qoutfile (str) – filename for corrected Stokes Q FITS cube.

  • Uoutfile (str) – filename for corrected Stokes U FITS cube.

  • overwrite (bool) – overwrite Stokes Q/U files if they already exist? [False]

FRion.correct.command_line()

When invoked from the command line, parse the input options to get the filenames and other parameters, then invoke apply_correction_to_files to run all the steps and save the output cubes.