)
TEQC — Tutorial
Table of Contents
- Section 1. -- Introduction: teqc
- Section 2. -- Support & Contact
- Section 3. -- Types of Data
- Section 4. -- Basic Modes of Operation
- Section 5. -- Operating Systems and Hardware
- Section 6. -- Standard Input, Standard Output, and Standard Error
- Section 7. -- General Concepts About Syntax
- Section 8. -- Using teqc for RINEX Formatting & RINEX Format Verification
- Section 9. -- Using teqc for RINEX Header Editing & Extraction; Introduction to Configuration Options and Files and the teqc Option Hierarchy
- Section 10. -- Configuration Options and Command Line Options
- Section 11. -- Using teqc for Quality Checking (qc) Mode
- Section 12. -- Using teqc with Multiple File Input or File Names Including a , (comma)
- Section 13. -- Time-Windowing with teqc
- Section 14. -- Splicing with teqc
- Section 15. -- Translating with teqc
- Section 16. -- Special Translator Considerations and Options
- Section 17. -- Wavelength Factors: What teqc Does With Them
- Section 18. -- Basic Commands: A Review
- Section 19. -- Using teqc in Scripts: Substitution for Batch Mode
- Section 20. -- Differences Between teqc's qc Mode and Original UNAVCO QC
- Section 21. -- Interpreting teqc's qc Mode Output
- Section 22. -- "Strange" Behavior (i.e. Don't Panic)
Introduction: teqc
Section 1.
This document describes and serves as a tutorial for the main features of teqc (pronounced "tek"). Although the capabilities of teqc extend beyond using just RINEX files, the most common type of data format that will probably be used by most users is the RINEX format, either as input, or output, or both. Consequently a shorthand for the three basic kinds of RINEX formats is used throughout this document:
- OBS for RINEX observation data file,
NAV for RINEX navigation message file,
MET for RINEX meteorological data file.
If your primary interest is translating native binary formats to RINEX, go directly to the sections on translation (Section 15 and Section 16).
If your primary interest is editing, go directly to the section on metadata editing/extraction (Section 9), or RINEX formatting (Section 8), or windowing (cutting) (Section 13)/splicing (Section 14) operations.
If your primary interest is qc-ing RINEX or native binary data, go directly to the section on the qc mode (Section 11) of teqc.
Support & Contact
Section 2.
• Information about teqc.
• This tutorial document.
• FAQs ("frequently asked questions") on teqc.
• The teqc development & release log (including bug fixes for the next release).
• A listing of release notes for each official release, covering details which might not be in this tutorial.
• Please contact teqc technical point of contact at GAGE for other questions, unresolved problems, or possible bug reports.
Types of Data
Section 3.
RINEX version 1 files can be read with teqc and are converted to RINEX version 2.10 files on output. Also, lowercase versions of the following header lines are recognized and converted to uppercase if output (e.g. rinex version / type is read and recognized and converted to RINEX VERSION / TYPE on RINEX output).
Each RINEX OBS file must have a header with header lines (starting at the 61st character in the line) that end with:
RINEX VERSION / TYPE (must be first line) PGM / RUN BY / DATE MARKER NAME OBSERVER / AGENCY REC # / TYPE / VERS ANT # / TYPE APPROX POSITION XYZ ANTENNA: DELTA H/E/N WAVELENGTH FACT L1/2 (default values) # / TYPES OF OBSERV TIME OF FIRST OBS END OF HEADER (must be last line of header for version 2.XX)where valid information (i.e., format version = 1, 2, or 2.XX; file type = 'O'; satellite system = ' ', 'G', 'R', 'S', 'T', or 'M') must be present in the first line, the number and types of observations must be specified on the # / TYPES OF OBSERV record line, and default values for the L1 and L2 wavelength factors must be given. The rest of the fields in other header records can be blank if a descriptor string is expected or have some numerical value if a numerical value (even if it is zero) is expected, but these other header lines must be present with or without non-blank information. Observation data usually follows the END OF HEADER header record. (Note that RINEX version 1 does not have a END OF HEADER field, but has a blank line instead.)
Each RINEX NAV file must have a header with header lines (starting at the 61st character in the line) that end with:
RINEX VERSION / TYPE (must be first line) PGM / RUN BY / DATE END OF HEADER (must be last line of header for version 2.XX)where valid information, i.e., format version = 1, 2, or 2.XX; file type =
-
'N' for a GPS navigation message file
'G' for a GLONASS navigation message file
'E' for a Galileo navigation message file
'C' for a Beidou/Compass navigation message file
'J' for a QZSS navigation message file
'I' for a IRNSS navigation message file
'H' for an SBAS navigation message file
Each RINEX MET file must have a header with header lines (starting at the 61st character in the line) that end with:
RINEX VERSION / TYPE (must be first line) PGM / RUN BY / DATE MARKER NAME # / TYPES OF OBSERV END OF HEADER (must be last line of header for version 2.XX)where valid information (i.e., format version = 1, 2, or 2.XX; file type = 'M') must be present in the first line and the number and types of observations specified on # / TYPES OF OBSERV header record line. Meteorological data usually follows the END OF HEADER header record. (Note that RINEX version 1 does not have a END OF HEADER field, but has a blank line instead.)
MES files are not required, but if they are present and you are using target file names (not stdin), then teqc will use the matching MES file for each target input file to help resolve certain metadata.
The ION and EPH download files are not used by teqc.
TurboBinary data from the AOA Benchmark ACT receiver can be tranlated in the usual way for TurboBinary, or using special Benchmark translation options. For example, using the -aoa tbY option (for "Y*-codeless" receivers), the C/A-derived L1 phase value is used for the RINEX "L1" observable, rather than the Y1-codeless L1 phase value.
- for old Trimble *.dat containing records 0 or 7, try Berne's TRRINEXO program ; if that does not work, try Trimble's dat2rin program; if that does not work, please contact Trimble for help
- for Ashtech B-files prior to Version 3, try Ashtech's convert program (contact Ashtech directly); if that does not work, try Berne's ASRINEXO; if that does not work, please contact Ashtech for additional help
Basic Modes of Operation
Section 4.
There are three different basic modes of operation of teqc:
- translation
- editing: metadata extraction and/or editing, formatting, windowing (cutting) and/or splicing
- quality checking (qc)
- check a RINEX file or files for compliance with RINEX version 2.XX specification; for example, missing non-optional header fields are identified
- modify (edit) any existing RINEX header fields in a RINEX file and output the resulting edited RINEX file
- quality check a valid RINEX OBS file or files, but without a RINEX NAV file or binary ephemerides (qc "lite" == no position information)
- quality check a valid RINEX OBS file or files using ephemerides data in a valid RINEX NAV file or files (qc "full" == position information possible)
- window or cut (specify a sub-window of time) and/or splice two or more RINEX files
- translate (convert) certain native binary formats (e.g., Trimble *.dat) to RINEX OBS and/or NAV files
It may also be helpful for the first-time user to be aware that:
- A minimal number of assumptions have been made about the file names that teqc uses. Essentially the file names can be any valid name for the OS, except that no input file name can start with a '-' or '+' character, and names with whitespace (like spaces) are probably best avoided. The Berne-recommended naming convention for RINEX files, though not necessary for teqc, is quite acceptable and can be readily used on the command line or in scripts using teqc.
- In general, teqc is now design-ready not only for data and navigation messages from the NAVSTAR GPS system, but also from GLONASS, Galileo, Beidou/Compass, QZSS, IRNSS (L-band), and SBAS (e.g. WAAS, EGNOS).
- teqc is 100% non-interactive; it will not query the user for input or to find out if something is OK. Your may receive a "Notice", "Warning", or "Error" to stderr. If something is wrong (ususally an "Error" or usage problem), teqc informs the user and terminates.
- In general, teqc does not use hard-wired array sizes, but instead allocates and deallocates memory as needed. As long as your computer has enough computer memory, you should never run into array bound problems.
- teqc is conservative about memory use.
Operating Systems and Hardware
Section 5.
To date, teqc has been tested by GAGE personnel and other users on:
-
Linux x86
Solaris Sparc 2.3 and higher
Solaris x86 2.6 and higher
HP-UX 10.20 and higher (PA-RISC platforms)
DEC Digital-UNIX OSF1 V4.0
DEC Alpha Linux
IBM AIX 4.3
SGI IRIX 5.3
Macintosh OSX
Microsoft (95/98/NT/2000/XP)
Standard Input, Standard Output, and Standard Error
Section 6.
Another basic design feature is the use of standard input (stdin), standard output (stdout), and standard error (stderr). Instead of a file as input, teqc can be in a pipeline accepting a RINEX format stream or binary data stream as stdin. Stderr is reserved for reporting problems that may occur any time teqc encounters something in any file or in stdin that it doesn't like or understand. Stdout is used for dumping the ASCII product requested by the user consistent with the command line syntax. The output from teqc then has the following caveats at the present time: stdout and stderr must be able to be separated.
Consequently, the user is encouraged to use a shell that can distinctly separate stdout and stderr. For UNIX, this includes the Bourne shell (sh) and the Korn shell (ksh). For UNIX C-shell (csh) or for DOS--which do not allow you to direct stdout and stderr separately to different files--an option of teqc (i.e. +err filename) can be used to send what would have gone to stderr to a separate file, to avoid unpleasantries when stdout and stderr would otherwise go to the same place. For the remainder of this document, it will be assumed that the UNIX user is using either sh or ksh, though the following examples should allow a user to easily use csh or a MS DOS shell to achieve the same results.
Though the rest of this tutorial assumes you will be using sh or ksh, you can easily use teqc with csh or a DOS to control stdout and stderr. When using csh or a DOS (or with any other shells), you can use the command options +out, ++out, +err and/or ++err to have teqc internally redirect stdout and/or stderr to specific files. Thus:
- sh or ksh:
- teqc {rest of command} 2> err.txt [stdout to screen]
- any shell:
- teqc +err err.txt {rest of command} [stdout to screen]
- sh or ksh:
- teqc {rest of command} > out.txt [stderr to screen]
- any shell:
- teqc +out out.txt {rest of command} [stderr to screen]
- sh or ksh:
- teqc {rest of command} > temp 2>&1
- any shell:
- teqc +out temp +err temp {rest of command}
- sh or ksh:
- teqc {rest of command} >> out.txt 2>> err.txt
- any shell:
- teqc ++out out.txt ++err err.txt {rest of command}
- any shell:
- teqc {rest of command} >> out.txt [stderr to screen]
- any shell:
- teqc ++out out.txt {rest of command} [stderr to screen]
- any shell:
- teqc {rest of command} 2>> err.txt [stdout to screen]
- any shell:
- teqc ++err err.txt {rest of command} [stdout to screen]
General Concepts About Syntax
Section 7.
The general syntax for teqc is:
-
teqc {options} [file1 [file2 [...]]]
-
teqc {options} < stdin
-
... | teqc {options}
Even executing just
-
teqc
There is a mnemonic governing the use of - and + preceding each option:
- leading -:
-
indicates intent to input something (besides stdin or target file list),
or indicates intent to turn off some option
- leading +:
- indicates intent to output something, (besides stdout and/or stderr),
or indicates intent to turn on some option
-
teqc -help
-
teqc +help
In order to try to detect possible command line input errors, target file names at the end of the command line starting with the character '-' or '+' are currently disallowed. Anything starting with the characters '-' or '+' is always assumed to be a command line option.
Sometimes, especially with new features (e.g., new translators) as they are being added and debugged, you may be inundated with warning messages going to stderr. Most of these can usually be suppressed by including the -warn option:
-
teqc -warn {rest of command}
Using teqc for RINEX Formatting & RINEX Format Verification
Section 8.
Suppose you have three RINEX files (using the Berne-recommended naming conventions): fbar0010.97o, fbar0010.97n, and fbar0010.97m being your OBS, NAV, and MET filenames respectively. Let us suppose that you first wish to verify that your fbar* files can be interpreted as RINEX version 2.XX format compliant, i.e. that their format is such that they have all the bits and pieces in them to make them look like a RINEX file (but not that the information in them is necessarily valid). One way of doing this is to execute:
-
teqc fbar0010.97o
teqc fbar0010.97n
teqc fbar0010.97m
Or you could execute:
-
teqc fbar0010.97o > temp0010.97o
teqc fbar0010.97n > temp0010.97n
teqc fbar0010.97m > temp0010.97m
After doing the above three commands, it might also be instructive to do something like:
-
diff fbar0010.97o temp0010.97o | more
If, in fact, there is some format problem with any of the above input RINEX files fbar0010.97*, teqc will output stdout (either to the screen as in the first set of examples, or redirected to files as in the second set of examples) until the problem is encountered, at which point it will report the problem using stderr and terminate. teqc makes few guesses about what a RINEX file is supposed to be; if a file has a problem, a human or some other program must be used to fix it before teqc will proceed further.
Now suppose that you have a list of RINEX files that you wish to check for RINEX version 2.XX format compliancy, but don't want to save any re-processed stdout. There are several ways to do this (e.g., in UNIX):
-
teqc fbar0010.97o > /dev/null
teqc fbar0010.97n > /dev/null
teqc fbar0010.97m > /dev/null
-
teqc +v fbar0010.97o
teqc +v fbar0010.97n
teqc +v fbar0010.97m
-
teqc +v fbar0010.97o fbar0010.97n fbar0010.97m
-
teqc +v fbar0010.97[m-o]
-
teqc +v `ls fbar0010.97*`
- shuts off the dump to stdout--so teqc +v fbar0010.97o should execute faster than teqc fbar0010.97o > /dev/null,
- suppresses file "splicing"--so teqc understands that the input files are not necessarily of the same RINEX type, and
- dumps a short message to stderr saying that each input file conforms to RINEX version 2.XX specifications at the end of the execution of the file, or a error message dumped to stderr if a problem was encountered.
When inputting multiple target files of the same type, teqc looks to see if this time ordering remains sequential (though neighboring epochs of exactly the same time are currently allowed)--except for RINEX NAV files, where the information is sorted before it is used. For this reason, assuming that the data in fbar0020.97o really follows fbar0010.97o, executing
-
teqc +v fbar0020.97o fbar0010.97o
Using teqc for RINEX Header Editing & Extraction;
Introduction to Configuration Options and Files and the teqc Option Hierarchy
Section 9.
As experienced RINEX file users know, any or all of the RINEX header information may be incorrect. In principal, any of this information can be modified by anyone using an editor for ASCII files, such as "ed", "ex", or "vi" on a UNIX OS, on a file-by-file basis (which, incidentally, highlights one of the most severe vulnerabilities of RINEX--ease of intentional or non-intentional data tampering).
However, it often occurs that the same type of information needs to be corrected on a large set of RINEX files and that the same corrected information needs to be placed in these fields on all the effected files. In this case, it may be easier to use the RINEX modification (editing) capabilities of teqc.
For example, suppose the monument (marker) name needs to be corrected to read "the foobar site" in the OBS file fbar0010.97o. This can be accomplished by executing
-
teqc -O.mo "the foobar site" fbar0010.97o > temp0010.97o
-
teqc -O.mo "foobar" fbar0010.97o > temp0010.97o
-
teqc -O.mo foobar fbar0010.97o > temp0010.97o
There is a similar mechanism to change every header field in a RINEX file, except 1) RINEX comments, in which case the user can only append more comments in the RINEX header, and 2) the first header record of the RINEX file. Rather than list all the possible options here, it is easier to have teqc do it, by using the ++config option with a RINEX target file:
-
teqc ++config fbar0010.97o
-
teqc -O.mo foobar +config fbar0010.97o
teqc -O.mo foobar ++config fbar0010.97o
Executing just
-
teqc ++config
When executing just teqc ++config (i.e. no target files), the two options -st[art_window] and -e[nd_window] show the total possible time range with which teqc is able to cope--down to a resolution less than a femtosecond (1e-15 sec). The format for the arguments of these options are YYYYMMDDhhmmss.sss. Internally, 12 bits are used to store the value of the year, giving teqc the capability of dealing with 4096 years. Thus, with the internal calendar starting at 1980 A.D. (the GPS calendar started on 6.0 Jan 1980), teqc's calendar won't become obsolete any time soon--e.g. teqc passed the Y2k transition on 1.0 Jan 2000 and the GPS week 1024 rollover on 22.0 Aug 1999 perfectly. Whether you specify it or not, teqc always works with a defined time window, where executing teqc ++config shows the maximum bounds on that time window. Note that you can't use times before 1.0 Jan 1980.
After executing teqc ++config, you probably noticed that some of the configuration options end with something like [stuff]. The characters in the brackets and the brackets themselves are optional material included only to make the option more understandable to the user; only the characters to the left of the leading [ is used to identify the configuration option. Thus -O.mo and -O.mo[nument] and -O.monument and -O.moe_and_curly all mean exactly the same thing: the user is trying to set the monument name with the next argument. However, like the rest of the option flag name, only printable characters are allowed in the brackets; no white space is allowed.
You can redirect this configuration information to a file, which is called a configuration file:
-
teqc ++config fbar0010.97o > my_obs_config
- -O.s[ystem]
- satellite system (G = GPS-only, R = GLONASS-only, E = Galileo, S = SBAS-only, etc., M = mixed = more than one system)
- -O.pr[ogram]
- program used to create RINEX file (note: will be obsolete and ignored in first release after 7 Jan 1999)
- -O.r[un_by]
- name of user of program
- -O.d[ate]
- date of program execution (note: will be obsolete and ignored in first release after 7 Jan 1999)
- -O.o[perator]
- name of site operator (observer)
- -O.ag[ency]
- name of agency
- -O.mo[nument]
- monument (marker) name
- -O.mn
- monument (marker) number
- -O.rn
- receiver number
- -O.rt
- receiver type
- -O.rv
- receiver software/firmware version
- -O.an
- antenna number
- -O.at
- antenna type
- -O.px[WGS84xyz,m]
- approximate geocentric position in WGS84 cartesian coordinates, in meters
- -O.pe[hEN,m]
- antenna topocentric correction, in meters
- -O.c[omment]
- original header comment (note: use +O.c[omment] to append a new comment)
- -O.int[erval,sec]
- sampling interval, in seconds
- -O.st[art]
- date & time of first observation epoch
- -O.e[nd]
- date & time of last observation epoch
- -O.def_wf
- default wavelength factors for L1 and L2 (see note on teqc's handling of wavelength factors)
- -O.obs[_types]
- list of observables and the observables themselves in the data portion of the file
- -O.dec[imate]
- modulo decimation of OBS epochs to # time units (seconds by default); -O.dec 30 or -O.dec 30s or -O.dec .5m results in epochs nominally at 00 and 30 seconds being output; millisecond jumps should be accounted for automatically
- -O.pg[eo,ddm]
- approximate geocentric position in WGS84 geographic coordinates, latitude and longitude in decimal degrees and elevation in meters (this input is converted to WGS84 cartesian coordinates)
- -O.sl[ant]
- input vertical topocentric antenna correction as slant height, antenna diameter, and vertical phase center offset (E and N are assumed to be zero) (this input is converted to the cartesian topocentric correction h 0 0)
- +O.c[omment]
- append a new comment field (note: you cannot change existing comments with -O.c[omment])
- -O.rename_obs
- change the character designations of the observables in the # / TYPES OF OBSERV in the RINEX OBS header, but does not rearrange the data in the file; use with care!
- -O.mod_wf
- set the wavelength factors for a specific set of SVs different from the default wavelength factors (this will not be present in the RINEX OBS header as a WAVELENGTH FACT L1/2 record; see note on teqc's handling of wavelength factors)
- -O.mov[ing] 1
- force RINEX OBS antenna position to be in kinematic (roving) state initially (especially regardless of binary flags if doing translation); note that this option has an argument: 1 to turn on and 0 to turn off
- -N.a[alpha]
- ionosphere alpha parameters
- -N.b[eta]
- ionosphere beta parameters
- -N.leap
- leap seconds for UTC time model
- -N.UTC
- UTC time model A0 A1 t w
- -N.pr[ogram]
- program used to create RINEX file (note: will be obsolete and ignored in first release after 7 Jan 1999)
- -N.r[un_by]
- name of user of program
- -N.d[ate]
- date of program execution (note: will be obsolete and ignored in first release after 7 Jan 1999)
- -N.s[ystem]
- satellite system (G = GPS, R = GLONASS, E = Galileo, S = SBAS, etc.)
- -N.c[omment]
- original header comment (note: use +N.c[omment] to append a new comment)
- +N.c[omment]
- append a new comment field (note: you cannot change existing comments with -N.c[omment])
- -M.pr[ogram]
- program used to create RINEX file (note: will be obsolete and ignored in first release after 7 Jan 1999)
- -M.r[un_by]
- name of user of program
- -M.d[ate]
- date of program execution (note: will be obsolete and ignored in first release after 7 Jan 1999)
- -M.obs[_types]
- list of meteorological observables and the met observables themselves in the data portion of the file
- -M.mo[nument]
- monument (marker) name
- -M.mn
- monument (marker) number
- -M.c[omment]
- original header comment (note: use +M.c[omment] to append a new comment)
- +M.c[omment]
- append a new comment field (note: you cannot change existing comments with -M.c[omment])
- -M.rename_obs
- change the character designations of the meterological observables in the # / TYPES OF OBSERV in the RINEX MET header, but does not rearrange the data in the file; use with care!
-
teqc `cat my_obs_config` fbar0010.97o > temp001a.97o
-
teqc -config my_obs_config fbar0010.97o > temp001b.97o
There is an important difference between the last two example commands, though it should not be apparent at this point (i.e., executing diff temp001a.97o temp001b.97o should show that the two modified files are identical). Here the option hierarchical procedure used in teqc is introduced. To make full use of teqc's capabilities, it is strongly suggested that the user eventually become familiar with this hierarchy.
The primary rule to remember when using configuration options is:
The first setting/value for a configuration option that is encountered is the one that's used (later settings/values for the same configuration option are ignored); except for three special cases: inputting multiple config files, multiple NAV files for the qc mode, and additional RINEX comments.All that is needed now is to know the order in which configuration options are processed.
The first configuration options that are processed are the command line options, processed left to right. For example, execute:
-
teqc -O.mo "the foobar site" -O.mo foobar ++config fbar0010.97o
-
teqc -O.mo foobar -O.mo "the foobar site" ++config fbar0010.97o
-
teqc `cat my_obs_config` fbar0010.97o > temp001a.97o
The next configuration options that are processed come from a special environment variable (if it exists), called $teqc_OPT. Actually, the executable looks for an environment variable that matches the name of the executable. So if you do cp teqc my_teqc and then use my_teqc as the executable, it will look in this case for the environment variable called $my_teqc_OPT.
Therefore, if you set $teqc_OPT (assuming sh or ksh):
-
export teqc_OPT="-O.mo foobar"
-
teqc ++config fbar0010.97o
teqc -O.mo "the foobar site" ++config fbar0010.97o
The next configuration options that are processed are all the specified configuration files. A list of these are formed in the following way. First, all -config command line arguments or any in $teqc_OPT are stored. Then (assuming, again, that our executable is still called teqc), the environment variable $teqc_CONFIG is looked for, which may contain the name or the complete path and name to another configuration file. If $teqc_CONFIG exists, the name it contains is appended to the end of this list of configuration files (if any) from the command line. Now all that is needed to is to find each of these configuration files (if they exist), which is done in the following way.
For each possible configuration file name, the name is first examined to see if it starts with a / character assuming a UNIX-style directory naming convention. (With the DOS-style convention, a \ is used; with the MacIntosh-style convention, a : is used.) If the name does start with /, teqc assumes that the configuration file name is absolute, i.e., it contains a full path preceding the file name. In this case, teqc will try only this path and name. If the file exists and can be read, it is processed as a configuration file; if it does not exist or cannot be read, teqc moves on to the next file in the list.
If the configuration file name does not start with a /, teqc assumes that the configuration file name is relative, i.e. it contains only a partial path and file name, or perhaps just the file name. At this point, teqc looks for an $teqc_PATH environment variable, set up the same way as other $*PATH environment variable, i.e. with a : separating the different paths. If this $teqc_PATH environment variable exists, each path in it is used as a prefix to the relative configuration file name. If a file is found that can be read, it is processed as a configuration file, and then teqc moves on to the next configuration file in the list. If it cannot be found or cannot be read, teqc tries the next path as a prefix, and so on.
If $teqc_PATH does not exist, teqc will always try the path ., i.e., the present working directory. If you use $teqc_PATH, you will probably want to make sure that . is one of your paths; teqc will not automatically include it for you in this case.
To summarize, the hierarchy for processing configuration options is:
- process command line options first, left to right
- any -config arguments are stored as a list of configuration files
- if it exists, the environment variable $teqc_OPT is processed according to the same hierarchy as 1) and 2) above
- if it exists, the environment variable $teqc_CONFIG is appended to the end of the list of configuration files extracted from the command line and the environment variable $teqc_OPT
- the accumulated list of configuration files is then processed, first to last:
- if the name of the configuration file is absolute, only that path and name are examined
- if the name of the configuration file is relative: the list of paths in $teqc_PATH is used until a file is found and read or until all the paths in $teqc_PATH are exhausted; if $teqc_PATH does not exist, only the relative path . is tried.
- then each configuration file is processed from left to right and top to bottom
- any configuration option not set by the above has a default configuration option hardwired in the teqc executable, or in the case of inputting RINEX or native binary formats (via stdin or files), the original information is used, or if that information is not present, it is null.
This may seem like a mind-boggling set of unnecessary possibilities, but you can be assured that there is a reason. So far you have only been exposed to the -O.* options for modifying header fields in RINEX OBS files. There are over 20 of these options. There is a similar set of -N.* options for RINEX NAV files and -M.* options for RINEX MET files. For general use of teqc there are about a dozen different options and with the quality checking mode (qc) there are about 7 dozen different options. To have all of these options crammed into one file (which is certainly possible), creates a near-unmanageable file if you are interested in changing only one or two parameters. Each configuration file need not have all the options specified, owing to the way that teqc looks at each file: more as a set of command line options with random order than a rigidly formatted file. If ideas are not already starting to churn in your head as to how to take advantage of this flexibility, an example in the section on scripts will show you how to easily make use of this option hierarchy.
Furthermore, you don't really need to use any configuration files (perhaps just a few configuration options used as command line options) to have teqc produce reasonable output in most cases, as demonstrated by the first examples in this document.
Configuration Options and Command Line Options; What's the Difference?
Section 10.
Syntactically, it may appear that there is no difference between what is being called a configuration option and a normal UNIX command line option for teqc. For many of the options, there is, in fact, no difference. That's the beauty of the whole teqc interface design!
However, for an important subset of teqc configuration options there is a critical difference. These are the options that have arguments which are characters strings that might encapsulate white space, like -O.mo discussed in detail above. Currently, these are only the -O., -N., and -M. options which will edit RINEX header character fields, plus the +O.c, +N.c, and +M.c options to include any new RINEX comments. The important differences for these options are:
- if the text string contains whitespace, the text string must be delimited by a set of " (double-quotes) (though delimiting any text string with a set of double-quotes is always permissible)
- if the text string contains a " (double-quote) or a \ (backslash) character itself, each instance must be preceded by an additional \, i.e. \" or \\
Create a config file, comment_config, containing:
+O.c " \"\\ This is a \"comment.\" \\ \" \ "and execute
<prompt> teqc -config comment_config RINEX_OBS | grep commentwhere RINEX_OBS is any RINEX OBS file. Or using the command line (e.g. with ksh):
"\ This is a "comment." \ " COMMENT
<prompt> teqc +O.c " \"\\\ This is a \"comment.\" \\\ \"" RINEX_OBS | grep commentNotice that two extra backslashes were required due to metacharacter interpretation of two of the backslashes by the shell. A similiar type of shell interpretation of the backslash is required here:
"\ This is a "comment." \ " COMMENT
<prompt> teqc +O.c long=123W34\'45\" RINEX_OBS | grep long=where an additional \ (backslash) had to included, not for teqc, but to suppress the metacharacter meaning of the ' (single-quote) for the shell. (In this latter example, note that the text string is not delimited by a set of " (double-quotes) since there is no whitespace included in the text string.) Or using $teqc_OPT, execute (e.g. with ksh):
long=123W34'45" COMMENT
<prompt> export teqc_OPT="+O.c \" \\\"\\\\ This is a \\\"comment.\\\" \\\\ \\\" \ \""where lots of extra backslashes were required by metacharacter interpretation of backslashes by the shell to establish the correct value for the environment variable $teqc_OPT.
<prompt> echo $teqc_OPT
+O.c " \"\\ This is a \"comment.\" \\ \" \ "
<prompt> teqc RINEX_OBS | grep comment
"\ This is a "comment." \ " COMMENT
A minor flaw occurs if trying:
<prompt> unset teqc_OPT(The initial unset command just eliminates $teqc_OPT in case it had a value.) Notice that each multiple whitespace area in the original comment string collapses into a single whitespace area in the RINEX comment. (The whitespace collapse occurs during the interpretation of the cat command by teqc.) In this case, this result is the best that can be accomplished given the way UNIX shells work.
<prompt> teqc `cat comment_config` RINEX_OBS | grep comment
"\ This is a "comment." \ " COMMENT
To complete the symmetry of the teqc interface, when using the +config or ++config options any existing " (double-quote) or \ characters in RINEX text fields are expanded into \" or \\ in the resulting config output. In this way, the config output is immediately usable as a valid and complete teqc config file.
Using teqc for Quality Checking (qc) Mode
Section 11.
A large portion of teqc is for quality checking or qc-ing of satellite positioning data. With teqc releases in 2018, this includes orbit calculations using broadcast navigation messages from any of NAVSTAR GPS, GLONASS, Galileo, Beidou/Compass, QZSS, IRNSS, and/or SBAS -- essentially any combination of GNSS.
To use teqc in a qc mode, try, for example:
-
teqc +qc fbar0010.97o
Executing the above should produce something if fbar0010.97o is a valid and complete RINEX OBS file. Exactly what is does (at this point) should only depend on the default qc-mode settings in teqc--which, incidentally, should represent what a majority of users feel they want from routine qc processing. However, nearly all qc parameters can be effected by the appropriate configuration option. And, yes, you can look at the qc configuration options to see what exactly you can effect, by:
-
teqc +qc ++config 2> /dev/null | more
Now let's look at what the execution of teqc +qc fbar0010.97o (perhaps followed by a pipe to more) finally produced. Assuming a successful run, the user should have noticed at least two things: 1) There should have been a set of characters going to the screen (actually, to stderr) during execution which looked like
-
qc lite>>>>>>>...
Next, look at the result of
-
teqc +qc ++config 2> /dev/null | grep report
-
+l[ong_report]
+s[short_report]
Next, look at the result of
-
teqc +qc ++config 2> /dev/null | grep plot
-
+plot
-
fbar0010.ion if +ion was set (ionospheric delay observable, in meters)
fbar0010.iod if +iod was set (derivative of ionospheric delay observable, in meters/minute)
fbar0010.mp1 and fbar0010.mp2 if +mp was set (MP1 and MP2 observables, in meters)
fbar0010.sn1 and fbar0010.sn2 if +sn was set (S/N for L1 and L2, in arbitrary units)
Next, move or create fbar0010.97n in the your working directory and execute:
-
teqc +qc fbar0010.97o
-
teqc +qc -nav fbar0010.97n fbar0010.97o
The case-sensitive algorithm for building matching NAV file names from OBS file names is as follows, where YY represents two digits, e.g. YY == 97:
*.YYo -> looks for *.YYn *.YYO -> looks for *.YYN *.obs -> looks for *.nav *.OBS -> looks for *.NAVOther cases for this NAV file auto-matching can easily be added to the code.
During execution (which will probably take slightly longer than the qc-lite run), you should now see:
-
qc full>>>>>>>...
-
fbar0010.azi andfbar0010.ele (satellite topocentric azimuths and
elevations as viewed from the antenna for every satellite for which an ephemeris
was present in the NAV file)
Using teqc with Multiple File Input or File Names Including a , (comma)
Section 12.
Cases always arise where you want to include multiple files as input. Let's look at some of these cases. First, there may be multiple configuration files:
-
teqc -config my_config_1 -config my_config_2 -config my_config_3 {rest of command}
-
teqc -config my_config_1,my_config_2,my_config_3 {rest of command}
-
teqc -config my_config_1,my_config_2 -config my_config_3 {rest of command}
-
teqc -config my_config_1 -config my_config_2,my_config_3 {rest of command}
-
teqc -delim= -config strange,one {rest of command}
The same type of scheme works for inputting multiple NAV files for a qc-full run:
-
teqc +qc -nav fbar0010.97n -nav fbar0020.97n -nav fbar0030.97n {rest of command}
-
teqc +qc -nav fbar0010.97n,fbar0020.97n,fbar0030.97n {rest of command}
Currently, all the target file names at the end of the command line are considered to be part of the single execution of teqc. For example, what should you expect when executing this:
-
teqc +qc -nav fbar0010.97n fbar0010.97o fbar0020.97o fbar0030.97o
Time-Windowing with teqc
Section 13.
As mentioned above in Section 9, teqc always windows the input data (somewhere between 1 Jan 1980 and 31 Dec 6075), though this is usually transparent to the user. There are eight different windowing strategies for you to be aware of; different information is supplied (or not supplied) to use each of these different strategies.
The nomenclature in the following table is as follows. A bracketed value is one determined by teqc from the target files (i.e., implied), whereas a non-bracketed value is explicitly supplied by the user (via a configuration option using the command line, $teqc_OPT, $teqc_CONFIG, or another configuration file). start refers to the argument of the configuration option flag -st[art_window], delta refers to the arguments of the configuration option flags +d... or -d..., and end refers to the argument of the configuration option flag -e[nd_window], and dir refers to whether a + or - was used with the delta configuration flag. The eight different windowing options are:
- [start] [end] (user supplies nothing except target files)
- [start] delta (dir == +) e.g. +dh 7 for 7 hours from the start
- delta [end] (dir == -) e.g. -dm 60 for 60 minutes from the end
- start [end]
- [start] end
- start end
- start delta (dir == + or -)
- delta end (dir == + or -)
For case (1), probably the most common, the user supplies nothing but the list of target files. teqc then does a fast search of the target files to be processed to determine the start and end times. If you input a file type for which a fast search algorithm has not yet been written or use stdin as the target, then you must use explicit windowing (case (6), (7), or (8)). Currently, the fast search algorithm has been implemented only for RINEX OBS, NAV, and MET files. The start time will be the first observation epoch or event epoch (RINEX OBS or MET files) or the first TOE epoch (RINEX NAV files) in the first target file listed and the end time will be the last epoch in the last target file listed. (As mentioned above, if your target files are not listed in a time-sequential order, or if one or more of your target files are not internally time-sequential, something will run afoul later in the execution process and teqc will tell you about it.)
As an example, let's return to:
-
teqc +qc -nav fbar0010.97n fbar0010.97o fbar0020.97o fbar0030.97o
For cases (2) and (3), the user supplies a +d... option or a -d... option with an argument. Currently, ... could be Y for years, M for months, d for days, h for hours, m for minutes, or s for seconds. The leading + or - means "give me a positive time delta from the start" or "give me a negative time delta from the end", respectively. Let's suppose, again, that the fbar00*0.97o files above are each 24-hours worth of data. Then the configuration option +dh 6 together with the file fbar0010.97o would mean: "start at 00:00:00.0 1 Jan 1997 and end at 06:00:00.0 1 Jan 1997", i.e. a delta of +6 hours from the (implied) window start. The configuration option -dh 6 together with the file fbar0010.97o would mean: "start at 18:00:00.0 3 Jan 1997 and end at 00:00:00.0 4 Jan 1997", i.e. a delta of -6 hours from the (implied) window end.
For cases (4) and (5), you supply explicitly either just a new partial or complete start time or just a partial or complete end time using the configuration option flags -st or -e with an argument. The argument for a complete start or end time is easy to understand; it has the format of [YY]YYMMddhhmmss[.sss...], though metacharacters like : (colon), , (comma), ; (semicolon), / (slash), \ (backslash), + (plus), - (minus), = (equal), _ (underscore), ~ (tilda), # (pound) can be used to improve readability. I.e.
-
19970229105937
970229105937
970229105937.000000
1997-02-29_10:59:37
Let's suppose we return to our command
-
teqc +qc -nav fbar0010.97n fbar0010.97o fbar0020.97o fbar0030.97o
-
-st 930.004
-st 9:30.004
-st 00:09:30.004
-
[[[[[[YY]YY]MM]dd]hh]mm]ss[.sss...]
For cases (6), (7), and (8), you are explicitly assigning the window of interest, and, again, partial arguments can be used for the start and/or end times. You can supply an explicit (partial or complete) start and end time, explicit (partial or complete) start time with a delta (a-la cases (2) and (3)), or an explicit (partial or complete) end time with a delta.
By using case (7), you can easily force your teqc processing to start at the same time of day and span the same length of time, regardless of the start and end times of the input target files. For example, suppose you wish to have a start time of 00:00:00.0000000 at each day and want exactly 24-hours worth of teqc processing. This is easily accomplished with something like
-
-st 00:00:00 +dh 24
.
-
-st 00:00:00 +dm 1439.5
You might think that just about every conceivable type of window possibility has been covered. Well, not quite yet. You can even introduce holes in the overall time window during which you are not interested in anything. teqc skips over all input that occur during your specified window holes, hole boundaries inclusive. Here the configuration option -hole followed by a file name is used. The file named is an ASCII file listing the holes that you want in your time window. The format of the hole file for each window hole is always
-
[YY]YY MM dd hh mm ss[.sss] [YY]YY MM dd hh mm ss[.sss]
97 2 15 00 00 00 1997 2 15 03 00 00.00 97 2 15 06 00 00 97 2 15 09 00 00is perfectly OK (though a little hard to read by humans). A more readable file (for humans) that does the same thing is:
97 2 15 00 00 00 97 2 15 03 00 00 97 2 15 06 00 00 97 2 15 09 00 00Obviously, this is a listing of start and end times for each hole desired. How many holes can you list in a file? As many as you want (or until computer memory is saturated). How many files do you get to name with the -hole option for each teqc run? Currently, one, so make sure it includes all the holes you want for the execution. Also remember: each hole includes the exact start and stop time of the hole.
This is a powerful option to create batches of RINEX or BINEX output files in various lengths, e.g. daily, 8-hour, hourly, 30-minute, 15-minute, 5-minute, ..., from one or more input files (manufacturers' formats, RINEX, or BINEX, and as usual, the input files all have to be of the same type). The -tbin option can create smaller output files than the input files (e.g. hourly files from daily files), and it also makes long files from several shorter files. It can use mixed length input files. So, the input might be a list of files of varying lengths, some shorter than a day, and the output could be binned into daily files.
Two options are used for time binning. The first and required option is -tbin which has two arguments, such as -tbin 1h myfile. The first and required argument, such as 1h, is the time duration for each bin (output file). The trailing letter specifies time units: s for seconds, m for minutes, h for hours, d for days. You must use d, h, m, or s. Time durations in sub-seconds are allowed: if sub-seconds are indicated, then resulting filenames will expand to include an additional ".ddd" after the seconds value showing the time down to milliseconds. Any value for the time duration is allowed: caveat emptor! If you type 1s and the input data is most of a day long, you are asking for tens of thousands of files to be made.
The second argument for -tbin, such as myfile, is the prefix part of the output filenames. The prefix can
be a 4-char ID, or some other printable string without whitespace.
The output filenames have the form <root> == prefix + doy-of-year, where the filenames themselves would be:
a) <root>0.yyo if delta (bin time duration) in days is an integer
b) <root>a.yyo - <root>x.yyo if case (a) doesn't work, but
24/(duration in hours) results in an integer hour, with the hour indicated by
a letter from a to x:
a = start in hour 0, ..., x = start in hour 23
c) <root>[a-x]00.yyo - <root>[a-x]59.yyo if cases (a) and (b) don't work,
but 60/(delta in minutes) results in an integer
00 = start in minute 0, ..., 59 = start in minute 59
d) <root>[a-x][00-59]00.yyo - <root>[a-x][00-59]59.yyo if cases (a)-(c)
don't work, but 60/(delta in seconds) results in an integer (or maybe
all remaining cases as well ...)
00 = start in second 0, ..., 59 = start in second 59
In a teqc command like
The option +nav +,+ means make separate NAVSTAR GPS and GLONASS nav files for the time bins, but
this syntax can also be extended to also include SBAS, Galileo, Beidou/Compass, QZSS, and IRNSS -- in that order.
For example, a command to translate from Trimble to RINEX
This example may be what you want if the tbin window is shorter than about 2-4 hours. Recall that the -tr d part is not required when the input file is a Trimble DAT/ION/EPH/MES download fileset (dat file) file.
There is a second option, -ast, aligned start time, which may be used with -tbin to specify the start time of the first bin. This option is not required for time binning. If no -ast option is specified, time binning uses a default alignment starting at 00:00:00 on the first data (obs, nav, or met). Option -ast - or -ast _ means start alignment to the first epoch that is output; -ast [[[[[[YY]YY]MM]DD]hh]mm]ss[.sssss] means start alignment at the specified time. Sub-seconds may be used with -ast.
Note the common and different option -st is reserved to mean when to start the data, which by default is the first epoch found. Don't confuse -ast and -st.
Option tbin works for all these cases:
N manufacturer's format
or BINEX files -> M RINEX filesets
The RINEX filenaming scheme with tbin is:
daily =
where
Note that teqc should select the coarsest filenaming binning in order to do what you've asked. Which filenaming binning is used depends on the -tbin unit selected or the -ast time unit. For example if using the default -ast (i.e. not explicitly specified) and using -tbin 30m test, then the minute filenaming binning is used; but if -tbin 1h test or -tbin 60m test, then the hourly filenaming binning is used.
For creating RINEX with time-binning, you have pretty good control over which files end up being created with time-binned names; e.g.:
+nav temp.gps,temp.glo +obs + -tbin 1h temp == all GPS nav messages go into RINEX file temp.gps and all GLONASS nav messages go into RINEX file temp.glo (in other words, neither are time binned), but all RINEX obs files are
time-binned (to 1-hour in this case)
+nav +,temp.glo +obs + -tbin 60m temp == all GLONASS nav messages go into RINEX file temp.glo, but all RINEX GPS nav files and all RINEX obs files are time-binned (again, to 1-hour)
+nav +,+ +obs + +met + -tbin 3600s temp == all RINEX (GPS and GLONASS nav, obs, and met) files are time-binned (and again, to 1-hour)
+tbin 3600s temp is a short-hand for the previous command (notice the + in +tbin), i.e., all RINEX files are time-binned.
The only difference to create time-binned BINEX is to use the +binex option (which takes its usual argument), and the resulting BINEX files will be named differently from time-binned RINEX:
<root> = prefix + GPS week + '_' + day_of_week (Sun=0,...,Sat=6)
daily = <root>.bnx
Examples of tbin usage:
1) You want the input broken up into daily files and the created obs filenames to start with test:
2) You want the input broken up into files of 1/12 sidereal days with filenames starting with sidx, and you want the first file to be time aligned to 00h30m09s (GPS time, as usual) of the first day of data, and
you want the data to start at 01h30m10s in the first file; use:
Note that a sidereal day is 23h 56m 4.091s, so 1/12th is 7180.3409 seconds.
3) With an input of one Topcon TPS file, cp_1p.tps the command
4) If you want the nav messages in a single RINEX nav file (temp0270.03n)
for GPS and a single RINEX nav file (temp0270.03g) for GLONASS, with time binning making 1 hour obs files:
5) Use of the +tbin short-hand
6) BINEX example with +tbin
The options +obs, +nav, or +met will not be required with the -tbin option in new versions of teqc, if the input target files are RINEX (but if the input is more than one file, the input files still all have to be of the same type). This simplified command syntax choice will be in the next full release after September 2009.
Time Binning with Option tbin
You can also invoke a time binning style of auto-windowing with option -tbin.
The -tbin option is only available in versions of teqc made on or after 18 July 2008.
teqc -tr d +obs + +nav + -tbin 1h mytbinfile inputdatafile
the extra bare + signs after +obs and +nav mean make a sequence of obs and nav files which match the 1 hour time bins made with the -tbin 1h temp arguments. The + argument after the +obs and +nav options only has meaning when using the -tbin option. If you tried that without -tbin you'd end up with a file named + .
teqc -tr d +obs + +nav myfull.nav -tbin 1h myhourly grnr2600.dat
will put all the GPS nav messages into one file myfull.nav, but the RINEX obs are tbinned as hourly files:
teqc: creating file myhourly260a.97o ...
teqc: creating file myhourly260b.97o ...
teqc: creating file myhourly260c.97o ...
N RINEX files of same type -> M RINEX files of same type as input
N manufacturer's format or BINEX files -> M BINEX files
N RINEX filesets -> M BINEX files
hourly =
minute =
second =
subsec =
[a-x] for hours 00 - 23
[onghem] -- RINEX suffix, e.g. 'o' for RINEX obs file, etc.
hourly = <root>[a-x].bnx
minute = <root>[a-x]00.bnx - <root>[a-x]59.bnx
second = <root>[a-x][00-59]00.bnx - <root>[a-x][00-59]59.bnx
subsec = <root>[a-x][00-59]00.ddd.bnx - <root>[a-x][00-59]59.ddd.bnx
teqc -tr d +obs + -tbin 1d test input.obs
If, say, the data started on day 2007:165, the output files would be named:
test1650.07o
test1660.07o
test1670.07o
test1670.07o
...
No nav files are made.
teqc -tr d +obs + -tbin 7180.3409 sidx -ast 00:30:09.000 -st 01:30:10 input.obs
If the data started on day 2007:165, then the output files would be named:
sidx165a3009.07o (but data here doesn't start in file until 01:30:10)
sidx165c2950.07o
sidx165e2930.07o
...
teqc cp_1p.tps
translates the input to RINEX as a single stream to stdout.
To create hourly time-binned RINEX obs files, and distinct nav files for GPS and GLONASS, use:
teqc +nav +,+ +obs + -tbin 1h temp cp_1p.jps
creating temp027m.03n ...
creating temp027k.03o ...
creating temp027k.03g ...
creating temp027l.03o ...
creating temp027l.03g ...
creating temp027o.03n ...
creating temp027m.03o ...
creating temp027m.03g ...
teqc +nav temp0270.03n,temp0270.03g +obs + -tbin 1h temp cp_1p.jps
creating temp027k.03o ...
creating temp027l.03o ...
creating temp027m.03o ...
creating temp027n.03o ...
creating temp027o.03o ...
creating temp027p.03o ...
teqc +tbin 1h mytbinfile grnr2600.dat
is a short-hand for
teqc +nav +,+ +obs + +met + -tbin 1h mytbinfile grnr2600.dat
Notice the +tbin instead of -tbin.
teqc +binex 0x7f-03 +tbin 15m tmp input.obs
! Notice ! using RINEX OBS default observable list
! Notice ! using RINEX MET default observable list
teqc: creating file tmp1488_1a00.bnx ...
teqc: creating file tmp1488_1a15.bnx ...
teqc: creating file tmp1488_1a30.bnx ...
teqc: creating file tmp1488_1a45.bnx ...
Splicing with teqc
Section 14.
Recall that executing the command
teqc fbar0010.97o
basically spews the contents of fbar0010.97o back out to stdout. Suppose
you have the RINEX OBS files fbar0010.97o
for 1 Jan 1997 and fbar0020.97o
for 2 Jan 1997 and you want to combine them into a single RINEX OBS file.
It would have been easy if the RINEX standard had been written so that two
RINEX files could be simply concatenated to one another to produce a new
valid RINEX file, a la the UNIX cat system command:
cat fbar0010.97o fbar0020.97o > oops0010.97o
But, alas, the RINEX standard does not allow this sort of obvious simplicity
and thus the file oops0010.97o is generally useless.
However, teqc takes care of the RINEX-idiosyncratic
boundary between the two files. Thus
teqc fbar0010.97o fbar0020.97o > good0010.97o
or using regular expressions (most UNIX shells)
teqc fbar00[12]0.97o > good0010.97o
produces a valid RINEX file, good0010.97o, with an added comment at the boundary:
RINEX FILE SPLICE COMMENT
(Note: This splice comment occurs only in a spliced RINEX
OBS file, since the current RINEX standard does not
allow for comments after the headers of RINEX NAV
and RINEX MET files.)
Multiple files can be spliced together and any of them can be for any session
length. However, the order (like always) must be time-sequential.
Header information from files after the first on are winnowed to preserve
only pertinent parts, and this can be further reduced by including the
-phc = delete post-header comments option, e.g.
teqc -phc fbar00[12]0.97o > good0010.97o
Receiver clock reset information is not carried across the splice boundary
of RINEX OBS files. Thus if there are millisecond receiver clock resets in
the first file OBS file, and the second OBS file has these millisecond resets
initialized back to zero, there will be a n-millisecond receiver clock jump
at the boundary of the OBS splice.
If desired, you can combine the window and splice operations in a single command.
Use any of the windowing options in combination with
the splice procedure.
Translating with teqc
Section 15.
teqc is being enhanced to handle a number of native binary formats
from various receivers. For now, teqc handles common formats for
many dual-frequency (L1 and L2) and a few single-frequency (L1) receivers.
The general use of teqc for all native binary formats
is similar. You need to specify three things:
(The big-endian/little-endian problem of the different binary formats is
automatically handled by teqc, so don't worry about it.)
Teqc also reads non-native formats, at the present time limited
to the RINEX format, the ARGO format, and BINEX. As you have probably
already determined, the RINEX format is assumed by default. To force
teqc to interpret the input in the other non-native formats, use:
(Note: there is no corresponding -rinex flag for RINEX since this
is always assumed to be the default.)
For native or receiver specific formats, an option flag may be needed to specify
the general type of receiver, and its argument is used to specify the receiver format:
For translation to RINEX, the user can specify what type file is of primary
interest; if none is specified, RINEX OBS is assumed.
For example, using either the receiver argument (i.e. format specification)
or appending an o onto the end of format specification means to
extract OBS by default, and so on:
Suppose, for example, that the file fbar.bin contains the
the Trimble RT17 for GPS week 866, 11 Aug 1996 - 17 Aug 1996 from a
Trimble SSE receiver. Then, execute
teqc -tr s -week 866 +nav fbar2240.96n fbar.bin > fbar2240.96o
Let's dissect the command line. First the -tr option flag tells
teqc that the target file(s) are from a Trimble receiver.
The argument to -tr is s (equivalent to just so), which tells teqc that the
native format is the RS-232 RT17 data stream and that you want to send translated
RINEX OBS to stdout. But the RT17 file fbar.bin, in general, is allowed
to contain both record types for both GPS observations and ephemerides.
The command line option +nav fbar224.96n tells teqc to dump any ephemeris
information in fbar.bin to the RINEX NAV file fbar2240.96n;
if there were no ephemeris records in fbar.bin, then fbar2240.96n will be
empty after execution is complete.
If you had had a Trimble *.dat file, fbar.dat, the analogous command line would
have been:
teqc -tr d -week 866 +nav fbar2240.96n fbar.dat > fbar2240.96o
Now, what about the option -week 866 (or using an alternative format
of -week 96:224)? By doing this, you are explicitly
telling teqc that the observation data starts in GPS week 866;
it may run on into GPS week 867 (or later), but teqc will track this. If you
had executed the shorter command
teqc -tr s +nav fbar2240.96n fbar.bin > fbar2240.96o
during the week of 11 Aug 1996 - 17 Aug 1996, and your CPU system time had
been set corrected, then teqc would have computed the GPS week and used that
(after issuing a warning to stderr: recall executing just
teqc
is one way for you to find out what GPS week teqc thinks it is).
Why must the GPS week be specified? It turns out that there is no information in the
Trimble RS-232 GPS observation records (and some other native formats) to indicate which
GPS week it is from; this is ancillary information that must be recorded external to
the contents of the observation records. (There is GPS week information
in the Trimble ephemeris records, but there is no guarantee that there will be
any ephemeris records in an arbitrary RT17 data segment, let alone an
ephemeris record in advance of all observation records.
A similar argument applies for Trimble *.dat files: there is no GPS week information
in Trimble's DAT observation records--though the GPS week appears in other records which
are usually in a *.dat file. Additionally, when using teqc with DAT files as
target files--not stdin--teqc will attempt to find a name-matching MES file
to help resolve the GPS week problem. But, again, there is no guarantee that a
matching MES file is present.)
Incidentally, the GPS week can be supplied by several formats when using the
-week option:
-week WEEK (WEEK = GPS week, e.g. -week 866)
You can also use a / (slash) as the delimiter instead of a : (colon).
Remember: you are specifying the GPS week when the data begins.
-week [YY]YY:DOY (YY = year, DOY = day of year, e.g. -week 96:228 or -week 1996:228)
-week [YY]YY:MM:DD (YY = year, MM = month, DD = day, e.g. -week 96:8:15 or -week 1996:8:15)
All or part of the RINEX header field PGM / RUN BY / DATE is filled in
automatically by teqc during translation. The program field is filled in
with the name of the executable (teqc in this case) and its current version
number.
The date is filled in by a query of the system time, and we are assuming
that the system time is set correctly. On UNIX systems, this date is UTC,
which is then written to the RINEX file. On Microsoft systems, this date
may or may not be UTC. For Microsoft Windows 95/98/NT systems,
the date should be set according to a specific time zone, or with
a known offset between local time and UTC. For these cases, the date
obtained should correctly be UTC.
For Microsoft DOS or Windows (or Windows 95/98/NT/2000/XP, in case teqc
cannot determine the OS), teqc will query for the environment variable
$UTC_MIN_OFFSET, which if set, should contain the numerical value of minutes
that should be added to the system time to yield UTC. The switches between
Daylight Saving Time and Standard Time will have to be done manually.
If this environment variable is not set, the system time will be queried
and put into the date field as "Lcl" = Local time.
Now examine the command line:
teqc -tr sn -week 866 +obs fbar2240.96o fbar.bin > fbar2240.96n
Here the argument to the -tr option flag is sn, i.e. your main interest
is the ephemeris information in fbar.bin, which is dumped to stdout as a
RINEX NAV file (and here redirected to the file fbar2240.96n). The
+obs fbar2240.96o option instructs teqc that if any observation records
are encountered in the target fbar.bin, they are to be decoded and written
as a RINEX OBS file fbar2240.96o. Again, the option -week 866 is needed
to determine the epochs of the observation data, not the ephemeris data.
Again, the analogous command line for a Trimble *.dat file would be:
teqc -tr dn -week 866 +obs fbar2240.96o fbar.dat > fbar2240.96n
If you execute the above commands for the RS-232 file fbar.bin and do not have the environment variables
$teqc_OPT or $teqc_CONFIG set (or if you do have them set but they do not contain
any -O.* or -N.* header modification options), then you will find that most
of the RINEX header fields in fbar2240.96o and fbar2240.96n are blank.
Why? Like the GPS week in RS-232 observation records, there are no fields in the Trimble
RS-232 data records to hold the type of information that would occupy these
RINEX fields. About the only fields that are filled automatically by teqc
are those for the initial RINEX VERSION / TYPE record (which are implied),
the default WAVELENGTH FACT L1/2 record (implied by the receiver type,
in this case), and the # / TYPES OF OBSERV record. However, you can override
these blank values by specifying your own -O.* and/or -N.* options
using the command line, $teqc_OPT, $teqc_CONFIG, or other configuration files.
This is using teqc simultaneously in edit and translate modes.
The above translation procedure can also be windowed. Currently, though,
fast search algorithms have not been written for any binary format,
so you must use an explicit windowing (windowing options
(6), (7), or (8)) or specify the window delta time from the start
(windowing option (2)).
The translation procedure can also be qc-ed. Here let's assume that
you have a Trimble *.dat file called fbar.dat. For the normal type of qc
operation, try something like:
teqc +qc -week 866 [-st 960811000000] +dh 24 -tr d \
where now, stdout will contain what you now expect from a qc-mode execution,
but the RINEX OBS file is still being output to the file fbar2240.96o using
the option flag +obs. The -st option is optional, indicated by the square
brackets. You use the explicit windowing (in this example,
windowing option (7) using both the
-st option and the +d* option).
+obs fbar2240.96o +nav fbar2240.96n fbar.dat | more
If translating to RINEX OBS,
an auto-identification feature of teqc may eliminate the need to
specify the input format. The auto-identification feature has been developed for
all the above formats except the Ashtech U-file (which always requires -ash u).
To make sure that teqc is able to identify a particular file, use
the +mdf option. Thus:
teqc +mdf fbar.dat
should return
probable format of fbar.dat: Trimble download
The assumed stdout for any translation is always RINEX OBS. Therefore
with the auto-identification:
teqc: ... exiting
teqc -tr d trimble.dat > RINEX_OBS
can be reduced to:
teqc trimble.dat > RINEX_OBS
The auto-identification will work most of the time but is not guaranteed!
This is because the auto-identification is based on reading only a small number of
bytes (usually only 1-4 bytes) at the beginning of the file.
This is probably most useful if you are testing files manually on the command
line. For use of teqc in scripts, use explicit receiver/format options.
To review, there are a few things to remember when using binary data:
Also, the time binning option can be used during translation.
For translation problems, etc., contact teqc technical contact for help.
Special Translator Considerations and Options
Section 16.
There are some translator options which are not specific to a particular
native binary format. There are
-L2 to indicate an L1-only (no L2 tracking) receiver
Using these options when needed helps set the default set of RINEX
OBS observables. For receivers that are both
L1-only and P-codeless, use both -L2 and -P.
-P to indicate a P-codeless receiver
Two useful options that can be used anytime, but are sometimes very
helpful prior to translating, are the metadata extractions options
+meta and +mds--which also work with RINEX as the target
files. For example,
teqc +meta trimble.dat
should return a 19-line metadata summary about the Trimble DAT file trimble.dat
(assuming that the auto-identify function works correctly). Executing
teqc +mds trimble.dat
returns "metadata short"--a shorthand for just the start and end times of the file, plus
the file size in bytes. If either of these terminate in a line like:
week: ####
this is an indication that you should use the -week option to set the starting
GPS week to the indicated value, e.g.
teqc -week #### +meta trimble.dat
There are several translator options which are specific to a particular
native binary format.
Also, when translating *.dat from P-codeless receivers (e.g. SD, STD, SST), you probably
will have to use the -P option. This informs teqc that the data
has no P-codes, and it performs bit-cleaning on certains flags. Without this
bit-cleaning, you are likely to only get the L2 observable.
When using the newest generation of receivers (e.g. SSE, SSi, 4700, 5700), a few
epochs of squared L2 data for a particular SV may be reported. Normally, these
epochs are translated with the appropriate bit-1 of the LLI flags added to
the RINEX OBS file with the (squared) L2 data (see
teqc's handling of wavelength factors for more
information). These L2 observables can be entirely removed during translation
by using the option -L2_2, i.e. no squared L2 data is passed to the
RINEX OBS file.
When using a Trimble DAT file as a target file (and not stdin), teqc attempts to find
a Trimble MES file with the same path and name prefix. The name matching uses:
*dat -> looks for *mes
*DAT -> looks for *MES
If a matching MES file is found, it is read to obtain the starting GPS week and
certain metadata (though there is no guarantee that this information is correct).
The result of various option combinations is:
For TurboBinary data collected with firmware dated before about 1 Dec 92 (version 2.5
or earlier), it is necessary to apply a correction to obtain valid pseudoranges.
To activate this correction, use the option +TB_ca_fix.
For TurboBinary data collected with a Benchmark ACT receiver, you may want to
try the -aoa tbY option to generate the RINEX OBS
file. This will use the C/A-derived L1-phase value for the RINEX L1, rather
than the noisier Y1-codeless derived L1-phase value.
Also, the RINEX L1 observable from teqc may be noted to vary slightly
(by up to 1 cm or so) from the L1 observable reported by other translators.
This results from the use of the L1-phase value reported in the P1-code data block,
rather than the L1-phase value reported in the C/A-code data block. Preliminary
testing at MIT suggests that the L1-phase value in the P1-code data block
results in a slightly lower RMS. For the time being, teqc will
continue to report this L1-phase value, though you can switch to the
L1(C/A) by using the +CA_L1 option.
For Ashtech download file sets, teqc may only work correctly
for "Version: 3" type downloads. For example, the older "Version: 1" and "Version: 2"
type downloads will not translate correctly at the present time, and the Berne
ASRINEXO or the Ashtech ASH2RIN translators should be used, or
try the Ashtech convert.exe program to change the B-file to a Version 3 B-file.
A bug in the some earlier firmware for the Z-XII resulted in the millisecond clock
resets being applied an epoch too late. If you notice periodic millisecond slips
(occurring just prior to the reported clock reset times), try using the option
+Ashtech_old_clk_reset during translation. This should remove this receiver
firmware artifact from the data.
Wavelength Factors: What teqc Does With Them
Section 17.
Wavelength factors, i.e. specifying whether L1 or L2 is being recording in
a full-wavelength or half-wavelength (squaring mode), can be done in various
ways in RINEX. In short, 1) there is a required RINEX header record WAVELENGTH
FACT L1/2 specifying the default wavelength factors for L1 and L2 for all SVs,
2) there can be other WAVELENGTH FACT L1/2 records specifying the a different
set of wavelength factors for specific SVs, and 3) there can be the use of
bit-1 in the LLI flag of the L1 or L2 observations to indicate the opposite
state of wavelength factor from the last WAVELENGTH FACT L1/2 record for
a specific SV. The possible set of values for any WAVELENGTH FACT L1/2 record
is "1 0", "1 1", "1 2", "2 0", "2 1", and "2 2". Setting bit-1 of the
LLI flag indicates a full-wavelength mode if the last WAVELENGTH FACT L1/2 record
for that frequency and that SV--somewhere earlier in file--was set at "2"
(half-wavelength). Likewise, setting bit-1 of the LLI flag indicates a half-wavelength
mode if the last WAVELENGTH FACT L1/2 record for that frequency and that
SV--somewhere earlier in the file--was set at "1" (full-wavelength).
The methodology used by teqc is a simple specific subset of all of the possibilities
for RINEX, but still retains all the same information. On output (either when translating
from native binary formats to RINEX or RINEX to RINEX), only the default
WAVELENGTH FACT L1/2 header record will appear and only the L1/L2 states of
"1 1" or "1 0" are used. In other words, the default setting reported in the RINEX
file header is always full wavelength for L1 and L2 (if present), even for squaring receivers.
Specific half-wavelength observations are indicated by setting the appropriate bit-1 of
the LLI flag on the L1 or L2 observations. Period.
During translation, you have the option of excluding all half-wavelength observations.
To do this, include either -L1_2 or -L2_2 to exclude squared L1 or L2, respectively.
This works either when translating native binary formats to RINEX or during any
RINEX to RINEX operations. The default settings of teqc for wavelength factors are
+L1_2 and +L2_2, i.e. include all half-wavelength observations.
Basic Commands: A Review
Section 18.
The following examples assume that the shell environment variables $teqc_OPT and $teqc_CONFIG
are unset or empty:
Using teqc in Scripts: Substitution for Batch Mode
Section 19.
Because teqc is 100% non-interactive, it is very well suited to be used in scripts and to be run in background. In fact, this is precisely the reason it is designed to be 100% non-interactive. Let's look at a simple script to translate Trimble *.dat files to RINEX and then qc the resulting RINEX files:
#!/bin/ksh
for file in $*
do
echo $file
teqc -O.int 30 -tr d +nav ${file%dat}97n $file > ${file%dat}97o
teqc +qc -set_mask 15 -plot ${file%dat}97o > ${file%dat}qc
done
#end of script
Make sure the script is executable, i.e. execute (in UNIX) chmod 755 script,
where script, say, is the name of your script file. To use it
-
script *.dat
If you wish to suppress the short report segment in the report (the *.97S file), include a -s on the qc command line. If you don't want any qc report file, include a -report on the command line. There is no way to suppress the short report segment going to stdout by command line option, but you can always use a > /dev/null on UNIX to eliminate the stdout.
Obviously, this script (as written) creates RINEX files named correctly according to the Berne naming conversion for *.dat files collected only in 1997, though the script will function for most *.dat files.
Notice that the GPS week has not been specified. For most *.dat files (at least from Trimble receivers with recent firmware), one of the first records usually contains the GPS week that the data starts. If this record is missing or is corrupted, then the resulting RINEX OBS file will probably have the wrong dates for the observations, leading to a poor qc report. For these rare *.dat cases, you must explicitly state the GPS week using the -week option.
Differences between teqc's qc mode and original UNAVCO QC
Section 20.
This section is only for those who are familiar with the original UNAVCO QC program (which is no longer supported) and are making the transition to the new teqc +qc.
Interface Differences:
- replacement of file qc.inp with teqc command line options, or equivalent format in environment variable $teqc_CONFIG, or in one or more configuration files which are accessed with the -config filename option; all options have a reasonable default value so the user need not be initially concerned with the details
- elimination of file qc.fil for batch modes; use a command line script instead
- elimination of auxiliary files like qc.tim or qc.sym
- roughly,
- original QC stdout is like the teqc +qc *.YYS qc report file
- original QC *.YYS file is like the teqc +qc stdout (qc short report segment)
- (nominal) one pass of files in teqc [original QC often required two complete passes of each RINEX OBS file]
- handling of NAVSTAR GPS, GLONASS, Galileo, Beidou/Compass, QZSS, IRNSS, and SBAS [original QC designed for NAVSTAR GPS only]
- well-defined symbol hierarchy for ASCII time plot [original QC had only a partially defined symbol hierarchy]
- cubic spline xyz fits of SV orbits for elevation, azimuth estimates [original QC used direct linear fits of elevation, azimuth which were only good for stationary antennas and were not smooth; algorithm occasionally resulted in large errors in azimuth]
- improved multipath algorithm
- improved detection and reporting of observation data gaps [original QC often did not detect and report long data gaps for individual SVs, and had no means of reporting short data gaps for all SVs]
- correct identification of SV data below elevation mask [original QC often falsely reported epochs below elevation mask w/ data, when, in fact, the receiver stopped tracking when the SV was well above the elevation mask]
- correct count of ionospheric delay slips and "observations per slip" [original QC would count the first observation w/ both L1 and L2 as an SV started to be tracked again after it had been observed and then set as an ionospheric delay slip]
- satellite elevation and azimuth accounts for WGS 84 ellipsoidal Earth model [original QC assumed spherical Earth model, resulting in elevation errors up to 1/5° for mid-latitudes]
- more accurate tally of expected number of observations for each SV [for some data sets, original QC sometimes reported more observations than expected, resulting in "%" values exceeding 100%]
- sign of clock resets shown on ASCII time plot [original QC did not shown the sign of the clock reset]
- correct reporting of indicators in ASCII time plot [original QC often did not show some clock resets, sometimes incorrectly showed a clock reset to occur when there was none, and other minor problems with indicators]
- does not produce any unneeded auxiliary files (like AUXFIL or temp.orb)
Interpreting teqc's qc Mode Output
Section 21.
The quality check output from teqc is in two portions, the short report segment and the long report segment. The short report segment include an ASCII time plot and a summary report on various parameters. The long report segment gives a more detailed breakdown on some of these parameters either by SV or by elevation (if qc full). In the short report segment, one of the most compact pieces of information from a qc output is the ASCII time plot. In this plot, a visual summary of various types of quality indicators are displayed for each satellite as a function of time. The SV PRN number is displayed on both the left and right side of the plot. The width of the ASCII time plot is controlled by the -w[idth] option, and is normally set to 72, though it can vary from 1 to 255; with a width of 72 and 24-hours worth of observation data, each ASCII character "bin" represents exactly 20 minutes of time. Each character shown in each spot in the ASCII time plot is the most significant item of note that took place for all of the observation epochs represented by that bin, according to a well-defined symbol hierarchy.
A listing of the entire ASCII plot symbol table can be dumped to stdout by executing:
-
teqc ++sym
- C
- a clock slip occurred; a clock slip is an MP1 and MP2 slip that occurred for all satellites being observed (tracked) and had a value that was the same integral number of milliseconds to a resolution specified by -msec_tol in milliseconds; detection is turned off with -cl option
- m
- similar to a clock slip, but only some (i.e. not all) satellites being observed (tracked) had an MP1 or MP2 slip that was an integral number of milliseconds, or the integral number was different for the different satellites; note: if the millisecond slip tolerance is 1e-2 (see -msec_tol), then there is roughly a 2:100 chance that a random MP1 or MP2 multipath slip will be tagged as an m, rather than M, 1, or 2 (see elsewhere in this table)
- I
- ionospheric delay (phase) slip occurred; detection is turned off with -ion option
- M
- both MP1 and MP2 (code) slip occurred, but was not integral number of milliseconds; detection is turned off with -mp option
- 1
- only MP1 (code) slip occurred, but was not integral number of milliseconds; detection is turned off with -mp option
- 2
- only MP2 (code) slip occurred, but was not integral number of milliseconds; detection is turned off with -mp option
- -
- for qc full, satellite was above elevation mask, but no data was apparently recorded by the receiver; for qc-lite (no ephemeris information), the data gap must also be less than the maximum specified (see argument of -gap_mx in minutes)
- +
- (qc full only) satellite was below elevation mask and a complete set of phase and code data was collected
- ^
- (qc full only) satellite was below elevation mask and a partial set of phase and code data was collected
- .
- phase and/or code data for SV is L1 and C/A only & A/S is off; if qc full, satellite was above elevation mask
- :
- phase and/or code data for SV is L1 and P1 only & A/S is off; if qc full, satellite was above elevation mask
- ~
- phase and/or code data for SV is L1, C/A, L2, P2 & A/S is off; if qc full, satellite was above elevation mask
- *
- phase and/or code data for SV is L1, P1, L2, P2 & A/S is off; if qc full, satellite was above elevation mask
- ,
- phase and/or code data for SV is L1 and C/A only & A/S is on; if qc full, satellite was above elevation mask
- ;
- phase and/or code data for SV is L1 and P1 only & A/S is on; if qc full, satellite was above elevation mask
- o
- phase and/or code data for SV is L1, C/A, L2, P2 & A/S is on; if qc full, satellite was above elevation mask
- y
- phase and/or code data for SV is L1, P1, L2, P2 & A/S is on; if qc full, satellite was above elevation mask
- L
- Loss of Lock indicator was set by receiver for L1 and/or L2; detection is turned off with -lli option
- _
- (underscore) (qc full only) satellite between horizon and elevation mask with no data collected by receiver; indicator is turned off with -hor option
- ` '
- (blank) qc lite: no satellite tracked; qc full: no satellite calculated to be above horizon (+hor option) or above mask (+hor option or both -hor and +mask options) (see also -set_hor and -set_mask options)
A/S on: _____--oooooooooooooooooo+++++__
A/S off: _____--******************+++++__
1 2 3 4 5 6
At time (1), the SV rises above the horizon (0°). At time (2), the
SV rises above the elevation mask (20°), but the receiver doesn't
start tracking until is rises to 25° at time (3). Between times
(3) and (4) all phase and code observables are collected by the receiver
(L1, L2, C/A, and P2 for A/S on; L1, L2, P1, and P2 for A/S off). Data
continued to be collected as the SV dropped below the elevation mask
at time (4) until the receiver stopped tracking at an elevation of 5°
at time (5). The SV finally sets below the horizon at time (6).
For qc lite, the above SV symbol track would appear as:
A/S on: ooooooooooooooooooooooo
A/S off: ***********************
1 2 3 4 5 6
as teqc as no information about the elevation of the satellite.
If the -hor option is set, the above qc full SV symbol tracks would then appear as:
A/S on: --oooooooooooooooooo+++++
A/S off: --******************+++++
1 2 3 4 5 6
so that you can determine everything you could with +hor set, except for
the rise and set times of the SV at times (1) and (2), respectively. For
qc lite, the SV symbol tracks would remain the same as before, since the
options -hor and +hor are meaningless.
Any additional symbols that occur in an SV symbol track not in the above examples fall into a "not so good" category, though seeing a lot of - symbols in a qc full output is also "not good". Let's take a look in more detail at what these other indicators might be.
The first "not so good" category could generally be considered "missing data". As mentioned above, the worst missing data indicator (qc full only) is the -, which means that the SV was calculated using the supplied ephemeris to be above the elevation mask, but no observation data was present for this SV. In other words, all data is missing.
Following the - "all data missing" indicator are the partial missing data indicators. For example, if A/S is normally on, seeing ; or , indicates that there was at least one observation epoch in that bin where L2 observables (i.e. L2 and P2) were missing. You are unlikely to see a y, as this would require a Y-code receiver (capable of tracking P1 while A/S is on). (An exception to this is when qc-ing data from an Ashtech receiver like the Z-XII. The C/A and P1 pseudorange observables are reported for all SVs, regardless of whether A/S is on or off.) If A/S is normally off, seeing : or . indicates that there was at least one observation epoch in that bin where the L2 observables were missing. A ~ indicates that, for some reason, the receiver could not track P1, even though A/S was off, so the receiver instead recorded the C/A observable.
If you are using a P-code (not a Y-code) receiver that reports C/A and P1 pseudoranges for each SV at each epoch (like the Ashtech Z-XII), you may want to use the -Y option, which informs teqc that this is data not from a Y-code receiver, and to treat the qc analysis as though from a P-code receiver.
-
Special Treatment of Data from Codeless Receivers
A/S on: _____--,,,,,,,,,,,,,,,,,,+++++__
A/S off: _____--..................+++++__
1 2 3 4 5 6
which (correctly) indicates a lack of L2 and P2, even though the observable
P2 is not possible (and thus never present) and L2 may be always present.
You can inform teqc that the data is to be interpreted as though it were collected by a codeless receiver by including a -P option (and, of course, the default option in +P). In this case, the absence of P-codes is ignored for statistics and the data indicators change collapse to just two possibilities (from the original eight possibilities):
- .
- phase and/or code data for SV is L1, C/A; if qc full, satellite was above elevation mask
- o
- phase and/or code data for SV is L1, C/A, and L2; if qc full, satellite was above elevation mask
A/S on: _____--oooooooooooooooooo+++++__
A/S off: _____--oooooooooooooooooo+++++__
1 2 3 4 5 6
i.e., there is no difference whether A/S is on or off. You will probably see
an occasional . data indicator:
A/S any: _____--ooo.ooooooo.oooooo+++++__
1 2 3 4 5 6
indicating one or more observation epochs where the observable L2 is missing.
A listing of the entire ASCII plot symbol table modified for codeless receivers can be dumped to stdout by executing:
-
teqc -P ++sym
-
Other Indicators
A/S on: _____--Iooooooooooooooooo++I+I__
A/S off: _____--I*****************++I+I__
1 2 3 4 5 6
In this example, ionospheric delay slips are detected shortly after the receiver starts
tracking the SV and as the SV is close to setting.
The other common type of slip is for one or both of the multipath (code) observables, MP1 and MP2. Again, these frequently occur at low elevations. There are three symbols: M for slip on both MP1 and MP2, 1 for slip on MP1 only, and 2 for slip on MP2 only. Notice that the multipath slip indicators take a lower priority in the symbol hierarchy, so if an ionospheric delay slip and multipath slip occur at different observations epochs within the ASCII bin, only the I symbol will be seen (assuming that the option configuration is +ion and +mp). If you use -ion to suppress ionospheric delay slip detection, the above SV symbol tracks might now appear as:
A/S on: _____--Mooooooooooooooooo++2+M__
A/S off: _____--M*****************++2+M__
1 2 3 4 5 6
Interestingly, the occurrence of ionospheric delay or multipath slips in the
recorded observations is not only a function of the antenna environment
(meaning all the way back to the transmitting SV), but is also a function
of the specific receiver. Due to internal slip detection and phase
observables resets, data from some receivers show virtually no ionospheric delay
slips and nearly all multipath slips. Other receivers do not reset the
phase observables, and show a larger number of ionospheric delay slips than
multipath slips.
The last type of slip is the "n-millisecond clock slip", where the value of n is usually 1, denoted by the symbol C in the SV symbol track. This slip is reported if all SVs being tracked have slips in MP1 and MP2 equivalent to the same number of integral milliseconds, to a tolerance specified by the -msec_tol option. If you set the tolerance to 1e-17 (milliseconds), you probably will never see any of these slips. However, the default tolerance is 1e-2 (milliseconds), and with this value the qc mode of teqc seems pretty capable of detecting these slips if they are present.
What does it mean if you see the C symbol in an SV symbol track? There are several causes, some more harmless than others. If the C symbol is preceded by an observation gap (no data collected for any SVs), there may be one or more millisecond clock resets missing from the observation epoch time tags. Also, if you use teqc to splice two RINEX OBS files together and clock resets occur in the first file, a C will occur at the first epoch of the second file (since the teqc splice does not modify the observation times in the second file to account for the accumulative clock resets in the first file). In other cases, however, if the observation epochs are fairly continuous, and the C indicator is appearing two or more times in 24-hours of data, there is a strong possibility that the receiver was not healthy.
This latter possibility (that the receiver was not healthy) prompted the inclusion of another slip indicator, the "n-millisecond multipath slip". It was observed that some receivers get so unhealthy that, even though n-millisecond clock slips should be occurring (i.e., given the specific receiver, no millisecond clock resets are present, even though they were expected) none were being found because the multipath slips for different SVs had different millisecond equivalents. In short, the value for n was not a constant for all SVs being tracked. In this case, the m symbol is used. There is some probability (roughly about 2 : inverse of millisecond tolerance) that a random multipath slip will be recorded as an m instead of as a M or 1 or 2; so, treat the occasional m as you would any multipath slip. However, if you start to see lots of m symbols, especially if you have seen C symbols being reported in the data from the same receiver, suspect that the receiver is ailing.
The next "not so good" category is presence of data gaps. There are really two types of gaps. One is a complete observation gap for all SVs. This can be caused perhaps by the receiver being turned off and later turned back on, by a loss of all data for a period of time either internal to the receiver itself or due to a communication breakdown with the receiver. Currently, a complete observation gap is not indicated in the SV symbol tracks, except (on occasion) if they are present in a qc lite run.
The other type of gap is the SV data gap, where the receiver stops tracking an SV for a period of time even though it is well above the horizon or elevation mask, perhaps due to an obstruction. The exact definition of an SV data gap depends on whether teqc is running in a qc full or qc lite mode. For qc full, an SV data gap occurs if there are one or more missing observation epochs while the SV is above the elevation mask. For qc lite, an SV data gap occurs if tracking stops for more than the specified minimum time (-gap_mn, again) and then tracking resumes before a specified maximum time (see -gap_mx option). The symbol used in the SV symbol track is now -, so an SV data gap might look like:
A/S on: _____--Ioooooooooo--ooooo++I+I__
A/S off: _____--I**********--*****++I+I__
1 2 3 ab 4 5 6
which occurred at the interval (ab). The meaning is really the same
as the interval (23), i.e. the SV was above the elevation mask, but no
data was received.
The only other indicator for SV data, low in the symbol hierarchy, is the "Loss of Lock" indicator, L, which is used when the receiver issues a loss of lock for either the L1 or the L2 observable. A large number of L symbols may indicate an unhealthy receiver or antenna. This should rarely, if ever, be seen in the ASCII time plot.
Following the SV symbol tracks are one or four more, depending on whether you are using qc lite or qc full, respectively. For qc lite, there is a symbol line labeled "Obs". This records the maximum number of SVs that were tracked by the receiver for each bin using a hexadecimal representation. For example, if there is a 7 on this line, then 7 SVs were tracked for at least one observation epoch represented by that time bin; if there is a b on this line, then 11 SVs were tracked for a least one observation epoch represented by that time bin; and so on. If no SVs were tracked, a (blank), rather than 0, is shown. If one or more s are present on the "Obs" line in a qc lite run, this is your best indicator that a complete observation gap has occurred.
For qc full runs, the "Obs" line is replaced by four lines, labeled "-dn", "+dn", "+XX", and "Pos". The "+XX" line is the one most like the qc lite "Obs" line; the XX is replaced by the elevation mask in degrees (rounded to the nearest degree) and indicates the maximum expected number of SVs that are above the elevation mask, according to the supplied ephemerides, again using a hexadecimal notation. The difference between the qc lite "Obs" line and the qc full "+XX" line is the difference between reality and theory: "Obs" shows what was seen, where "+XX" shows what could have been seen (above the elevation mask).
The discrepancy between reality and theory is recorded in the "-dn" and "+dn" lines, which are the SV tracking discrepancy counts, and record the two bounds of the discrepancy given the current elevation mask. These lines can be thought of as showing the "good new/bad news" to the number of SVs not tracked. The line "-dn" records the minimum discrepancy of all observation epochs for that time bin while the line "+dn" records the maximum discrepancy of all observation epochs for that time bin. The discrepancy count is also shown in hexadecimal notation, with ' ' (blank) for 0. As of 2009 Mar 9, there is also a reverse discrepancy indicator, '+', meaning that there is data for one or more SVs below the elevation mask.
For the discrepancy lines to work correctly, the option -max_rx_SVs must be set correctly. This states the maximum number of SVs that are capable of being tracked by the receiver, and currently has a default value of 12. If a complete observation gap occurs with qc full, a group of c characters will be shown (c is hexadecimal for 12), at least on the "+dn" line, and if the gap is large enough, on the "-dn" line as well.
By way of example, let's suppose there is a '1' on the "-dn" line; this means that every epoch in that time bin is missing at least 1 SV that could have been tracked. A '2' on the "-dn" line means that every epoch in that time bin is missing at least 2 SVs that could have been tracked, and so on. A ' ' (blank, i.e. 0) on the "-dn" line means that there is at least one epoch in that time bin where all possible SVs (given the receiver's channel limit) were being tracked.
On the "+dn" line, a 1' means there is at least one epoch in that time bin that is missing 1 SV that could have been tracked; a '2' means there is at least one epoch in that time bin that is missing 2 SVs that could have been tracked; and so on. A ' ' (blank, i.e. 0) on the "+dn" line means that every epoch in that time bin had all possible SVs (given the receiver's channel limit) being tracked.
When populated with non-zero entries (i.e. not ' ' or blank), the "-dn" and "+dn" lines with "-dn" on the top form a simple type of histogram, for example, Kunming IGS site, 2007 Jan 17 (with a TurboRogue receiver with only 8 channels):
-dn| 1 12223321 122111123 11321111112211211 1111 |-dn +dn|1211 1 11121 222421335433342222323335311223332122322232223211223 11 |+dnfollowed by the theoretical SVs that could have been tracked on the "+XX" line; again, Kunming IGS site, 2007 Jan 17:
+10|889877777777777668aa989aabbbbbaaaaaa9aaaa97899bbba9aaaaaaaaaaa9999aa8888|+10
The "Pos" line records the success or non-success of calculated code positions for the antenna at the different epochs. Generally, you should see an o recorded for each bin in which a position calculation was successful.
The last symbol line in the ASCII time plot is labeled "Clk". This line represents all millisecond receiver clock resets present in the observation time tags with either a + or - symbol, meaning either a positive or negative millisecond receiver clock reset was detected, respectively. Another symbol which may be placed on this line is ^, which is lower in the clock symbol hierarchy that either + or -, and indicates at least one missed observation epoch in that time bin, though a correct value of the observation sampling interval must be set (see -O.int option) for this to work correctly. This symbol was added to help reveal two things: 1) the existence of "micro-gaps", i.e. missing data periods less than that set by the -gap_mn option, and 2) to identify short gaps during which a millisecond clock reset may have occurred. For example, if a portion of the "Clk" symbol track is:
Clk: + + + ^^ + + + ^+ + + + +
12 3
then you can suspect a missing (positive) millisecond receiver clock reset
at time (1) due to the regularity of the rest of the identified resets and
the missing epoch indicator ^, and other missing observation epochs at
times (2) and (3). Other micro-gaps might exist in the data, but their
presence would be hidden by the + symbols.
Incidentally, another "micro-gap" indicator exists for qc full runs on the "+dn" line. Since this is maximum discrepancy between the number of SVs that could have been observed and what were actually observed. However, for missing observation epochs (no SVs observed), rather than placing a count of just "SVs that could have been observed" based on the ephemerides, teqc places a count of the maximum allowed by the receiver. So, for a receiver capable of tracking 12 SVs (see -max_rx_SVs option), you will also see a c (hexadecimal for 12) on this line when missing a observation epoch.
Following the "Clk" line of the ASCII time plot is a scale bar with tick marks. The separation between tick marks is indicated a few lines lower at "Time line window length". The tick marks should occur at even values of the tick interval. For example, if the time window starts at 01:39:30.000 (1h 39m 30s) and the tick interval is 3 hours, the tick marks will be placed at 03:00:00, 06:00:00, 09:00:00, and so on, to the best resolution possible on the ASCII plot. The tic interval is self-scaling, from 0.1 seconds to 7 days, depending on the length of the time window.
At the end of the ASCII time plot, the beginning and end time and date follow at the ends of scale bar. Seconds are only printed out if they are non-zero.
Following the ASCII time plot in the short report segment is a report summary. First is a listing of the name of target files, and if qc-full, the RINEX NAV files used.
The bounds of the time window is then shown. If the times of the first and/or last observation epochs do not match the bounds of the time window, these epoch times are shown as well.
If the configuration environment variable or any configuration files were used, these are listed next.
If the observation interval is non-zero, this is given.
The total number of satellites (SVs) with any type of observations is then given. This is followed by a list of missing SVs, up to the maximum set by default (probably 32), or using the -PRNs option, for each satellite system that had any members. Finally, if doing qc-full, a list of SVs that did not have ephemeris information is given.
The number of SVs which can be simultaneously tracked by the receiver is then given. This currently has a default value of 12, or can be changed using the -max_rx_SVs option.
If the observation interval is non-zero, the total number of possible observation epochs in the time window is given. This is followed the number of epochs that actually had "complete observations" from at least one SV.
The definition of a "complete observation" is important, so it will be defined in detail here. In order for an observation from a GPS SV to be "complete", it must have :
- P1 or C/A code data
- P2 code data
- L1 and L2 phase data
- S/N for both L1 and L2 be at or above specified minima
- if qc-full, an SV elevation at or above the elevation mask
If the multipath option was set (which it is by default), the average multipath RMS is given. If a moving average window was used (which is used by default), information about the length of this window is given. If qc-full, the multipath RMS is only for observations above the elevation mask.
The number of detected millisecond receiver clock resets is then given. This is followed by the total drift of the receiver clock, an estimate of the average receiver clock drift, and, if the number of clock resets is non-zero, the average time between resets in minutes.
The length of time required before an SV data gap is reported is given next. If qc-lite, a maximum time is also given.
If the detection of n-millisecond clock slips is on (+cl option), the number of epochs with n-msec clock slips is reported. This occurs when all SVs with multipath observables must have multipath slips of the same size to within a specified tolerance (fraction of millisecond).
This is followed by the number of other n-millisecond multipath slips which do not qualify as n-millisecond clock slips. Given a non-zero tolerance, there is a certain probability that a few multipath slips fall within the tolerance. Therefore, a second value is given in parentheses and this is the total number of multipath slips for the time window (no elevation mask cutoff). If the tolerance is set to 1e-2 millisecond, ratios on the order of 2:100 are expected due to chance. Significantly higher ratios are an indication of a sick receiver.
Next if doing the derivative of the ionospheric delay observable (+iod) or multipath (+mp), counts of the number of IOD and/or multipath slips is given. If qc-full, this is further broken down according to elevation mask. In order to qualify as a count here, both MP1 and MP2 must slip (though not necessarily by the same amount) at the same epoch for a particular SV.
Finally, a "SUM" line in printed, showing the start and end times of the window, the length of the time window in hours, the observation interval in seconds, the number of possible observations (if qc-full), the number of complete observations, the ratio of complete to possible observations as a percent (if qc-full), the multipath RMS values for MP1 and MP2 (limited by the elevation mask if qc-full), and lastly the "observations per slip".
The "observations per slip" needs a bit of explanation. First, "observations" means "complete observations" as defined above, including the elevation mask if qc-full. Second, "slip" means "either an IOD slip and/or both MP1 and MP2 slips occurred during the epoch having a complete observation for this SV".
Some additional information for each SV can be included in the short report segment by using the +ssv option. Similar to the main SUM line, shown for each SV with observations are: the expected number of observations, the number of complete observations, the number of deleted observations, ratio of complete to possible observations, multipath RMS values for MP1 and MP2, and the observations per slip. The long report segment contains a further breakdown of information by SV and by elevation (if qc-full). In the long report segment, individual SVs are often referenced. The leading character indicated the satellite system:
-
G: NAVSTAR GPS (US) system
R: GLONASS (Russian) system
E: Galileo (European) system
C: Beidou/Compass (Chinese) system
J: QZSS (Japanese) system
I: IRNSS (Indian) system
S: SBAS (e.g. WAAS, EGNOS)
Next is a breakdown of observations per SV. If doing qc-full and the SV had ephemeris data, the values in the first four columns have meaning:
- #+hor:
- number of observations above the horizon for this SV
- <ele>:
- mean elevation of SV above the horizon for epochs with observations
- #+mask:
- number of observations above the elevation mask for this SV
- <ele>:
- mean elevation of SV above the elevation mask for epochs with observations
- #reprt:
- number of observations with any data reported for this SV
- #compl:
- number of "complete" observations reported for this SV (see definition in "Short Report Segment")
- L1:
- number of L1 observations for this SV
- L2:
- number of L2 observations for this SV
- P1:
- number of P1 observations for this SV
- P2:
- number of P2 observations for this SV
- CA:
- number of C/A observations for this SV
If doing qc-full, any SV not having ephemeris data but having observation data of any kind is identified with a "*".
Next, a summary tally is given. If doing qc-full and a site position was found, the total number of observation below the elevation mask is given (i.e., number of observations excluded because of low elevation). Next, reasons for incomplete observations (above the elevation mask if a site position was found) are summarized: missing L1, L2, P1 or C/A, or P2, or poor S/N for L1 or L2.
Following this is the number of observations reported with any code or phase data. (Note: If an SV has only, say, Doppler data, it will not be reported here.) This is followed by the number of observation deleted for any reason: below elevation mask (if qc-full), missing code or phase data, and/or poor S/N. Finally, the number of complete observation is given.
Next, repeat of the receiver clock offset and drift statistics is given.
Next there is one of several elevation histograms, from the horizon angle (default of 0°) to the zenith (90°). These need some explanation as to the style of presentation. The x- or horizontal labeling of the histograms may use something like:
5=% 1|m 15=% 2|m
In these cases, the histogram is really then a dual histogram, using the "=" symbol
to show percentages and the "|" symbol to show meters, and a "#" symbol to show
where both histograms occur. Hence, histogram lines like:
##############|||||||| ##======would show about 7% and 1.1 meters on the first line and 4% and 0.1 meters on the second line. A ">" at the extreme right of the histogram bar indicates that the bar extends off scale to the right. The y- or vertical labeling of the bins is in degrees from the horizon to the zenith.
The first histogram in for the ionospheric delay. Currently then is not a measure of the ion RMS in the qc (hence all the
Beneath this is the MP1 RMS summary per SV and the gross statistics for all SVs, followed by the MP1 RMS histogram. The summary per SV shows the number of observations above the mask angle (default of 10°) and how many were deleted for MP1 observations (due to lack of one or more observables), followed by the mean elevation (in degrees), and the MP1 rms in meters. There is also a breakdown of MP1 slips above and below 25° of elevation, and what the receiver reported for slips in L1 and L2. The individual SV MP1 statistics are followed for the gross statistics for all SVs. The elevation statistics and histogram shows the total number of observations per elevation bin, the number of MP1 slips detected, and the mean MP1 rms numerically, followed by the histogram bars for MP1 rms in meters (as "|" symbol) and the percentage of observations that had MP1 slips (as "=" symbol). (Recall that if "|" and "=" overlap the "#" symbol is used.)
The MP2 summary follows and is analogous to the MP1 summary.
The final two histograms are for the L1 and L2 SNR values. These are also dual histograms, showing the mean SNR with the "|" symbol and the one-sigma value with the "=" symbol. (Recall that if "|" and "=" overlap the "#" symbol is used.) In these histograms, both scales use the same units, which are arbitrary. If a manufacturer's format binary file was used as input for the qc, or a RINEX OBS file with observables S1 and/or S2, then the units are receiver specific. If a RINEX OBS file without S1 or S2 is used, then the scaled RINEX 0-9 flag for SNR is shown.
"Strange" Behavior
Section 22.
-
If doing qc full mode (i.e., NAV file(s) supplied either
implicitly or explicitly or using binary target files)
the qc full>>>>>>>... indicator may, on some file data sets, pause part way
through and then appear to keep going. Don't panic. Everything is operating
normally. Here's what is happening:
The qc full mode really starts off in a qc lite mode. When using target files (as opposed to stdin), teqc has the luxury of being able to go to any arbitrary location in a file. The first primary goal of the a qc full run is to find the pseudorange point position of the antenna. A certain minimal amount of information is required before this is possible. There must be a certain number of SVs reporting pseudorange data for a given epoch and teqc must have ephemeris information for those SVs. Occasionally, this does not happen early in the file. When it does happen, teqc starts re-reading and re-processing the target file now knowing the antenna position. If plot files have been requested, this is when they are written. The pause you are seeing is the time it takes teqc to go back and re-do all these items and get back up to the epoch when the point position was determined. - If doing qc full mode (i.e., NAV file(s) supplied either implicitly or explicitly or using binary target files) and the plot option is turned on, but no position was found (for whatever reason), no plot files are created. This is a consequence of the logic used for the qc full mode (see above item).
- Direct qc of binary files produces a slightly different result than qc of RINEX files. This is due to the direct qc of binaries being designed for direct data streams from receivers, and thus lacking the capability of treating the data stream as a file. Also for direct qc, the plot file information regarding the elevation and azimuth of each SV will begin at the first epoch where both the antenna position and an SV ephemeris are both known, whereas for qc of RINEX files, the elevation and azimuth information will be computed for the entire window of interest. This behavior can usually be correctly by pre-loading a RINEX NAV file, say, from the same site and the previous day, using the -nav option.
- If doing any qc mode, the user intends to input NAV file(s), but uses +nav filename instead of -nav filename, the original file filename may be re-opened and destroyed. One safeguard has been implemented to help prevent this when the qc command is ordered:
- When using the Borland DOS shell version of teqc, ASCII lines written to files by teqc terminate with a newline ('\n' = CTRL J = 0x0a). ASCII lines spewed to stdout and then redirected to a file will be terminated with a carriage return ('\r' = CTRL M = 0x0d) and then the newline. This added carriage return is apparently being done by the DOS shell.
-
teqc [options] +qc [options] +nav filename [rest_of_command]
The WatCom DOS shell version of teqc results in the extra carriage returns being added in both cases, both as files written by teqc and stdout redirected to a file.
As usual, if you ftp the DOS-created files to UNIX in ASCII mode, the added carriage returns are removed; if you ftp the same files to UNIX in binary mode, the added carriage returns are left in the files.
Last modified: 2024-05-31 14:43:28 America/Denver