First, you should load recharts:

library(recharts)

1 Introduction

Proper marklines makes a chart more informative. We can use addMarkLine (or addML for short) to add markLines series by series, timeline by timeline. We can also use overideMarkLine (or overideML for short) to overide existing markLines.

2 Function Call

All the function names have two forms: small camel and lowercase_underscore (endorsed by Hadley Wickham). To be lazy, we also provide short forms as well (e.g., ml for markLine).

addMarkLine(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = c("circle", "arrow"), symbolSize = c(2, 4),
  symbolRotate = NULL, large = FALSE, smooth = FALSE, smoothness = 0.2,
  precision = 2, bundling = list(enable = FALSE, maxTurningAngle = 45),
  effect = list(show = FALSE), itemStyle = NULL, mode = c("add",
  "overide"), ...)

addML(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = c("circle", "arrow"), symbolSize = c(2, 4),
  symbolRotate = NULL, large = FALSE, smooth = FALSE, smoothness = 0.2,
  precision = 2, bundling = list(enable = FALSE, maxTurningAngle = 45),
  effect = list(show = FALSE), itemStyle = NULL, mode = c("add",
  "overide"), ...)

addMarkline(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = c("circle", "arrow"), symbolSize = c(2, 4),
  symbolRotate = NULL, large = FALSE, smooth = FALSE, smoothness = 0.2,
  precision = 2, bundling = list(enable = FALSE, maxTurningAngle = 45),
  effect = list(show = FALSE), itemStyle = NULL, mode = c("add",
  "overide"), ...)

add_markline(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = c("circle", "arrow"), symbolSize = c(2, 4),
  symbolRotate = NULL, large = FALSE, smooth = FALSE, smoothness = 0.2,
  precision = 2, bundling = list(enable = FALSE, maxTurningAngle = 45),
  effect = list(show = FALSE), itemStyle = NULL, mode = c("add",
  "overide"), ...)

add_ml(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = c("circle", "arrow"), symbolSize = c(2, 4),
  symbolRotate = NULL, large = FALSE, smooth = FALSE, smoothness = 0.2,
  precision = 2, bundling = list(enable = FALSE, maxTurningAngle = 45),
  effect = list(show = FALSE), itemStyle = NULL, mode = c("add",
  "overide"), ...)

overideMarkLine(chart, ...)

overideMarkline(chart, ...)

overideML(chart, ...)

overideML is exactly the same as addML(mode='overide', ...).

Arg Requirement

chart

Echarts object generated by echartR or echart.

series

Numeric (series index) or character (series name), numeric preferred. If set NULL, then apply the markPoint to all the series.

timeslots

Numeric (timeslot index) or character (timeslot name), numeric is preferred. If set NULL, then apply the markLine to all the timeslots. You can use z for short.

data

Data.frame, the data of the markLines. It must contain the following columns: name1, name2, value / type and/or x1 / xAxis1, y1 / yAxis1, x2 / xAxis2, y2 / yAxis2 and/or series. When series is given, it must be cooresponding to the series argument in addML call.

  • generic:
    • generic form: columns [name1, name2, value, x1, y1, x2, y2]
    • minimum form: columns [name1, x1, y1, x2, y2]
  • scatter, line, bar:
    • basic form: columns [name1, name2, value, x1, y1, x2, y2]
    • minimum form: columns [name1, type] (type can only be ‘max’, ‘min’ or ‘average’)
    • axis-mapping: columns [name1, name2, value, xAxis1, yAxis1, xAxis2, yAxis2]
  • k, eventRiver:
    • basic form: [name1, name2, value, x1, y1, x2, y2]
    • axis-mapping: [name1, name2, value, xAxis1, yAxis1, xAxis2, yAxis2]
  • map:
    • [name1, name2, value]. You need to pass in [name1, lng1, lat1], [name2, lng2, lat2] using addGeoCoord separately.

clickable

Logical, if the graphs are clickable. Default TRUE.

symbol

Symbol vector of the markLines, refer to recharts:::validSymbols. Default c('circle', 'arrow').

symbolSize

Numeric vector or JS function defining the size of the the beginning symbol and the end symbol of the marklines. Default c(2, 4).

symbolRotate

Numeric -180 ~ 180. Default NULL.

large

Logical, if large effect is on. Default FALSE.

effect

