MHO_NotchComb

Purpose

MHO_NotchComb applies a periodic comb of notches across the frequency spectrum of visibility data. Notches are defined by a starting offset, a repetition period, and a notch width, producing regularly spaced frequency regions that are zeroed out. This operator is useful for excising known periodic interferers (e.g., p-cal tones from a neighboring station) that recur at regular frequency intervals.

Control File Trigger

Keyword: notch_comb
Category: flagging
Priority: 4.5

Parameters for `notch_comb`
Parameter	Type	Description
offset	real	Frequency offset (in MHz) at which the first notch center is placed. Defaults to 0.
period	real	Repetition period (in MHz) between consecutive notch centers. Must be positive.
width	real	Width (in MHz) of each individual notch. Must be positive and less than the period.

The builder (MHO_NotchCombBuilder) silently takes the absolute value of offset, period, and width (so negative inputs are accepted but treated as their positive equivalent), and separately rejects (with an error) any configuration where width exceeds period. The builder retrieves both the visibility and weight containers from the container store and configures the operator with all three parameters.

Input Data

This operator acts on the visibility_type container and simultaneously modifies the weight_type container (supplied via SetWeights).

Algorithm

MHO_NotchComb has no Initialize method; all work occurs in ExecuteInPlace.

Execution (``ExecuteInPlace``):

If either period or width is non-positive, the operator is a no-op and returns immediately.
Retrieve the channel axis and frequency axis from the visibility container.
Iterate over every frequency channel:
1. Retrieve the channel’s sky frequency, bandwidth label, and net_sideband label (U for upper sideband, L for lower sideband).
2. Compute the channel’s lower and upper frequency limits using DetermineChannelFrequencyLimits:
  
  \[\begin{split}[f_{\rm low}, f_{\rm high}] = \begin{cases} [f_{\rm sky},\ f_{\rm sky} + B] & \text{USB} \\ [f_{\rm sky} - B,\ f_{\rm sky}] & \text{LSB} \end{cases}\end{split}\]
  
  where \(f_{\rm sky}\) is the sky frequency and \(B\) is the bandwidth.
3. Determine which notch centers fall within (or overlap) the channel’s frequency span. A notch center is defined as:
  
  \[f_{\rm notch}(n) = f_{\rm offset} + n \cdot P\]
  
  where \(f_{\rm offset}\) is the notch offset, \(P\) is the period, and \(n\) is an integer. The range of \(n\) values is computed as:
  
  \[\begin{split}\begin{aligned} n_{\rm lower} &= \left\lfloor \frac{f_{\rm low} - f_{\rm offset}}{P} \right\rfloor \\ n_{\rm upper} &= \left\lceil \frac{f_{\rm high} - f_{\rm offset}}{P} \right\rceil \end{aligned}\end{split}\]
  
  The floor/ceil are chosen so that notches outside the nominal channel range but overlapping due to finite notch width are still captured.
4. For each integer \(m = 0, \dots, n_{\rm upper} - n_{\rm lower} - 1\):
  1. Compute the notch center: \(f_{\rm notch} = f_{\rm offset} + (n_{\rm lower} + m) \cdot P\).
  2. Compute the notch boundaries: \([f_{\rm notch} - W/2,\ f_{\rm notch} + W/2]\) where \(W\) is the notch width.
  3. Use FindIntersection to check whether the notch interval overlaps the channel interval.
  4. If there is overlap, iterate over all spectral points within the channel. For each spectral point, compute the absolute frequency:
    
    \[f_{\rm sp} = f_{\rm sky} + s_b \cdot \Delta f_{\rm sp}\]
    
    where \(s_b = +1\) for USB and \(s_b = -1\) for LSB, and \(\Delta f_{\rm sp}\) is the frequency-axis value for that spectral point.
  5. If \(f_{\rm sp}\) falls within the notch boundaries, zero out the visibility slice for that spectral point across all polarization products and accumulation periods, and increment a counter.
5. After all notches for the channel are processed, compute the used bandwidth fraction:
  
  \[\text{frac} = \frac{N_{\rm freq} - N_{\rm zeroed}}{N_{\rm freq}}\]
  
  and the rescaling factor:
  
  \[\begin{split}\text{factor} = \begin{cases} 1/\text{frac} & \text{frac} > 0 \\ 0 & \text{otherwise} \end{cases}\end{split}\]
6. Multiply the weight slice for the channel by the rescaling factor.
7. Store the metadata keys used_bandwidth_fraction and rescaling_factor on the channel axis.

Effect on Data

For each channel, spectral points whose absolute frequency falls within any notch interval are zeroed across all polarization products and accumulation periods. The weight container is rescaled per channel: each channel’s weights are multiplied by 1/frac where frac is the fraction of spectral points retained. Two metadata keys are recorded on the channel axis for every channel: used_bandwidth_fraction (the fraction of spectral points not zeroed) and rescaling_factor (the inverse of that fraction). This weight rescaling compensates approximately for the reduced effective bandwidth.