Echarts custom component for Streamlit
Project description
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 Python 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
- map : register a map using the dedicated
Map
class
from streamlit_echarts import Map
with open("USA.json", "r") as f:
map = Map(
"USA",
json.loads(f.read()),
{
"Alaska": {"left": -131, "top": 25, "width": 15},
"Hawaii": {"left": -110, "top": 28, "width": 5},
"Puerto Rico": {"left": -76, "top": 26, "width": 2},
},
)
options = {...}
st_echarts(options, map=map)
You'll find a lot of GeoJSON data inside the source code of echarts-countries-js.
- 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
Demo example is on https://github.com/andfanilo/streamlit-echarts-demo.
git clone https://github.com/andfanilo/streamlit-echarts-demo
cd streamlit-echarts-demo/
streamlit run 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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for streamlit_echarts-0.3.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4b1ba1e76d92c65aac5250b4eb482de4fc1f34bbed89667ca35424e2f339ad50 |
|
MD5 | 7d43c151baf4afb2a92b93b6f2a804da |
|
BLAKE2b-256 | cf16ef6b62c7bc0662520334dc48b8205bd73392d3a2fed407e84d10931a2d85 |