Skip to contents

Initialize a chart

Source: R/echarty.R
ec.init.Rd

Required to build a chart. In most cases this will be the only command necessary.

Usage

ec.init(
  df = NULL,
  preset = TRUE,
  ...,
  series.param = NULL,
  tl.series = NULL,
  width = NULL,
  height = NULL
)

Arguments

df

Optional data.frame to be preset as dataset, default NULL
By default the first column is for X values, second column is for Y, and third is for Z when in 3D.
Best practice is to have the grouping column placed last. Grouping column cannot be used as axis.
Timeline requires a grouped data.frame to build its options.
If grouping is on multiple columns, only the first one is used to determine settings.

preset

Boolean (default TRUE). Build preset attributes like dataset, series, xAxis, yAxis, etc.
When preset is FALSE, these attributes need to be set explicitly.

...

Optional widget attributes. See Details.

series.param

Additional attributes for single preset series, default is NULL.
Defines a single series for both non-timeline and timeline charts. Default type is 'scatter'.
Multiple series need to be defined directly with series=list(list(type=...),list(type=...)) or added with ec.upd.

tl.series

Deprecated, use timeline and series.param instead.

width, height

Optional valid CSS unit (like '100%', '500px', 'auto') or a number, which will be coerced to a string and have 'px' appended.

Value

A widget to plot, or to save and expand with more features.

Details

Command ec.init creates a widget with createWidget, then adds some ECharts features to it.
Numerical indexes for series,visualMap,etc. are R-counted (1,2...)

Presets
A dataset is pre-set when data.frame df is present.
When df is grouped, more datasets with legend and series are also preset.
Axes for some charts are preset with name and type when suitable.
Plugin '3D' (load='3D') is required for GL series like scatterGL, linesGL, etc.
Plugins 'leaflet' and 'world' preset center to the mean of all coordinates from df.
Users can delete or overwrite any presets as needed.

Widget attributes
Optional echarty widget attributes include:

  • elementId - Id of the widget, default is NULL(auto-generated, stored as echwid variable for JS)

  • load - name(s) of plugin(s) to load. A character vector or comma-delimited string. default NULL.

  • ask - boolean to prompt user before downloading plugins when load is present, default is FALSE.
      Could also be string 'loadRemote' to load plugins remotely.

  • ctype - alternative way of setting chart type name, default is 'scatter'.

  • js - single string or a vector with JavaScript expressions to evaluate.
    single: exposed chart object (most common)
    vector:   see code in examples
      First expression evaluated with exposed objects window and echarts
      Second is evaluated with exposed object opts.
      Third is evaluated with exposed chart object after initialization with opts already set.

  • theme - name of built-in theme to apply, or JSON object from fromJSON, see opts in echarts.init

  • iniOpts - a list of initialization options, see opts in echarts.init
      Defaults: renderer='canvas', locale='EN', useDirtyRect=FALSE

  • on,off,capture,group - chart instance properties, namely:
      on/off is a list of events to handle with JS, each in a list, see chart.on and example below
      capture is a vector of event names to capture in Shiny, etc.

  • connect,disconnect,register,etc. - see echarts object methods

Built-in plugins

  • leaflet - Leaflet maps with customizable tiles, see source

  • world - world map with country boundaries, see source

  • lottie - support for https://lottiefiles.com

  • ecStat - statistical tools, seeecharts-stat

  • custom - renderers for echarty plugins like ecr.band and ecr.ebars

Plugins with one-time installation

  • 3D - support for 3D charts and WebGL acceleration, see source and docs
      This plugin is auto-loaded when 3D/GL axes/series are detected.

  • gmodular - graph modularity, see source

  • liquid - liquid fill, see source

  • wordcloud - cloud of words, see source
    Note: the last three are being moved to the official custom series.
    OR install your own third-party plugins like confetti, see example below.

Crosstalk
Parameter df should be of type SharedData, see more info.
Optional parameter xtKey: unique ID column name of data frame df. Must be same as key parameter used in SharedData$new(). If missing, a new column XkeyX will be appended to df.
Enabling crosstalk will also generate an additional dataset called Xtalk and bind the first series to it.

Timeline
Defined by series.param for the options series and a timeline list for the actual control. A grouped df is required, each group providing data for one option serie. Timeline data and options will be preset for the chart.
Each option title can include the current timeline item by adding a placeholder '%@' in title$text. See example below.
Another preset is encode(x=1,y=2,z=3), which are the first 3 columns of df. Parameter z is ignored in 2D. See Details below.
Optional attribute groupBy, a df column name, can create series groups inside each timeline option.
Options/timeline for hierarchical charts like graph,tree,treemap,sankey have to be built directly, see example.

Optional series attribute encode defines which columns to use for the axes, depending on chart type and coordinate system:

  • set x and y for coordinateSystem cartesian2d

  • set lng and lat for coordinateSystem geo and scatter series

  • set value and name for coordinateSystem geo and map series

  • set radius and angle for coordinateSystem polar

  • set value and itemName for pie chart.

There is an advanced usage of encode when each series' item needs to be customized.
For example encode= list(itemStyle= list(opacity='opac')) will create series data where each series item's opacity comes from df column 'opac'.
This binding feature is specific to echarty and does not exist in ECharts. See example below.

Examples

 # basic scatter chart from a data.frame using presets
cars |> ec.init()



 # custom inititlization options and theme
myth <- '{"color": ["green"], "backgroundColor": "lemonchiffon"}'
ec.init( cars,
  iniOpts= list(renderer= 'svg', width= '222px'),
  theme= jsonlite::fromJSON(myth),
  toolbox= list(feature= list(saveAsImage= list()))
)


 
 # grouping, tooltips, formatting, events
iris |> dplyr::group_by(Species) |> 
ec.init(        # init with presets
  tooltip= list(show= TRUE),
  series.param= list( 
    symbolSize= ec.clmn('Petal.Width', scale=7),
    tooltip= list(formatter= ec.clmn('Petal.Width: %@', 'Petal.Width'))
  ),
  on= list(   # events with Javascript handler
    list(event= 'legendselectchanged', handler= ec.clmn("(e) => alert('legend:'+e.name);"))
 )
)



data.frame(n=1:5) |> dplyr::group_by(n) |> ec.init(
  title= list(text= "gauge #%@"),
  timeline= list(show=TRUE, autoPlay=TRUE),
  series.param= list(type='gauge', max=5)
)



ec.init(
  series.param= list(
    renderItem= 'segmentedDoughnut',   # v.6  from https://github.com/apache/echarts-custom-series
    itemPayload= list(segmentCount= 8, label= list(show=TRUE, formatter= '{c}/{b}', fontSize=35) ),
    data= list(5) )
)



ec.init(cars, js= 'confetti();',  # js code executes on init
  load= 'https://cdn.jsdelivr.net/npm/canvas-confetti@1.9.4/dist/confetti.browser.min.js',
  ask= 'loadRemote',
  on= list(list(event= 'click', handler= ec.clmn('() => confetti()')) )
)