plot.md

plot

This document describes the bash helper utility plot, which provides shorter syntax for calling the plot.py utility for plotting sidmon5 data. plot.py generates time plots of a variety of polarization parameters of the transmitter signals in a sidmon5 file, and scatter plots of one or more pairs of signals. The latter is particularly useful for identifying populations of points (segments of time) representing stages of a process a transmitter signal (or the ionosphere) is undergoing. Consult the last two documents for more detailed information on what plot.py is doing or if you prefer finer control of plot.py. In the mean time this document provides a quick description of the use of the plot helper for generating plots.

Because the data contain the four Stokes parameters (I, Q, U, and V) for each transmitter, there are capabilities for displaying additional information Stokes parameters provide, such as intensity and other Stokes parameters, linear polarization, total polarization, etc.

The Stokes parameters tend to scale identically, which is not particularly interesting. So one often looks for variation of the scaling when a SID occurs, such as when the direction, X-Y phase, or circular polarization changes. plot.py has the flexibility to display such variations. It can also generate scatter plots of one or more pairs of parameters. In addition, plotted parameters can be normaized to Stokes I using the --normalize switch, which also highlights variations of scaling.

Enter the program name without arguments to print a short usage description.

    $ plot

The basic syntax has the command name, subcommand, list of files, list of signals, and then other options. The most basic subcommand is select for an arbitrary selection of signals.

    $ plot select 20250515towne16 NPMi

This simply generates a time plot of NPM Stokes I. Signal types can also be

• i, q, u, and v for Stokes I, Q, U, and V respectively,
• l for total linear polarization (sqrt(Q²+U²),
• t for total polarization (sqrt(Q²+U²+V²),
• a, b, and th for polarization-ellipse parameters (major and monor axes and orientation), and
• x, y, and p for X and Y intensities and relative phase.

These signal types can also be subcommands, for example,

    $ plot i 20250515towne16 NPM,NAA,NML

where Stokes I of each transmitter is plotted.

The station subcommand plots the four Stokes parameters given a single transmitter.

    $ plot station 20250515towne16 NPM

A list of file names can be given. Filenames ordinarily have the form yyyymmdd<hostname>.csv, but the extension must be omitted. To not have to enter the host name repetitively, use the --host switch. A path part of the file name is not given because plot finds the files in the path in the file /etc/sidmon5.net/data_location.

    $ plot <subcommand> <filename>,...  <transmitter/signallist> --host <hostname>
    $ plot station 20250614,20250614 NPM --host=towne24

If the data files have extension other than .csv, use the -ext switch, e.g.,

    $ plot station 20250614towne24 NPM -ext=txt

A fixed scale of the y axis is set using the --yrange switch

    $ plot select 20250515towne16 NLKv,NMLv --yrange=-100,100

A leading 'm' is necessary when there is a leading minus sign and the '=' syntax is not used.

A fixed time-axis range can similarly be given with the --xrange switch, where each time limit has the form yyyy-mm-ddTHH:MM:SS. Yes, this is clumsy. The second parameter is optional, defaulting to the end of the UT day.

By default, the data in the plot are decimated (with averaging) by the factor 19 so that there are not so many points plotted and each point represents a longer integration time. This factor can be changed with the -d switch. For example, to plot at the full temporal resolution, used -d1.

The --normalize switch scales the plotted data so that

• Stokes I has a maximum of 1,
• Stokes Q, U, V, linear polarization, and total polarization are divided by Stokes I, and
• polarization-ellipse major and mintor axes, and X and Y intensities are divided by the square root of Stokes I.

Flagging is discussed elsewhere.

Annotation for events reports and GOES x-ray intensity

There are a couple sources for x-ray data useful for annotating plot.py time graphs.

The first is SWPC, which archives daily events reports containing information on x-ray bursts, as well as other events, at ftp.swpc.noaa.gov. plot has a convenience utility for downloading these files (via utils.py).

    $ plot events yyyymmdd
    $ plot events 20250522  # or
    $ python/utils.py events 20250522

When a file for the date is available, plot will annotate time plots with start, max, and stop times in the spirit of the original supersid_plot.py.

The second is GOES x-ray intensity data. plot can download the raw GOES 18 data files, but there is not yet a utility for reducing them to a form used by plot.py. So this is a work in progress. For reference, downloads are by

   $ plot goesdata yyyy mm dd

The files are placed in~/tmp.