gvisAnnotatedTimeLine: Google Annotated Time Line with R

Description Usage Arguments Details Value Warnings Author(s) References See Also Examples

Description

The gvisAnnotatedTimeLine function reads a data.frame and creates text output referring to the Google Visualisation API, which can be included into a web page, or as a stand-alone page.

An annotated time line is an interactive time series line chart with optional annotations. The chart is rendered within the browser using Flash.

Usage

1
2
3
4
gvisAnnotatedTimeLine(data,  datevar = "", numvar="", idvar = "",
                      titlevar="", annotationvar="",
                      date.format = "%Y/%m/%d",
                      options = list(), chartid)

Arguments

data

a data.frame. The data has to have at least two columns, one with date information (datevar) and one numerical variable.

datevar

column name of data which shows the date dimension. The information has to be of class Date or POSIX* time series.

numvar

column name of data which shows the values to be displayed against datevar. The information has to be numeric.

idvar

column name of data which identifies different groups of the data. The information has to be of class character or factor.

titlevar

column name of data which shows the title of the annotations. The information has to be of class character or factor. Missing information can be set to NA. See section 'Details' for more details.

annotationvar

column name of data which shows the annotation text. The information has to be of class character or factor. Missing information can be set to NA. See section 'Details' for more details.

date.format

if datevar is of class Date then this argument specifies how the dates are reformatted to be used by JavaScript.

options

list of configuration options for Google Annotated Time Line.

gvis.editor

a character label for an on-page button which opens an in-page dialog box that enables users to edit, change and customise the chart. By default no value is given and therefore no button is displayed.

gvis.language

values may be 'ca', 'da', 'de', 'en', 'en_GB', 'en_IE', 'es', 'es_419', 'fi', 'fr', 'id', 'in', 'is', 'it', 'nl', 'no', 'pt', 'pt_BR', 'pt_PT', 'sv'. If not set the API detects the language settings of the browser.

Further possible components are, taken from https://google-developers.appspot.com/chart/interactive/docs/gallery/annotatedtimeline#Configuration_Options:

height

height of the chart in pixels.

width

width of the chart in pixels.

allowHtml

boolean. Default FALSE. If set to TRUE, any annotation text that includes HTML tags will be rendered as HTML.

allowRedraw

boolean. Default FALSE. Enables a more efficient redrawing technique for the second and later calls to draw() on this visualization. It only redraws the chart area. To use this option, you must fulfill the following requirements:

  • allowRedraw must be TRUE

  • displayAnnotations must be FALSE (that is, you cannot show annotations)

  • you must pass in the same options and values (except for the allowRedraw and displayAnnotations) as in your first call to draw().

allValuesSuffix

string. Default none. A suffix to be added to all values in the scales and the legend.

annotationsWidth

number. Default 25. The width (in percent) of the annotations area, out of the entire chart area. Must be a number in the range 5-80.

colors

a JSON array of strings. Default colors. The colors to use for the chart lines and labels. An array of strings. Each element is a string in a valid HTML color format. For example 'red' or '#00cc00'.

dateFormat

string. Either 'MMMM dd, yyyy' or 'HH:mm MMMM dd, yyyy', depending on the type of the first column (date, or datetime, respectively). The format used to display the date information in the top right corner. The format of this field is as specified by the java SimpleDateFormat class.

displayAnnotations

boolean. Default FALSE. If set to TRUE, the chart will show annotations on top of selected values. When this option is set to TRUE, after every numeric column, two optional annotation string columns can be added, one for the annotation title and one for the annotation text.

displayAnnotationsFilter

boolean. Default FALSE. If set to TRUE, the chart will display a filter contol to filter annotations. Use this option when there are many annotations.

displayDateBarSeparator

boolean. Default TRUE. Whether to display a small bar separator ( | ) between the series values and the date in the legend, where TRUE means yes.

displayExactValues

boolean. Default FALSE. Whether to display a shortened, rounded version of the values on the top of the graph, to save space; false indicates that it may. For example, if set to false, 56123.45 might be displayed as 56.12k.

displayLegendDots

boolean. Default TRUE. Whether to display dots next to the values in the legend text, where TRUE means yes.

displayLegendValues

boolean. Default TRUE. Whether to display the highlighted values in the legend, where TRUE means yes.

displayRangeSelector

boolean. Default TRUE. Whether to show the zoom range selection area (the area at the bottom of the chart), where FALSE means no.

The outline in the zoom selector is a log scale version of the last series in the chart, scaled to fit the height of the zoom selector.

displayZoomButtons

boolean. Default TRUE. Whether to show the zoom links ("1d 5d 1m" and so on), where FALSE means no.

fill

number. Default 0. A number from 0-100 (inclusive) specifying the alpha of the fill below each line in the line graph. 100 means 100% opaque fill, 0 means no fill at all. The fill color is the same color as the line above it.

