PGPLOT Module: PGTBOX -- draw frame and write (DD) HH MM SS.S labelling



Draw a box and optionally label one or both axes with (DD) HH MM SS
style numeric labels (useful for time or RA - DEC plots). If this
style of labelling is desired, then PGSWIN should have been called
previously with the extrema in SECONDS of time.

In the seconds field, you can have at most 3 places after the decimal
point, so that 1 ms is the smallest time interval you can time label.

Large numbers are coped with by fields of 6 characters long. Thus
you could have times with days or hours as big as 999999. However,
in practice, you might have trouble with labels overwriting themselves
with such large numbers unless you a) use a small time INTERVAL,
b) use a small character size or c) choose your own sparse ticks in
the call to PGTBOX.

PGTBOX will attempt, when choosing its own ticks, not to overwrite
the labels, but this algorithm is not very bright and may fail.

Note that small intervals but large absolute times such as
TMIN = 200000.0 s and TMAX=200000.1 s will cause the algorithm
to fail. This is inherent in PGPLOT's use of single precision
and cannot be avoided. In such cases, you should use relative
times if possible.

PGTBOX's labelling philosophy is that the left-most or bottom tick of
the axis contains a full label. Thereafter, only changing fields are
labelled. Negative fields are given a '-' label, positive fields
have none. Axes that have the DD (or HH if the day field is not
used) field on each major tick carry the sign on each field. If the
axis crosses zero, the zero tick will carry a full label and sign.

This labelling style can cause a little confusion with some special
cases, but as long as you know its philosophy, the truth can be divined.
Consider an axis with TMIN=20s, TMAX=-20s. The labels will look like

0h0m20s 10s -0h0m0s 10s 20s

Knowing that the left field always has a full label and that
positive fields are unsigned, informs that time is decreasing
from left to right, not vice versa. This can become very
unclear if you have used the 'F' option, but that is your problem !

Exceptions to this labelling philosophy are when the finest time
increment being displayed is hours (with option 'Y') or days.
Then all fields carry a label. For example,

-10h -8h -6h -4h -2h

PGTBOX can be used in place of PGBOX; it calls PGBOX and only invokes
time labelling if requested. Other options are passed intact to PGBOX.

XOPT : X-options for PGTBOX. Same as for PGBOX plus

'Z' for (DD) HH MM SS.S time labelling
'Y' means don't include the day field so that labels
are HH MM SS.S rather than DD HH MM SS.S The hours
will accumulate beyond 24 if necessary in this case.
'X' label the HH field as modulo 24. Thus, a label
such as 25h 10m would come out as 1h 10m
'H' means superscript numbers with d, h, m, & s symbols
'D' means superscript numbers with o, ', & '' symbols
'F' causes the first label (left- or bottom-most) to
be omitted. Useful for sub-panels that abut each other.
Care is needed because first label carries sign as well.
'O' means omit leading zeros in numbers < 10
E.g. 3h 3m 1.2s rather than 03h 03m 01.2s Useful
to help save space on X-axes. The day field does not
use this facility.

YOPT : Y-options for PGTBOX. See above.
XTICK : X-axis major tick increment. 0.0 for default.
YTICK : Y-axis major tick increment. 0.0 for default.
If the 'Z' option is used then XTICK and/or YTICK must
be in seconds.
NXSUB : Number of intervals for minor ticks on X-axis. 0 for default
NYSUB : Number of intervals for minor ticks on Y-axis. 0 for default

The regular XOPT and YOPT axis options for PGBOX are

A : draw Axis (X axis is horizontal line Y=0, Y axis is vertical
line X=0).
B : draw bottom (X) or left (Y) edge of frame.
C : draw top (X) or right (Y) edge of frame.
G : draw Grid of vertical (X) or horizontal (Y) lines.
I : Invert the tick marks; ie draw them outside the viewport
instead of inside.
L : label axis Logarithmically (see below).
N : write Numeric labels in the conventional location below the
viewport (X) or to the left of the viewport (Y).
P : extend ("Project") major tick marks outside the box (ignored if
option I is specified).
M : write numeric labels in the unconventional location above the
viewport (X) or to the right of the viewport (Y).
T : draw major Tick marks at the major coordinate interval.
S : draw minor tick marks (Subticks).
V : orient numeric labels Vertically. This is only applicable to Y.
The default is to write Y-labels parallel to the axis.
1 : force decimal labelling, instead of automatic choice (see PGNUMB).
2 : force exponential labelling, instead of automatic.

The default is to write Y-labels parallel to the axis

****************** EXCEPTIONS *******************

Note that
1) PGBOX option 'L' (log labels) is ignored with option 'Z'
2) The 'O' option will be ignored for the 'V' option as it
makes it impossible to align the labels nicely
3) Option 'Y' is forced with option 'D'