Browse Source

Add first version of documentation.

master
Bob Eldering 6 months ago
parent
commit
2b57ba2b2b
10 changed files with 333 additions and 0 deletions
  1. +174
    -0
      README.md
  2. BIN
      README.pdf
  3. +159
    -0
      doc/antab_editor.tex
  4. BIN
      doc/interpolate.png
  5. BIN
      doc/overview.png
  6. BIN
      doc/poly.png
  7. BIN
      doc/removed.png
  8. BIN
      doc/selection.png
  9. BIN
      doc/station.png
  10. BIN
      doc/time-selection.png

+ 174
- 0
README.md View File

@@ -0,0 +1,174 @@
Introduction
============

Antab editor is a program to help identify and fix problems with ANTAB
files generated by stations. This document will walk you through the
basic uses of antab editor.

How to start
============

Antab editor is installed in a conda environment for user pipe on the
archive machine, jop83. To activate this environment in a bash shell use
these commands:

/home/pipe> bash
pipe@jop83:~> source /jop83_0/pipe/in/miniconda3/bin/activate antab

Antab editor will look for its input files in the current directory. So
go to the directory with the stations' ANTAB files and start the program
from there. For example:

(antab) pipe@jop83:~> cd $IN/marcote/n20c2
(antab) pipe@jop83:/jop83_0/pipe/in/marcote/n20c2> antab_editor.py

Input and output files
======================

By default, antab editor will get the experiment name from the current
directory, but it can also be given as a command line argument. See
`antab_editor.py -h` for all command line arguments. The first input
file read will be the VEX file, antab editor will look in the current
directory for the file named `<experiment>.vix`.

On the first start-up of antab editor for an experiment, it will read in
all FITS files for that experiment and save the relevant data in the
file `fits_cache.editor`. This might take a few minutes, but the next
time you start antab editor, the cache file will be used, which is much
faster.

The final files read are the ANTAB files, for each station in the VEX
file, antab editor will look for the ANTAB file in the current directory
with the file name `<experiment><station>.antabfs`. However, any
intermediate progress made on editing the ANTAB files will be saved in
the file `<experiment><station>.editor`. If this file exists, it will be
read instead of the `.antabfs` file. So if you want to reset any editing
on the ANTAB file for a particular station, just remove the
corresponding `.editor` file.

The final result of antab editor will be the ANTAB file with all
stations in it, this will be saved to\
`<experiment>.antab`.

The GUI
=======

