amLineChart {rAmCharts4}

HTML widget displaying a line chart

Description

Create a HTML widget displaying a line chart.

Usage

amLineChart(
  data,
  data2 = NULL,
  xValue,
  yValues,
  yValueNames = NULL,
  hline = NULL,
  vline = NULL,
  xLimits = NULL,
  yLimits = NULL,
  expandX = 0,
  expandY = 5,
  Xformatter = ifelse(isDate, "yyyy-MM-dd", "#."),
  Yformatter = "#.",
  trend = FALSE,
  chartTitle = NULL,
  theme = NULL,
  animated = TRUE,
  draggable = FALSE,
  tooltip = NULL,
  bullets = NULL,
  alwaysShowBullets = FALSE,
  lineStyle = NULL,
  backgroundColor = NULL,
  xAxis = NULL,
  yAxis = NULL,
  scrollbarX = FALSE,
  scrollbarY = FALSE,
  legend = NULL,
  caption = NULL,
  image = NULL,
  button = NULL,
  cursor = FALSE,
  zoomButtons = FALSE,
  width = NULL,
  height = NULL,
  export = FALSE,
  chartId = NULL,
  elementId = NULL
)

Arguments

data

a dataframe

data2

NULL or a dataframe used to update the data with the button; its column names must include the column names of data given in yValues as well as the column name given in xValue; moreover it must have the same number of rows as data and its rows must be in the same order as those of data

xValue

name of the column of data to be used on the x-axis

yValues

name(s) of the column(s) of data to be used on the y-axis

yValueNames

names of the variables on the y-axis, to appear in the legend; NULL to use yValues as names, otherwise a named list of the form list(yvalue1 = "ValueName1", yvalue2 = "ValueName2", ...) where yvalue1, yvalue2, ... are the column names given in yValues and "ValueName1", "ValueName2", ... are the desired names to appear in the legend

hline

an optional horizontal line to add to the chart; it must be a named list of the form list(value = h, line = settings) where h is the "intercept" and settings is a list of settings created with amLine

vline

an optional vertical line to add to the chart; it must be a named list of the form list(value = v, line = settings) where v is the "intercept" and settings is a list of settings created with amLine

xLimits

range of the x-axis, a vector of two values specifying the left and right limits of the x-axis; NULL for default values

yLimits

range of the y-axis, a vector of two values specifying the lower and the upper limits of the y-axis; NULL for default values

expandX

if xLimits = NULL, a percentage of the range of the x-axis used to expand this range

expandY

if yLimits = NULL, a percentage of the range of the y-axis used to expand this range

Xformatter

a number formatting string if xValue is set to a numeric column of data; it is used to format the values displayed in the cursor tooltips if cursor = TRUE, the labels of the x-axis unless you specify your own formatter in the labels field of the list passed on to the xAxis option, and the values displayed in the tooltips unless you specify your own tooltip text; if xValue is set to a date column of data, this option should be set to a date formatting string, and it has an effect only on the values displayed in the tooltips (unless you specify your own tooltip text); formatting the dates on the x-axis is done via the labels field of the list passed on to the xAxis option

Yformatter

a number formatting string; it is used to format the values displayed in the cursor tooltips if cursor = TRUE, the labels of the y-axis unless you specify your own formatter in the labels field of the list passed on to the yAxis option, and the values displayed in the tooltips unless you specify your own tooltip text (see the first example of amBarChart for the way to set a number formatter in the tooltip text)

trend

option to request trend lines and to set their settings; FALSE for no trend line, otherwise a named list of the form list(yvalue1 = trend1, yvalue2 = trend2, ...) where trend1, trend2, ... are lists with the following fields:

method

the modelling method, can be "lm", "lm.js", "nls", "nlsLM", or "loess"; "lm.js" performs a polynomial regression in JavaScript, its advantage is that the fitted regression line is updated when the points of the line are dragged

formula

a formula passed on to the modelling function for methods "lm", "nls" or "nlsLM"; the lefthandside of this formula must always be y, and its righthandside must be a symbolic expression depending on x only, e.g. y ~ x, y ~ x + I(x^2), y ~ poly(x,2)

interval

effective for methods "lm" and "lm.js" only; a list with five possible fields: type can be "confidence" or "prediction", level is the confidence or prediction level (number between 0 and 1), color is the color of the shaded area, opacity is the opacity of the shaded area (number between 0 and 1), tensionX and tensionY to control the smoothing (see amLine)

order

the order of the polynomial regression when method = "lm.js"

method.args

a list of additional arguments passed on to the modelling function defined by method for methods "nls", "nlsLM" or "loess", e.g. method.args = list(span = 0.3) for method "loess"

style

a list of settings for the trend line created with amLine