List. effect configurator of markLines. Default NULL, which is list(show=FALSE, loop=TRUE, period=15, scaleSize=2, color=NULL, shadowColor=NULL, shadowBlur=0)

itemStyle

List. It is a list with the structure list(normal=list(...), emphasis=list(...)). Default NULL.

mode

‘add’ or ‘overide’ the data part of markLine to the echarts object. Default ‘add’. You can use overideMarkLine to overide data part of existing markLine.

…

Elipsis.

3 Showcase

3.1 Cartesian Coordinate System

The example below is from Scatterplot Manual.

lm <- with(iris, lm(Petal.Width~Sepal.Width))
pred <- predict(lm, data.frame(Sepal.Width=c(2, 4.5)))

We, respectively, add markLines of max, mean, min of data series 1 (‘setosa’), 2 (‘versicolor’) and 3 (‘virginica’). Then we addditionally add markLine of linear regression model.

The fourth markLine calls a special data strucutre: a data.frame containing ‘name1’, ‘value’, ‘xAxis1’, ‘yAxis1’, ‘xAxis2’, and ‘yAxis2’. This is the only acceptable form for Cartesian coordinate system.

g = echartr(iris, Sepal.Width, Petal.Width, Species) %>% 
    setToolbox(show=FALSE) %>% setTheme(width=400, height=300)
g = g %>% addML(series=1, data=data.frame(
    name1='Max', type='max'))
g
 
g = g %>% addML(series=2, data=data.frame(
        name1='Mean', type='average')) 
g
 
g = g %>%  addML(series=3, data=data.frame(
    name1='Min', type='min')) 
g
 
g %>% addML(series='Linear Regr', data=data.frame(
    name1='Regr', value=round(lm$coefficients[2], 3), 
    xAxis1=2, yAxis1=pred[1], xAxis2=4.5, yAxis2=pred[2]))

We can also combine the markLine data into one data.frame with valid columns names: ‘name1’, ‘type’, ‘series’, etc., of which ‘series’ must be corrsponding to the series argumnet (i.e. each row of data will be mapped to series argument of addML).

data <- data.frame(
    name1=c('Max', 'Mean', 'Min', 'Linear Regr'), 
    type=c('max', 'average', 'min', NA),
    series=c(levels(iris$Species), 'Linear Regr'),
    value=c(rep(NA, 3), round(lm$coefficients[2], 3)),
    xAxis1=c(rep(NA, 3), 2),
    yAxis1=c(rep(NA, 3), pred[1]), 
    xAxis2=c(rep(NA, 3), 4.5),
    yAxis2=c(rep(NA, 3), pred[2])
)
knitr::kable(data)
name1 type series value xAxis1 yAxis1 xAxis2 yAxis2
Max max setosa NA NA NA NA NA
Mean average versicolor NA NA NA NA NA
Min min virginica NA NA NA NA NA
Linear Regr NA Linear Regr -0.64 2 1.876319 4.5 0.2756276 
echartr(iris, Sepal.Width, Petal.Width, Species) %>%
    addML(series=c(levels(iris$Species), 'Linear Regr'), data=data)

3.2 Non-cartesian Coordinate System

When it applies to non-cartesian coordinate system (polar or geographic), do not provide an axis-mapping form of dataset. For polar coordinate system, x and y are cooresponding to position on the canvas, while for geographic system, it accepts lng and lat from addGeoCoord instead of addML call.

Note that the zero point on the canvas is upper-left point.

Let’s use the example in Pie Chart Manual.

titanic <- data.table::melt(apply(Titanic, c(1,4), sum))
names(titanic) <- c('Class', 'Survived', 'Count')
g <- echartr(titanic, Survived, Count, facet=Class, type='pie') 
## Warning in split_indices(.group, .n): '.Random.seed' is not an integer
## vector but of type 'NULL', so ignored
data <- data.frame(
    name1=c('hor', 'ver'), name2=c('', ''), value=c(NA, NA), x1=c(10, 336), 
    y1=c(240, 470), x2=c(660, 336), y2=c(240, 10)
)
knitr::kable(data)
name1 name2 value x1 y1 x2 y2
hor NA 10 240 660 240
ver NA 336 470 336 10 
g %>% addML(series='crossing', data=data) %>% 
    setSeries(series='crossing', type='line')