WDM Time-Frequency Transform¶
This guide explains how pycWB converts each conditioned detector strain into Wilson-Daubechies-Meyer (WDM) time-frequency maps at several resolutions. It also covers how the time-delay filters and the cross-talk (XTalk) catalog are prepared, and which parameters control them.
Why this matters¶
All later stages work on WDM pixels: pixel selection, clustering, the
likelihood sky scan and waveform reconstruction. l_low … l_high sets
the available pixel shapes, from short and broadband to long and narrowband,
and the WDM filter parameters must match the XTalk catalog. For a standard
search keep the defaults; change the levels only with a catalog that covers them.
The WDM Basis¶
The WDM transform (Necula et al., J. Phys.: Conf. Ser. 363 (2012) 012032)
tiles the time-frequency plane evenly. With \(M\) layers, \(N\)
samples at rate \(R\) become a complex array of \(M+1\) frequency
layers (\(m = 0\) at DC to \(m = M\) at \(R/2\), layer \(m\)
centred at \(m\,\Delta f\)) by \(\lceil N/M \rceil\) time bins. The
real part holds the 0° (00) amplitude, the imaginary part the 90° (90)
quadrature. Every pixel has the same area:
Resolution levels¶
pycWB sets \(R\) to the analysis rate rateANA (fResample if set,
otherwise inRate, divided by \(2^{\text{levelR}}\); see
Data Conditioning). Level \(l\) uses \(M_l = 2^l\) layers:
\(r_l\) is the pixel rate used by the clustering metric. The defaults
(inRate 16384, levelR 2, so rateANA = 4096 Hz; levels 3 … 8) give:
Level |
M |
Δf [Hz] |
Δt [ms] |
rate [Hz] |
|---|---|---|---|---|
3 |
8 |
256 |
1.953 |
512 |
4 |
16 |
128 |
3.906 |
256 |
5 |
32 |
64 |
7.8125 |
128 |
6 |
64 |
32 |
15.625 |
64 |
7 |
128 |
16 |
31.25 |
32 |
8 |
256 |
8 |
62.5 |
16 |
WDM filter¶
The basis uses a Meyer window with transition parameter \(K = M\) and
beta-function order WDM_beta_order. The one-sided filter length
\(m_H\) is the smallest \(N\) with \(N-1\) a multiple of
\(2M\), \(N \ge 6M+1\), and truncated-tail energy below
\(10^{-p}\), \(p\) = WDM_precision. The defaults (6, 10) give
\(m_H = 12M+1\) taps (0.75 s at level 8, rateANA = 4096 Hz). The filter
must fit in the padding: \(m_H/\text{rateANA} \le\) segEdge.
Multi-Resolution Analysis¶
pycWB transforms the same whitened strain independently at every level from
l_high down to l_low (nRES = l_high − l_low + 1; this
descending order is config.WDM_level). A short broadband signal is compact
at low \(l\), a long narrowband one at high \(l\). Pixel selection and
single-resolution clustering run per level; superclustering merges across
levels (see Clustering Algorithm). Bases at different levels are not
orthogonal, so the same energy appears in several maps; the XTalk catalog
records these overlaps (see XTalk (MRA) Catalog).
Time-index parity. WDM basis functions alternate with time-index parity,
and the XTalk catalog is indexed by it, so shifts must keep parity at every
level. check_lagStep() requires
lagStep, segEdge and segMLS to be multiples of \(2/r_{\min}\),
\(r_{\min} = \text{rateANA}/2^{l_{\rm high}}\) (0.125 s by default); it
tests that \(\lfloor x\,r_{\min} \rfloor\) is even. Job construction
shortens a job by 1 s if its length breaks parity (see Job Control).
Time-Delay Filters¶
Likelihood needs pixel amplitudes at sky-dependent detector delays. WDM gives
them from the map itself, without re-transforming shifted data (Necula et al.
2012, Sec. 4). WDM.set_td_filter(TDSize, upTDF) precomputes the tables:
covering \(|\tau| \le \Delta t\); longer delays become an even number of
whole time bins plus an in-table remainder. The delayed amplitude of pixel
\((n, m)\) combines time bins \(n-\text{TDSize} \dots n+\text{TDSize}\)
of layers \(m-1, m, m+1\); \(M\) must be even. segEdge must be at least
\(\lfloor 1.5\,\text{TDSize}/r_l + 0.5 \rfloor\) s to avoid distorted
border pixels. The delays extracted per pixel, \(K_{td}\), are set in
supercluster setup (see Clustering Algorithm, “Time-Delay
Precomputation”).
XTalk (MRA) Catalog¶
The catalog is wdmXTalk under filter_dir (full path: derived key
MRAcatalog). For each pair of resolutions, including a resolution with
itself, it is indexed by the frequency layer and time parity of the first
pixel. Each entry is an overlapping pixel of the second resolution: a relative
index plus four overlaps (00·00, 00·90, 90·00, 90·90). pycWB only reads
catalogs; the cWB C++ WDMOverlap builder (cwb-core/) stores overlaps
above a threshold (default 0.01), so the table is sparse. Pixels name their
resolution by \(M+1\) (the layers field, cWB convention).
The header stores nRes and the layer counts; a tagged catalog also
stores the beta order, precision and \(K\) used to build it. At
configuration load, check_MRA_catalog()
requires every level’s \(2^l\) in the layer list, and a tagged catalog
overwrites WDM_beta_order and WDM_precision (an untagged one is not
checked against them).
The default catalog (layers 8 … 256, per its name) matches levels 3 … 8. A
missing file is downloaded by check_xtalk_file()
if its name is in the PycWB xtalk-data repository; otherwise
FileNotFoundError. pycwb.modules.xtalk.type.XTalk.load() parses a
.bin/.xbin file and writes a .npz with the same stem beside it,
which later loads read instead.
Later, the sub-network cut uses the catalog in its MRA step (see
Clustering Algorithm), and likelihood uses the per-cluster overlap lists
from get_xtalk_pixels() for
cross-talk-corrected data and null energies and to normalise the packet
amplitudes stored on the cluster pixels (see Likelihood). Waveform
synthesis reads those amplitudes, not the catalog itself.
Implementation¶
pycwb.modules.coherence_native.setup.setup_coherence()buildswdm_wavelet.wdm.WDM(M, K=M, beta_order, precision)(companion packagewdm-wavelet) per level and transforms all detectors in one JAX call,pycwb.modules.coherence_native.tf_batch_generation.batch_t2w_detectors()(per-detector fallback on failure), intopycwb.types.time_frequency_map.TimeFrequencyMapobjects.pycwb.utils.td_vector_batch.build_td_inputs_cache()builds a second WDM for every level, callsset_td_filter(TDSize, upTDF)and transforms each detector’s strain again. It stores zero-padded float32 00/90 planes and the filter tables aspycwb.types.td_batch_inputs.TDBatchInputs.pycwb.modules.xtalk.type.XTalkandpycwb.modules.xtalk.monster.read_catalog_metadata()read the catalog;pycwb.config.config.Config.add_derived_key()derivesrateANA,nRES,WDM_level,TDRateandMRAcatalog._create_wdm_set_python(pycwb.modules.reconstruction.getMRAwaveform) builds the filters likelihood uses for waveform synthesis and raisesValueErrorif asegEdgelimit is violated;pycwb.modules.multi_resolution_wdm.wdm.create_wdm_for_level()does the same for the ROOT modules withpycwb.types.wdm.WDM.
Execution-profile flags (tiled_wdm, wdm_*) change how the transform
runs, not the analysis (see Execution and memory options).
cWB-2G correspondence¶
This is the “WDM and MRA setup” row of the Pipeline Lifecycle table:
WDM<double>(layers, layers, WDM_beta_order, WDM_precision)per level →wdm_wavelet.wdm.WDM(M, M, ...)(pycwb.types.wdm.WDMon ROOT).WDM::setTDFilter(TDSize, upTDF)→set_td_filter(TDSize, upTDF).network::setMRAcatalog(MRAcatalog)(monstercatalog) →load()ofconfig.MRAcatalog.
Configuration¶
Defaults come from pycwb.constants.user_parameters_schema.
Parameter |
Default |
Meaning |
|---|---|---|
|
3 |
Lowest level (\(M = 2^{l_{\rm low}}\), finest time resolution) |
|
8 |
Highest level (\(M = 2^{l_{\rm high}}\), finest frequency resolution) |
|
6 |
Beta-function order of the Meyer window (overridden by a tagged catalog) |
|
10 |
Filter truncation precision, \(10^{-p}\) (overridden by a tagged catalog) |
|
12 (max 20) |
Half-width of the time-delay filters, in time bins |
|
4 |
Delay upsampling factor; |
|
|
XTalk catalog path relative to |
|
|
Catalog directory; if empty, |
|
8.0 |
Segment padding [s]; must contain the WDM and TD filter lengths |
rateANA, nRES, WDM_level, TDRate and MRAcatalog are
derived; do not set them (see User Parameters).
Output¶
TF maps: one complex \((M+1) \times n_{\rm time}\)
TimeFrequencyMapper detector and level (0 to \(R/2\); band limits andsegEdgeare metadata).setup_coherencepasses them straight to pixel selection (see Clustering Algorithm, “Pixel Selection”) and returns per-level dicts (level,layers= \(M\),rate= \(r_l\),tf_maps,Eo) forcoherence_single_lag.TD-inputs cache:
{M: [TDBatchInputs per detector]}, also keyed by \(M+1\). Supercluster uses it to fill delayed amplitudes.XTalk object: passed to the sub-network cut and to likelihood.
Troubleshoot transform setup¶
Resolution log: each level logs
rate(hz),layers,df(hz)anddt(ms); compare with the table for yourrateANA.Catalog match:
analysis layers do not match the MRA catalog: a level is missing from the catalog (see Troubleshooting).Filter parameters: if you change
WDM_beta_orderorWDM_precision, use a catalog built with the same values. A tagged catalog takes precedence over YAML; the log then showsupdating beta order and precision from MRA catalog.Edge length:
Filter length must be <= segEdgeorsegEdge must be > 1.5x the length for time delay amplitudesmeanssegEdgeis too short forl_highorTDSize.Parity:
not a multple of 2*max_time_resolution(spelled so in the code) names the offendinglagStep,segEdgeorsegMLS.Catalog cache: if you replace a
.bincatalog, delete the.npzbeside it; the.npzis loaded in preference.
See also: Pipeline Lifecycle · Data Conditioning · Clustering Algorithm
Next: Clustering Algorithm — pixel selection, clustering and superclustering