it is also possible to request the same kind of trend lines for all series given by the yValues argument, by passing a list of the form list("_all" = trendconfig), e.g. list("_all" = list(method = "lm", formula = y ~ 0+x, style = amLine()))

chartTitle

chart title, it can be NULL or FALSE for no title, a character string, a list of settings created with amText, or a list with two fields: text, a list of settings created with amText, and align, can be "left", "right" or "center"

theme

theme, NULL or one of "dataviz", "material", "kelly", "dark", "moonrisekingdom", "frozen", "spiritedaway", "patterns", "microchart"

animated

Boolean, whether to animate the rendering of the graphic

draggable

TRUE/FALSE to enable/disable dragging of all lines, otherwise a named list of the form list(yvalue1 = TRUE, yvalue2 = FALSE, ...) to enable/disable the dragging for each series corresponding to a column given in yValues

tooltip

settings of the tooltips; NULL for default, FALSE for no tooltip, otherwise a named list of the form list(yvalue1 = settings1, yvalue2 = settings2, ...) where settings1, settings2, ... are lists created with amTooltip; this can also be a single list of settings that will be applied to each series, or a just a string for the text to display in the tooltip

bullets

settings of the bullets; NULL for default, otherwise a named list of the form list(yvalue1 = settings1, yvalue2 = settings2, ...) where settings1, settings2, ... are lists created with amCircle, amTriangle or amRectangle; this can also be a single list of settings that will be applied to each series

alwaysShowBullets

logical, whether the bullets should always be visible, or visible on hover only

lineStyle

settings of the lines; NULL for default, otherwise a named list of the form list(yvalue1 = settings1, yvalue2 = settings2, ...) where settings1, settings2, ... are lists created with amLine; this can also be a single list of settings that will be applied to each line

backgroundColor

a color for the chart background; it can be given by the name of a R color, the name of a CSS color, e.g. "teal" or "fuchsia", an HEX code like "#ff009a", a RGB code like "rgb(255,100,39)", or a HSL code like "hsl(360,11,255)"

xAxis

settings of the x-axis given as a list, or just a string for the axis title; the list of settings has five possible fields: a field title, a list of settings for the axis title created with amText, a field labels, a list of settings for the axis labels created with amAxisLabels, a field adjust, a number defining the vertical adjustment of the axis (in pixels), a field gridLines, a list of settings for the grid lines created with amLine, and a field breaks to control the axis breaks, an R object created with amAxisBreaks

yAxis

settings of the y-axis given as a list, or just a string for the axis title; the list of settings has five possible fields: a field title, a list of settings for the axis title created with amText, a field labels, a list of settings for the axis labels created with amAxisLabels, a field adjust, a number defining the horizontal adjustment of the axis (in pixels), a field gridLines, a list of settings for the grid lines created with amLine, and a field breaks to control the axis breaks, an R object created with amAxisBreaks

scrollbarX

logical, whether to add a scrollbar for the x-axis

scrollbarY

logical, whether to add a scrollbar for the y-axis

legend

FALSE for no legend, TRUE for a legend with default settings, or a list of settings created with amLegend

caption

NULL or FALSE for no caption, a formatted text created with amText, or a list with two fields: text, a list created with amText, and align, can be "left", "right" or "center"

image

option to include an image at a corner of the chart; NULL or FALSE for no image, otherwise a named list with four possible fields: the field image (required) is a list created with amImage, the field position can be "topleft", "topright", "bottomleft" or "bottomright", the field hjust defines the horizontal adjustment, and the field vjust defines the vertical adjustment

button

NULL for the default, FALSE for no button, or a list of settings created with amButton; this button is used to replace the current data with data2

cursor

option to add a cursor on the chart; FALSE for no cursor, TRUE for a cursor for both axes with default settings for the axes tooltips, otherwise a named list with four possible fields: a field axes to specify the axes for which the cursor is requested, can be "x", "y", or "xy", a field tooltip to set the style of the axes tooltips, this must be a list of settings created with amTooltip, a field extraTooltipPrecision, a named list of the form list(x = i, y = j) where i and j are the desired numbers of additional decimals for the tooltips on the x-axis and on the y-axis respectively, and a field modifier, a list with two possible fields, x and y, which defines modifiers for the values displayed in the tooltips; a modifier is some JavaScript code given a string, which performs a modification of a string named text, e.g. "text = '[font-style:italic]' + text + '[/]';"; see the first example for an example of modifier

zoomButtons

a Boolean value, or a list created with amZoomButtons

width

the width of the chart, e.g. "600px" or "80%"; ignored if the chart is displayed in Shiny, in which case the width is given in amChart4Output

height

the height of the chart, e.g. "400px"; ignored if the chart is displayed in Shiny, in which case the height is given in amChart4Output

export

logical, whether to enable the export menu

chartId

a HTML id for the chart

elementId

