Time Axis for Time Series Plot

DESCRIPTION:

Function to compute the parameters needed to render an x-axis for calendar time series plotting.

USAGE:

axis.time(pos, n.ticks=100, nobreaks=F, min.span=NULL, mkt.oc=T,  
          align.break=T, by.align=NULL, k.by.align=NULL, extend=T,  
          skip.weekends=T, week.align="Monday", 
          tick.levels=c("small", "medium", "big"), by.label=NULL,  
          k.by.label=NULL, style.number=1, level.label="medium",  
          placement=c("at.tick", "between.tick"), line.label=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], 
          reference.grids=T, break.width = 0.05, break.max.width = 0.15,
          at=NULL, labels=NULL, xlim=NULL)
 

REQUIRED ARGUMENTS:

pos
the positions/times for the time series.

OPTIONAL ARGUMENTS:

n.ticks
the approximate number of desired tick marks on the x-axis.
nobreaks
if TRUE, do not use axis breaks; if FALSE, then axis.compute.time.breaks is called to compute possible times for axis breaks.
min.span
(if nobreaks is FALSE) a time span object that is used to identify breaks as those time periods without positions that exceed min.span. If NULL, the default is selected from axis.break.table based on min(diff(pos))
mkt.oc
(if nobreaks is FALSE) TRUE or FALSE to determine whether daily market opening and closing times to use as axis breaks should be estimated from pos; can also be a list with named open and close components giving the regular opening and closing times of the market to use for generating axis breaks. The times are given as time span objects, representing the time after midnight for the daily openings and closings of the market.
align.break
(if nobreaks is FALSE) if TRUE, the break intervals are extended so that the intervals are aligned according to by.align and k.by.align.
by.align
(if nobreaks is FALSE) a character string giving the time units for aligning the intervals if align.break is TRUE. Possible values are "years", "quarters", "months", "weeks", "days", "hours", "minutes", "minutes", "seconds", or "milliseconds". If NULL, the default is selected from axis.break.table based on min(diff(pos))
k.by.align
(if nobreaks is FALSE) an integer indicating the number of by.align units for aligning. If NULL, the default is selected from axis.break.table based on min(diff(pos))
extend
if TRUE, the axis is extended past the range of pos to the next small tick mark.
skip.weekends
if TRUE, the axis skips weekends if the time series has no data on the weekends.
week.align
a character string (or an integer, 0 to 6 with 0 being Sunday) to specify a weekday to align weekly tick marks to. The character string must be sufficient to make a unique case-insensitive match to the strings in options("time.day.name").
tick.levels
a vector of character strings indicating which tick marks are to be displayed. Up to three types of tick marks are supported: "small", "medium", and "big".
by.label
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.label
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.
level.label
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.label
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.
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 to be displayed if appropriate for the label style.
reference.grids
if TRUE, reference grids will be added.
break.width
width for axis breaks, as a fraction of the plotting region.
break.max.width
maximum total width for axis breaks, as a fraction of the plotting region.
at
if not NULL, put ticks and labels for the tick level given by level.label at these values, instead of calculating "pretty" values. Note that this does not override the axis limits.
labels
if not NULL, and at != NULL as well, this character vector is used for the labels instead of formatting the tick positions.
xlim
range limit for axis.

VALUE:

a list with components
ticks
information for rendering the tick marks, calculated by axis.time.tick.
labels
information for rendering the tick labels, calculated by axis.time.label.
breaks
information for rendering the tick breaks, calculated by axis.time.breaks.
grid
information for rendering the reference grid lines, calculated by axis.time.grid .
scale
information for mapping from user coordinates to plot coordinates, calculated by axis.time.scale.
line
an empty list, letting the axis line be plotted from its defaults.

SEE ALSO:

, , , , ,