Predict tools

Functions for predicting ionospheric Faraday rotation effects, both time-dependent and time-averaged. Uses RMextract package to get time-dependent ionospheric RMs for a given observation, then performs the time-integration to work out the effective change in polarization angle, and the effective depolarization (together, called the ionospheric modulation, which is called Theta in the derivation).

The ionospheric prediction is currently derived from RMExtract (https://github.com/lofar-astron/RMextract/). Other ionosphere RM codes are available (ionFR, ALBUS) are available, but RMextract was selected for its comparative ease of install and use.

RMextract relies on external maps of Total Electron Content (TEC). As of version 1.1, the default is to get the TEC data from CDDIS (https://cddis.nasa.gov/Data_and_Derived_Products/GNSS/atmospheric_products.html). This requires an account and a .netrc file with the credentials (https://cddis.nasa.gov/Data_and_Derived_Products/CreateNetrcFile.html). Advanced users can change the TEC source using the kwargs for RMextract’s getRM function, with the caveat that this is not supported for the command line tools. The default TEC maps are now the JPL global maps, based on the results of Porayko et al. 2019 who found they performed the best.

Two command line functions are available and documented below:

predict(): time-averaged Faraday rotation.
timeseries(): time-dependent Faraday rotation.

FRion.predict.predict()

Wrapper for command line interface, for time-averaging mode. Gets command line arguments, calculates ionospheric effects, and saves modulation and/or figure if specified.

If the package is installed, it can be called as frion_predict, otherwise as python predict.py

Call with the -h flag to see command line options.

FRion.predict.calculate_modulation(start_time, end_time, freq_array, telescope_location, ra, dec, timestep=600.0, ionexPath='./IONEXdata/', **kwargs)

Calculate the ionospheric FR modulation (time-averaged effect), as a function of frequency, for a given observation (time, location, target direction).

Parameters:

start_time (astropy.time Time, or string readable by astropy.time Time) – Starting time of observation. Example time string: ‘2010-01-02T00:00:00’
end_time (astropy.time.Time, or string readable by astropy.time.Time) – ending time of observation.
freq_array (array-like, either floats or Astropy Quantity) – vector of channel frequencies (in Hz)
telescope_location (astropy.coordinates EarthLocation or string) – location of telescope, or name of telescope known to get_telescope_coordinates() function.
ra (astropy.coordinates Angle, astropy.units Quantity, or float) – right ascension of observation center (if float: in deg, J2000)
dec (astropy.coordinates Angle, astropy.units Quantity, or float) – declination of observation center (if float: in deg, J2000)
timestep (astropy.time TimeDelta, astropy.units Quantity, or float) – time between ionosphere FR estimates. If float, time must be in seconds.
ionexPath (str, default='./IONEXdata/') – path to download IONEX files to for ionosphere calculations.
**kwargs – additional keyword arguments to pass to RMextract.getRM()

Returns:

tuple containing

-times (astropy Time array): vector of times of each ionospheric RM calculation

-RMs (array): vector of RM values computed for each time step

-theta (array) vector containing the (complex) ionospheric polarization for each frequency channel.

FRion.predict.get_RM(start_time, end_time, telescope_location, ra, dec, timestep=600.0, ionexPath='./IONEXdata/', pre_download=True, prefix='jplg', server='http://cddis.gsfc.nasa.gov', **kwargs)

Calculate the ionospheric Faraday rotation as a function of time, for a given observation (time, location, target direction).

Parameters:

start_time (astropy.time Time, or string readable by astropy.time Time) – Starting time of observation. Example time string: ‘2010-01-02T00:00:00’
end_time (astropy.time.Time, or string readable by astropy.time.Time) – ending time of observation.
telescope_location (astropy.coordinates EarthLocation or string) – location of telescope, or name of telescope known to get_telescope_coordinates() function.
ra (astropy.coordinates Angle, astropy.units Quantity, or float) – right ascension of observation center (if float: in deg, J2000)
dec (astropy.coordinates Angle, astropy.units Quantity, or float) – declination of observation center (if float: in deg, J2000)
timestep (astropy.time TimeDelta, astropy.units Quantity, or float) – time between ionosphere FR estimates. If float, time must be in seconds.
ionexPath (str, default='./IONEXdata/') – path to download IONEX files to for ionosphere calculations.
pre_download (bool, default=True) – if True, will pre-download the IONEX files from CDDIS before running RMextract.
prefix (str, default='jplg') – prefix for IONEX files to download.
(str (server) – //cddis.gsfc.nasa.gov’): server to download IONEX files from.
default='http – //cddis.gsfc.nasa.gov’): server to download IONEX files from.
**kwargs – additional keyword arguments to pass to RMextract.getRM()

Returns:

tuple containing

-times (astropy Time array): vector of times of each ionospheric RM calculation

-RMs (array): vector of RM values computed for each time step

FRion.predict.numeric_integration(times, RMs, freq_array)

Numerical integration of the time-varying ionospheric polariation modulation. Testing has shown that numerical integration is accurate to better than 1% accuracy except where depolarization is extreme (>99%).

Parameters:

times (array) – ionosphere sampling times (in MJD seconds, as used in RMextract)
RMs (array) – ionospheric RMs at each time (in rad/m^2)
freq_array (array) – channel frequencies (in Hz)

Returns: array: time-integrated ionospheric modulation per channel.

FRion.predict.check_numeric_problems(RMs, freq_array, theta)

Checks for conditions that might cause numeric instability in the time-integration, and warns the user if there might be concerns.

Specifically, checks for extreme jumps in polarization angle between timesteps (will cause integration errorrs), and for extreme depolarization (high liklihood of large errors).

Parameters:

RMs (array) – ionospheric RMs per time step
freq_array (array) – channel frequencies (in Hz)
theta (array) – ionospheric modulation per channel.

FRion.predict.write_modulation(freq_array, theta, filename)

Saves predicted ionospheric modulation to a text file. File has two columns, whitespace-delimited.

Parameters:

freq_array (array) – channel frequencies (in Hz)
theta (array) – ionospheric (complex) modulation at each frequency
filename (str) – file path to save data to.

FRion.predict.get_telescope_coordinates(telescope)

Return the astropy.coordinates EarthLocation object associated with the position of the telescope. The input must be either a string with the name of a telescope listed in Astropy’s sites list (https://github.com/astropy/astropy-data/blob/gh-pages/coordinates/sites.json), an EarthLocation object (which is passed through unchanged), or a 3-component tuple with the latitude [deg], longitude [deg], and height [m].

Since ASKAP is not yet listed in the Astropy sites list, it’s position is manually coded in as a temporary measure.

FRion.predict.generate_plots(times, RMs, theta, freq_array, position=None, savename=None)

Makes a figure with two plots: the RM variation over time, and the (modulus of the) modulation as a function of frequency. If savename contains a string it will save the plots to that filename, otherwise the plots are not saved. If position ([ra,dec]) is given, it will be printed above the plots.

Parameters:

times (astropy Time array) – ionosphere sampling times
RMs (array) – ionospheric RMs at each time (in rad/m^2)
theta (array) – ionospheric (complex) modulation at each frequency
freq_array (array) – channel frequencies (in Hz)
position (list) – [ra, dec] in degrees, left blank if not supplied.
savename (str) – File path to save plot to; if ‘screen’ will send to display.

FRion.predict.get_parms_from_FITS(filename)

Extract relevant parameters (start time, end time, telescope, ra, dec, and frequencies) from a FITS file, possibly a PSRFITS file. If the missing keywords are not found in the FITS file, they are left blank and the user

Parameters:: filename (str) – path to the FITS file.
Returns:: start_time end_time freq_arr telescope ra dec

FRion.predict.timeseries()

Wrapper for command line interface, for time-series mode. Gets command line arguments, feeds them into RMextract, and saves the output to the file if specified or prints to terminal.

If the package is installed, it can be called as frion_timeseries, otherwise as python -c ‘import FRion.predict; predict.timeseries()’

Call with the -h flag to see command line options.

FRion.predict.write_timeseries(times, RMs, filename, timeformat='mjd')

Saves the predicted ionospheric RMs as a function of time to a text file. File has two columns, whitespace-delimited (Be aware that some time formats will add whitespace to the time column.)

Parameters:

times (astropy Time array) – ionosphere sampling times
RMs (array) – ionospheric RMs at each time (in rad/m^2)
filename (str) – file path to save data to.
timeformat (str) – preferred format for writing times. Possible values can be found at https://docs.astropy.org/en/stable/time/index.html#time-format default is ‘mjd’ (e.g., ‘51544.0’).

FRion.predict.plot_timeseries(times, RMs, position=None, savename=None)

Makes a figure plotting the RM variation over time, If savename contains a string it will save the plots to that filename (unless the name is ‘screen’, in which case it will plot on screen), otherwise the plots are not saved. If position ([ra,dec]) is given, it will be printed above the plots.

Parameters:

times (astropy Time array) – ionosphere sampling times
RMs (array) – ionospheric RMs at each time (in rad/m^2)
position (list) – [ra, dec] in degrees, left blank if not supplied.
savename (str) – File path to save plot to; if ‘screen’ will send to display.