Highcharts for Python - High-end Data Visualization for the Python Ecosystem


Highcharts Maps for Python

High-end data and map visualization for the Python ecosystem

Highcharts Maps for Python is an extension to the Highcharts for Python library, and provides a Python wrapper for the fantastic Highcharts Maps JavaScript data visualization library. Highcharts Maps for Python also supports

  • Highcharts JS - the core Highcharts data visualization library

  • The Highcharts Export Server - enabling the programmatic creation of static (downloadable) data visualizations

In order to integrate Highcharts Maps for Python into the Python ecosystem, the library features native integration with:

  • Jupyter Labs/Notebook. You can now produce high-end and interactive plots and renders using the full suite of Highcharts visualization capabilities.

  • Pandas. Automatically produce data visualizations from your Pandas dataframes

  • PySpark. Automatically produce data visualizations from data in a PySpark dataframe.

  • GeoPandas. Automatically incorporate GIS / map visualizations with data from your GeoPandas GeoDataFrames.

  • Topojson. Automatically visualizes TopoJSON map geometries.

  • Geojson. Automatically visualizes GeoJSON map geometries.

Installation

To install Highcharts Maps for Python, just execute:

$ pip install highcharts-maps

Dependencies

Note

Highcharts Maps for Python has several types of dependencies:

  • “hard” dependencies, without which you will not be able to use the library at all,

  • “soft” dependencies, which will not produce errors but which may limit the value you get from the library,

  • “developer” dependencies that contributors will need in their local environment, and

  • “documentation” dependencies that are necessary if you wish to generate (this) documentation

Warning

If these hard dependencies are not available in the environment where Highcharts Maps for Python is running, then the library will simply not work. Besides Highcharts JS itself, all of the other hard dependencies are automatically installed when installing Highcharts Maps for Python using:

$ pip install highcharts-core

Why Highcharts for Python?

Odds are you are aware of Highcharts Maps. If not, why not? It is the world’s most popular, most powerful, category-defining JavaScript data visualization library and - in particular - for map/GIS data.

If you are building a web or mobile app/dashboard that will be visualizing data in a geographic context, you should absolutely take a look at the Highcharts suite of solutions. Just take a look at some of their fantastic Highcharts Maps demo visualizations.

Highcharts Maps is a JavaScript library, and is an extension of the Highcharts JS JavaScript library. It is written in JavaScript, and is specifically used to configure and render data visualizations in a web browser (or other JavaScript-executing, like mobile app) environment. As a JavaScript library, its audience is JavaScript developers. But what about the broader ecosystem of Python developers and data scientists?

Python is increasingly used as the technology of choice for data science and for the backends of leading enterprise-grade applications. In other words, Python is often the backend that delivers data and content to the front-end…which then renders it using JavaScript and HTML.

There are numerous Python frameworks (Django, Flask, Tornado, etc.) with specific capabilities to simplify integration with Javascript frontend frameworks (React, Angular, VueJS, etc.). But facilitating that with Highcharts has historically been very difficult. Part of this difficulty is because the Highcharts JavaScript suite - while supporting JSON as a serialization/deserialization format - leverages JavaScript object literals to expose the full power and interactivity of its data visualizations. And while it’s easy to serialize JSON from Python, serializing and deserializing to/from JavaScript object literal notation is much more complicated. This means that Python developers looking to integrate with Highcharts typically had to either invest a lot of effort, or were only able to leverage a small portion of Highcharts’ rich functionality.

So I wrote the Highcharts for Python toolkit to bridge that gap, and Highcharts Maps for Python to provide full support for the Highcharts Maps library extension.

Highcharts Maps for Python provides support for the Highcharts Maps extension, which is designed to provide extensive time series data visualization capabilities optimized for GIS data visualization, with robust interactivity. For ease of use, it also includes the full functionality of Highcharts for Python as well.

