In nearly all physics experiments where the
time is an important variable, the use of GPS (Global Positioning System) is
generalized. This allows to get a microsecond precision clock synchronized
throughout the whole world. But the inconvenience is for everyday use that GPS
times are expressed as seconds since 1980, January 5, 24:00:00. That means 9
digits numbers. This may be very cumbersome. So there is a need for a convenient
way of expressing time while working.
This problem arises in two different fields,
when one wants to access data and when one tries to output information related
to time.
VIII.1 Time
when accessing data
When trying to access data, it would be nice
if one could say “I want to access a frame or vector that began 10 minutes
ago” or “Give me the vector beginning the 14th of July
2001 at 14:34:05” instead of “time =
632145148”.
VIII.1.1 The
reference time
This is why in VEGA, one can access data
with respect to a reference time. This reference time is local to a frame
channel. To access data, one can use two types of methods. The standard ones,
which work in an absolute way, i.e. you have to give the absolute GPS time (like
VFrameChannel::GetVect),
and the ones that work by reference to a given time. They differ from the first
ones only by the fact that there is an R at the end of the methods name. For
instance
VFrameChannel::GetVectR.
The arguments are the same except that the time is expressed as the number of
seconds since the reference time. It may be negative to define a time that was
before the reference one. See the chapter on data access for more
information.
VIII.1.2 How
to set a reference time
Since each frame channel has its reference
time, setting it is done by the VFrameChannel method
SetRefTime.
Easy.
void SetRefTime(double reftime)
void SetRefTime(char* when, int
leapseconds=0)
reftime
is the GPS time expressed as a double to take care of fractions of
seconds.
when
is a character string that may be one of the following
“now”
for the time at which this setting is done (script executed or command typed at
the command line)
“start”
for the beginning time of the first frame indexed by the information database.
It’s the database start time.
a string describing the time (universal
time) in the format
“day/month/year(4 digits)
hour(1-24):minute:seconds”.
For example “12/04/2000
21:15:34”
leapseconds
is the number of leap seconds that was the reference at the specified time. This
is necessary since we are internally using the GPS time. When you express the
time as “12/04/2000
21:15:34” it will be
converted in universal time (UTC), referring to earth’s rotation. But GPS
is a number of seconds since a reference date. Earth’s rotation being
non-uniform, these two times drift with respect to each other. The amount of
drifting is the number of leap seconds. It is automatically given in a frame
header or in a vector. In case you
don’t know it, let it to 0. Be aware that you may have a difference of
around 30 seconds (beginning 2000). The number of leap seconds is, as of today,
increasing by approximately a little bit more than 1s per
year.
Example : If
fc
is a frame channel object opened previously,
vega[]
fc->SetRefTime("start")
will set the reference time to be the start
of the info database
vega[]
fc->SetRefTime("12/04/2000 21:15:34")
will set the reference time to the specified
date, putting leap seconds to 0. May have a 30 seconds difference with what is
expected.
vega[]
fc->SetRefTime("12/04/2000 21:15:34",32)
will set the reference time to the specified
date, putting leap seconds to 32. This will be much more correct.
VIII.2 Time
when outputting information
VIII.2.1 Plotting
frames or vectors start time
From Framelib version v4r0, each FrVect
vector has its absolute GPS beginning time included. In VEGA, this start time is
automatically plotted below the VSPlot produced when drawing
vectors.
Though the default behavior should be all
right for most users, one may change the options used for drawing this time by
using the global variables gVStyle that holds the style options for the VEGA
session. It is described in chapter “The global variables often
used”.
To change the default behavior, one should
set the values in gVStyle BEFORE drawing the vector. These are the x offset, the
y offset and the display on/off state, as shown below :
One could use the following methods of
gVStyle :
VStyle::SetStartTimeDisplay(true_or_false)
This
method toggles the start time display. A call to it :
vega[]
gVStyle->SetStartTimeDisplay(0)
will toggle off all subsequent displays,
i.e. no plots will have their start time plotted from then on.
VStyle::SetStartTimeXOffset(float
offset)
The
position of the time string in the plot is fixed. This method sets the offset of
the string with respect to the left side of the pad. A call to it
:
vega[]
gVStyle->SetStartTimeXOffset(0.04)
will fix the string position horizontally
for all vectors drawn after this call. The default value is
0.02.
VStyle::SetStartTimeYOffset(float
offset)
This method
sets the offset of the string with respect to the bottom of the pad. A call to
it :
vega[]
gVStyle->SetStartTimeXOffset(0.04)
will fix the string position vertically for
all vectors drawn after this call. The default value is 0.02.
Once a VSPlot is drawn, similar methods
exist to change the position of the start time if needed. They are used in
exactly the same way as the VStyle ones, except you need to have a valid pointer
to a VSPlot :
VSPlot::SetStartTimeDisplay(true_or_false)
VSPlot::SetStartTimeXOffset(float
offset)
VSPlot::SetStartTimeYOffset(float
offset)
For
instance if vs is a pointer to the last drawn plot, that you get via
gVStyle->SetStartTimeXOffset,
the following :
vega[]
vs->SetStartTimeXOffset(0.04)
will change the x offset of start
time.
VIII.2.2 Plotting
time on time series axis
While it is convenient to plot the start
time of the vector, it is also interesting to have the numbers on the axis
expressed in seconds or minutes or hours or, why not, days.
By default, the numbers displayed on an axis
are expressed in seconds since the start time of the vector. One can set the
axis so that time is expressed in seconds/minutes/hours/days.
VIII.2.2.1 Interactively
setting time display on the axis
Interactively, one can set it by using the
“SetTimeDisplay” entry of the popup menu of the axis
:
The result is the following
:
The careful reader will have noticed that
the second displayed on the axis is the one of the starting time, also displayed
(08/09/92
15:07:09). This is general,
the time displayed on the axis is the last part of the absolute time, so one can
easily and visually connect it with the starting time of the vector.
Furthermore, the transitions from one minute to the next or from one hour to the
next are correctly handled (we hope so !).
The format of the time display may be set
with the SetTimeFormat entry of the popup. This format is the same as the one
used in the standard C function strftime. It is a format string that contains
:
For the date :
%a
Abbreviated weekday name
%b
Abbreviated month name
%d
Day of the month (01-31)
%m
Month (01-12)
%y
Year without century
For time :
%H
Hour (24 hour clock)
%I
Hour (12 hour clock)
%p
Local equivalent of AM or PM
%M
Minute (00-59)
%S
Seconds (00-61)
%%
%
For example the standard string used in
Europe is “%d/%m/%y
%H:%M:%S”.
VIII.2.2.2 Set
axis time parameters in a script
In a script, one will need to
set/unset/change the time format or parameters with statements. There are two
ways.
VIII.2.2.2.1 Directly
The first is to access the axis object of
the plot. It is of type TAxis and, given a plot “vs” is accessed via
“vs->GetXaxis()” or
“vs->GetYaxis()”.
Suppose we have a vector ve of type FrVect*
already extracted. A typical use would be :
Draw the vector and get the associated
VSPplot :
vega[]
gVM->Draw(vect)
vega[]
vs = gVM->GetLastPlot()
Set the time display on the X-axis. In
order to do this, since time display are axis characteristics, one first
accesses the axis object with
vs->GetXaxis()
and then calls the
SetTimeXXX
method :
vega[]
vs->GetXaxis()->SetTimeDisplay()
Set the time format :
vega[]
vs->GetXaxis()->SetTimeFormat("a user
format")
of course, replace “a user
format” by what you want to be the format. Format options are described in
the previous paragraph.
VIII.2.2.2.2 Through the
style
The second possible way is to use the
gVStyle variable, so that you set it once and all the subsequent plots will be
drawn with the specified options, as for example, time on axis turned on, as in
:
vega[]
gVStyle->SetTimeOnXAxis(1)
The other available option are
:
gVStyle->SetTimeFormat("a user
format")
Again, see preceding paragraphs for the
format.
Remember : use the style global gVStyle
BEFORE drawing the plot.