highlightDot

string. Default 'nearest'. Which dot on the series to highlight, and corresponding values to show in the legend. Select from one of these values:

'nearest'

The values closest along the X axis to the mouse.

'last'

The next set of values to the left of the mouse.

legendPosition

string. Default 'sameRow'. Whether to put the colored legend on the same row with the zoom buttons and the date ('sameRow'), or on a new row ('newRow').

max

number. Default automatic. The maximum value to show on the Y axis. If the maximum data point exceeds this value, this setting will be ignored, and the chart will be adjusted to show the next major tick mark above the maximum data point. This will take precedence over the Y axis maximum determined by scaleType.

min

number. Default automatic. The minimum value to show on the Y axis. If the minimum data point is less than this value, this setting will be ignored, and the chart will be adjusted to show the next major tick mark below the minimum data point. This will take precedence over the Y axis minimum determined by scaleType.

numberFormats

string, or a map of number:String pairs. Default automatic. Specifies the number format patterns to be used to format the values at the top of the graph.

The patterns should be in the format as specified by the java DecimalFormat class.

  • If not specified, the default format pattern is used.

  • If a single string pattern is specified, it is used for all of the values.

  • If a map is specified, the keys are (zero-based) indexes of series, and the values are the patterns to be used to format the specified series.

    You are not required to include a format for every series on the chart; any unspecified series will use the default format. If this option is specified, the displayExactValues option is ignored.

scaleColumns

a JSON array of numbers. Default automatic. Specifies which values to show on the Y axis tick marks in the graph. The default is to have a single scale on the right side, which applies to both series; but you can have different sides of the graph scaled to different series values.

This option takes an array of zero to three numbers specifying the (zero-based) index of the series to use as the scale value. Where these values are shown depends on how many values you include in your array:

  • If you specify an empty array, the chart will not show Y values next to the tick marks.

  • If you specify one value, the scale of the indicated series will be displayed on the right side of the chart only.

  • If you specify two values, a the scale for the second series will be added to the right of the chart.

  • If you specify three values, a scale for the third series will be added to the middle of the chart.

  • Any values after the third in the array will be ignored.

When displaying more than one scale, it is advisable to set the scaleType option to either 'allfixed' or 'allmaximized'.

scaleType

string. Default 'fixed'. Sets the maximum and minimum values shown on the Y axis. The following options are available:

'maximized'

The Y axis will span the minimum to the maximum values of the series. If you have more than one series, use 'allmaximized'.

'fixed' [default]

The Y axis varies, depending on the data values values:

  • If all values are >=0, the Y axis will span from zero to the maximum data value.

  • If all values are <=0, the Y axis will span from zero to the minimum data value.

  • If values are both positive and negative, the Y axis will range from the series maximum to the series minimum.

    For multiple series, use 'allfixed'.

'allmaximized'

Same as 'maximized,' but used when multiple scales are displayed. Both charts will be maximized within the same scale, which means that one will be misrepresented against the Y axis, but hovering over each series will display it's true value.

'allfixed'

Same as 'fixed,' but used when multiple scales are displayed. This setting adjusts each scale to the series to which it applies (use this in conjunction with scaleColumns).

If you specify the min and/or max options, they will take precedence over the minimum and maximum values determined by your scale type.

thickness

number. Default 0. A number from 0-10 (inclusive) specifying the thickness of the lines, where 0 is the thinnest.

wmode

string. Default 'window'. The Window Mode (wmode) parameter for the Flash chart. Available values are: 'opaque', 'window' or 'transparent'.

zoomEndTime

Date. Default none. Sets the end date/time of the selected zoom range.

zoomStartTime

Date. Default none. Sets the start date/time of the selected zoom range.

chartid

character. If missing (default) a random chart id will be generated based on chart type and tempfile

Details

From https://google-developers.appspot.com/chart/interactive/docs/gallery/annotatedtimeline.html#Data_Format:

You can display one or more lines on your chart. Each row represents an X position on the chart - that is, a specific time; each line is described by a set of one to three columns.

Value

gvisAnnotatedTimeLine returns list of class "gvis" and "list".

An object of class "gvis" is a list containing at least the following components:

type

Google visualisation type, here 'AnnotatedTimeLine'

chartid

character id of the chart object. Unique chart ids are required to place several charts on the same page.

html

a list with the building blocks for a page

header

a character string of a html page header: <html>...<body>,

chart

a named character vector of the chart's building blocks:

jsHeader

Opening <script> tag and reference to Google's JavaScript library.

jsData

JavaScript function defining the input data as a JSON object.

jsDrawChart

JavaScript function combing the data with the visualisation API and user options.

jsDisplayChart

JavaScript function calling the handler to display the chart.

jsFooter

