Functions

This section lists all the Lua functions provided by AOFlagger.

Detailed descriptions

aoflagger.apply_bandpass(data, filename)

Apply a bandpass file to the data. The data is changed in place. Each line in the file contains <antenna name> <X/Y polarization> <channel index> <gain>, separated by spaces, for example:

RT2 X 0 0.7022
RT2 X 1 0.7371
RT2 X 2 0.8092
…
Parameters:
  • data (Data) – Data to which the bandpass is applied.
  • filename (string) – Path to bandpass textfile.
aoflagger.collect_statistics(after_data, before_data)

Calculate statistics, such as visibility standard deviation and flag percentages. When running the strategy on a measurement set, the statistics are stored inside the measurement set after finishing all baselines. These can be inspected by the aoqplot tool.

The function takes the data after and before flagging. Any data that are flagged in before_data will not contribute to the statistics. This avoids counting e.g. correlator faults or shadowing as interference.

Parameters:
  • after_data (Data) – Flagged data.
  • before_data (Data) – Unflagged data.
aoflagger.downsample(data, xfactor, yfactor, masked)

Decrease the resolution of the data using simple linear binning. This can be effective to increase the speed of data smoothing, for example when using high_pass_filter(). At the function end of execute(), the data should have the original size. Therefore, a call to downsample should normally be followed by a call to upsample() to restore the flags and visibilities to their original resolution.

When the input data is not exactly divisable by the downsampling factors, fewer samples will be averaged into the last bins.

Parameters:
  • data (Data) – Input data (not modified).
  • xfactor (integer) – Downsampling factor in time direction.
  • yfactor (integer) – Downsampling factor in frequency direction.
  • masked (boolean) – true means take flags into account during averaging
Returns:

Downsampled version of input data.
Return type:

Data
aoflagger.high_pass_filter(data, xsize, ysize, xsigma, ysigma)

Apply a Gaussian high-pass filter to the data. This removes the diffuse ‘background’ in the data. With appropriate settings, it can filter the signal of interest (slow sinusoidal signals), making the interference easier to detect.

The function convolves the data with a 2D “1 minus Gaussian” kernel. The kernel is clipped at the edges. The sigma parameters define the strength (band-limit) of the filter: lower values remove more of the diffuse structure.

Parameters:
  • data (Data) – The data (modified in place).
  • xsize (integer) – Kernel size in time direction
  • ysize (integer) – Kernel size in frequency direction
  • xsigma (number) – Gaussian width in time direction.
  • ysigma (number) – Gaussian width in frequency direction.
aoflagger.low_pass_filter(data, xsize, ysize, xsigma, ysigma)

Apply a Gaussian low-pass filter to the data. It convolves the data with a Gaussian. See high_pass_filter() for further details.

Parameters:
  • data (Data) – The data (modified in place).
  • xsize (integer) – Kernel size in time direction
  • ysize (integer) – Kernel size in frequency direction
  • xsigma (number) – Gaussian width in time direction.
  • ysigma (number) – Gaussian width in frequency direction.
aoflagger.normalize_subbands(data, nr_subbands)

Remove jumps between subbands. A subband is in this context a number of adjacent channels, equally spaced over the bandwidth. This function therefore assumes that all subbands have an equal number of channels.

Each subband is scaled such that the standard deviation of the visibilities in a subband is unity. To avoid influence from interference, a stable method is used to estimate the standard deviation (Winsorized standard deviation).

A typical use-case for this function is the MWA phase 1 and 2. The 30 MHz bandwidth of the MWA is split in 24 ‘course channels’, each consisting of 128 channels. Each course channel has an independent gain, and needs normalization before it can be compared with adjacent course channels.

Parameters:
  • data (Data) – The data (modified in place).
  • nr_subbands (integer) – Number of subbands.
aoflagger.print_polarization_statistics(data)

Print RFI percentages per polarization to the command line.

Parameters:data (Data) – Input data.
aoflagger.save_heat_map(filename, data)

Save the data as a “heat map” image. The type is determined from the extension. Supported extensions are .svg, .png and .pdf.

Parameters:
  • filename (string) – Path to image to be written.
  • data (Data) – Input data.
aoflagger.scale_invariant_rank_operator(data, xlevel, ylevel)

Extend flags in time and frequency direction in a scale-invariant manner. This fills holes in the flag mask and makes flag sequences longer. Details are described in Offringa et al. 2012.

Parameters:
  • data (Data) – The data (modified in place).
  • xlevel (number) – aggressiveness in time-direction
  • ylevel (number) – aggressiveness in frequency-direction