Key Highcharts Maps for Python Features

  • Clean and consistent API. No reliance on “hacky” code, dict and JSON serialization, or impossible to maintain / copy-pasted “spaghetti code”.

  • Comprehensive Highcharts support. Every single Highcharts chart type and every single configuration option is supported in Highcharts Maps for Python. This includes the over 70 data visualization types supported by Highcharts JS and the four core map visualizations available in Highcharts Maps, with full support for the rich JavaScript formatter (JS callback functions) capabilities that are often needed to get the most out of Highcharts’ visualization and interaction capabilities.

    See also

  • Simple JavaScript Code Generation. With one method call, produce production-ready JavaScript code to render your interactive visualizations using Highcharts’ rich capabilities.

  • Easy Chart Download. With one method call, produce high-end static visualizations that can be downloaded or shared as files with your audience. Produce static charts using the Highsoft-provided Highcharts Export Server, or using your own private export server as needed.

  • Asynchronous Map Data Retrieval. To minimize the amount of data transferred over the wire, Highcharts Maps for Python has built-in support for the configuration of asynchronous client-side retrieval of your map data.

  • Automatic TopoJSON Optimization. To minimize the amount of data transferred over the wire, Highcharts Maps for Python automatically converts your map geometries to highly-efficient TopoJSON topologies while still allowing you to work with GeoJSON data if you choose to.

  • Integration with GeoPandas, Pandas, and PySpark. With two lines of code, produce a high-end interactive visualization of your GeoPandas, Pandas, or PySpark dataframes.

  • Consistent Code Style. For Python developers, switching between Pythonic code conventions and JavaScript code conventions can be…annoying. So Highcharts for Python applies Pythonic syntax with automatic conversion between Pythonic snake_case notation and JavaScript camelCase styles.


Highcharts Maps for Python vs Alternatives

Since Highcharts Maps is one of the most popular high-end GIS data visualization libraries for JavaScript, there are a variety of alternative ways of working with it in Python. We have an obvious bias towards Highcharts Maps for Python, but it may be useful to compare it against some commonly-used alternatives:

By far, this is the most common approach to integrating Highcharts into your Python code. As a developer, you know that your JavaScript front-end will be using Highcharts Stock. So you work in your Python backend to deliver the data to your front-end that your front-end will need. Simple, right? Often, more complicated than one might think.

There are many patterns for rolling your own Highcharts + Python implementation, but the patterns I have seen most often include:

  • Hands Off Approach. Your Python code is “hands off” - it does not touch any data visualization configuration or manipulation. All of that gets handled in your JavaScript front-end code.

  • JSON Serialization. Your Python code constructs a JSON object (typically by serializing a Python dict to JSON) which gets delivered to your JavaScript front-end, which then hands the JSON code off to Highcharts to visualize.

  • Custom Serialization. The most sophisticated implementations I have seen actually replicate much of the functionality of Highcharts for Python, where they construct JavaScript object literal notation serialization and de-serialization for their robust use cases.

  • Don’t Use Highcharts. In many cases, particularly when working with data science teams who are data scientists first and software developers by necessity, the team turns to weaker data visualization packages because they are available in Python.

The first approach is very “clean” from a code architecture standpoint. It maintains good separation of concerns, and leaves the problem of visualization to where (architecturally) it should be: in your front-end code. However, in practice it is often problematic because it delegates data manipulation and (potentially) business logic handling to your front-end code. Depending on the overall design of your application, it can make your code harder to maintain. Furthermore, depending on your team composition, it may simply be impractical for your team.

The second approach is also fairly clean. JSON, after all, is easy in both Python and JavaScript. But JSON is a suboptimal transport mechanism for some of Highcharts most powerful features: callback functions. As these are native JavaScript code, they cannot be serialized securely to JSON and then executed directly by the Highcharts library. This is a big security anti-pattern, so while simple use cases can be handled through JSON serialization, many more sophisticated uses of Highcharts (which would rely on formatters, event handling, etc.) will simply not work.

The third approach is the most robust. And for the most sophisticated Highcharts + Python applications that I have seen, it has been the approach of choice because it eliminates all of the limitations of the other approaches mentioned. But to do it on a custom basis takes a huge amount of effort, because the complexity of constructing a library like Highcharts for Python is non-trivial.

And the fourth option is - in my experience - one of the most common. Even though plenty of developers coming to Python from the JavaScript ecosystem ask “Why can’t we just use Highcharts?”, many in the Python ecosystem will answer “because it’s a pain to do”. So they turn to Highcharts alternatives that are more Python-friendly, like plotly.

Highcharts for Python and its Highcharts Maps for Python extension are designed to eliminate this pain.

Tip

When to use it?

In practice, I find that rolling my own is great when I’m doing a limited number of simple and static (non-interactive) visualizations. Then I just quickly use some simple JSON serialization, and rapidly get a high-quality chart visualized cleanly using Highcharts. But anything more robust than that is going to prove “hacky” and incredibly difficult to maintain.

Which is why I wrote Highcharts for Python and Highcharts Maps for Python.

Hello World, and Basic Usage

1. Import Highcharts Maps for Python

Tip

Best Practice!

This method of importing Highcharts Maps for Python objects yields the fastest performance for the import statement. However, it is more verbose and requires you to navigate the extensive Highcharts Maps for Python API.

# Import classes using precise module indications. For example:
from highcharts_maps.chart import Chart
from highcharts_maps.global_options.shared_options import SharedMapsOptions
from highcharts_maps.options import HighchartsMapsOptions
from highcharts_maps.options.plot_options.map import MapOptions
from highcharts_maps.options.series.map import MapSeries

