Internal Calculations for Time Series Plotting

DESCRIPTION:

Compute the labels of the time axis for plotting a calendar time series. This function is meant to be called from axis.time.

USAGE:

axis.time.labels(axis.info, ticks, by=NULL,  
                 k.by=NULL, style.number=1, tick.level="medium",  
                 placement=c("at.tick", "between.tick"),  
                 line=c(1, 2), format.label=NULL, side=1, diagonal=c(F,F),  
                 year.digits=4, date.style="US", 
                 alpha.sep.date=" ", numeric.sep.date="/",  
                 day.style="abb", month.style="abb", quarter.style="Q1",  
                 zerofill=F, time.of.day.style="12:00",  
                 add.outer=!diagonal[1], override=NULL) 

REQUIRED ARGUMENTS:

axis.info
the output from axis.time.build.
ticks
the output from axis.time.ticks. The labels will be placed relative to the tick.level ticks; if ticks does not have that component, it will be computed by calling axis.time.ticks again.

OPTIONAL ARGUMENTS:

by
a character string specifying the calendar unit of the main labels, used to choose the format from the axis.label.style table. Possible values of by are "milliseconds", "seconds", "minutes", "hours", "days", "weeks", "months", "quarters", or "years"; if by is NULL, it is read from axis.info$tick.by.
k.by
an integer specifying the label increment in number of calendar units corresponding to by, used to choose the format; if k.by is NULL, it is read from axis.info$tick.k.by.
style.number
an integer specifying the style number, to choose axis label styles from axis.label.table.
tick.level
a character string specifying which level of tick marks should be labeled, one of "small", "medium", or "big".
placement
a character vector of length 2 specifying the placement of the labels relative to the tick marks for the main and outer labels. Possible choices for placement are "at.tick" and "between.tick".
line
a numeric vector of length 2 specifying the number of lines away from the axis on which to place the main and outer axis labels.
format.label
a character vector of length 2 specifying the label format for the main and outer axis labels; the format strings must be valid time formats as desribed in the documentation for the timeDate class. If it is NULL, it is calculated from the other arguments by calling axis.time.label.format.
side
an integer specifying the side on which the axis is to be placed: 1 for bottom or 3 for top. This is used to determine the angle of a diagonal axis label.
diagonal
a logical vector of length 2 that, if TRUE, rotates the main or outer labels to produce a diagonal label. This is especially useful for long labels, such as time of day, dates, or unabbreviated day of week or months.
year.digits
an integer specifying the number of digits to use in labeling the year, either 0, 2 or 4.
date.style
a character string specifying the style of the date: "US" for month/day/year style and "International" for day/month/year style.
alpha.sep.date
a character string used to separate the month, day, and year fields of the date in alphabetical style of dates (e.g., Jan 3 1998).
numeric.sep.date
a character string used to separate the month, day, and year fields of the date in numerical style of dates (e.g., 1/3/1998).
day.style
a character string specifying the label style of the days. Possible values are "abb" for a 3 character abbreviation, "abb1" for a 1 character abbreviation, "name" for the full name, and "number" for the day of the month.
month.style
a character string specifying the label style of the months. Possible values are "abb" for a 3 character abbreviation, "abb1" for a 1 character abbreviation, "name" for a full name, and "number" (1-12).
quarter.style
a character string specifying the label style of the quarters. Possible values are "Q1", "1Q", and "I".
zerofill
if TRUE, numeric days and months will be zero-filled in dates (e.g., 01/01/98 versus 1/1/98).
time.of.day.style
a character string specifying the label style for the time of day. Possible values are 12:00 or 12 for a twelve hour clock without printing AM or PM, "am.pm" for a twelve hour clock with AM or PM printed, and "24" or "24:00"for a twenty-four hour clock. The difference between "12" and "12:00" is that if the labels are every hour or more, the latter will print the ":00" after the hours.
add.outer
if TRUE, an outer label will be displayed if appropriate for the label style.
override
if not NULL, override the entire label formatting process by substituting these labels. Assumes that ticks were already calculated, and that they contain the level given by tick.level.

VALUE:

the function returns a list suitable for passing to axis.render that contains parameters for generating axis labels. If an outer label is not displayed, then the result is a list with the following components:
at
where to put the labels in time coordinates.
pos
the position the label would be in if the placement was "at.tick", for use by axis.time.grid.
text
the label strings.
line
how far from the axis to put labels.
srt
string rotation, if the labels are diagonal. If an outer label is to be displayed, then the returned value is a list of 2 lists, one list called main.label for the main label and one called outer.label for the outer label, with the components described above. The other label parameters use the default values from trellis.par.get ; for more information see axis.render.

SEE ALSO:

, , , , , , , .