First, you should load recharts:

library(recharts)

1 Introduction

Proper markpoints makes a chart more informative. We can use addMarkPoint (or addMP for short) to add markPoints series by series, timeline by timeline. We can also use overideMarkPoint (or overideMP for short) to overide existing markPoints.

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., mp for markPoint).

addMarkPoint(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = "pin", symbolSize = 10,
  symbolRotate = NULL, large = FALSE, effect = list(show = FALSE),
  itemStyle = NULL, ...)

addMP(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = "pin", symbolSize = 10,
  symbolRotate = NULL, large = FALSE, effect = list(show = FALSE),
  itemStyle = NULL, ...)

add_markpoint(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = "pin", symbolSize = 10,
  symbolRotate = NULL, large = FALSE, effect = list(show = FALSE),
  itemStyle = NULL, ...)

add_mp(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = "pin", symbolSize = 10,
  symbolRotate = NULL, large = FALSE, effect = list(show = FALSE),
  itemStyle = NULL, ...)

addMarkpoint(chart, series = NULL, timeslots = NULL, data = NULL,
  clickable = TRUE, symbol = "pin", symbolSize = 10,
  symbolRotate = NULL, large = FALSE, effect = list(show = FALSE),
  itemStyle = NULL, ...)

overideMarkPoint(chart, ...)

overideMarkpoint(chart, ...)

overideMP(chart, ...)

overide_mp(chart, ...)

overide_markpoint(chart, ...)

overideMP is exactly the same as addMP(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 markPoint to all the timeslots. You can use z for short.

data

Data.frame, the data of the markPoints. It must contain the following columns: name, and/or value / type and/or x / xAxis, y / yAxis and/or series. When series is given, it must be cooresponding to the series argument in addMP call.

  • generic:
    • generic form: columns [name, value, x, y]
    • minimum form: columns [name, x, y]
  • scatter, line, bar:
    • basic form: columns [name, value, x, y]
    • minimum form: columns [name, type] (type can only be ‘max’, ‘min’)
    • axis-mapping: columns [name, value, xAxis, yAxis]
  • k, eventRiver:
    • basic form: [name, value, x, y]
    • axis-mapping: [name, value, xAxis, yAxis]
  • map:
    • [name, value]. You need to pass in [name, lng, lat] using addGeoCoord separately.

Note that markLine dataset is compatible in addMarkPoint.

  • x1, x2 are treated as x (keep the first detected one only)
  • y1, y2 are treated as y (keep the first detected one only)
  • xAxis1, xAxis2 are treated as xAxis (keep the first detected one only)
  • yAxis1, yAxis2 are treated as yAxis (keep the first detected one only)

clickable

Logical, if the points are clickable. Default TRUE.

symbol

Symbol of the markpoints, refer to recharts:::validSymbols. Default ‘pin’.

symbolSize

Numeric or vector c(height, width) or JS function. Default 10.

symbolRotate

Numeric -180 ~ 180. Default NULL.

large

Logical, if large effect is on. Default FALSE.

effect

List. effect configurator of markPoints. Default NULL, which is list(show=FALSE, type='scale', loop=TRUE, period=15, scaleSize=2, bounceDistance=10, 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 markPoint to the echarts object. Default ‘add’. You can use overideMarkPoint to overide data part of existing markPoint.

…

Elipsis.

3 Showcase

3.1 Cartesian Coordinate System

The example below is from Scatterplot Manual.

We, respectively, add markPoints of max, min of data series 1 (‘setosa’) and 2 (‘versicolor’). And we add another two markPoints with absolute position.

The thrid markPoint calls a special data strucutre: a data.frame containing ‘name’, ‘value’, ‘xAxis’, ‘yAxis’. This is the only acceptable form for Cartesian coordinate system.

The fourth markPoint calls a generic data structure which refer to absolute coodinates on the canvas. However, it cannot be correctly parsed in Cartesian coordinate system, and hence is place at the zero coordinate point.

g = echartr(iris, Sepal.Width, Petal.Width, Species) %>% 
    setToolbox(show=FALSE) %>% setTheme(width=400, height=300)
g = g %>% addMP(series=1, data=data.frame(
    name='Max', type='max'))
g
 
g = g %>% addMP(series=2, data=data.frame(
        name='Min', type='min')) 
g
 
g = g %>%  addMP(series=3, data=data.frame(
    name='Misc', value=5, xAxis=3, yAxis=5)) 
g
 
g = g %>% addMP(series='Not Known', data=data.frame(
    name='Not Known', value=2, x=350, y=300))
g

We can combine the data for the three markPoints into a data.frame with valid columns names: ‘name’, ‘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 addMP).

data <- data.frame(
    name=c('Max', 'Min', 'Misc', 'Not Known'), type=c('max', 'min', NA, NA),
    series=c(levels(iris$Species), 'Not Known'), x=c(NA, NA, NA, 350),
    y=c(NA, NA, NA, 300), xAxis=c(NA, NA, 3, NA), yAxis=c(NA, NA, 5, NA))
knitr::kable(data)
name type series x y xAxis yAxis
Max max setosa NA NA NA NA
Min min versicolor NA NA NA NA
Misc NA virginica NA NA 3 5
Not Known NA Not Known 350 300 NA NA 
echartr(iris, Sepal.Width, Petal.Width, Species) %>%
    addMP(series=c(levels(iris$Species), 'Not Known'), 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 addMP 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(
    name=rep('', 4), value=1:4, x=c(190, 490, 190, 490), y=c(132, 132, 348, 348)
)
knitr::kable(data)
name value x y
1 190 132
2 490 132
3 190 348
4 490 348 
g %>% addMP(series='Series Index', data=data) %>% 
    setSeries(series='Series Index', type='scatter')