2. Create Your Chart

# from a JavaScript file
my_chart = highcharts.Chart.from_js_literal('my_js_literal.js')

# from a JSON file
my_chart = highcharts.Chart.from_json('my_json.json')

# from a Python dict
my_chart = highcharts.Chart.from_dict(my_dict_obj)

# from a GeoPandas GeoDataFrame
my_chart = highcharts.Chart.from_geopandas(gdf,
                                           property_map = {
                                               'z': 'caseCount',
                                               'id': 'id',
                                           },
                                           series_type = 'mapbubble')

# from a Pandas dataframe
my_chart = highcharts.Chart.from_pandas(df,
                                        property_map = {
                                            'x': 'transactionDate',
                                            'y': 'invoiceAmt',
                                            'id': 'id'
                                        },
                                        series_type = 'line')

# from a PySpark dataframe
my_chart = highcharts.Chart.from_pyspark(df,
                                         property_map = {
                                             'x': 'transactionDate',
                                             'y': 'invoiceAmt',
                                             'id': 'id'
                                         },
                                         series_type = 'line')

# from a CSV
my_chart = highcharts.Chart.from_csv('/some_file_location/filename.csv'
                                     column_property_map = {
                                        'x': 0,
                                        'y': 4,
                                        'id': 14
                                     },
                                     series_type = 'line')

# from a HighchartsOptions configuration object
my_chart = highcharts.Chart.from_options(my_options)

# from a Series configuration
my_chart = highcharts.Chart.from_series(my_series)

3. Configure Global Settings (optional)

# Import SharedMapsOptions
from highcharts_maps.global_options.shared_options import SharedMapsOptions

# from a JavaScript file
my_global_settings = SharedMapsOptions.from_js_literal('my_js_literal.js')

# from a JSON file
my_global_settings = SharedMapsOptions.from_json('my_json.json')

# from a Python dict
my_global_settings = SharedMapsOptions.from_dict(my_dict_obj)

# from a HighchartsOptions configuration object
my_global_settings = SharedMapsOptions.from_options(my_options)

4. Configure Your Chart / Global Settings

from highcharts_maps.options.title import Title
from highcharts_maps.options.credits import Credits

# Using dicts
my_chart.title = {
    'align': 'center'
    'floating': True,
    'text': 'The Title for My Chart',
    'use_html': False,
}

my_chart.credits = {
    'enabled': True,
    'href': 'https://www.highcharts.com/',
    'position': {
        'align': 'center',
        'vertical_align': 'bottom',
        'x': 123,
        'y': 456
    },
    'style': {
        'color': '#cccccc',
        'cursor': 'pointer',
        'font_size': '9px'
    },
    'text': 'Chris Modzelewski'
}

# Using direct objects
from highcharts_maps.options.title import Title
from highcharts_maps.options.credits import Credits

my_title = Title(text = 'The Title for My Chart', floating = True, align = 'center')
my_chart.options.title = my_title

my_credits = Credits(text = 'Chris Modzelewski', enabled = True, href = 'https://www.highcharts.com')
my_chart.options.credits = my_credits

5. Generate the JavaScript Code for Your Chart

Now having configured your chart in full, you can easily generate the JavaScript code that will render the chart wherever it is you want it to go:

# as a string
js_as_str = my_chart.to_js_literal()

# to a file (and as a string)
js_as_str = my_chart.to_js_literal(filename = 'my_target_file.js')

6. Generate the JavaScript Code for Your Global Settings (optional)

# as a string
global_settings_js = my_global_settings.to_js_literal()

# to a file (and as a string)
global_settings_js = my_global_settings.to_js_literal('my_target_file.js')

7. Generate a Static Version of Your Chart

# as in-memory bytes
my_image_bytes = my_chart.download_chart(format = 'png')

# to an image file (and as in-memory bytes)
my_image_bytes = my_chart.download_chart(filename = 'my_target_file.png',
                                         format = 'png')

Getting Help/Support

The Highcharts for Python toolkit comes with all of the great support that you are used to from working with the Highcharts JavaScript libraries. When you license the toolkit, you are welcome to use any of the following tools to get help using the toolkit. In particular, you can:

FOR MORE INFORMATION: https://www.highchartspython.com/get-help

Contributing

We welcome contributions and pull requests! For more information, please see the Contributor Guide. And thanks to all those who’ve already contributed:

Testing

We use TravisCI for our build automation and ReadTheDocs for our documentation.

Detailed information about our test suite and how to run tests locally can be found in our Testing Reference.

Indices and tables