AIPS NRAO AIPS HELP file for TECOR in 31DEC25



As of Tue Dec 10 3:54:44 2024


TECOR: Task to calibrate ionospheric delay and Faraday rotn.

INPUTS

INNAME                             Input UV file name (name)
INCLASS                            Input UV file name (class)
INSEQ             0.0     9999.0   Input UV file name (seq. #)
INDISK            0.0        9.0   Input UV file disk unit #
INFILE                             IONEX file name
NFILES            0.0      999.0   # of INFILES
SUBARR                             Subarray to correct
                                     (0 => all)
ANTENNAS                           Antennas to correct
                                     (all 0 => all)
GAINVER                            Input CL table version
GAINUSE                            Output CL table version
APARM                              Switches
                                     (1) if > 0 correct for
                                         dispersive delay
                                     (2) Follow ionosphere
                                         factor
                                     (3) > 0 use old model field
                                         <= 0 use IGRFv13 for
                                         Earth magnetic field
                                     (4) TEC correction factor
                                         default 1.
                                     (5) TEC elevation increment
                                         (km) default 0
                                     (6) TEC elevation fudge
                                         factor, default 1
DOTABLE                            > 0 -> write TE table to
                                   examine TEC in detail

HELP SECTION

TECOR
Task:   Derives corrections for ionospheric Faraday rotation and
        dispersive delay from maps of total electron content in
        IONEX format.
        There are two procedures that will download the files
        automatically (including calculating the day number) and
        run TECOR.  They are VLBATECR and VLATECR and they are
        part of the procedure packages VLBAUTIL and VLAPROCS
        respectively.  See HELP VLBATECR or VLATECR for more info.

        See HELP TECRTYPE or HELP VLBATECR for information on
        TECRTYPE.  The jplg one refernced below produces the
        most excessive values.  The default TECRTYPE is emrg
        which is less excessive.  But the data file access is
        complex.  Use the procedures.

        Moving sources are supported if a PO table is present.
Adverbs
  INNAME.....Input UV file name (name).      Standard defaults.
  INCLASS....Input UV file name (class).     Standard defaults.
  INSEQ......Input UV file name (seq. #).    0 => highest.
  INDISK.....Disk drive # of input UV file.  0 => any.
  INFILE.....The name of the file containing the TEC data. The
             filename should be given in the usual AIPS style as
             a logical directory name followed by a colon and
             the name of the file or the directory path.
             The file should contain TEC maps spanning the time
             range covered by the input CL table and should be in
             IONEX format.  If NFILES > 1 then the name MUST be in
             standard format CCCCdddC.yyC where C can be any
             character, ddd is the day number, and yy is the year.
             Also the name given in INFILE must be the first day.
             Even for NFILES=1, the standard name is recommended
             since the TE table will record the first 4 characters
             after the : or / as the TECRTYPE.
             See EXPLAIN TECOR for more details.
             Compressed files are not allowed, but names ending in
             .Z or .gz will have the .Z or .gz removed before being
             read.
  NFILES.....Number of IONEX files to use.  Note that if NFILES > 1
             then the INFILE must be in a standard format and the
             file in INFILE must be the first day of those to be
             loaded.  0 => 1
  SUBARR.....Subarray to correct.            0 => all.
  ANTENNAS...A list of antennas to correct. If all entries are
             zero then all antennas in the subarray or subarrays
             selected by SUBARR will be corrected. If all of the
             entries are positive or zero then only those
             antennas with numbers corresponding to the positive
             entries will be corrected. If any entries are
             negative then all of the antennas in the selected
             subarray or subarrays will be corrected except
             those with numbers corresponding the the absolute
             values of the non-zero entries in this array.
  GAINVER....Version number of the input CL table to use.
                                             0 => highest
  GAINUSE....Version number of output CL table. This must not
             be the number of an existing CL table.
                                             0 => highest + 1
  APARM......Miscellaneous settings and switches.
             (1) Enable (> 0.5) or disable (<= 0.5) dispersive
                 delay corrections.  These are VERY important for
                 VLBA data and may even be useful for A-configuration
                 VLA data.
             (2) In principle, it is thought that the ionosphere
                 remains approximately fixed wrt the Sun.  Thus, the
                 task should predict which ionosphere is now in the
                 direction of the source by applying a time correction
                 to the apparent longitude while interpolating between
                 the table values, which are only given every two
                 hours (or 1 hour or even 30 minutes depending on
                 TECRTYPE).  This works well most of the time, but
                 sometimes seems to do odd things.  This parameter
                 allows you to do only a fraction of the time
                 correction, from epsilon to 1.0.   0 -> 1; < 0 -> 0.
                 A correction of zero is equivalent to a model in which
                 the ionosphere rotates with the Earth.
             (3) <= 0 -> use IGRF version 13 magnetic field model for the
                        Earth
                 > 0     use older simpler magnetic model
             (4)-(6) Leonid Petrov suggests a revised "mapping" function
                 See AJ, 2023, 165:183.  Instead of
                     TEPATH = TEC / cos (ZAion)
                 use
                     TEPATH = TEC * APARM(4) / P
                 where
                     P = sqrt (1 - Rf^2 * cos^2 (a*EL))
                     Rf = (Rearth / (Rearth + Alt + APARM(5))
                     a = APARM(6)
                 Petrov recommends 0.85, 56.7 km, 0.9782.
                 Defaults:
                    If APARM(4) < 0.1 or > 5, APARM(4) = 1
                    If APARM(5) < -200 or > 200, APARM(5) = 0
                    If APARM(6) < 0.5 or > 2, APARM(6) = 1
                 web reference:
             https://iopscience.iop.org/article/10.3847/1538-3881/acc174
  DOTABLE....> 0 -> write a TE table.  TEPLT then allows you to
             examine in detail the TECs as functions of source, azimuth,
             elevation etc etc

EXPLAIN SECTION

TECOR:   Task that corrects ionospheric Faraday rotation and
         dispersive delay using maps of ionospheric electron
         content.
         There are two procedures that will download the files
         automatically (including calulating the day number) and
         run TECOR.  They are VLBATECR and VLATECR and they are
         part of the procedure packages VLBAUTIL and VLAPROCS
         respectively.  See HELP VLBATECR or VLATECR for more info.
DOCUMENTOR: Chris Flatters, Amy Mioduszewski, NRAO
RELATED PROGRAMS: LDGPS, GPSDL, PCAL, LPCAL, VLBATECR, VLATECR
                  most programs that apply calibration

TECOR uses a model of the Earth's magnetic field to determine
the contribution of the ionosphere electrons to the observed
rotation measure.  The default field is the official IGRF-13
model supported by Fortran code provided by the IGRF.  See
the web page https://www.ngdc.noaa.gov/IAGA/vmod/igrf.html.
The reference is Alken, P., Thebault, E., Beggan, C.D. et al.
International Geomagnetic Reference Field: the thirteenth
generation. Earth Planets Space 73, 49 (2021).
https://doi.org/10.1186/s40623-020-01288-x

TECOR reads a set of maps of ionospheric electron content that
covers the time range of the observations and uses this data
to calculate the ionospheric Faraday rotation and, if you
request it, the dispersive delay introduced by the ionosphere.
The dispersive delay that is in put in the CL table (column
DISP) is the dispersive delay at a wavelength of 1 meter.  The
input data is expected to be text files in IONEX format.

The IONEX format is a standard format for the interchange of
ionosphere maps and is used by NASA's crustal dynamics data
interchange system (CDDIS), among others. Each IONEX file
contains a series of maps of the zenith total electron content
of the ionosphere as a function of geographical latitude and
longitude taken at different times. TECOR expects the input
file to contain maps covering the whole range of times contained
in the AIPS data file.

Some IONEX files may contain maps that do not cover all of the
antenna in the array. If this is the case then you should
use the ANTENNAS adverb to prevent TECOR from trying to
determine corrections for antennas outside the covered area
otherwise the calibration records for these antennas will be
marked as invalid. Note that you only need to determine the
ionospheric Faraday rotation for your phase reference
antenna to calibrate polarization; differences between the
antennas are removed by self-calibration.

Dispersive delay corrections depend greatly on the accuracy of
the input file and should therefore be checked carefully if they
are turned on.

Ionospheric models are available from the CDDIS data archive.
There are many IONEX files produced by different groups for each
day archived at CDDIS.  These groups are the Jet Propulsion
Laboratory (JPL), the Center for Orbit Determination in Europe
(CODE), the Geodetic Survey Division of Natural resources Canada
(EMR), the ESOC Ionosphere Monitoring Facility (ESA), and the
Technical University of Catalonia (UPC).  At this time, all the
files provide maps every 2 hours.  Since these things change so
rapidly, it is difficult to recommend one file over another.
For the best possible results try all the files and use the one
that seems to work the best (this can be judged using VPLOT).
If you only try one, there is a marginal recommendation that you
use the JPL or CODE files.  As mentioned above, there might come
a time where one or more of these files will become significantly
better than the others so downloading all the files might be a
good idea even if you do not plan of trying them all (they are
not large files).  See the EXPLAIN for a current list of recognized
codes (not all of which may work).


WHICH FILES TO DOWNLOAD
=======================
The IONEX files being read in must bracket the entire
experiment.

BEFORE November 3, 2002 the IONEX files on the CDDIS archive
spanned the time from 1:00 to 23:00.  So if you have an experiment
which starts before 1:00 or ends after 23:00 then you need to get
IONEX files for the day of the experiment and the previous day or
next day respectively.

AFTER November 3, 2002 the IONEX files on the CDDIS archive
span the time from 0:00 to 24:00.  So you can now download
files for only the days on which your experiment has data.

*********************************************************************
*  NOTE: There are two procedures that will download the files      *
*        automatically (including calulating the day number) and    *
*        run TECOR.  They are VLBATECR and VLATECR and are          *
*        part of the procedure packages VLBAUTIL and VLAPROCS       *
*        respectively.  See HELP VLBATECR or VLATECR for more info. *
*********************************************************************

Procedures VLATECR and VLBATECR determine which file(s) are needed and
attempt to download them automatically.  If there is a problem with the
automatic download then you can download the IONEX file(s) manually and
set INFILE and NFILES:

Sometime in October 2020, for new requirements, you can consult

https://cddis.nasa.gov/Data_and_Derived_Products/CDDIS_Archive_Access.html

You may have to create an account with cddis in order to download in
some other fashion.

The command that does work from VLBATECR is (all on one line!)

curl -u anonymous:daip@nrao.edu --ftp-ssl ftp://gdc.cddis.eosdis.nasa.gov/
   gps/products/ionex/YYYY/DDD/jplgDDD0.YYi.Z > /tmp/jplgDDD0.YYi.Z

(no blanks between gov/ and gps) where YYYY is the year e.g. 2015, YY is
the last 2 digits of the year e.g. 15, and DDD is the day number within
the year.

                 **************************************

On or about Oct 1, 2023, new names for the JPL TEC files were introduced
for files created after day 219 (Aug 7).  Files from before use the above
naming convention.  The new names are

curl -u anonymous:daip@nrao.edu --ftp-ssl ftp://gdc.cddis.eosdis.nasa.gov/
   gps/products/ionex/YYYY/DDD/JPL0OPSFIN_YYYYDDD0000_01D_02H_GIM.INX.gz
 > /tmp/jplgDDD0.YYi.gz

and these files need gunzip rather the uncompress.  The JPL is replaced
with TECRTYPE first 3 characters in upper case.  The file name is slightly
different for CODG:

curl -u anonymous:daip@nrao.edu --ftp-ssl ftp://gdc.cddis.eosdis.nasa.gov/
   gps/products/ionex/YYYY/DDD/COD0OPSFIN_YYYYDDD0000_01D_01H_GIM.INX.gz
 > /tmp/codgDDD0.YYi.gz

Other file codes changed to the new file name format at different dates.
These are known for esa, cod, egs, cas, emr, jpl, and upc codes only
and are implemented in the VLBATECR procedure.

                 **************************************

If you do not have curl or a firewall or other issue makes this command
fail then,

Try going to https://cddis.nasa.gov/archive/gnss/products/ionex/YYYY/DDD

You may need to create a login account to cddis to do this.

The commands below will not work after October 2020.


TO DOWNLOAD THE FILES:
======================

1) ftp cddis.gsfc.nasa.gov; login as anonymous.
   -- note that there is a mirror site at igs.ensg.ign.fr

2) cd pub/gps/products/ionex/YYYY/DDD (YYYY-year; DDD-day number)
   -- for igs.ensg.ign.fr: cd pub/igs/iono/YYYY/DDD

3) prompt -1