a HTML id for the container of the chart; ignored if the chart is displayed in Shiny, in which case the id is given by the Shiny id

Examples

# a line chart with a numeric x-axis ####

set.seed(666)
dat <- data.frame(
  x = 1:10,
  y1 = rnorm(10),
  y2 = rnorm(10)
)

amLineChart(
  data = dat,
  width = "700px",
  xValue = "x",
  yValues = c("y1", "y2"),
  yValueNames = list(y1 = "Sample 1", y2 = "Sample 2"),
  trend = list(
    y1 = list(
      method = "lm.js",
      order = 3,
      style = amLine(color = "lightyellow", dash = "3,2")
    ),
    y2 = list(
      method = "loess",
      style = amLine(color = "palevioletred", dash = "3,2")
    )
  ),
  draggable = list(y1 = TRUE, y2 = FALSE),
  backgroundColor = "#30303d",
  tooltip = amTooltip(
    text = "[bold]({valueX},{valueY})[/]",
    textColor = "white",
    backgroundColor = "#101010",
    borderColor = "whitesmoke"
  ),
  bullets = list(
    y1 = amCircle(color = "yellow", strokeColor = "olive"),
    y2 = amCircle(color = "orangered", strokeColor = "darkred")
  ),
  alwaysShowBullets = TRUE,
  cursor = list(
    extraTooltipPrecision = list(x = 0, y = 2),
    modifier = list(
      y = c(
        "var value = parseFloat(text);",
        "var style = value > 0 ? '[#0000ff]' : '[#ff0000]';",
        "text = style + text + '[/]';"
      )
    )
  ),
  lineStyle = list(
    y1 = amLine(color = "yellow", width = 4),
    y2 = amLine(color = "orangered", width = 4)
  ),
  chartTitle = amText(
    text = "Gaussian samples",
    color = "whitesmoke",
    fontWeight = "bold"
  ),
  xAxis = list(title = amText(text = "Observation",
                             fontSize = 21,
                             color = "silver",
                             fontWeight = "bold"),
               labels = amAxisLabels(fontSize = 17),
               breaks = amAxisBreaks(
                 values = 1:10,
                 labels = sprintf("[bold %s]%d[/]", rainbow(10), 1:10))),
  yAxis = list(title = amText(text = "Value",
                             fontSize = 21,
                             color = "silver",
                             fontWeight = "bold"),
               labels = amAxisLabels(color = "whitesmoke",
                                     fontSize = 14),
               gridLines = amLine(color = "whitesmoke",
                                  opacity = 0.4,
                                  width = 1)),
  yLimits = c(-3, 3),
  Yformatter = "#.00",
  caption = amText(text = "[font-style:italic]try to drag the yellow line![/]",
                   color = "yellow"),
  theme = "dark")


# line chart with a date x-axis ####

library(lubridate)

set.seed(666)
dat <- data.frame(
  date = ymd(180101) + days(0:60),
  visits = rpois(61, 20)
)

amLineChart(
  data = dat,
  width = "750px",
  xValue = "date",
  yValues = "visits",
  draggable = TRUE,
  chartTitle = "Number of visits",
  xAxis = list(
    title = "Date",
    labels = amAxisLabels(
      formatter = amDateAxisFormatter(
        day = c("dt", "[bold]MMM[/] dt"),
        week = c("dt", "[bold]MMM[/] dt")
      )
    ),
    breaks = amAxisBreaks(timeInterval = "7 days")
  ),
  yAxis = "Visits",
  xLimits = range(dat$date) + c(0,7),
  yLimits = c(0, 35),
  backgroundColor = "whitesmoke",
  tooltip = paste0(
    "[bold][font-style:italic]{dateX.value.formatDate('yyyy/MM/dd')}[/]",
    "\nvisits: {valueY}[/]"
  ),
  caption = amText(text = "Year 2018"),
  theme = "material")


# smoothed lines ####

x <- seq(-4, 4, length.out = 100)
dat <- data.frame(
  x = x,
  Gauss = dnorm(x),
  Cauchy = dcauchy(x)
)

amLineChart(
  data = dat,
  width = "700px",
  xValue = "x",
  yValues = c("Gauss", "Cauchy"),
  yValueNames = list(
    Gauss = "Standard normal distribution",
    Cauchy = "Cauchy distribution"
  ),
  draggable = FALSE,
  tooltip = FALSE,
  lineStyle = amLine(
    width = 4,
    tensionX = 0.8,
    tensionY = 0.8
  ),
  xAxis = list(title = amText(text = "x",
                             fontSize = 21,
                             color = "navyblue"),
               labels = amAxisLabels(
                 color = "midnightblue",
                 fontSize = 17)),
  yAxis = list(title = amText(text = "density",
                              fontSize = 21,
                              color = "navyblue"),
               labels = FALSE),
  theme = "dataviz")