aoflagger.scale_invariant_rank_operator_masked(data, mask_data, xlevel, ylevel)

Perform the same operation as scale_invariant_rank_operator(), but with a mask. Data that is flagged in the mask are removed before applying the operator.

Parameters:
  • data (Data) – The data (modified in place).
  • mask_data (Data) – The data that is used as mask.
  • xlevel (number) – aggressiveness in time-direction
  • ylevel (number) – aggressiveness in frequency-direction
aoflagger.set_progress(progress, max_progress)

Notify user of the progress of this call. The gui uses this information to show a progress bar to the user. Example: when the execute() function iterates over the polarizations, progress can be reported by calling aoflagger.set_progress(curpol, npol) inside the loop.

Parameters:
  • progress (integer) – current progress
  • max_progress (integer) – value of progress when complete
aoflagger.set_progress_text(task_description)

Notify user of the current task being done. The description can be anything, and can literally be presented to the user.

Parameters:task_description (string) – Description string.
aoflagger.sumthreshold(data, xthreshold_f, ythreshold_f, include_x, include_y)

Run the SumThreshold algorithm on the data. This algorithm detects sharp, line-shaped features in the time-frequency domain that are typical for RFI. See Offringa et al. (2010) for details about the algorithm.

The thresholds are relative to a (stable) estimate of the noise in the visibilities. They define the base sensitivity of the algorithm. Lower values will detect more features. A reasonable value for the thresholds is 1.

The “include” parameters turn detection in their particular directions on and off. Note that detection in “x” (=time) direction means detection of contiguous high-power samples in time, such as transmitters that occupy the same channel continuously. The y-direction detection is sensitive to transient, broadband RFI.

Parameters:
  • data (Data) – The data (modified in place).
  • xthreshold_f (number) – Threshold factor in time direction
  • ythreshold_f (number) – Threshold factor in frequency direction
  • include_x (Data) – The data that is used as mask.
  • include_y (Data) – The data that is used as mask.
aoflagger.sumthreshold_masked(data, mask_data, x_threshold_f, y_threshold_f, x_direction, y_direction)

Same as sumthreshold(), but with a mask. Visibilities that are flagged in the mask are considered to be visibilities that have not been sampled and are removed from the SumThreshold operation. A typical case for this is to make sure that correlator faults, shadowing and band-edges are correctly treated.

Parameters:
  • data (Data) – The data (modified in place).
  • mask_data (Data) – The data that is used as mask.
  • x_threshold_f (number) – Threshold factor in time direction
  • y_threshold_f (number) – Threshold factor in frequency direction
  • x_direction (boolean) – The data that is used as mask.
  • y_direction (boolean) – The data that is used as mask.
aoflagger.threshold_channel_rms(data, threshold, flag_low_outliers)

Calculate the root-mean-square (RMS) for each channel and flags channels that have an outlier RMS. The threshold is a “sigma level”. Typical values for the threshold are therefore around 3.

Parameters:
  • data (Data) – The data (modified in place).
  • threshold (number) – Sigma-level of threshold
  • flag_low_outliers (boolean) – Flag channels with low RMS
aoflagger.threshold_timestep_rms(data, threshold)

Like threshold_channel_rms(), but thresholds timesteps with outlier RMS. Both timesteps with high and low RMS values are flagged.

Parameters:
  • data (Data) – The data (modified in place).
  • threshold (number) – Sigma-level of threshold
aoflagger.upsample(input_data, destination_data, xfactor, yfactor)

Increase the resolution of the data. This function is to restore the resolution of the data after having called downsample(). input_data is normally the data that was returned by downsample(), and destination_data is the input object that was specified as parameter. The upsampling is done by nearest neighbour interpolation.

The x and y factors should be the equal to the values specified in the call to downsample. The size of the destination_data is not changed: the input data is stretched by the given factors, and trimmed to the destination size in case the image dimensions were not exactly divisable by the factors.

Parameters:
  • input_data (Data) – Input low-resolution data (not modified).
  • destination_data (Data) – Where the result will be stored.
  • xfactor (integer) – Upsampling factor in time direction.
  • yfactor (integer) – Upsampling factor in frequency direction.
aoflagger.visualize(data, label, sorting_index)

Save a visualization of the data for inspection in rfigui. When this strategy runs outside of the rfigui, the call is ignored. Can be used to e.g. inspect partial results.

Parameters:
  • data (Data) – Input data (not modified).
  • label (string) – A short description that is displayed to the user.
  • sorting_index – Where to place this visualization in the list of visualization