{"id":23478,"date":"2023-04-09T13:21:53","date_gmt":"2023-04-09T13:21:53","guid":{"rendered":"https:\/\/www.highcharts.com\/blog\/?p=23478"},"modified":"2026-01-13T11:30:12","modified_gmt":"2026-01-13T11:30:12","slug":"highcharts-python-pandas-pyspark","status":"publish","type":"post","link":"https:\/\/www.highcharts.com\/blog\/integration\/highcharts-python-pandas-pyspark\/","title":{"rendered":"Using Highcharts for Python with Pandas and PySpark"},"content":{"rendered":"

Highcharts Core<\/a>\u00a0is the gold standard in JavaScript data visualization, offering far more customizability and interactivity out-of-the-box than \u201cmere\u201d plotting libraries. And using the Highcharts for Python Toolkit<\/a>, you can now easily use it in your Python code (or even in your Jupyter notebook), and rapidly visualize data that you have loaded into a Pandas or PySpark DataFrame<\/b>.<\/p>\n

Tip<\/b>
\nThe Highcharts for Python capabilities are quite extensive, and this tutorial is meant to be a quick intro to using Highcharts for Python with Pandas and PySpark. But we definitely recommend that you review our other tutorials to see more detail on how you can enrich your data visualizations using Highcharts for Python and Highcharts Core.<\/i><\/p>\n

Getting Started with Highcharts for Python<\/h2>\n

To use Highcharts for Python, like with any Python library, you first have to install it. That\u2019s super easy. Just open your project (in your virtual environment \u2013 you are using virtual environments, right?) and execute:<\/p>\n

$ pip install highcharts-core<\/pre>\n
And that\u2019s it Highcharts for Python will now be\u00a0in stalled in\u00a0your\u00a0project and available for use. To use it in your\u00a0code, you just have to import it the way you would any other library.<\/p>\n
Importing Highcharts for Python<\/h2>\n
The Highcharts for Python library is quite extensive. It\u2019s got a rich (read: complicated) API, with lots of different objects and modules. That\u2019s a reflection of the visualization power that Highcharts offers you, but it does make the decision of what to import and how to import it a little more complicated.<\/p>\n
Python\u2019s best practice is to import only what you need, which helps to maximize the performance of your Python code and prevents your application\u2019s namespace from getting cluttered with various things (and further reduces the memory footprint of your Python code, which is always good).<\/p>\n
You can either import specific things from their precise locations, or you can also just import the catch-all highcharts module, which flattens the entire API and exposes just about every class\/object in one location. We definitely recommend importing things from their precise location like so:<\/p>\n
# Import classes using precise module indications. For example:\r\nfrom highcharts_core.chart import Chart\r\nfrom highcharts_core.options import HighchartsOptions\r\nfrom highcharts_core.options.plot_options.scatter import ScatterOptions\r\nfrom highcharts_core.options.series.scatter import ScatterSeries<\/pre>\n
A Super Simple Example<\/h2>\n
So, let\u2019s assume that you are merely analyzing a bunch of data. You have extracted it from the underlying data files or database, loaded it up into a Pandas or PySpark DataFrame<\/b>, and performed whatever calculations you want to perform on your dataset. While Pandas and PySpark are two different libraries, the way that Highcharts for Python visualizes data from either is extremely similar.<\/p>\n
Let\u2019s assume you have your data stored in a DataFrame called df<\/code> (creative, right?). And let\u2019s further assume that you have two columns with the data that you want to plot: one labeled actual<\/code> and one labeled forecast<\/code>. As you can probably guess, we want to plot the forecast against the actuals across the observations in our dataset to better evaluate fit.<\/p>\n
\"Image<\/p>\n
The process of doing this is very simple:<\/p>\n
    \n
  1. Import the Chart<\/code> type from highcharts_core.chart<\/code> and the ScatterSeries<\/code> type from highcharts_core.options.series.scatter<\/code>:\n
    from highcharts_core.chart import Chart\r\nfrom highcharts_core.options.series.scatter import ScatterSeries<\/pre>\n<\/li>\n
  2. Create your two series \u2013 one for actual<\/code> and one for forecast<\/code> \u2013 using the ScatterSeries.from_pandas()<\/code> or ScatterSeries.from_pyspark()<\/code> class method, which will create new ScatterSeries<\/code> instances:\n
    from highcharts_core.options.series.scatter\r\nimport ScatterSeries\r\n# Create a new ScatterSeries instance plotting df['actual']\r\nactual_series = ScatterSeries.from_pandas(df,\r\n  property_map = {\r\n    'x': 'idx',\r\n    'y': 'actual',\r\n    'id': 'actual',\r\n    'name': 'Observed Value for Metric'\r\n  },\r\n  series_type = 'scatter'\r\n)\r\n# Create a new ScatterSeries instance plotting df['forecast']\r\nactual_series = ScatterSeries.from_pandas(df,\r\n    property_map = {\r\n      'x': 'idx',\r\n      'y': 'forecast',\r\n      'id': 'forecast',\r\n      'name': 'Forecast Value for Metric'\r\n    }\r\n)<\/pre>\n<\/li>\n
  3. Create a Chart<\/code> instance and add your two series to it.\n
    # Create a Chart and add your two series to the chart.\r\nmy_chart = Chart.from_series(actual_series, forecast_series)\r\n<\/pre>\n<\/li>\n<\/ol>\n
    And that\u2019s it! Let\u2019s breakdown what\u2019s happening in the method calls above:<\/p>\n
    First, you\u2019re telling the ScatterSeries.from_pandas()<\/code> method which dataframe to use, in this case, df.<\/code> That\u2019s pretty straightforward. But the magic really happens in the property_map argument<\/code>, which tells the method which DataFrame<\/code> columns correspond to which properties in the series\u2019 data points.<\/p>\n
    And then, once your series are created, you create a chart that contains those two series by calling Chart.from_series()<\/code>.<\/p>\n
    The property_map Argument<\/h2>\n
    The property_map<\/code> argument takes a dict<\/code> whose keys correspond to the properties in the series type\u2019s .data<\/code> property. That can seem a little complicated, but think of it this way:
    \nThe Highcharts for Python toolkit supports over 70 different series types in its visualization. Different series types may have different properties for their data points. Some (like the ScatterSeries<\/code> shown above) may be very simple: they get an \u201cx\u201d<\/code> value for the x-axis<\/code>, and a \u201cy\u201d<\/code> value for the y-axis<\/code>, and an \u201cid\u201d<\/code> that uniquely identifies the data point.
    \nThe keys in property_map<\/code> are the data point properties that should be populated. In the example above:<\/p>\n
      \n
    1. The \u201cx\u201d<\/code> key corresponds to the data point\u2019s .x<\/code> property \u2013 which in this case gets populated using the column labeled 'idx'<\/code> in the DataFrame<\/li>\n
    2. The \u201cy\u201d<\/code> key corresponds to the data point\u2019s .y<\/code> property \u2013 which in this case gets populated using the column labeled 'actual'<\/code> for the actual series, and 'forecast'<\/code> for the forecast series.<\/li>\n
    3. The \u201cid\u201d<\/code> key corresponds to the data point\u2019s .id property, which in this case will be given the same ID<\/code> as the original column label, and
      \nThe \u201cname\u201d<\/code> key corresponds to the data point\u2019s .name<\/code> property, which in this case gives each series a label that will be shown in the visualization\u2019s legend.<\/li>\n<\/ol>\n
      So the property_map<\/code> argument tells Highcharts for Python which DataFrame<\/code> column maps to which property. Pretty straightforward!<\/p>\n
      Tip<\/b>
      \nIf you use convenience methods like .from_pandas()<\/code> or .from_pyspark()<\/code> make sure to review the series type\u2019s data points to map your data to the appropriate properties. You can do so in the extensive API reference<\/a> for the series type you want to chart.<\/i><\/p>\n
      Tapping Into Richer Functionality<\/h2>\n
      The .from_pandas()<\/code> and .from_pyspark()<\/code> methods also accept a series_kwargs<\/code> argument, which expects a dict whose keys are keyword parameters that you can use when instantiating the series. Those parameters can be used to further customize how the series gets rendered, including indicating the axis it should be rendered on, adjusting its interactivity, or more. For more details, please see the extensive API reference<\/a> documentation for the series types you wish to visualize.<\/p>\n
      Other Approaches<\/h2>\n
      The example above focuses on using a DataFrame<\/code>, but Highcharts for Python has you covered regardless of how you are managing your data. You have similar convenience functions for loading data:<\/p>\n