VII Dealing
with time
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.
VII.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”.
VII.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 database. 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 VFrDataBase::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 VFrDataBase::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.
VII.1.2 How
to set a reference time
Since each database has its reference time, setting it is done by the
VFrDataBase 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 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 vd is a metadatabase object
defined previously,
vega[] vd->SetRefTime("start")
will set the reference time to be the start of the metadatabase
vega[] vd->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[] vd-> 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.
VII.2 Time
when outputting information
VII.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.
VII.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.
VII.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”.
VII.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.
VII.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.
VII.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.
Damir BUSKULIC
Last update :19/11/2001;