4) mget jpl*.Z  (or get jplgDDD0.YYi.Z)  (not all *.Z !)

5) uncompress above file(s) before using TECOR

If more than one file is needed to cover the time period of
the experiment:

	-- download all the files

        -- make sure the files have the format CCCCdddC.yyC; where
           C is any character, ddd is the three digit day number and
           yy is the 2 digit year.  This is designed to work with
           the standard file names that the CDDIS data archive
           uses.  Note that the C's must be the same for each file
           and they must all be in the same directory.

        -- use the FIRST file as the INFILE

        -- set NFILES to the number of files

Example:

   INFILE 'FITS:CODG1230.99I'
   NFILES 4

   Will expect to find files:

   CODG1230.99I
   CODG1240.99I
   CODG1250.99I
   CODG1260.99I

   in directory $FITS.

TECRTYPE possibilities include

Code    Meaning

Date of name format change known
casg    Final solution (Chinese Academy of Science)
esag    Final solution (European Space Agency ESOC)
codg    Final solution (Center for Orbit Determination in Europe)
igsg    Final combined solution (IGS combined)
emrg    Final solution (Space Weather Canada)
jplg    Final solution (Jet Propulsion Laboratory)
upcg    Final solution (Universitat Politecnica de Catalunya,
                        Barcelona)

esa files from 20221127 to 20230205 exist with wrong names
they can be downloaded using the web site cited above

The following appears useful even though it is a rapid rather
than final solution.  Name format is still the old form.
uqrg    Rapid high-rate solution, one map per 15 minutes, (UPC)

Rapid solutions, name still old format
uhrg    Rapid high-rate solution, one map per hour, (UPC)
uprg    Rapid solution (UPC)

Not recommended: They are rapid solutions and they
are not present in 2024
corg    Rapid solution (CODE)
ehrg    Rapid high-rate solution, one map per hour, (ESA)
esrg    Rapid solution (ESA)
igrg    Rapid solution (IGS combined)

Predictions are even less useful
c1pg    1-day predicted solution (CODE)
c2pg    2-day predicted solution (CODE)
e1pg    1-day predicted solution (ESA)
e2pg    2-day predicted solution (ESA)
ilpg    1-day predicted solution (IGS combined)
i2pg    2-day predicted solution (IGS combined)
u2pg    2 day predicted solution (UPC)

The previous list
c1pg (number '1'), c2pg, carg, casg, codg, corg, ehrg, emrg (good?),
esag, esrg, igrg, igsg, jplg, jprg, uhrg, upcg, uprg, uqrg, whrg, whug

AIPS