[teqc] helpful tip of week 1904

Lou Estey lou at unavco.org
Wed Jul 6 08:03:46 MDT 2016

This week's tip: the '-week' option

The '-week' option is perhaps the most overused, misused, least understood option
in the entire teqc option menagerie.  First, let's be clear what it really is.  This
is an option to specify, _if_ needed, what the GPS week is for the first data epoch
in raw data input (but not RINEX input), regardless of whether that epoch is part
of the output because of decimation, time windowing, etc.

 From this, there are several things you should now know what '-week' is not:

- It is for GPS weeks (starting 6.0 Jan 1980), not the Galileo weeks (starting 22.0 Aug 1999)
or Beidou weeks (starting 1.0 Jan 2006).  Sorry, Galileo and Beidou, but GPS is
grandfathered in because it came first.

- It is not for changing the GPS week when reading RINEX as input.  (You can put it
on the command in this situation, but it does absolutely nothing.)

- It has nothing to do with the GPS week of any epoch other than the first data epoch.
Hence if the first data epoch of a file was in GPS week 1903 and the week rolls over
for the second data epoch, the GPS week is automatically assumed to increment to 1904
for the second data epoch.  You just concern yourself with the first data epoch.

- You probably shouldn't use the '-week' unless you really need it.

So how do you know if you need to use it?

Case 1: You are using '+meta' or '+mds' with a raw data file and teqc sent "week: ####'
to stdout and then stopped.  Then try using "-week ####" using the number that teqc provided.

Case 2: You are trying to translate a raw data file or extracting metadata (using '+meta'
or '+mds') from the raw data file and get a totally nonsensical answer for the date -- but
you have a pretty good idea which GPS week when the data start in the file.

Fortunately, both of these cases are rare.  But they are possible.

Occasionally, even '+meta' or '+mds' stopping with a "week: ####" gives the wrong value.
The most likely cause of this is a raw data file that has navigation messages from some
week before the start of the data (usually two or more weeks before).  Code is in place
to try to work around these cases, but sometimes a new situation occurs.  Part of a
conversation that occurs around here at UNAVCO once or twice a year:

David (Maggert):  "Lou, we have a file where teqc reports the wrong week."

Me: "Huh.  Really.  No kidding.  I'll take a look ..."

... and then I try to figure out why, and sometimes this requires a tweak to the code.

Why is the '-week' option even needed?  All raw data formats have the GNSS observation
data for each epoch in one or more records (or "messages", depending on what the
manufacturer wants to call them).  Somewhere in each of these data epochs will be the
time of the observation.  Now, as strange as this may sound to you, depending on the
format, or perhaps even the data record being used in the format, the record may only
say when in the GPS week the epoch occurs, but not in which GPS week.

An example of this is the difference between Trimble's .dat and .tgd files.  The older
.dat format stores data for each epoch in a record 17 (based on "data payload" 17, or RT17)
and the newer .tgd format is essentially identical except it stores data for each epoch
in a record 27 ("data payload" 27, or RT27): record 17 specifies when in the week the epoch
is, but not which week; record 27 (among other differences) specifies both the week
and the time in the week.  The starting GPS week in a .dat file needs to be determined
from other records in the .dat file (or the .mes file, if it is present), which hopefully
exist and contain the correct value. (By the way, I'm not picking on Trimble here.  The
same problem occurs with some other formats.  We just happen to have far more experience
here at UNAVCO with Trimble data based on volume than any other format.)

If the data record (like Trimble's record 17) does not contain the week (and '-week'
is not being used), an attempt is made to get the week value from somewhere else.
The ultimate fallback plan in teqc is to use the current GPS week based on the computer's
system time (under the assumption that the user is looking at "current" data and that
the user's computer system time is correct).  Regardless of the source, any assumed
GPS week value (that is, '-week' is _not_ being used to supply the initial value) is
tested against other information, like the week of navigation messages -- and this is
why navigation messages about ephemerides several weeks prior to the first data epoch
can trip up teqc.

Does it do any harm to use the '-week' option if you are sure of the GPS week of the
first observation?  In a perfect world, it shouldn't.  Probably there is no harm.
But strange exceptions do occur.  (Please report such cases.)

One final note: You don't necessarily have to use a GPS week argument with the
'-week' option; instead, you could use either either the Gregorian calendar date
or the year and day-of-year as arguments, as long as:

- you give the year first and the day (or day-of-year) last

- the arguments are separated by a colon (:), slash (/), dash (-), or underscore (_)
(but no whitespace or other delimiter characters)

Therefore, all of the following specify the same GPS week, 1904:

-week 1904
-week 2016/7/3
-week 2016-July-9
-week 2016:185
-week 2016_191

Happy teqc-ing!


Louis H. Estey, Ph.D.              office:  [+001] 303-381-7456
UNAVCO, 6350 Nautilus Drive           FAX:  [+001] 303-381-7451
Boulder, CO  80301-5554            e-mail:  lou  unavco.org
      WWW:  http://www.unavco.org   http://jules.unavco.org

"If the universe is the answer, what is the question?"
                                                -- Leon Lederman

Past helpful tips:

week 1894: using teqc config files - http://postal.unavco.org/pipermail/teqc/2016/002067.html
week 1895: qc of high-rate data - http://postal.unavco.org/pipermail/teqc/2016/002071.html
week 1896: UNIX/Linux shells for Windows - http://postal.unavco.org/pipermail/teqc/2016/002072.html
week 1897: '-' vs. '+' teqc options - http://postal.unavco.org/pipermail/teqc/2016/002076.html
week 1898: auto-identification of formats - http://postal.unavco.org/pipermail/teqc/2016/002092.html
week 1899: auto-identification vs. format flags - http://postal.unavco.org/pipermail/teqc/2016/002096.html
week 1900: square brackets in options - http://postal.unavco.org/pipermail/teqc/2016/002105.html
week 1901: using option '+mds' - http://postal.unavco.org/pipermail/teqc/2016/002108.html
week 1902: qc results w/ problematic nav messages - http://postal.unavco.org/pipermail/teqc/2016/002113.html
week 1903: '-no_orb[it]' and '-no_pos[ition]' options - http://postal.unavco.org/pipermail/teqc/2016/002115.html

More information about the teqc mailing list