# RayleighMonitor : A Time-Frequency Gaussianity Monitor for the DMT

RayleighMonitor is a DMT monitor which produces a frequency-dependent measure of the non-Gaussianity of data from selected channels.

## Concept

The idea behind RayleighMonitor is to use the variations in the noise power on short timescales to learn about the statistics of the noise. Consider a string of data x(t) of duration T. The power spectrum is calculated by dividing the data into N equal segments x_i(t) and averaging the square of their Fourier transforms X_i(f):

This averaging loses information about the power on timescales less than T. Some of this information can be retained by examining the standard deviation of the |X_i(f)|^2. Define the Rayleigh statistic R(f) as the dimensionless ratio

One can show that if x(t) is Gaussian-distributed, the expectation value of R(f) is unity for all frequencies. This provides a 'white' consistency test for Gaussianity:

The Rayleigh statistic at each frequency thus measures the variability of the power on time scales of T/N to T relative to Gaussian noise. A Rayleigh statistic significantly above unity indicates that the power of the dominant noise is more variable than for a Gaussian (``glitchy'' data), while ratios significantly below unity indicate the dominant noise source at that frequency is coherent (such as power lines or violin modes):

The RayleighMonitor computes this Rayleigh statistic for the desired channel and produces scrolling time-frequency spectrograms and ``Rayleighgrams''.

 This document provides general information about RayleighMonitor. Detailed instructions for running RayleighMonitor in the LIGO control rooms have been written by Butler, Matone, Riles, and Shawhan (thanks). See also the RayleighMonitor tutorial for further guidance.

## Starting RayleighMonitor

The Rayleigh monitor is run with the command

`          RayleighMonitor <optional arguments>`
The available options are listed below; they can be invoked in any order. Options in green are on by default.
```  -batch           Run in batch mode.  STRONGLY RECOMMENDED.  (S5 version
of RayleighMonitor is only stable in -batch mode.)  No
GUI front-end and plots are non-interactive.  A properly
formatted configuration file named RMconfig.txt must
already exist in the current directory.

-canvas_height   Specify height of each plot in pixels.

-canvas_width    Specify width of each plot in pixels.

-fast            ON BY DEFAULT; disable with -slow option.
Use special code for fast scrolling plot updates.
This option is useful when two-dimensional graphical
output is slow, such as when running RayleighMonitor
remotely or at the LIGO sites.  WARNING: Only stable
when used with -batch option, in which case the
plots are non-interactive.  Also, the -record, -skip
options are not available in this mode.  Recommend
using the -fixedrange option in this mode.

-fixedrange      ON BY DEFAULT; disable with the -nofixedrange option.
Fix the range of the Rayleigh and PSD plots instead
of allowing the ranges to 'float' to follow the data.
Recommended for -fast mode, in which the monitor is
unable to update the range scale.  Rayleighgram
ranges are fixed to [0.3,3.0], while spectrogram ranges
are fixed to a factor of 3 below and above the minimum
and maximum values in the first PSD calculated.

-greyscale       Use greyscale rather than color for plots.

-h, --help       Print usage information and exit.

-local           Local mode:  All output files are placed in the
the current directory.  By default, all output is
diverted to the directory specified by the environment
variable \$DMTHTMLOUT (if set).

-logf            Set logscale in frequency for plots.

-nofixedrange    Range of plots floats with the range of the data
displayed.  Opposite of the -fixedrange option.

-screen          Divert update and error messages to the screen instead
of to the standard files RayleighMonitor_Log.html,
RayleighMonitor_Errors.html.  Useful for debugging.

-seek <time>     Do not start analyzing data until the specified GPS
<time> is reached in the data.  May be useful for
offline running.  Note that RayleighMonitor cannot
search into the past; if you specify a time in the
past while running on online data the monitor will
never start!

-simulation      Replace the data in each channel with simulated
Gaussian noise of unit amplitude.

-skip            Update time-frequency plots only every tenth timestep
instead of every timestep; may improve speed.  Not
available in -fast mode.

-slow            Not available in S5.
Use plotting method which allows for plotting of arbitrary
numbers of channels with interactive plots.  Very nice if
you have speedy graphics hardware; terribly slow otherwise.
Opposite of the -fast option.\n"

-version         Print usage information and exit.

--version        Print usage information and exit.

-whiten <N> <scale>  Approximate whitening of PSD by dividing by average of
the first <N> PSDs measured.  Reset scale of PSD plot to
[1/<scale>,<scale>].  Only works with -fast option.  Note
that first <N> PSD plots will not display properly.
```

When started a graphical user interface (GUI) is created through which the user can configure, run, pause, or exit the monitor. If the -batch option is selected this GUI is not available; the monitor looks for a configuration file named RMconfig.txt (see below) and, if found, executes using this configuration information.

## Configuring RayleighMonitor

The RayleighMonitor Configuration window allows you to select the channel and parameters used by the monitor.

• ### Parameter Selection:

The basic configurable parameters are:
```     Stride:  Length of each data segment to be Fourier-transformed,
in seconds.  Note that frequency resolution = Stride^{-1}.
WARNING:  The decimal part of Stride must be an integer
multiple of a power of 2 (eg, 0.25, 0.375, etc.).

Number of Averages (N):  Number of data segments of length Stride to
be used in calculating the average and standard deviation for
the power spectrum and Rayleigh statistic.  WARNING: Must
have N > 1.

Maximum Number of Strides:  Maximum number of times to calculate the
power spectrum and Rayleigh statistic before exiting.
```
RayleighMonitor also detrends the data and uses a Hanning window in computing the Fourier transform.
• ### Channel Selection:

The current version of RayleighMontior (6.2) is designed to run on a single channel at a time. Click on the down arrow under 'Channel' to see a clickable list of available channels and their sampling rates, or type the name of the desired channel directly into the box. Click the 'Active' box to include the channel; otherwise the selection is ignored. A restricted frequency range may also be specified.
• ### All Done?

When ready, click the 'Set Parameters' button to pass the configuration to the monitor, and then 'Close Window' to return to the main dialog.   'Retrieve Last Parameters' recalls the last configuration entered.