ec.init {echarty}

Initialize command

Description

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

Usage

ec.init(
  df = NULL,
  preset = TRUE,
  ctype = "scatter",
  ...,
  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.

ctype

Chart type, default is 'scatter'.

...

Optional widget attributes. See Details.

series.param

Additional attributes for preset series, default is NULL.
Defines a single series type. Can be used for both non-timeline and timeline series.
Multiple series types need to be defined directly with series=list(list(...),list...) 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.

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:
When data.frame df is chained to ec.init, a dataset is preset.
When the data.frame is grouped and ctype is not null, more datasets with legend and series are also preset.
Plugin '3D' is required for 2D series 'scatterGL'. Use preset=FALSE and set explicitly xAxis and yAxis.
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)

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

• ask - prompt user before downloading plugins when load is present, FALSE by default

• js - single string or a vector with JavaScript expressions to evaluate.
  single: exposed chart object (most common)
  vector:
  ⁠ ⁠First expression is evaluated before chart initialization.
  ⁠ ⁠Second is evaluated with exposed object opts.
  ⁠ ⁠Third is evaluated with exposed chart object after opts set.

• renderer - 'canvas'(default) or 'svg'

• locale - 'EN'(default) or 'ZH'. Use predefined or custom like so.

• useDirtyRect - enable dirty rectangle rendering or not, FALSE by default, see here
  

Built-in plugins:

• leaflet - Leaflet maps with customizable tiles, see source
  

• world - world map with country boundaries, see source
  

• lottie - support for lotties
  

• ecStat - statistical tools, seeecharts-stat
  

• custom - renderers for ecr.band and ecr.ebars
  Plugins with one-time installation:
  

• 3D - 3D charts and WebGL acceleration, see source and docs
  

• liquid - liquid fill, see source
  

• gmodular - graph modularity, see source
  

• wordcloud - cloud of words, see source
  or install your own third-party plugins.
  

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.
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.
Timeline cannot be used for hierarchical charts like graph,tree,treemap,sankey. Chart options/timeline have to be built directly, see example.

Encode
A series attribute to define 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 Example: encode(x='col3', y='col1') binds xAxis to df column 'col3'.

Value

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

Examples

 # basic scatter chart from a data.frame, using presets
cars |> ec.init()
 
 # grouping, tooltips, formatting
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'))
  )
)

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