Figure [1](#fig:overview){reference-type="ref" reference="fig:overview"}
shows the initial window.

![Initial window](overview.png){#fig:overview width="70%"}

Note the tabs at the top of the window: Overview, Polys and one tab for
each station. These tabs will be discussed in reversed order below.

Station
-------

![Station tab](station.png){#fig:station width="70%"}

The station tab has a plot of the ANTAB values on the left and on the
right three section, see Figure [2](#fig:station){reference-type="ref"
reference="fig:station"}. The top section shows the ANTAB header and
makes it available for editing. The bottom shows the ANTAB values in a
table. The middle section gives generic options to edit the ANTAB
values.

The plot has all the default toolbar buttons of a matplotlib plot to
allow zooming, panning, etc. It has one extra button, represented by the
scissors, which is selected by default. When this tool is selected, you
can drag an area in the plot using the left mouse button to mark the
values to be deleted, see Figure [3](#fig:select){reference-type="ref"
reference="fig:select"}.

![Marking points to blank](selection.png){#fig:select width="70%"}

Pressing the delete key, when you are satisfied with the selection, will
blank all values in the selected area. This will be reflected in the
table, see Figure [4](#fig:remove){reference-type="ref"
reference="fig:remove"}.

![After pressing delete](removed.png){#fig:remove width="70%"}

Note the legend immediately right of the plot, clicking a channel in
this legend will hide/show the selected subband in the plot. This
selection will also affect which values are blanked when the scissors
tool is used.

After blanking points, you generally want to insert new values. This is
where the "Edit" section on the middle right of the window comes into
play. The top row of that section allows you to fill in missing values
(or just replace all values) for certain columns. The methods available
to do so are interpolation, using the nominal values or copying from
another column. The next row allows you to create new timestamps for
ANTAB values (which will be blank initially). For example, in Figure
[5](#fig:interpolate){reference-type="ref" reference="fig:interpolate"},
a timestamp was added every 15 seconds, with the new values filled using
interpolation.

![Interpolating every 15 seconds](interpolate.png){#fig:interpolate
width="70%"}

It is also possible to do editing directly in the table. For example you
can select multiple time rows (see Figure
[6](#fig:time-select){reference-type="ref" reference="fig:time-select"})
and press the delete key to blank these values.

![Selecting multiple time rows](time-selection.png){#fig:time-select
width="70%"}

To permanently delete these timestamps, click the "Remove empty
timestamps" button in the "Edit" section.

The subbands as shown in the plot and the columns of the table are the
subbands of the correlator data. The subbands given in the station's
ANTAB file are translated to correlator subbands using the VEX and FITS
files. The original subbands as given by the station are still available
in the "Header" section, in the "Index" field. It is possible to edit
the "Index" field to have antab editor re-map station subbands to
correlator subband. However, if you want to do this, it is usually best
to do so at the start of the editing process. After editing, re-mapping
the subbands might not be possible anymore.

The "Save" button in the "Edit" section will save the current values to
the `<experiment><station>.editor` file, for just this station.

 \

Polys
=====

The "Polys" tab will display each station's gain polynomial in plots,
see Figure [7](#fig:poly){reference-type="ref" reference="fig:poly"}.

![The polys tab](poly.png){#fig:poly width="70%"}

These plots reflect the "Poly" as displayed in the station tab under the
"Header" section, evaluated for an elevation from 0 to 90 degrees.
Editing the "Poly" values in the station tab will update the plot in the
"Polys" tab.

Overview
========

With the last tab to discuss, we return to the "Overview" tab, see
Figure [1](#fig:overview){reference-type="ref"
reference="fig:overview"}. At the top of this tab are two buttons. The
"Generate ANTAB" button will generate the `<experiment>.antab` file from
the current values in all the station tabs. The "Save all" button will
act like pushing the "Save" button in all station tabs, saving all the
`<experiment><station>.editor` files.

The table below those buttons is used to warn for potential problems
with a station: a red box signals such a problem, a green box signals no
problem. The categories are:

- Station name: check whether the station name in the ANTAB header is
equal to the station name in the ANTAB file name.

- Frequency range: check whether the frequency range in the ANTAB
header includes all correlated frequencies for that station.

- Time stamps: check whether all scan which include the station have
at least one time stamp with ANTAB values in it.

- Empty values: check whether there are any blank ANTAB values left.

BIN
README.pdf View File


+ 159
- 0
doc/antab_editor.tex View File

@@ -0,0 +1,159 @@
\documentclass[10pt,a4paper]{article}
\usepackage[margin=0.5in]{geometry}
\usepackage{bookman}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{amsfonts}
\usepackage{graphicx}
\usepackage{url}
\usepackage{hyperref}
\setlength\parskip{\medskipamount}
\setlength\parindent{0pt}
\usepackage{graphicx}
\thispagestyle{empty}
\title{Antab Editor}
\author{Bob Eldering}
\begin{document}
\maketitle

\section{Introduction}
Antab editor is a program to help identify and fix problems with ANTAB files generated by stations.
This document will walk you through the basic uses of antab editor.

\section{How to start}
Antab editor is installed in a conda environment for user pipe on the archive machine, jop83.
To activate this environment in a bash shell use these commands:

\begin{verbatim}
/home/pipe> bash
pipe@jop83:~> source /jop83_0/pipe/in/miniconda3/bin/activate antab
\end{verbatim}

Antab editor will look for its input files in the current directory.
So go to the directory with the stations' ANTAB files and start the program from there. For example:

\begin{verbatim}
(antab) pipe@jop83:~> cd $IN/marcote/n20c2
(antab) pipe@jop83:/jop83_0/pipe/in/marcote/n20c2> antab_editor.py
\end{verbatim}

\section{Input and output files}
By default, antab editor will get the experiment name from the current directory, but it can also be given as a command line argument.
See \verb!antab_editor.py -h! for all command line arguments.
The first input file read will be the VEX file, antab editor will look in the current directory for the file named \verb!<experiment>.vix!.

On the first start-up of antab editor for an experiment, it will read in all FITS files for that experiment and save the relevant data in the file \verb!fits_cache.editor!.
This might take a few minutes, but the next time you start antab editor, the cache file will be used, which is much faster.

The final files read are the ANTAB files, for each station in the VEX file, antab editor will look for the ANTAB file in the current directory with the file name \verb!<experiment><station>.antabfs!.
However, any intermediate progress made on editing the ANTAB files will be saved in the file \verb!<experiment><station>.editor!.
If this file exists, it will be read instead of the \verb!.antabfs! file.
So if you want to reset any editing on the ANTAB file for a particular station, just remove the corresponding \verb!.editor! file.

The final result of antab editor will be the ANTAB file with all stations in it, this will be saved to \\
\verb!<experiment>.antab!.

\section{The GUI}
Figure \ref{fig:overview} shows the initial window.
\begin{figure}[h!]
\centering
\includegraphics[width=0.7\textwidth]{overview.png}
\caption{Initial window}
\label{fig:overview}
\end{figure}
Note the tabs at the top of the window: Overview, Polys and one tab for each station.
These tabs will be discussed in reversed order below.

\subsection{Station}
\begin{figure}[h!]
\centering
\includegraphics[width=0.7\textwidth]{station.png}
\caption{Station tab}
\label{fig:station}
\end{figure}
The station tab has a plot of the ANTAB values on the left and on the right three section, see Figure \ref{fig:station}. The top section shows the ANTAB header and makes it available for editing. The bottom shows the ANTAB values in a table. The middle section gives generic options to edit the ANTAB values.

The plot has all the default toolbar buttons of a matplotlib plot to allow zooming, panning, etc. It has one extra button, represented by the scissors, which is selected by default. When this tool is selected, you can drag an area in the plot using the left mouse button to mark the values to be deleted, see Figure \ref{fig:select}.
\begin{figure}[h!]
\centering
\includegraphics[width=0.7\textwidth]{selection.png}
\caption{Marking points to blank}
\label{fig:select}
\end{figure}
Pressing the delete key, when you are satisfied with the selection, will blank all values in the selected area.
This will be reflected in the table, see Figure \ref{fig:remove}.
\begin{figure}[h!]
\centering
\includegraphics[width=0.7\textwidth]{removed.png}
\caption{After pressing delete}
\label{fig:remove}
\end{figure}

Note the legend immediately right of the plot, clicking a channel in this legend will hide/show the selected subband in the plot.
This selection will also affect which values are blanked when the scissors tool is used.

After blanking points, you generally want to insert new values.
This is where the ``Edit'' section on the middle right of the window comes into play.
The top row of that section allows you to fill in missing values (or just replace all values) for certain columns.
The methods available to do so are interpolation, using the nominal values or copying from another column.
The next row allows you to create new timestamps for ANTAB values (which will be blank initially).
For example, in Figure \ref{fig:interpolate}, a timestamp was added every 15 seconds, with the new values filled using interpolation.
\begin{figure}[h!]
\centering
\includegraphics[width=0.7\textwidth]{interpolate.png}
\caption{Interpolating every 15 seconds}
\label{fig:interpolate}
\end{figure}

It is also possible to do editing directly in the table.
For example you can select multiple time rows (see Figure \ref{fig:time-select}) and press the delete key to blank these values.
\begin{figure}[h!]
\centering
\includegraphics[width=0.7\textwidth]{time-selection.png}
\caption{Selecting multiple time rows}
\label{fig:time-select}
\end{figure}
To permanently delete these timestamps, click the ``Remove empty timestamps'' button in the ``Edit'' section.

The subbands as shown in the plot and the columns of the table are the subbands of the correlator data.
The subbands given in the station's ANTAB file are translated to correlator subbands using the VEX and FITS files.
The original subbands as given by the station are still available in the ``Header'' section, in the ``Index'' field.
It is possible to edit the ``Index'' field to have antab editor re-map station subbands to correlator subband.
However, if you want to do this, it is usually best to do so at the start of the editing process.
After editing, re-mapping the subbands might not be possible anymore.

The ``Save'' button in the ``Edit'' section will save the current values to the \verb!<experiment><station>.editor! file, for just this station.

\newpage
~\\
\newpage

\section{Polys}
The ``Polys'' tab will display each station's gain polynomial in plots, see Figure \ref{fig:poly}.
\begin{figure}[h!]
\centering
\includegraphics[width=0.7\textwidth]{poly.png}
\caption{The polys tab}
\label{fig:poly}
\end{figure}

These plots reflect the ``Poly'' as displayed in the station tab under the ``Header'' section, evaluated for an elevation from 0 to 90 degrees.
Editing the ``Poly'' values in the station tab will update the plot in the ``Polys'' tab.

\section{Overview}

With the last tab to discuss, we return to the ``Overview'' tab, see Figure \ref{fig:overview}.
At the top of this tab are two buttons.
The ``Generate ANTAB'' button will generate the \verb!<experiment>.antab! file from the current values in all the station tabs.
The ``Save all'' button will act like pushing the ``Save'' button in all station tabs, saving all the \verb!<experiment><station>.editor! files.

The table below those buttons is used to warn for potential problems with a station: a red box signals such a problem, a green box signals no problem.
The categories are:
\begin{itemize}
\item Station name: check whether the station name in the ANTAB header is equal to the station name in the ANTAB file name.
\item Frequency range: check whether the frequency range in the ANTAB header includes all correlated frequencies for that station.
\item Time stamps: check whether all scan which include the station have at least one time stamp with ANTAB values in it.
\item Empty values: check whether there are any blank ANTAB values left.
\end{itemize}

\end{document}

BIN
doc/interpolate.png View File

Before After
Width: 1154  |  Height: 738  |  Size: 126 KiB

BIN
doc/overview.png View File

Before After
Width: 1154  |  Height: 738  |  Size: 31 KiB

BIN
doc/poly.png View File

Before After
Width: 1154  |  Height: 738  |  Size: 73 KiB

BIN
doc/removed.png View File

Before After
Width: 1154  |  Height: 738  |  Size: 122 KiB

BIN
doc/selection.png View File

Before After
Width: 1154  |  Height: 738  |  Size: 156 KiB

BIN
doc/station.png View File

Before After
Width: 1154  |  Height: 738  |  Size: 154 KiB

BIN
doc/time-selection.png View File

Before After
Width: 1154  |  Height: 738  |  Size: 126 KiB

Loading…
Cancel
Save