# python-highcharts [](https://circleci.com/gh/kyper-data/python-highcharts)
## License
The python-highcharts wrapper is licensed under the [MIT license](http://opensource.org/licenses/MIT).
However, please be aware that the Highcharts project itself, as well as Highmaps and Highstock, are only free for non-commercial use under the Creative Commons Attribution-NonCommercial license. Commercial use requires the purchase of a separate license. Pop over to [Highcharts](http://shop.highsoft.com/) for more information.
## Overview
python-highcharts is a simple translation layer between Python and Javascript for Highcharts projects (highcharts, highmaps, and highstocks).
In addition, python-highcharts integrates with [Jupyter notebook](https://github.com/jupyter/notebook), which enables you to render Highcharts, Highmaps, and Highstock visualizations directly in notebooks. See examples [here](https://github.com/kyper-data/python-highcharts/tree/developer/examples/ipynb).
The original framework was inspired by [python-nvd3](https://github.com/areski/python-nvd3) and [PyHighcharts](https://github.com/fidyeates/PyHighcharts).
## Installation
python-highcharts supports Python 2.7/3.4+ and is available on PyPI. To install:
```
pip install python-highcharts
```
---------------------------------------------------------------------------------------------------------------
# Highcharts/Highstock
## Basic Usage
Usage of python-highcharts is very similar to usage of the original Javascript library.
The main input is a python dictionary similar to Highcharts's 'options' object. The dictionary supports most options listed in the official [Highcharts documentation](http://api.highcharts.com/highcharts).
However, the data_set(s) need to be input by a separate function.
```python
from highcharts import Highchart
# A chart is the container that your data will be rendered in, it can (obviously) support multiple data series within it.
chart = Highchart()
# Adding a series requires at minimum an array of data points.
# You can also change the series type, the name, or other series options as kwargs.
data = range(1,20)
chart.add_data_set(data, series_type='line', name='Example Series')
# This will generate and save a .html file at the location you assign
chart.save_file()
```
You can add chart options using set_options. Ex:
```python
chart.set_options('chart', {'resetZoomButton': {'relativeTo': 'plot', 'position': {'x': 0,'y': -30}}})
chart.set_options('xAxis', {'events': {'afterBreaks': 'function(e){return}'}})
chart.set_options('tooltip', {'formatter': 'default_tooltip'})
```
The set_options function can update the options automatically if you input the same option_type. Ex:
```python
chart.set_options('chart', {'style': {"fontSize": '22px'}})
chart.set_options('chart', {'resetZoomButton': {'position': {'x': 10}}})
chart.set_options('chart', {'resetZoomButton': {'relativeTo': 'chart'}})
chart.set_options('xAxis', {'plotBands': {'color': '#FCFFC5', 'from': 2, 'to': 4}})
chart.set_options('xAxis', {'plotBands': {'color': '#FCFFC5', 'from': 6, 'to': 8}})
chart.set_options('xAxis', {'plotBands': {'color': '#FCFFC5', 'from': 10, 'to': 12}})
```
However, the better practice is to construct chart options by a dictionary (as Highcharts suggests: http://www.highcharts.com/docs/getting-started/your-first-chart) and then input by the set_dict_options function. Ex:
```python
options = {
'title': {
'text': 'Atmosphere Temperature by Altitude'
},
'subtitle': {
'text': 'According to the Standard Atmosphere Model'
},
'xAxis': {
'reversed': False,
'title': {
'enabled': True,
'text': 'Altitude'
},
'labels': {
'formatter': 'function () {\
return this.value + "km";\
}'
},
'maxPadding': 0.05,
'showLastLabel': True
},
'yAxis': {
'title': {
'text': 'Temperature'
},
'labels': {
'formatter': "function () {\
return this.value + '°';\
}"
},
'lineWidth': 2
},
'legend': {
'enabled': False
},
'tooltip': {
'headerFormat': '<b>{series.name}</b><br/>',
'pointFormat': '{point.x} km: {point.y}°C'
}
}
chart.set_dict_options(options)
```
Unlike Javascript Highcharts, the series option can't be included in the options dictionary. It needs to input by the add_data_set (and/or add_drilldown_data_set) function, Ex:
```python
chart.add_data_set(data, 'scatter', 'Outlier',
marker={
'fillColor': 'white',
'lineWidth': 1,
'lineColor': 'Highcharts.getOptions().colors[0]'
},
tooltip={'pointFormat': 'Observation: {point.y}'}
)
chart.add_drilldown_data_set(data_2, 'column', 'Chrome', name='Chrome')
```
## Example Usage
```python
from highcharts import Highchart
chart = Highchart()
chart.set_options('chart', {'inverted': True})
options = {
'title': {
'text': 'Atmosphere Temperature by Altitude'
},
'subtitle': {
'text': 'According to the Standard Atmosphere Model'
},
'xAxis': {
'reversed': False,
'title': {
'enabled': True,
'text': 'Altitude'
},
'labels': {
'formatter': 'function () {\
return this.value + "km";\
}'
},
'maxPadding': 0.05,
'showLastLabel': True
},
'yAxis': {
'title': {
'text': 'Temperature'
},
'labels': {
'formatter': "function () {\
return this.value + '°';\
}"
},
'lineWidth': 2
},
'legend': {
'enabled': False
},
'tooltip': {
'headerFormat': '<b>{series.name}</b><br/>',
'pointFormat': '{point.x} km: {point.y}°C'
}
}
chart.set_dict_options(options)
data = [[0, 15], [10, -50], [20, -56.5], [30, -46.5], [40, -22.1],
[50, -2.5], [60, -27.7], [70, -55.7], [80, -76.5]]
chart.add_data_set(data, 'spline', 'Temperature', marker={'enabled': False})
chart.save_file()
```
## Jupyter/IPython notebook
To render charts in Jupyter notebooks, simply put the chart object on the last line of a cell:
```python
chart.set_dict_options(options)
data = [[0, 15], [10, -50], [20, -56.5], [30, -46.5], [40, -22.1],
[50, -2.5], [60, -27.7], [70, -55.7], [80, -76.5]]
chart.add_data_set(data, 'spline', 'Temperature', marker={'enabled': False})
chart
```
### Example notebooks:
* [Highcharts](http://nbviewer.ipython.org/github/kyper-data/python-highcharts/blob/master/examples/ipynb/highcharts/Example1.ipynb)
* [Highmaps](http://nbviewer.ipython.org/github/kyper-data/python-highcharts/blob/master/examples/ipynb/highmaps/Example1.ipynb)
* [Highstock](http://nbviewer.ipython.org/github/kyper-data/python-highcharts/blob/master/examples/ipynb/highstock/Example1-basic-line.ipynb)
## Todo:
* More charts support
* Clean code and put more explanation
Reference: [Highcharts API](http://api.highcharts.com/highcharts)
---------------------------------------------------------------------------------------------------------------
# Highmaps
## Basic Usage
Usage of python-highcharts is very similar to usage of the original Javascript library.
The main input is a python dictionary similar to Highmaps's 'options' object. The dictionary supports most options listed in the official [Highmaps documentation](http://api.highcharts.com/highmaps).
However, the data_set(s) need to be input by a separate function.
```python
from highcharts import Highmap
# A chart is the container that your data will be rendered in, it can (obviously) support multiple data series within it.
chart = Highmap()
# Adding a series requires a minimum of one argument, an array of data points
chart.add_data_set(data, series_type='map', name='Example Series')
# This will generate and save a .html file at the location you assign
chart.save_file()
```
Although you can add chart option using set_options, but
a better practice is to construct chart options by a dictionary (as highcharts suggests: http://www.highcharts.com/docs/getting-started/your-first-chart) and then input by set_dict_optoins function. Ex.
```python
options = {
'chart': {
'borderWidth': 1,
'marginRight': 50
},
'title': {
'text': 'US Counties unemployment rates, April 2015'
},
'legend': {
'title': {
'text': 'Unemployment<br>rate',
'style': {
'color': "(Highcharts.theme && Highcharts.theme.textColor) || 'black'"
}
},
'layout': 'vertical',
'align': 'right',
'floating': True,
'valueDecimals': 0,
'valueSuffix': '%',
'backgroundColor': "(Highcharts.theme && Highcharts.theme.legendBackgroundColor) || 'rgba(255, 255, 255, 0.85)'",
'symbolRadius': 0,
'symbolHeight': 14
},
'mapNavigation': {
'enabled': True
},
'colorAxis': {
'dataClasses': [{
'from': 0,
'to': 2,
'color': "#F1EEF6"
}, {
'from': 2,
'to': 4,
'color': "#D4B9DA"
}, {
'from': 4,
'to': 6,
'color': "#C994C7"
}, {
'from': 6,
'to': 8,
'color': "#DF65B0"
}, {
'from': 8,
'to': 10,
'color': "#DD1C77"
}, {
'from': 10,
'color': "#980043"
}]
},
'plotOptions': {
'map':{
'mapData': 'geojson'
},
'mapline': {
'showInLegend': False,
'enableMouseTracking': False
}
},
}
chart.set_dict_options(options)
```
The map data is set by set_map_source function. It is recommended to use the map collection on highcharts: http://code.highcharts.com/mapdata/
For the map properties visit: http://www.highcharts.com/docs/maps/map-collection
The default setting is to use the Highchart Javascript map.
```python
# set_map_source requires a least one argument: the map data url
chart.set_map_source('http://code.highcharts.com/mapdata/countries/us/us-all-all.js', jsonp_map = False)
```
However, the better practice is to load map data using function in highmap_helper library
and convert it in preparation to be added directly by the add_map or add_data_set functions.
```python
from highmap_helper import jsonp_loader, js_map_loader, geojson_handler
map_url = 'http://code.highcharts.com/mapdata/countries/us/us-all-all.js'
# Load .js format map data from the source and convert to GeoJSON object
geojson = js_map_loader(map_url)
# Similarly, json format (jsonp) map data can be loaded using:
geojson = jsonp_loader("a_jsonp_map_url")
# Reconstruct a GeoJSON object in preparation to be read directly.
# geojson_handler function is similar to Highcharts.geojson in Highcharts: http://api.highcharts.com/highmaps#Highcharts.geojson
mapdata = geojson_handler(geojson)
chart.add_map_data(mapdata)
```
The series option in Highmaps needs to be input separately using add_data_set (and/or add_drilldown_data_set) function, Ex.
```python
chart.add_data_set(data, 'map', 'Unemployment rate', joinBy=['hc-key', 'code'],
tooltip={
'valueSuffix': '%'
},
borderWidth = 0.5,
states={
'hover': {
'color': '#bada55'
}
}
)
chart.add_drilldown_data_set(sub_data, 'map', id=mapkey, name=item['name'],
dataLabels={
'enabled': True,
'format': '{point.name}'
}
)
```
The data set can be loaded directly from the url (jsonp format), but it is not recommended:
```python
data_url = 'http://www.highcharts.com/samples/data/jsonp.php?filename=us-counties-unemployment.json&callback=?'
chart.add_data_from_jsonp(data_url, 'json_data', 'map', 'Unemployment rate', joinBy=['hc-key', 'code'],
tooltip={
'valueSuffix': '%'
},
borderWidth = 0.5,
states={
'hover': {
'color': '#bada55'
}
}
)
```
Furthermore, python-highcharts has a function to add Javascript in the beginning or the end of JQuery body: $(function(){},
but, again, it is not recommended unless it is really necessary.
```python
# function requires at least two arguments: script (javascript) and location ('head' or 'end')
chart.add_JSscript("var lines = Highcharts.geojson(Highcharts.maps['countries/us/us-all-all'], 'mapline');", 'head')
```
## Examples
Bad practice:
1) load data directly and handle it in Javascript 2) insert javascript into thea head 3) use unquote function RawJavaScriptText to prepare Javascript:
```python
from highcharts import Highmap
from common import RawJavaScriptText
chart = Highmap()
options = {
'chart': {
'borderWidth': 1,
'marginRight': 50
},
'title': {
'text': 'US Counties unemployment rates, April 2015'
},
'legend': {
'title': {
'text': 'Unemployment<br>rate',
'style': {
'color': "(Highcharts.theme && Highcharts.theme.textColor) || 'black'"
}
},
'layout': 'vertical',
'align': 'right',
'floating': True,
'valueDecimals': 0,
'valueSuffix': '%',
'backgroundColor': "(Highcharts.theme && Highcharts.theme.legendBackgroundColor) || 'rgba(255, 255, 255, 0.85)'",
'symbolRadius': 0,
'symbolHeight': 14
},
'mapNavigation': {
'enabled': True
},
'colorAxis': {
'dataClasses': [{
'from': 0,
'to': 2,
'color': "#F1EEF6"
}, {
'from': 2,
'to': 4,
'color': "#D4B9DA"
}, {
'from': 4,
'to': 6,
'color': "#C994C7"
}, {
'from': 6,
'to': 8,
'color': "#DF65B0"
}, {
'from': 8,
'to': 10,
'color': "#DD1C77"
}, {
'from': 10,
'color': "#980043"
}]
},
'plotOptions': {
'mapline': {
'showInLegend': False,
'enableMouseTracking': False
}
}
}
chart.set_dict_options(options)
data_url = 'http://www.highcharts.com/samples/data/jsonp.php?filename=us-counties-unemployment.json&callback=?'
chart.add_data_from_jsonp(data_url, 'json_data', 'map', 'Unemployment rate',
joinBy=['hc-key', 'code'],
tooltip={'valueSuffix': '%'},
borderWidth=0.5,
states={'hover': {'color': '#bada55'}}
)
chart.add_data_set(RawJavaScriptText('[lines[0]]'), 'mapline', 'State borders', color = 'white')
chart.add_data_set(RawJavaScriptText('[lines[1]]'), 'mapline', 'Separator', color = 'gray')
chart.set_map_source('http://code.highcharts.com/mapdata/countries/us/us-all-all.js', jsonp_map = False)
chart.add_JSscript("var lines = Highcharts.geojson(Highcharts.maps['countries/us/us-all-all'], 'mapline');", 'head')
chart.add_JSscript("Highcharts.each(geojson, function (mapPoint) {\
mapPoint.name = mapPoint.name + ', ' + mapPoint.properties['hc-key'].substr(3, 2);\
});", 'head')
chart.save_file()
```
Better practice:
```python
from highcharts import Highmap
from highmap_helper import jsonp_loader, js_map_loader, geojson_handler
chart = Highmap()
options = {
'chart': {
'borderWidth': 1,
'marginRight': 50
},
'title': {
'text': 'US Counties unemployment rates, April 2015'
},
'legend': {
'title': {
'text': 'Unemployment<br>rate',
'style': {
'color': "(Highcharts.theme && Highcharts.theme.textColor) || 'black'"
}
},
'layout': 'vertical',
'align': 'right',
'floating': True,
'valueDecimals': 0,
'valueSuffix': '%',
'backgroundColor': "(Highcharts.theme && Highcharts.theme.legendBackgroundColor) || 'rgba(255, 255, 255, 0.85)'",
'symbolRadius': 0,
'symbolHeight': 14
},
'mapNavigation': {
'enabled': True
},
'colorAxis': {
'dataClasses': [{
'from': 0,
'to': 2,
'color': "#F1EEF6"
}, {
'from': 2,
'to': 4,
'color': "#D4B9DA"
}, {
'from': 4,
'to': 6,
'color': "#C994C7"
}, {
'from': 6,
'to': 8,
'color': "#DF65B0"
}, {
'from': 8,
'to': 10,
'color': "#DD1C77"
}, {
'from': 10,
'color': "#980043"
}]
},
'plotOptions': {
'map':{
'mapData': 'geojson'
},
'mapline': {
'showInLegend': False,
'enableMouseTracking': False
}
}
}
chart.set_dict_options(options)
# read data and map directly from url
data_url = 'http://www.highcharts.com/samples/data/jsonp.php?filename=us-counties-unemployment.json&callback=?'
map_url = 'http://code.highcharts.com/mapdata/countries/us/us-all-all.js'
data = jsonp_loader(data_url)
geojson = js_map_loader(map_url)
mapdata = geojson_handler(geojson)
lines = geojson_handler(geojson, 'mapline')
for x in mapdata:
x.update({'name':x['name']+', '+x['properties']['hc-key'].split('-')[1].upper()})
#map(lambda x: x['properties'].update({'name':x['properties']['name']+', '+x['properties']['hc-key'].split('-')[1]}), geojson['features'])
chart.add_data_set(data, 'map', 'Unemployment rate', joinBy = ['hc-key', 'code'],
tooltip={'valueSuffix': '%'},
borderWidth=0.5,
states={
'hover': {
'color': '#bada55'
}
}
)
chart.add_data_set([lines[0]], 'mapline', 'State borders', color = 'white')
chart.add_data_set([lines[3]], 'mapline', 'Separator', color = 'gray')
chart.add_map_data(mapdata)
chart.save_file()
```
## Todo:
* More examples
* Clean code and put more explanation
Reference: [Highcharts API](http://api.highcharts.com/highcharts)
Raw data
{
"_id": null,
"home_page": "https://github.com/excentis/python-highcharts",
"name": "python-highcharts-excentis",
"maintainer": "Excentis Software",
"docs_url": null,
"requires_python": "",
"maintainer_email": "support@excentis.com",
"keywords": "python,ipython,highcharts,chart,visualization,graph,javascript,html",
"author": "Kyper Developers",
"author_email": "developers@kyperdata.com",
"download_url": "https://files.pythonhosted.org/packages/74/71/476ac5cc61606816a27546e5b74b9abad547fc8739bb549fe2ca05195ab6/python-highcharts-excentis-0.4.3b20230324.tar.gz",
"platform": null,
"description": "# python-highcharts [](https://circleci.com/gh/kyper-data/python-highcharts)\n\n## License\n\nThe python-highcharts wrapper is licensed under the [MIT license](http://opensource.org/licenses/MIT).\n\nHowever, please be aware that the Highcharts project itself, as well as Highmaps and Highstock, are only free for non-commercial use under the Creative Commons Attribution-NonCommercial license. Commercial use requires the purchase of a separate license. Pop over to [Highcharts](http://shop.highsoft.com/) for more information.\n\n## Overview\n\npython-highcharts is a simple translation layer between Python and Javascript for Highcharts projects (highcharts, highmaps, and highstocks).\n\nIn addition, python-highcharts integrates with [Jupyter notebook](https://github.com/jupyter/notebook), which enables you to render Highcharts, Highmaps, and Highstock visualizations directly in notebooks. See examples [here](https://github.com/kyper-data/python-highcharts/tree/developer/examples/ipynb).\n\nThe original framework was inspired by [python-nvd3](https://github.com/areski/python-nvd3) and [PyHighcharts](https://github.com/fidyeates/PyHighcharts).\n\n## Installation\n\npython-highcharts supports Python 2.7/3.4+ and is available on PyPI. To install:\n```\npip install python-highcharts\n```\n\n---------------------------------------------------------------------------------------------------------------\n# Highcharts/Highstock\n\n## Basic Usage\n\nUsage of python-highcharts is very similar to usage of the original Javascript library. \n\nThe main input is a python dictionary similar to Highcharts's 'options' object. The dictionary supports most options listed in the official [Highcharts documentation](http://api.highcharts.com/highcharts). \n\nHowever, the data_set(s) need to be input by a separate function.\n\n```python\nfrom highcharts import Highchart\n\n# A chart is the container that your data will be rendered in, it can (obviously) support multiple data series within it.\nchart = Highchart()\n\n# Adding a series requires at minimum an array of data points. \n# You can also change the series type, the name, or other series options as kwargs.\ndata = range(1,20)\nchart.add_data_set(data, series_type='line', name='Example Series')\n\n# This will generate and save a .html file at the location you assign\nchart.save_file()\n```\n\nYou can add chart options using set_options. Ex:\n```python\nchart.set_options('chart', {'resetZoomButton': {'relativeTo': 'plot', 'position': {'x': 0,'y': -30}}})\nchart.set_options('xAxis', {'events': {'afterBreaks': 'function(e){return}'}})\nchart.set_options('tooltip', {'formatter': 'default_tooltip'})\n```\n\nThe set_options function can update the options automatically if you input the same option_type. Ex:\n```python\nchart.set_options('chart', {'style': {\"fontSize\": '22px'}})\nchart.set_options('chart', {'resetZoomButton': {'position': {'x': 10}}})\nchart.set_options('chart', {'resetZoomButton': {'relativeTo': 'chart'}})\nchart.set_options('xAxis', {'plotBands': {'color': '#FCFFC5', 'from': 2, 'to': 4}})\nchart.set_options('xAxis', {'plotBands': {'color': '#FCFFC5', 'from': 6, 'to': 8}})\nchart.set_options('xAxis', {'plotBands': {'color': '#FCFFC5', 'from': 10, 'to': 12}})\n```\n\nHowever, the better practice is to construct chart options by a dictionary (as Highcharts suggests: http://www.highcharts.com/docs/getting-started/your-first-chart) and then input by the set_dict_options function. Ex:\n```python\noptions = {\n 'title': {\n 'text': 'Atmosphere Temperature by Altitude'\n },\n 'subtitle': {\n 'text': 'According to the Standard Atmosphere Model'\n },\n 'xAxis': {\n 'reversed': False,\n 'title': {\n 'enabled': True,\n 'text': 'Altitude'\n },\n 'labels': {\n 'formatter': 'function () {\\\n return this.value + \"km\";\\\n }'\n },\n 'maxPadding': 0.05,\n 'showLastLabel': True\n },\n 'yAxis': {\n 'title': {\n 'text': 'Temperature'\n },\n 'labels': {\n 'formatter': \"function () {\\\n return this.value + '\u00b0';\\\n }\"\n },\n 'lineWidth': 2\n },\n 'legend': {\n 'enabled': False\n },\n 'tooltip': {\n 'headerFormat': '<b>{series.name}</b><br/>',\n 'pointFormat': '{point.x} km: {point.y}\u00b0C'\n }\n}\n\nchart.set_dict_options(options)\n```\n\nUnlike Javascript Highcharts, the series option can't be included in the options dictionary. It needs to input by the add_data_set (and/or add_drilldown_data_set) function, Ex:\n```python\nchart.add_data_set(data, 'scatter', 'Outlier', \n marker={\n 'fillColor': 'white',\n 'lineWidth': 1,\n 'lineColor': 'Highcharts.getOptions().colors[0]'\n },\n tooltip={'pointFormat': 'Observation: {point.y}'}\n)\n\nchart.add_drilldown_data_set(data_2, 'column', 'Chrome', name='Chrome')\n```\n\n\n## Example Usage\n\n```python\nfrom highcharts import Highchart\nchart = Highchart()\n\nchart.set_options('chart', {'inverted': True})\n\noptions = {\n 'title': {\n 'text': 'Atmosphere Temperature by Altitude'\n },\n 'subtitle': {\n 'text': 'According to the Standard Atmosphere Model'\n },\n 'xAxis': {\n 'reversed': False,\n 'title': {\n 'enabled': True,\n 'text': 'Altitude'\n },\n 'labels': {\n 'formatter': 'function () {\\\n return this.value + \"km\";\\\n }'\n },\n 'maxPadding': 0.05,\n 'showLastLabel': True\n },\n 'yAxis': {\n 'title': {\n 'text': 'Temperature'\n },\n 'labels': {\n 'formatter': \"function () {\\\n return this.value + '\u00b0';\\\n }\"\n },\n 'lineWidth': 2\n },\n 'legend': {\n 'enabled': False\n },\n 'tooltip': {\n 'headerFormat': '<b>{series.name}</b><br/>',\n 'pointFormat': '{point.x} km: {point.y}\u00b0C'\n }\n}\n\nchart.set_dict_options(options)\ndata = [[0, 15], [10, -50], [20, -56.5], [30, -46.5], [40, -22.1], \n[50, -2.5], [60, -27.7], [70, -55.7], [80, -76.5]]\nchart.add_data_set(data, 'spline', 'Temperature', marker={'enabled': False}) \n\nchart.save_file()\n\n```\n\n## Jupyter/IPython notebook\n\nTo render charts in Jupyter notebooks, simply put the chart object on the last line of a cell:\n\n```python\nchart.set_dict_options(options)\ndata = [[0, 15], [10, -50], [20, -56.5], [30, -46.5], [40, -22.1], \n[50, -2.5], [60, -27.7], [70, -55.7], [80, -76.5]]\nchart.add_data_set(data, 'spline', 'Temperature', marker={'enabled': False}) \n\nchart\n```\n\n### Example notebooks:\n\n* [Highcharts](http://nbviewer.ipython.org/github/kyper-data/python-highcharts/blob/master/examples/ipynb/highcharts/Example1.ipynb)\n* [Highmaps](http://nbviewer.ipython.org/github/kyper-data/python-highcharts/blob/master/examples/ipynb/highmaps/Example1.ipynb)\n* [Highstock](http://nbviewer.ipython.org/github/kyper-data/python-highcharts/blob/master/examples/ipynb/highstock/Example1-basic-line.ipynb)\n\n## Todo:\n\n* More charts support\n* Clean code and put more explanation\n\nReference: [Highcharts API](http://api.highcharts.com/highcharts)\n\n---------------------------------------------------------------------------------------------------------------\n# Highmaps\n\n## Basic Usage\n\nUsage of python-highcharts is very similar to usage of the original Javascript library. \n\nThe main input is a python dictionary similar to Highmaps's 'options' object. The dictionary supports most options listed in the official [Highmaps documentation](http://api.highcharts.com/highmaps). \n\nHowever, the data_set(s) need to be input by a separate function.\n\n```python\nfrom highcharts import Highmap\n\n# A chart is the container that your data will be rendered in, it can (obviously) support multiple data series within it.\nchart = Highmap()\n\n# Adding a series requires a minimum of one argument, an array of data points\nchart.add_data_set(data, series_type='map', name='Example Series')\n\n# This will generate and save a .html file at the location you assign\nchart.save_file()\n```\n\nAlthough you can add chart option using set_options, but\na better practice is to construct chart options by a dictionary (as highcharts suggests: http://www.highcharts.com/docs/getting-started/your-first-chart) and then input by set_dict_optoins function. Ex.\n\n```python\noptions = {\n 'chart': {\n 'borderWidth': 1,\n 'marginRight': 50 \n },\n\n 'title': {\n 'text': 'US Counties unemployment rates, April 2015'\n },\n\n 'legend': {\n 'title': {\n 'text': 'Unemployment<br>rate',\n 'style': {\n 'color': \"(Highcharts.theme && Highcharts.theme.textColor) || 'black'\"\n }\n },\n 'layout': 'vertical',\n 'align': 'right',\n 'floating': True,\n 'valueDecimals': 0,\n 'valueSuffix': '%',\n 'backgroundColor': \"(Highcharts.theme && Highcharts.theme.legendBackgroundColor) || 'rgba(255, 255, 255, 0.85)'\",\n 'symbolRadius': 0,\n 'symbolHeight': 14\n },\n\n 'mapNavigation': {\n 'enabled': True\n },\n\n 'colorAxis': {\n 'dataClasses': [{\n 'from': 0,\n 'to': 2,\n 'color': \"#F1EEF6\"\n }, {\n 'from': 2,\n 'to': 4,\n 'color': \"#D4B9DA\"\n }, {\n 'from': 4,\n 'to': 6,\n 'color': \"#C994C7\"\n }, {\n 'from': 6,\n 'to': 8,\n 'color': \"#DF65B0\"\n }, {\n 'from': 8,\n 'to': 10,\n 'color': \"#DD1C77\"\n }, {\n 'from': 10,\n 'color': \"#980043\"\n }]\n },\n\n 'plotOptions': {\n 'map':{\n 'mapData': 'geojson'\n\n },\n 'mapline': {\n 'showInLegend': False,\n 'enableMouseTracking': False\n }\n },\n} \n\nchart.set_dict_options(options)\n\n```\n\nThe map data is set by set_map_source function. It is recommended to use the map collection on highcharts: http://code.highcharts.com/mapdata/\n\nFor the map properties visit: http://www.highcharts.com/docs/maps/map-collection\n\nThe default setting is to use the Highchart Javascript map.\n\n```python\n\n# set_map_source requires a least one argument: the map data url\nchart.set_map_source('http://code.highcharts.com/mapdata/countries/us/us-all-all.js', jsonp_map = False)\n```\n\nHowever, the better practice is to load map data using function in highmap_helper library \nand convert it in preparation to be added directly by the add_map or add_data_set functions. \n\n```python\nfrom highmap_helper import jsonp_loader, js_map_loader, geojson_handler\n\nmap_url = 'http://code.highcharts.com/mapdata/countries/us/us-all-all.js'\n\n# Load .js format map data from the source and convert to GeoJSON object\ngeojson = js_map_loader(map_url)\n\n# Similarly, json format (jsonp) map data can be loaded using:\ngeojson = jsonp_loader(\"a_jsonp_map_url\")\n\n# Reconstruct a GeoJSON object in preparation to be read directly. \n# geojson_handler function is similar to Highcharts.geojson in Highcharts: http://api.highcharts.com/highmaps#Highcharts.geojson\nmapdata = geojson_handler(geojson)\n\nchart.add_map_data(mapdata)\n\n```\n\nThe series option in Highmaps needs to be input separately using add_data_set (and/or add_drilldown_data_set) function, Ex.\n\n```python\nchart.add_data_set(data, 'map', 'Unemployment rate', joinBy=['hc-key', 'code'], \n tooltip={\n 'valueSuffix': '%'\n },\n borderWidth = 0.5,\n states={\n 'hover': {\n 'color': '#bada55'\n }\n }\n)\nchart.add_drilldown_data_set(sub_data, 'map', id=mapkey, name=item['name'], \n dataLabels={\n 'enabled': True,\n 'format': '{point.name}'\n }\n)\n```\n\nThe data set can be loaded directly from the url (jsonp format), but it is not recommended:\n```python\ndata_url = 'http://www.highcharts.com/samples/data/jsonp.php?filename=us-counties-unemployment.json&callback=?'\nchart.add_data_from_jsonp(data_url, 'json_data', 'map', 'Unemployment rate', joinBy=['hc-key', 'code'], \n tooltip={\n 'valueSuffix': '%'\n },\n borderWidth = 0.5,\n states={\n 'hover': {\n 'color': '#bada55'\n }\n }\n)\n\n```\n\nFurthermore, python-highcharts has a function to add Javascript in the beginning or the end of JQuery body: $(function(){},\nbut, again, it is not recommended unless it is really necessary. \n\n```python\n# function requires at least two arguments: script (javascript) and location ('head' or 'end')\nchart.add_JSscript(\"var lines = Highcharts.geojson(Highcharts.maps['countries/us/us-all-all'], 'mapline');\", 'head')\n```\n\n## Examples\n\nBad practice: \n1) load data directly and handle it in Javascript 2) insert javascript into thea head 3) use unquote function RawJavaScriptText to prepare Javascript:\n```python\nfrom highcharts import Highmap\nfrom common import RawJavaScriptText\n\nchart = Highmap()\n\noptions = {\n 'chart': {\n 'borderWidth': 1,\n 'marginRight': 50 \n },\n 'title': {\n 'text': 'US Counties unemployment rates, April 2015'\n },\n 'legend': {\n 'title': {\n 'text': 'Unemployment<br>rate',\n 'style': {\n 'color': \"(Highcharts.theme && Highcharts.theme.textColor) || 'black'\"\n }\n },\n 'layout': 'vertical',\n 'align': 'right',\n 'floating': True,\n 'valueDecimals': 0,\n 'valueSuffix': '%',\n 'backgroundColor': \"(Highcharts.theme && Highcharts.theme.legendBackgroundColor) || 'rgba(255, 255, 255, 0.85)'\",\n 'symbolRadius': 0,\n 'symbolHeight': 14\n },\n 'mapNavigation': {\n 'enabled': True\n },\n 'colorAxis': {\n 'dataClasses': [{\n 'from': 0,\n 'to': 2,\n 'color': \"#F1EEF6\"\n }, {\n 'from': 2,\n 'to': 4,\n 'color': \"#D4B9DA\"\n }, {\n 'from': 4,\n 'to': 6,\n 'color': \"#C994C7\"\n }, {\n 'from': 6,\n 'to': 8,\n 'color': \"#DF65B0\"\n }, {\n 'from': 8,\n 'to': 10,\n 'color': \"#DD1C77\"\n }, {\n 'from': 10,\n 'color': \"#980043\"\n }]\n },\n 'plotOptions': {\n 'mapline': {\n 'showInLegend': False,\n 'enableMouseTracking': False\n }\n }\n} \n\nchart.set_dict_options(options)\ndata_url = 'http://www.highcharts.com/samples/data/jsonp.php?filename=us-counties-unemployment.json&callback=?'\nchart.add_data_from_jsonp(data_url, 'json_data', 'map', 'Unemployment rate', \n joinBy=['hc-key', 'code'], \n tooltip={'valueSuffix': '%'},\n borderWidth=0.5,\n states={'hover': {'color': '#bada55'}}\n)\nchart.add_data_set(RawJavaScriptText('[lines[0]]'), 'mapline', 'State borders', color = 'white')\nchart.add_data_set(RawJavaScriptText('[lines[1]]'), 'mapline', 'Separator', color = 'gray')\nchart.set_map_source('http://code.highcharts.com/mapdata/countries/us/us-all-all.js', jsonp_map = False)\nchart.add_JSscript(\"var lines = Highcharts.geojson(Highcharts.maps['countries/us/us-all-all'], 'mapline');\", 'head')\nchart.add_JSscript(\"Highcharts.each(geojson, function (mapPoint) {\\\n mapPoint.name = mapPoint.name + ', ' + mapPoint.properties['hc-key'].substr(3, 2);\\\n});\", 'head')\n\nchart.save_file()\n```\n\nBetter practice: \n```python\n\nfrom highcharts import Highmap\nfrom highmap_helper import jsonp_loader, js_map_loader, geojson_handler\n\nchart = Highmap()\noptions = {\n 'chart': {\n 'borderWidth': 1,\n 'marginRight': 50 \n },\n 'title': {\n 'text': 'US Counties unemployment rates, April 2015'\n },\n 'legend': {\n 'title': {\n 'text': 'Unemployment<br>rate',\n 'style': {\n 'color': \"(Highcharts.theme && Highcharts.theme.textColor) || 'black'\"\n }\n },\n 'layout': 'vertical',\n 'align': 'right',\n 'floating': True,\n 'valueDecimals': 0,\n 'valueSuffix': '%',\n 'backgroundColor': \"(Highcharts.theme && Highcharts.theme.legendBackgroundColor) || 'rgba(255, 255, 255, 0.85)'\",\n 'symbolRadius': 0,\n 'symbolHeight': 14\n },\n 'mapNavigation': {\n 'enabled': True\n },\n 'colorAxis': {\n 'dataClasses': [{\n 'from': 0,\n 'to': 2,\n 'color': \"#F1EEF6\"\n }, {\n 'from': 2,\n 'to': 4,\n 'color': \"#D4B9DA\"\n }, {\n 'from': 4,\n 'to': 6,\n 'color': \"#C994C7\"\n }, {\n 'from': 6,\n 'to': 8,\n 'color': \"#DF65B0\"\n }, {\n 'from': 8,\n 'to': 10,\n 'color': \"#DD1C77\"\n }, {\n 'from': 10,\n 'color': \"#980043\"\n }]\n },\n 'plotOptions': {\n 'map':{\n 'mapData': 'geojson'\n },\n 'mapline': {\n 'showInLegend': False,\n 'enableMouseTracking': False\n }\n }\n} \n\nchart.set_dict_options(options)\n\n# read data and map directly from url\ndata_url = 'http://www.highcharts.com/samples/data/jsonp.php?filename=us-counties-unemployment.json&callback=?'\nmap_url = 'http://code.highcharts.com/mapdata/countries/us/us-all-all.js'\n\ndata = jsonp_loader(data_url)\ngeojson = js_map_loader(map_url)\nmapdata = geojson_handler(geojson)\nlines = geojson_handler(geojson, 'mapline')\nfor x in mapdata:\n x.update({'name':x['name']+', '+x['properties']['hc-key'].split('-')[1].upper()})\n\n#map(lambda x: x['properties'].update({'name':x['properties']['name']+', '+x['properties']['hc-key'].split('-')[1]}), geojson['features'])\n\nchart.add_data_set(data, 'map', 'Unemployment rate', joinBy = ['hc-key', 'code'], \n tooltip={'valueSuffix': '%'},\n borderWidth=0.5,\n states={\n 'hover': {\n 'color': '#bada55'\n }\n }\n)\nchart.add_data_set([lines[0]], 'mapline', 'State borders', color = 'white')\nchart.add_data_set([lines[3]], 'mapline', 'Separator', color = 'gray')\nchart.add_map_data(mapdata)\n\nchart.save_file()\n\n```\n\n## Todo:\n\n* More examples\n* Clean code and put more explanation\n\nReference: [Highcharts API](http://api.highcharts.com/highcharts)\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Python Highcharts wrapper",
"version": "0.4.3b20230324",
"split_keywords": [
"python",
"ipython",
"highcharts",
"chart",
"visualization",
"graph",
"javascript",
"html"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "05d300ed7fc39f8f3c508c6e849e43ad656fadd970513317e34b4e2f9ea1eccb",
"md5": "780201b8ee71df20de7b32e7931493b5",
"sha256": "01ac25eeeb53f121a3a57618bb14e4cd749cc90221e656b84cd2be65e859c2f0"
},
"downloads": -1,
"filename": "python_highcharts_excentis-0.4.3b20230324-py3-none-any.whl",
"has_sig": false,
"md5_digest": "780201b8ee71df20de7b32e7931493b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 64982,
"upload_time": "2023-03-24T14:37:28",
"upload_time_iso_8601": "2023-03-24T14:37:28.979958Z",
"url": "https://files.pythonhosted.org/packages/05/d3/00ed7fc39f8f3c508c6e849e43ad656fadd970513317e34b4e2f9ea1eccb/python_highcharts_excentis-0.4.3b20230324-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7471476ac5cc61606816a27546e5b74b9abad547fc8739bb549fe2ca05195ab6",
"md5": "7f6a0a0a2535782e5b97c2a30df7d9af",
"sha256": "ae59b99281f7d345d4993f48b846ed634855e21eb3bff9fff9b447ce723fca0e"
},
"downloads": -1,
"filename": "python-highcharts-excentis-0.4.3b20230324.tar.gz",
"has_sig": false,
"md5_digest": "7f6a0a0a2535782e5b97c2a30df7d9af",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 58215,
"upload_time": "2023-03-24T14:37:31",
"upload_time_iso_8601": "2023-03-24T14:37:31.455747Z",
"url": "https://files.pythonhosted.org/packages/74/71/476ac5cc61606816a27546e5b74b9abad547fc8739bb549fe2ca05195ab6/python-highcharts-excentis-0.4.3b20230324.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-24 14:37:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "excentis",
"github_project": "python-highcharts",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "python-highcharts-excentis"
}
JSON
