User's guide of program Phase Doctor
Contents:
Overview
Program Phase_Doctor is an interactive graphical tool for investigation and
calibration of instrumental delays in a given geo-VLBI experiment.
Input information for Phase_Doctor is
- a pair of X- and S-band databases which are assumed to be in the
SOLVE databases catalogue system;
- log-files of all stations.
Phase_Doctor is for
- Examination of auxiliary quantities of VLBI observations:
- system temperatures;
- phase and amplitudes of phase calibration signals;
- residual phases fringe phase;
- cable calibration.
- Displaying various plots associated with these quantities;
- Fitting parameters of the model of some functions of these quantities;
- Computation of corrections to group and phase delays for instrumental
errors:
- correction for presence of spurious signals in phase
calibration signal.
putting these corrections to a calibration file which can be applied by
SOLVE in a user calibration mode.
- Estimation of station performance and quality of
- system temperature;
- phase calibration;
- residual fringe phases.
Loading the experiment
Usage: phase_doctor [-h] [-f <input_file>] [-d <experiment_id>]
[-v <verbosity_level>] [-w <web_dir>]
Options
- -h -- to show a short help message.
- -f -- specifies an input file with definitions of files
with data for Phase_Doctor
- -d -- an experiment identifier
- -v -- verbosity level
- 0 -- silent mode
- 1 -- normal verbosity [default]
- 2 -- eloquent mode
- 3,4 -- debugging modes
- -w -- directory name where hard-copies of plots and tables
will be put. Trailing symbol / should present in the
name if it is a name of a directory.
Phase_doctor requires log-files for all stations and a pair of databases
for X- and S-band which are assumed to be already in the SOLVE catalogue
system. Input files are to be specified in the so-called definitions file
which is passed to a Phase_Doctor.
Format of a definitions file:
<Keyword> <value_1> [<value_2>]
Keyword is one of
- DATABASE: -- value_1 is a database name.
Dollar sign may be omitted.
- MK3: -- value_1 is directory name with MK3 correlator
output.
**not implemented**
- MK4: -- value_1 is directory name with MK4 correlator
output.
**not implemented**
- MON: -- value_1 file name of VLBI monitor file.
**not implemented**
- LOG: -- value_1 is a station name using exactly the same
syntax as in SOLVE, however blanks in station
name should replaced with ~ (decimal code 126);
value_2 is a log file name.
- * -- comment.
- # -- comment.
Example of a definitions file:
DATABASE: $99MAY18XA
*
LOG: ALGOPARK /diskB5/logs/ca062_log_algo
LOG: GILCREEK /diskB5/logs/ca062_log_gilc
LOG: MATERA /diskB5/logs/ca062_log_mate
LOG: MEDICINA /diskB5/logs/ca062_log_medi
LOG: HARTRAO /diskB5/logs/ca062_log_hart
LOG: NRAO85~3 /diskB5/logs/nrao85_3_log_hart
LOG: WESTFORD /diskB5/logs/ca062_log_west
If log file for some stations(s) is not available you can omit the line
in the definitions file for that station but then Phase_Doctor will not "see"
that station as if it didn't participate in the experiment.
An experiment file is created after processing the input definitions file.
An experiment identifier is a main part of the definition file name (without
path and extension). For example, if a definitions file has name
/geo/vlbi/phase/99MAY18XA.def then the experiment identifier would be 99MAY18XA
Phase_Doctor parses definitions file, then reads both databases, then
read and parses all log-files. The program writes down an intermediary file in
the directory with names specified in the variable PHD_DIR defined in the
../src/solve/gsfcb.i file. The name of the intermediary file has the same main
part as the definitions file but extension phd. Then Phase_Doctor displays the
first user menu.
The next call of Phase_Doctor for this experiment may be done either by
specifying a definitions file or by specifying an experiment identifier, f.e.
phase_doctor -f /geo/vlbi/phase/99MAY18XA.def
or
phase_doctor -d 99MAY18XA
or
phase_doctor -d 99MAY18XA.phd
The latter variant is executed much faster.
Graphic interface
Phase_Doctor uses graphic Multi_DiaGI
interface. Two kind of menus appear at the screen: purely command menus
and command-graphic menus. The menus of the first sort contain a set of
command yellow-brown boxes. The menu of the second type contains both a set
of command yellow-brown boxes in the right part of the screen and a set of
grey boxes with plots in the left part of the screen.
A yellow-brown command box contains a brown letter code in the right upper
corner of the box and the text of the command. A user can execute a command
either by hitting a key with the letter code using keyboard or by positioning
the cursor to the command box and hitting either the left or the middle mouse
button. All DiaGI commands can be applied to the expanded graphic box,
f.e. changing boundary box, printing and etc.
A grey graphic box can be expanded to the entire screen if user position
the cursor on the box and hit either the left or the middle mouse button.
Right/mouse and a keyboard key X always means exit the current menu level
and return to the previous level of menu.
Many plots have argument Time in hours. Time tag 0 corresponds to the nominal
start of the session (first value of lcode INTERVAL recorded in the database).
Many plots admits to have two types of bounding boxes for plots: global
and local. Global bounding box is a bounding box between minimal and maximal
values of parameters and arguments among all displayed plots. Local bounding
box is a bounding box between minimal and maximal values of parameters and
arguments for each plot individually.
A hard copy of graphic boxes can be obtained. Refer to the
Multi_DiaGI manual.
Normally each station measures system temperature before each scan and
records it in log-file. Phase_doctor parses log files: find a correspondence
between the index of the tsys arrays and a channels sequence, put the system
temperature to the correct slot and filters out false readings: it discards
system temperature values below 10K and higher than 900K as well as "values"
of system temperature $$$$$$$.
Option (T) Plots of system temperatures is invoked from the main
Phase_Doctor menu: the menu which has a title Phase_Doctor, its version and
the identifier of the database. No plots will be shown if the station didn't
record system temperature in log-file or some channels were dropped in fringing.
Plots of system temperature menu allows to build plots of
- (R) Raw system temperature versus time -- recorded values of
system temperature without any transformations except filtering out
values where Tsys were below 10K or higher 900K
or were in overflow. These plots are useful for checking presence
of RFI (radio interference).
- (Z) Zenith system temperature versus time. Recorded system
temperature is decomposed on
Tsys = To * A(t) * B(e) where
To is a constant for this session and this
station, A(t) is a function of time modeled by linear
spline, B(e) is a function of elevation modeled by linear
spline. Decomposition is performed by non-linear LSQ fitting.
Outliers (but not more than 20%) are rejected.
Plots of dependence of zenith system temperature on time are shown
for the elevation when system temperature is minimal. The blue
points are Tsys/( To * B(e) ) and the
red line is a model: = To * A(t)
Simultaneously the table of statistics of system temperature of
this station for each channel is generated. It is written in
the current Web_dir under name
sts_<station_name>.txt .
- (E) Dependence of system temperature on elevation angle is
computed by the same algorithm as dependence of zenith system
temperature versus time.
Plots of dependence of zenith system temperature on elevation
angle are shown for the moment of time when system temperature is
minimal. The blue points are
Tsys/( To * A(t) ) and the
red line is a model: = To * B(e)
Simultaneously the table of statistics of system temperature of
this station for each channel is generated. It is written in
the current Web_dir under name
sts_<station_name>.txt .
- (S) Change station menu allows to change the current station
and to build the plot for another station.
Analysis of phase-cal
Normally each station has a phase calibrating system. Phase-cal phases
and amplitudes for each channel for each scan are computed by a correlator and
are written into the database. However, if manual phase calibration was applied
during fringing then no information about measured phase-cal phase and phase-cal
amplitudes remains in the database for this station. If some channel(s) was
dropped during the final fringing then no information about phase-cal at that
channel at that station remains in the database. Boxes for phase-cal plots
for these channels will be empty.
Option (P) Plots of phase cal is invoked from the main
Phase_Doctor menu (the menu which has a title Phase_Doctor, its version and
the identifier of the database).
Plots of phase calmenu allows to build plots of
Phase clinic
Option (C) Phase clinic is invoked from the main
Phase_Doctor menu. It allows to run some procedures for evaluation of
phase and amplitude of spurious signals. Routines of computation of amplitudes
and phases of spurious signals at the specific station run under the control
of a so-called procedure file. Phase_doctor expects to find the procedure file
in the $PHD_DIR directory. The name of the procedure file is
<experiment_name>.prc , f.e. 00JAN10XH.prc .
Syntax of procedure file is described below.
The main Phase clinic menu supports commands:
- (E) Edit procedure file. If the procedure file
$PHD_DIR/<experiment_name>.prc doesn't exist a template
file is created. Then a text editor is called, and it allows to edit
the procedure file related to the experiment. The name of the
system-wide default editor is defined in the variable SOLVE_EDITOR
in ../src/solve/include/glbc4.i . User can override a
system wide default by setting an environment variable SOLVE_EDIT.
Refer to
solve_env.template for details.
You can edit existing procedure file by calling an editor outside
Phase_Doctor, moreover, it is more convenient. However, it is
recommended to use a command "Edit procedure file" when
the experiment is analyzed the first time in order to create
a correct template file. See below
a description of syntax of the procedure file.
- (V) Evaluate spurious signals in phase-cal. Amplitudes and
phases of the spurious signals at the current station which have
been defined in the procedure file are evaluated by using LSQ.
First, the model of system temperature is computed, then bad values
of system temperature are filtered out on the basis of that model.
Amplitude of phase-cal is calibrated for variations of system
temperature. Then amplitudes and phases of phase-cal are computed
by iterative LSQ. Finally, the table of the solution listing is put
in the current Web-directory under the name
spt_<station_name>.txt and the plots of phase-cal amplitude
versus phase-cal phase and the plots the model of phase-cal amplitude
dependence on its phase-cal phase due to spurious signals for
each channel are shown.
NB: Channels without system temperature are ignored and
and empty grey boxes will be shown in plots. If station didn't
record system temperature at all then the command evaluation of
spurious signals in phase-cal will do nothing.
Points of measured phase-cal amplitude are shown by green color.
A red line represents modeled phase-cal amplitudes.
This menus supports the following commands:
- (E) Edit procedure file
-- allows to invoke
an editor and edit the procedure file.
- (V) Evaluate spurious signals
-- reads
procedure file and evaluate spurious signals once
more. If user made changes in procedure file he/she
can wish to re-compute amplitudes and phases of
spurious signals.
- Toggle (R) Plot residual amplitudes /
(F) Plot full adjustments . If to hit
(R) then residuals after estimation will
be shown. Hitting (V) returns to a normal
mode which shows measured normalized phase-cal
amplitudes and a modeled phase-cal amplitudes.
- (L) Look at results
-- prints content of
the listing of the solution in text window.
Graphic window is iconized. Hit (Q) in
text window in order to return to Phase_Doctor.
- (S) Change station
-- invokes a menu where
user is able to select the next station. Then it
returns to the main menu of Phase Clinic.
- (W) Change web directory -- allows to change the
prefix which is prepended before the output files: tables and
plots which are created by a make-hardcopy function of DiaGI.
You can change the default prefix. NB: If you are going to
specify a directory name, you should use a trailing / symbol,
otherwise the file will not be put in the desired directory.
- (S) Change station -- invokes a menu where user is able
to select the station which becomes the new current station.
Format of a procedure file.
Procedure file describes operations to be performed under phases and
amplitudes at the channels at all stations.
Procedure file consists of records of variable length. Each record consist of
one or more words separated by one or more blanks. The first word is considered
as a keyword, other words are considered as values of the that keyword.
The order of records is fixed and cannot be changed. Empty lines and lines
which start from symbols * are considered as comments and ignored.
Procedure file consist of a preamble, a session section and station sections.
Each station section consists of channel subsections.
Preamble is the first line of the file, and it indicates that this file is
a valid Phase_Doctor procedure file. The first symbols of the preamble should
be a string "Phase_Doctor proc file".
Session section should precede any station sections.
Supported keywords of the session section:
- Offset_estimation: Sets the flag of the estimation of fringe
phase offsets for all channels at all stations except the station
taken as a reference one. A value after the keyword
Offset_estimation is expected: the name of the reference station.
Phase offset estimation (if specified) is done when contributions
if spurious signals in phase and group delays are computed.
If a keyword Offset_estimation in the session sections omitted
no fringe phase offsets are computed.
A station section defines modes of treatment of each station participated in the
experiment. Phase_Doctor expects to find the station section for each station.
Supported keywords of the station section:
A channel subsection should follow a station name keyword. It defines actions
appropriate for the specific channel at this station. Phase_Doctor expects
to find the channel subsection for each station section for each channel.
Supported keywords of the channel subsection:
- Channel name keyword. the first symbol of the keyword should be #
the next symbols defines the consecutive number of the channel in
the channels table. Channels table is sorted first in increasing
frequencies at X-band then in increasing frequencies at S-band.
The first value is a central frequency of the channel in MHz in
format F7.2. The second value is a string MHz. Values from the 3-rd
till the 7-th defines Spurs_codes and action_codes.
Spurs_code is an identifier of the type of spurious signal and is
one of
- A: -- (A-spur) -- Additive spur. The spurious signal
generated by an electronic of a data acquisition system and
is not related to the signal.
- B: -- (B-spur) -- Image spur. It occurs due
to an admixture of the signal at the imaginary band of
the intermediary frequency.
- C: -- (C-spur) -- Cross-band spur. It occurs due to
an admixture of the signal from the opposite band.
- D: -- (D-spur) -- Image cross-band spur. It occurs due
to an admixture of the signal at the imaginary band of
the intermediary frequency of the opposite band.
- L: -- (L-spur) -- Linear spur: dependence of
phase and amplitude of spurious signal on total phase of
phase-cal is linear. The origin is unclear.
An action_code consist of 0, 1 or 2 letters: e,a. Action_code
is attached to the spur_code without delimiters. If the action code
is empty then amplitude and phase of spurious signal will not be
computed and only the averaged amplitude will be calculated.
If the action code contains a letter e then the amplitude and
phase of spurious signal is computed. If the action code contains
a letter a then the amplitude and phase of spurious
signal is computed and applied if the contribution of
spurious signals of phase-cal in group and phase delay is computed.
- BREAK: -- Specifies the time epoch for break in phase of the
current channel. Time epoch is expressed in hours from the nominal
start of the session. The current channel is the channel defined
before the keyword BREAK.
Example
of the valid procedure file.
Baseline clinic
Option (B) Baseline clinic is invoked from the main
Phase_Doctor menu. It allows to display plots of residual fringe phases
before and after applying a model of spurious signals, plots of contribution
of spurious signals in phase and group delay.
The main Phase clinic menu supports commands:
Save delays update
Option (S) Save contributions to delay is invoked from the main
Phase_Doctor menu. It allows to write down the contributions to delay
which has been computed previously by Phase_Doctor in order to apply it
solution.
It recognizes the following commands:
- (M) Save as MODE CALIBRATION writes down a file with
6 quantities for each observation:
- contribution to group delay at X-band (sec);
- contribution to phase delay at X-band (sec);
- contribution to delay rate at X-band (sec/sec);
- contribution to group delay at S-band (sec);
- contribution to phase delay at S-band (sec);
- contribution to delay rate at S-band (sec/sec).
The filename of the binary output file is
$PHD_DIR/<experiment_name>.umc . The output file
contains records with 6 REAL*8 numbers. The number of records
is the nominal number of observations in the X-band database.
Interface with SOLVE.
It is assumed that the output of Phase_Doctor will be imported to
SOLVE by using a "user_calibration" gate. F-SOLVE released after
01-JAN-2000 supports so called mode-calibration. There is
USERMCAL program (source code is in
../src/solve/util/usermcal.f ) which provides
a convenient user interface. It will find
$PHD_DIR/<experiment_name>.umc file if environment
variable UMC_DIR is set to $PHD_DIR. Refer to comments to
usermcal.f program for details.
- (D) Save as a DATABASE UPDATE -- currently not implemented.
Customization
Phase_Doctor uses a
PGPLOT library
of graphic utilities which in turn invokes
XSERV
or pgxwin driver. It requires a proper setting X-resources.
You should add the following lines to the file ~/.Xdefaults
if you use a big screen: 340x280mm
pgxwin.Win.geometry: 1260x800+0+90
pgxwin.Win.maxColors: 69
pgxwin.Win.iconize: True
or
pgxwin.Win.geometry: 1000x680+0+90
pgxwin.Win.maxColors: 69
pgxwin.Win.iconize: True
if you use a small screen: 300x230mm.
Then you have to activate the settings defined in ~/.Xdefaults by
the command
xrdb -merge ~/.Xdefaults
(NB: Environment variable DISPLAY should be set up properly
before using xrdb). This operation should be done each time when you
start a terminal session, therefore it is reasonable to put the call
of xrdb in your customization file, namely ~/.vueprofile
1260x800+0+90 means that the window will have 1260 pixels width, 800 in height,
0 -- shift to the right respectively to the left edge of the screen, 90 pixels
shift down respectively to the top edge of the screen. Parameters window width
and window heights are ignored. Line "pgxwin.Win.iconize: True" means that
PGPLOT window will be iconize and go out from the screen after termination
of DiaGI. This resource is MANDATORY, otherwise
DiaGI will require confirmation from the text screen when it terminates.
The following command should be run before the first call of pgxwin_server:
xrdb -merge ~/.Xdefaults
NB: if pgxwin_server is running xrdb will be ignored! pgxwin_server
should be stopped before execution xrdb command and then launched
again.
The following environment variable should be set up:
- DISPLAY -- name of the screen.
Refer to X11 user documentation for details;
- PGPLOT_DIR -- directory where files pgwin_server and
libpgplot.sl are kept;
- HELP_DIR -- directory name where help files are kept;
- DIAGI_PRICOM -- contains the command for printing
PostScript file. Example:
"lp -onb -dlaser2" for printer which has built-in PostScript
interpreter (don't use it if printer doesn't have such a
capacity!)
Optionally environment the following environment variables can be set up:
- PHD_DIR -- Phase_Doctor writes down files with experiment
to a specific directory. Default name of this
directory is defined by the variable PHD_DIR
defined in the ../solve/gsfcb.i file.
Environment variable PH_DIR overrides the name
directory. Typical size of experiment files
is several megabytes.
Notation:
- $PHD_DIR -- directory where scratch files for phase_doctor are
located. System-wide default name for that directory is defined in
../srdc/solve/gsfcb.i. User can override it by specifying an
environment variable PHD_DIR.
- Current Web_dir -- the prefix which is added before all names of the
output files unless otherwise is specified. Current Web_dir is defined
in the command string for launching Phase_Doctor. If the argument
-w is omitted than /tmp/ is used as a current Web
directory. NB: if it is intended to use web_dir as
a directory name, then a trailing / must be specified.
Input files
Input files are listed here. Some files may not be used. Some files are
can be used as output files also.
- Database file for X- and for S-band. Name of the database, not
the database files is supplied.
- Log-file. Name is arbitrary. It is assumed that the name contains
a full path. Examples:
/diskB5/logs/is146gc.log
/diskB5/logs/euro53mc.log
- Definitions file. Contains filenames used to load data to the
Phase_Doctor when it is called the first time.
Filename is $PHD_DIR/<database_name>.def Examples:
/diskB5/ph_dir/00JAN27XA.def
/geo/vlbi/phase/99DEC13XA.def
- Experiment file. Contains results of reading the databases and
log files. It is used when Phase_Doctor is used not the first
time for this experiment. File name is
$PHD_DIR/<database_name>.phd Examples:
/diskB5/ph_dir/00JAN27XA.phd
/geo/vlbi/phase/99DEC13XA.phd
Output files
Output files are listed here. Files with extension .gif are binary files
in GIF format, files with extension .ps are ASCII files in Postscript format,
files with extension .txt are text ASCII files.
- Experiment file. Contains results of reading the databases and
log files. It is written when Phase_Doctor is used with flag -f.
File name is
$PHD_DIR/<database_name>.phd Examples:
/diskB5/ph_dir/00JAN27XA.phd
/geo/vlbi/phase/99DEC13XA.phd
- File of mode calibrations: contributions of phase-cal to group
and phase delay.
$PHD_DIR/<database_name>.umc Examples:
/diskB5/ph_dir/00JAN27XA.umc
/geo/vlbi/phase/99DEC13XA.umc
- Table of statistics of system temperature.
Filename: {web_dir}sts_{station_name}.gif
- Table of listing of estimation of amplitude and phase of spurious
signal.
Filename: {web_dir}spr_{station_name}.gif
- Table of residual fringe phase offsets.
Filename: {web_dir}residual_phase_offsets.txt
- Table of listing of estimation of residual phases in phase-cal
signal.
Filename: {web_dir}spr_{station_name}.gif
- Plot of raw system temperature.
Filename: {web_dir}rst_tim_{station_name}.gif
- Plot of system temperature in zenith direction versus time.
Filename: {web_dir}zst_tim_{station_name}.gif
- Plot of system temperature versus elevation angle.
Filename: {web_dir}zst_ele_{station_name}.gif
- Plot of raw phase-cal amplitude versus time.
Filename: {web_dir}rca_tim_{station_name}.gif
- Plot of phase-cal phase with ambiguities fixed versus time.
Filename: {web_dir}acp_tim_{station_name}.gif
- Plot of raw phase-cal amplitude versus raw phase-cal phases.
Filename: {web_dir}rca_rcp_{station_name}.gif
- Plot of normalized phase-cal amplitude versus phase-cal phase
with ambiguities fixed.
Filename: {web_dir}nca_acp_{station_name}.gif
- Plot of normalized phase-cal amplitude versus phase-cal phase
with ambiguities fixed PLUS mode of phase_cal amplitude.
Filename: {web_dir}pcs_adj_{station_name}.gif
- Plot of residuals of normalized phase-cal amplitude versus
phase-cal phase with ambiguities fixed after LSQ estimation.
Filename: {web_dir}pcs_res_{station_name}.gif
- Plot of residuals phases in phase-cal versus time.
Filename: {web_dir}pcr_tim_{station_name}.gif
- Plot of residuals phases in phase-cal versus full phase.
Filename: {web_dir}pcr_phs_{station_name}.gif
- Plot of group delays, phase delay in phase-cal phases and cable
delay.
Filename: {web_dir}pcf_phs_{station_name}.gif
- Plot of raw residual fringe phases at X-band
delay. Filename:
{web_dir}rsx_phs_{station_name1}_{station_name2}.gif
- Plot of raw residual fringe phases at S-band
delay. Filename:
{web_dir}rss_phs_{station_name1}_{station_name2}.gif
- Plot of residual fringe phases at X-band after applying
spurious signals model. Filename:
{web_dir}rcx_phs_{station_name1}_{station_name2}.gif
- Plot of residual fringe phases at S-band after applying
spurious signals model. Filename:
{web_dir}rcs_phs_{station_name1}_{station_name2}.gif
- Plot of contribution of spurious signals in phase-cal to group
delay at X-band. Filename:
{web_dir}gdx_spr_{station_name1}_{station_name2}.gif
- Plot of contribution of spurious signals in phase-cal to group
delay at S-band. Filename:
{web_dir}gds_spr_{station_name1}_{station_name2}.gif
- Plot of contribution of spurious signals in phase-cal to phase
delay at X-band. Filename:
{web_dir}pdx_spr_{station_name1}_{station_name2}.gif
- Plot of contribution of spurious signals in phase-cal to phase
delay at S-band. Filename:
{web_dir}pds_spr_{station_name1}_{station_name2}.gif
References
Dialogue Graphic Interface. DiaGI.
-
DiaGI. User guide.
-
DiaGI. Brief description of DiaGI commands.
-
DiaGI. Verbose description of DiaGI commands.
-
Multi_DiaGI. Description of Multi_DiaGI commands.
- Example
of the procedure file.
Phase_Doctor was developed by Leonid Petrov.
This document was prepared by
Leonid Petrov
Last update: 24-MAR-2000 17:01:25