Streamlit - ECharts
A custom component to run Echarts in Streamlit session.
It's basically a Streamlit wrapper over echarts-for-react.
Install
pip install streamlit-echarts
Usage
This library provides 2 functions to display echarts :
st_echarts
to display charts from echarts json options as Python dictsst_pyecharts
to display charts from Pyecharts instances
Check the examples/
folder of the project for a more thourough quick start.
st_echarts example
from streamlit_echarts import st_echarts
options = {
"xAxis": {
"type": "category",
"data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
},
"yAxis": {"type": "value"},
"series": [
{"data": [820, 932, 901, 934, 1290, 1330, 1320], "type": "line"}
],
}
st_echarts(options=options)
st_pyecharts example
from pyecharts import options as opts
from pyecharts.charts import Bar
from streamlit_echarts import st_pyecharts
b = (
Bar()
.add_xaxis(["Microsoft", "Amazon", "IBM", "Oracle", "Google", "Alibaba"])
.add_yaxis(
"2017-2018 Revenue in (billion $)", [21.2, 20.4, 10.3, 6.08, 4, 2.2]
)
.set_global_opts(
title_opts=opts.TitleOpts(
title="Top cloud providers 2018", subtitle="2017-2018 Revenue"
),
toolbox_opts=opts.ToolboxOpts(),
)
)
st_pyecharts(b)
st_echarts API
st_echarts(
options: Dict
theme: Union[str, Dict]
events: Dict[str, str]
height: str
width: str
renderer: str
key: str
)
- options : Python dictionary that resembles the JSON counterpart of echarts options. For example the basic line chart in JS :
option = {
xAxis: {
type: 'category',
data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
},
yAxis: { type: 'value' },
series: [
{ data: [820, 932, 901, 934, 1290, 1330, 1320], type: 'line' }
]
};
is represented in Python :
option = {
"xAxis": {
"type": "category",
"data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
},
"yAxis": { "type": "value" },
"series": [
{"data": [820, 932, 901, 934, 1290, 1330, 1320], "type": "line" }
],
}
- theme : echarts theme. You can specify built-int themes or pass over style configuration as a Pythcon dict.
- events : Python dictionary which maps an event to a Js function as string. For example :
{
"click": "function(params) { console.log(params.name) }"
}
will get mapped to :
myChart.on('click', function (params) {
console.log(params.name);
});
- height / width : size of the div wrapper
- renderer : SVG or canvas
- key : assign a fixed identity if you want to change its arguments over time and not have it be re-created.
Using st_pyecharts
def st_pyecharts(
chart: Base
theme: Union[str, Dict]
events: Dict[str, str]
height: str
width: str
renderer: str
key: str
)
- chart : Pyecharts instance
The docs for the remaining inputs are the same as its st_echarts
counterpart.
Development
Install
- JS side
cd frontend
npm install
- Python side
conda create -n streamlit-echarts python=3.7
conda activate streamlit-echarts
pip install -e .
Run
Both webpack dev server and Streamlit need to run for development mode.
- JS side
cd frontend
npm run start
- Python side
streamlit run examples/app.py
Caveats
Theme definition
- Defining the theme in Pyecharts when instantiating chart like
Bar(init_opts=opts.InitOpts(theme=ThemeType.LIGHT))
does not work, you need to call theme inst_pyecharts(c, theme=ThemeType.LIGHT)
.
Maps definition
- For now only china map is loaded. Need to find a way how to load json maps or from URL.
On Javascript functions
This library also provides the JsCode
util class directly from pyecharts
.
This class is used to indicate javascript code by wrapping it with a specific placeholder. On the custom component side, we parse every value in options looking for this specific placeholder to determine whether a value is a JS function.
As such, if you want to pass JS functions as strings in your options,
you should use the corresponding JsCode
module to wrap code with this placeholder :
- In Python dicts representing the JSON option counterpart,
wrap any JS string function with
streamlit_echarts.JsCode
by callingJsCode(function).jscode
. It's a smaller version ofpyecharts.commons.utils.JsCode
so you don't need to installpyecharts
to use it.
series: [
{
type: 'scatter', // this is scatter chart
itemStyle: {
opacity: 0.8
},
symbolSize: JsCode("function (val) { return val[2] * 40;}").js_code,
data: [["14.616","7.241","0.896"],["3.958","5.701","0.955"],["2.768","8.971","0.669"],["9.051","9.710","0.171"],["14.046","4.182","0.536"],["12.295","1.429","0.962"],["4.417","8.167","0.113"],["0.492","4.771","0.785"],["7.632","2.605","0.645"],["14.242","5.042","0.368"]]
}
]
- In Pyecharts, use
pyecharts.commons.utils.JsCode
directly, JsCode automatically calls.jscode
when dumping options.
.set_series_opts(
label_opts=opts.LabelOpts(
position="right",
formatter=JsCode(
"function(x){return Number(x.data.percent * 100).toFixed() + '%';}"
),
)
)
st_pyecharts VS using pyecharts with components.html
While this package provides a st_pyecharts
method, if you're using pyecharts
you can directly embed your pyecharts visualization inside st.html
by passing the output of the chart's .render_embed()
.
from pyecharts.charts import Bar
from pyecharts import options as opts
import streamlit.components.v1 as components
c = (Bar()
.add_xaxis(["Microsoft", "Amazon", "IBM", "Oracle", "Google", "Alibaba"])
.add_yaxis('2017-2018 Revenue in (billion $)', [21.2, 20.4, 10.3, 6.08, 4, 2.2])
.set_global_opts(title_opts=opts.TitleOpts(title="Top cloud providers 2018", subtitle="2017-2018 Revenue"),
toolbox_opts=opts.ToolboxOpts())
.render_embed() # generate a local HTML file
)
components.html(c, width=1000, height=1000)
Using st_pyecharts
is still something you would want if you need to change data regularly
without remounting the component, check for examples examples/app_pyecharts.py
for Chart with randomization
example.