End tag </script>.

jsChart

Call of the jsDisplayChart function.

divChart

<div> container to embed the chart into the page.

caption

character string of a standard caption, including data name and chart id.

footer

character string of a html page footer: </body>...</html>, including the used R and googleVis version and link to Google's Terms of Use.

Warnings

Because of Flash security settings the chart might not work correctly when accessed from a file location in the browser (e.g., file:///c:/webhost/myhost/myviz.html) rather than from a web server URL (e.g. http://www.myhost.com/myviz.html). See the googleVis package vignette and the Macromedia web site (http://www.macromedia.com/support/documentation/en/flashplayer/help/) for more details.

Author(s)

Markus Gesmann markus.gesmann@gmail.com,

Diego de Castillo decastillo@gmail.com

References

Google Annotated Time Line API: https://google-developers.appspot.com/chart/interactive/docs/gallery/annotatedtimeline.html

Follow the link for Google's data policy.

See Also

See also print.gvis, plot.gvis for printing and plotting methods. Further see reshape for reshaping data, e.g. from a wide format into a long format.

Examples

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
## Please note that by default the googleVis plot command
## will open a browser window and requires Flash and Internet
## connection to display the visualisation.


data(Stock)
Stock
A1 <- gvisAnnotatedTimeLine(Stock, datevar="Date",
                           numvar="Value", idvar="Device",
                           titlevar="Title", annotationvar="Annotation",
                           options=list(displayAnnotations=TRUE,
                            legendPosition='newRow',
                            width=600, height=350)
                           )
plot(A1)

## Two Y-axis
A2 <- gvisAnnotatedTimeLine(Stock, datevar="Date",
                           numvar="Value", idvar="Device",
                           titlevar="Title", annotationvar="Annotation",
                           options=list(displayAnnotations=TRUE, 
                            width=600, height=350, scaleColumns='[0,1]',
                            scaleType='allmaximized')
                          )
plot(A2)

## Zoom into the time window, no Y-axis ticks
A3 <- gvisAnnotatedTimeLine(Stock, datevar="Date",
                           numvar="Value", idvar="Device",
                           titlevar="Title", annotationvar="Annotation",
                           options=list(
                             width=600, height=350,
                            zoomStartTime=as.Date("2008-01-04"),
                            zoomEndTime=as.Date("2008-01-05")) 
                          )
plot(A3)



## Colouring the area below the lines to create an area chart
A4 <- gvisAnnotatedTimeLine(Stock, datevar="Date",
                           numvar="Value", idvar="Device",
                           titlevar="Title", annotationvar="Annotation",
                           options=list(
                             width=600, height=350,
                             fill=10, displayExactValues=TRUE,
                             colors="['#0000ff','#00ff00']")
                           )
                          
plot(A4)


## Data with POSIXct datetime variable
A5 <- gvisAnnotatedTimeLine(Andrew, datevar="Date/Time UTC",
                            numvar="Pressure_mb",
                            options=list(scaleType='maximized')
                            )

plot(A5)


## Not run: 

## Plot Apple's monthly stock prices since 1984

## Get current date
d <- Sys.time() 
current.year <- format(d, "%Y")
current.month <- format(d, "%m")
current.day <- format(d, "%d")

## Yahoo finance sets January to 00 hence: 
month <- as.numeric(current.month)  - 1
month <- ifelse(month < 10, paste("0",month, sep=""), m)

## Get weekly stock prices from Apple Inc.
tckr <- 'AAPL'
yahoo <- 'http://ichart.finance.yahoo.com/table.csv'

fn <- sprintf('%s?s=%s&a=08&b=7&c=1984&d=%s&e=%s&f=%s&g=w&ignore=.csv',
      yahoo, tckr, month, current.day, current.year)

## Get data from Yahoo! Finance
data <- read.csv(fn, colClasses=c("Date", rep("numeric",6)))

AAPL <- reshape(data[,c("Date", "Close", "Volume")], idvar="Date", 
     		times=c("Close", "Volume"), 
                timevar="Type",
                varying=list(c("Close", "Volume")),
                v.names="Value",
                direction="long")

## Calculate previous two years for zoom start time
lyd <- as.POSIXlt(as.Date(d))
lyd$year <- lyd$year-2
lyd <- as.Date(lyd)

aapl <- gvisAnnotatedTimeLine(AAPL, datevar="Date",
                           numvar="Value", idvar="Type",
                          options=list(
                            colors="['blue', 'lightblue']",
                            zoomStartTime=lyd,
                            zoomEndTime=as.Date(d),
                            legendPosition='newRow',
                            width=600, height=400, scaleColumns='[0,1]',
                            scaleType='allmaximized')
                           )

plot(aapl)

## End(Not run)

jburos/GoogleVis documentation built on May 18, 2019, 9:19 p.m.