###################################################
Highcharts Maps for Python
###################################################
**High-end data and map visualizations for the Python ecosystem**
**Highcharts Maps for Python** is an extension to the
`Highcharts Core for Python <https://core-docs.highchartspython.com>`__ library, providing
a Python wrapper for the
`Highcharts Maps <https://www.highcharts.com/products/maps/>`__
JavaScript data visualization library.
**Highcharts Maps for Python** also supports
* **Highcharts Core (JS)** - the core Highcharts data visualization library
* The **Highcharts Export Server** - enabling the programmatic creation of static
(downloadable) data visualizations
The library supports Highcharts (JS) v.10.2 and higher, including Highcharts (JS) v.11.4.0.
**Highcharts Maps for Python** is fully integrated with the broader Python ecosystem,
offering native integrations 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.
**COMPLETE DOCUMENTATION:** https://maps-docs.highchartspython.com/en/latest/index.html
--------------------
***************************************
The Highcharts for Python Toolkit
***************************************
The **Highcharts Maps for Python** library is part of the broader
`Highcharts for Python Toolkit <https://www.highcharts.com/integrations/python>`__,
which together provides comprehensive support across the entire
`Highcharts <https://www.highcharts.com>`__ suite of data visualization libraries:
.. list-table::
:widths: 30 30 40
:header-rows: 1
* - Python Library
- JavaScript Library
- Description
* - `Highcharts Core for Python <https://core-docs.highchartspython.com/>`__
- `Highcharts Core (JS) <https://www.highcharts.com/products/highcharts/>`__
- (this library) the core Highcharts data visualization library
* - `Highcharts Stock for Python <https://stock-docs.highchartspython.com/>`__
- `Highcharts Stock (JS) <https://www.highcharts.com/products/stock/>`__
- the time series visualization extension to Highcharts Core
* - **Highcharts Maps for Python**
- `Highcharts Maps (JS) <https://www.highcharts.com/products/maps/>`__
- the map visualization extension to Highcharts Core
* - `Highcharts Gantt for Python <https://gantt-docs.highchartspython.com/>`__
- `Highcharts Gantt (JS) <https://www.highcharts.com/products/gantt/>`__
- the Gantt charting extension to Highcharts Core
* - (all libraries in the Python toolkit)
- The **Highcharts Export Server**
- enabling the programmatic creation of static (downloadable) data visualizations
--------------------
***************
Installation
***************
To install **Highcharts Maps for Python**, just execute:
.. code-block:: bash
$ pip install highcharts-maps
Before you install, please be aware of the following "hard" dependencies:
* Python 3.10 or higher
* Highcharts Maps (JS) v.10.2 or higher (not technically a Python dependency, but
it won't work with earlier versions of Highcharts)
* `Highcharts Core for Python <https://core-docs.highchartspython.com/en/latest/>`__ v.1.7 or higher
* `esprima-python <https://github.com/Kronuz/esprima-python>`__ v.4.0 or higher
* `requests <https://requests.readthedocs.io/en/latest/>`__ v.2.31 or higher
* `validator-collection <https://validator-collection.readthedocs.io/en/latest/>`__
v.1.5 or higher
* `topojson <https://mattijn.github.io/topojson/>`__ v.1.5 or higher
* `geojson <https://github.com/jazzband/geojson/>`__ v.3.0 or higher
You can find more information about soft and development dependencies in the
`complete documentation <https://maps-docs.highchartspython.com/en/latest/#dependencies>`__.
-------------
*********************************
Why Highcharts for Python?
*********************************
`Highcharts <https://www.highcharts.com>`__ is the world's most popular, most powerful,
category-defining JavaScript data visualization library. If you are building a web or
mobile app/dashboard that will be visualizing data in some fashion, you should
absolutely take a look at the Highcharts suite of solutions. Take a peak at some
fantastic `demo visualizations <https://www.highcharts.com/demo/maps>`__.
As a suite of JavaScript libraries, `Highcharts <https://www.highcharts.com>`__ is
written in JavaScript, and is used to configure and render data visualizations in a
web browser (or other JavaScript-executing) environment. As a set of JavaScript
libraries, its audience is JavaScript developers. But what about the broader ecosystem of
Python developers and data scientists?
Given Python's increasing adoption as the technology of choice for data science and for
the backends of leading enterprise-grade applications, 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 we wrote the **Highcharts for Python Toolkit** to bridge that gap.
**Highcharts for Python** provides Python object representation for *all* of the
JavaScript objects defined in the
`Highcharts (JavaScript) API <https://api.highcharts.com/highcharts/>`__. It provides automatic
data validation, and exposes simple and standardized methods for serializing those Python
objects back-and-forth to JavaScript object literal notation.
**Highcharts Maps for Python** in particular provides support for
the `Highcharts Maps <https://www.highcharts.com/products/maps/>`__ extension, which is
designed to provide extensive map and data visualization capabilities optimized for
GIS (Geographic Information System) data visualization, with
robust interactivity. For ease of use, it also includes the full functionality of
`Highcharts Core for Python <https://core-docs.highchartspython.com>`__ 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 Core <https://www.highcharts.com/product/highcharts/>`__ and the four
core map visualizations available in
`Highcharts Maps <https://www.highcharts.com/product/maps/>`__.
Every Highcharts for Python library provides 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.
.. note::
**See also:**
* `Supported Visualizations <https://maps-docs.highchartspython.com/en/latest/visualizations.html>`__
* **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
the Highcharts for Python toolkit applies Pythonic syntax with automatic conversion between
Pythonic ``snake_case`` notation and JavaScript ``camelCase`` styles.
|
**Highcharts Maps for Python** vs Alternatives
===================================================
For a discussion of **Highcharts Maps for Python** in comparison to alternatives, please see
the **COMPLETE DOCUMENTATION:** https://maps-docs.highchartspython.com/en/latest/index.html
---------------------
********************************
Hello World, and Basic Usage
********************************
1. Import Highcharts Maps for Python
==========================================
.. code-block:: python
# PRECISE IMPORT PATTERN
# 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
# CATCH-ALL IMPORT PATTERN
# This method of importing Highcharts Maps for Python classes has relatively slow
# performance because it imports hundreds of different classes from across the entire
# library. This is also a known anti-pattern, as it obscures the namespace within the
# library. Both may be acceptable to you in your use-case, but do use at your own risk.
# Import objects from the catch-all ".highcharts" module.
from highcharts_maps import highcharts
# You can now access specific classes without individual import statements.
highcharts.Chart
highcharts.SharedMapsOptions
highcharts.HighchartsMapsOptions
highcharts.MapOptions
highcharts.MapSeries
2. Create Your Chart
================================
.. code-block:: python
# from a primitive array, using keyword arguments
my_chart = Chart(data = [[1, 23], [2, 34], [3, 45]],
series_type = 'line')
# from a primitive array, using the .from_array() method
my_chart = Chart.from_array([[1, 23], [2, 34], [3, 45]],
series_type = 'line')
# from a Numpy ndarray, using keyword arguments
my_chart = Chart(data = numpy_array, series_type = 'line')
# from a Numpy ndarray, using the .from_array() method
my_chart = Chart.from_array(data = numpy_array, series_type = 'line')
# from a JavaScript file
my_chart = Chart.from_js_literal('my_js_literal.js')
# from a JSON file
my_chart = Chart.from_json('my_json.json')
# from a Python dict
my_chart = Chart.from_dict(my_dict_obj)
# from a Pandas dataframe
my_chart = Chart.from_pandas(df)
# from a PySpark dataframe
my_chart = Chart.from_pyspark(df,
property_map = {
'x': 'transactionDate',
'y': 'invoiceAmt',
'id': 'id'
},
series_type = 'line')
# from a CSV
my_chart = Chart.from_csv('/some_file_location/filename.csv')
# from a HighchartsOptions configuration object
my_chart = Chart.from_options(my_options)
# from a Series configuration, using keyword arguments
my_chart = Chart(series = my_series)
# from a Series configuration, using .from_series()
my_chart = Chart.from_series(my_series)
3. Configure Global Settings (optional)
=============================================
.. code-block:: python
# 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
================================================
.. code-block:: python
from highcharts_core.options.title import Title
from highcharts_core.options.credits import Credits
# EXAMPLE 1.
# 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.highchartspython.com/',
'position': {
'align': 'center',
'vertical_align': 'bottom',
'x': 123,
'y': 456
},
'style': {
'color': '#cccccc',
'cursor': 'pointer',
'font_size': '9px'
},
'text': 'Chris Modzelewski'
}
# EXAMPLE 2.
# Using direct objects
from highcharts_core.options.title import Title
from highcharts_core.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.highchartspython.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:
.. code-block:: python
# 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)
=========================================================================
.. code-block:: python
# 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
==============================================
.. code-block:: python
# 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')
8. Render Your Chart in a Jupyter Notebook
===============================================
.. code-block:: python
my_chart.display()
--------------
***********************
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 channels to get
help using the toolkit:
* Use the `Highcharts Forums <https://highcharts.com/forum>`__
* Use `Stack Overflow <https://stackoverflow.com/questions/tagged/highcharts-for-python>`__
with the ``highcharts-for-python`` tag
* `Report bugs or request features <https://github.com/highcharts-for-python/highcharts-maps/issues>`__
in the library's Github repository
* `File a support ticket <https://www.highchartspython.com/get-help>`__ with us
* `Schedule a live chat or video call <https://www.highchartspython.com/get-help>`__
with us
**FOR MORE INFORMATION:** https://www.highchartspython.com/get-help
-----------------
*********************
Contributing
*********************
We welcome contributions and pull requests! For more information, please see the
`Contributor Guide <https://maps-docs.highchartspython.com/en/latest/contributing.html>`__.
And thanks to all those who've already contributed!
-------------------
*********************
Testing
*********************
We use `TravisCI <https://travisci.com>`_ for our build automation and
`ReadTheDocs <https://readthedocs.com>`_ for our documentation.
Detailed information about our test suite and how to run tests locally can be
found in our Testing Reference.
Raw data
{
"_id": null,
"home_page": null,
"name": "highcharts-maps",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "charts, data visualization, data viz, geospatial, gis, graphing, highcharts, highcharts maps, maps, plotting",
"author": null,
"author_email": "HCP LLC <support@highchartspython.com>",
"download_url": "https://files.pythonhosted.org/packages/4d/18/50134987d97366cc23487b1586e9e3d586f57d7d5d4a8d4655fc81630090/highcharts_maps-1.7.0.tar.gz",
"platform": null,
"description": "###################################################\nHighcharts Maps for Python\n###################################################\n\n**High-end data and map visualizations for the Python ecosystem**\n\n**Highcharts Maps for Python** is an extension to the\n`Highcharts Core for Python <https://core-docs.highchartspython.com>`__ library, providing\na Python wrapper for the \n`Highcharts Maps <https://www.highcharts.com/products/maps/>`__\nJavaScript data visualization library. \n\n**Highcharts Maps for Python** also supports\n\n * **Highcharts Core (JS)** - the core Highcharts data visualization library\n * The **Highcharts Export Server** - enabling the programmatic creation of static\n (downloadable) data visualizations\n\nThe library supports Highcharts (JS) v.10.2 and higher, including Highcharts (JS) v.11.4.0.\n\n**Highcharts Maps for Python** is fully integrated with the broader Python ecosystem,\noffering native integrations with:\n\n * **Jupyter Labs/Notebook**. You can now produce high-end and interactive plots and\n renders using the full suite of Highcharts visualization capabilities.\n * **Pandas**. Automatically produce data visualizations from your Pandas dataframes\n * **PySpark**. Automatically produce data visualizations from data in a PySpark\n dataframe.\n * **GeoPandas**. Automatically incorporate GIS / map visualizations with data from your\n GeoPandas GeoDataFrames.\n * **Topojson**. Automatically visualizes TopoJSON map geometries.\n * **Geojson**. Automatically visualizes GeoJSON map geometries.\n\n\n**COMPLETE DOCUMENTATION:** https://maps-docs.highchartspython.com/en/latest/index.html\n\n--------------------\n\n***************************************\nThe Highcharts for Python Toolkit\n***************************************\n\nThe **Highcharts Maps for Python** library is part of the broader \n`Highcharts for Python Toolkit <https://www.highcharts.com/integrations/python>`__, \nwhich together provides comprehensive support across the entire \n`Highcharts <https://www.highcharts.com>`__ suite of data visualization libraries:\n\n.. list-table::\n :widths: 30 30 40\n :header-rows: 1\n\n * - Python Library\n - JavaScript Library\n - Description\n * - `Highcharts Core for Python <https://core-docs.highchartspython.com/>`__\n - `Highcharts Core (JS) <https://www.highcharts.com/products/highcharts/>`__\n - (this library) the core Highcharts data visualization library\n * - `Highcharts Stock for Python <https://stock-docs.highchartspython.com/>`__\n - `Highcharts Stock (JS) <https://www.highcharts.com/products/stock/>`__\n - the time series visualization extension to Highcharts Core\n * - **Highcharts Maps for Python**\n - `Highcharts Maps (JS) <https://www.highcharts.com/products/maps/>`__\n - the map visualization extension to Highcharts Core\n * - `Highcharts Gantt for Python <https://gantt-docs.highchartspython.com/>`__\n - `Highcharts Gantt (JS) <https://www.highcharts.com/products/gantt/>`__\n - the Gantt charting extension to Highcharts Core\n * - (all libraries in the Python toolkit)\n - The **Highcharts Export Server** \n - enabling the programmatic creation of static (downloadable) data visualizations\n\n--------------------\n\n***************\nInstallation\n***************\n\nTo install **Highcharts Maps for Python**, just execute:\n\n .. code-block:: bash\n\n $ pip install highcharts-maps\n\nBefore you install, please be aware of the following \"hard\" dependencies:\n\n * Python 3.10 or higher\n * Highcharts Maps (JS) v.10.2 or higher (not technically a Python dependency, but \n it won't work with earlier versions of Highcharts)\n * `Highcharts Core for Python <https://core-docs.highchartspython.com/en/latest/>`__ v.1.7 or higher\n * `esprima-python <https://github.com/Kronuz/esprima-python>`__ v.4.0 or higher\n * `requests <https://requests.readthedocs.io/en/latest/>`__ v.2.31 or higher\n * `validator-collection <https://validator-collection.readthedocs.io/en/latest/>`__\n v.1.5 or higher\n * `topojson <https://mattijn.github.io/topojson/>`__ v.1.5 or higher\n * `geojson <https://github.com/jazzband/geojson/>`__ v.3.0 or higher\n\nYou can find more information about soft and development dependencies in the\n`complete documentation <https://maps-docs.highchartspython.com/en/latest/#dependencies>`__.\n\n\n-------------\n\n*********************************\nWhy Highcharts for Python?\n*********************************\n\n`Highcharts <https://www.highcharts.com>`__ is the world's most popular, most powerful, \ncategory-defining JavaScript data visualization library. If you are building a web or \nmobile app/dashboard that will be visualizing data in some fashion, you should \nabsolutely take a look at the Highcharts suite of solutions. Take a peak at some \nfantastic `demo visualizations <https://www.highcharts.com/demo/maps>`__.\n\nAs a suite of JavaScript libraries, `Highcharts <https://www.highcharts.com>`__ is \nwritten in JavaScript, and is used to configure and render data visualizations in a\nweb browser (or other JavaScript-executing) environment. As a set of JavaScript\nlibraries, its audience is JavaScript developers. But what about the broader ecosystem of\nPython developers and data scientists?\n\nGiven Python's increasing adoption as the technology of choice for data science and for\nthe backends of leading enterprise-grade applications, Python is often the backend that \ndelivers data and content to the front-end...which then renders it using JavaScript and \nHTML.\n\nThere are numerous Python frameworks (Django, Flask, Tornado, etc.) with specific\ncapabilities to simplify integration with Javascript frontend frameworks (React, Angular,\nVueJS, etc.). But facilitating that with Highcharts has historically been very difficult.\nPart of this difficulty is because the Highcharts JavaScript suite - while supporting JSON as a\nserialization/deserialization format - leverages JavaScript object literals to expose the\nfull power and interactivity of its data visualizations. And while it's easy to serialize\nJSON from Python, serializing and deserializing to/from JavaScript object literal notation\nis much more complicated. \n\nThis means that Python developers looking to integrate with Highcharts typically had to \neither invest a lot of effort, or were only able to leverage a small portion of Highcharts' \nrich functionality.\n\nSo we wrote the **Highcharts for Python Toolkit** to bridge that gap.\n\n**Highcharts for Python** provides Python object representation for *all* of the\nJavaScript objects defined in the\n`Highcharts (JavaScript) API <https://api.highcharts.com/highcharts/>`__. It provides automatic \ndata validation, and exposes simple and standardized methods for serializing those Python\nobjects back-and-forth to JavaScript object literal notation.\n\n**Highcharts Maps for Python** in particular provides support for\nthe `Highcharts Maps <https://www.highcharts.com/products/maps/>`__ extension, which is\ndesigned to provide extensive map and data visualization capabilities optimized for\nGIS (Geographic Information System) data visualization, with\nrobust interactivity. For ease of use, it also includes the full functionality of\n`Highcharts Core for Python <https://core-docs.highchartspython.com>`__ as well.\n\nKey Highcharts Maps for Python Features\n==============================================\n\n* **Clean and consistent API**. No reliance on \"hacky\" code, ``dict``\n and JSON serialization, or impossible to maintain / copy-pasted \"spaghetti code\".\n* **Comprehensive Highcharts support**. Every single Highcharts chart type and every\n single configuration option is supported in **Highcharts Maps for Python**. This\n includes the over 70 data visualization types supported by\n `Highcharts Core <https://www.highcharts.com/product/highcharts/>`__ and the four\n core map visualizations available in \n `Highcharts Maps <https://www.highcharts.com/product/maps/>`__.\n \n Every Highcharts for Python library provides full support for the rich JavaScript \n formatter (JS callback functions) capabilities that are often needed to get the most \n out of Highcharts' visualization and interaction capabilities.\n\n .. note::\n\n **See also:**\n \n * `Supported Visualizations <https://maps-docs.highchartspython.com/en/latest/visualizations.html>`__\n\n* **Simple JavaScript Code Generation**. With one method call, produce production-ready\n JavaScript code to render your interactive visualizations using Highcharts' rich\n capabilities.\n* **Easy Chart Download**. With one method call, produce high-end static\n visualizations that can be downloaded or shared as files with your audience. Produce\n static charts using the Highsoft-provided **Highcharts Export Server**, or using your \n own private export server as needed.\n* **Asynchronous Map Data Retrieval**. To minimize the amount of data transferred over\n the wire, **Highcharts Maps for Python** has built-in support for the configuration of\n asynchronous client-side retrieval of your map data.\n* **Automatic TopoJSON Optimization**. To minimize the amount of data transferred over\n the wire, **Highcharts Maps for Python** automatically converts your\n map geometries to highly-efficient TopoJSON topologies while\n still allowing you to work with GeoJSON data if you choose to.\n* **Integration with GeoPandas, Pandas, and PySpark**. With two lines of code, produce a\n high-end interactive visualization of your GeoPandas, Pandas, or PySpark dataframes.\n* **Consistent code style**. For Python developers, switching between Pythonic code\n conventions and JavaScript code conventions can be...annoying. So\n the Highcharts for Python toolkit applies Pythonic syntax with automatic conversion between\n Pythonic ``snake_case`` notation and JavaScript ``camelCase`` styles.\n\n|\n\n**Highcharts Maps for Python** vs Alternatives\n===================================================\n\nFor a discussion of **Highcharts Maps for Python** in comparison to alternatives, please see\nthe **COMPLETE DOCUMENTATION:** https://maps-docs.highchartspython.com/en/latest/index.html\n\n---------------------\n\n********************************\nHello World, and Basic Usage\n********************************\n\n1. Import Highcharts Maps for Python\n==========================================\n\n.. code-block:: python\n\n # PRECISE IMPORT PATTERN \n # This method of importing Highcharts Maps for Python objects yields the fastest\n # performance for the import statement. However, it is more verbose and requires\n # you to navigate the extensive Highcharts Maps for Python API.\n\n # Import classes using precise module indications. For example:\n from highcharts_maps.chart import Chart\n from highcharts_maps.global_options.shared_options import SharedMapsOptions\n from highcharts_maps.options import HighchartsMapsOptions\n from highcharts_maps.options.plot_options.map import MapOptions\n from highcharts_maps.options.series.map import MapSeries\n\n # CATCH-ALL IMPORT PATTERN\n # This method of importing Highcharts Maps for Python classes has relatively slow\n # performance because it imports hundreds of different classes from across the entire\n # library. This is also a known anti-pattern, as it obscures the namespace within the\n # library. Both may be acceptable to you in your use-case, but do use at your own risk.\n\n # Import objects from the catch-all \".highcharts\" module.\n from highcharts_maps import highcharts\n\n # You can now access specific classes without individual import statements.\n highcharts.Chart\n highcharts.SharedMapsOptions\n highcharts.HighchartsMapsOptions\n highcharts.MapOptions\n highcharts.MapSeries\n\n\n2. Create Your Chart\n================================\n\n .. code-block:: python\n\n # from a primitive array, using keyword arguments\n my_chart = Chart(data = [[1, 23], [2, 34], [3, 45]], \n series_type = 'line')\n\n # from a primitive array, using the .from_array() method\n my_chart = Chart.from_array([[1, 23], [2, 34], [3, 45]], \n series_type = 'line')\n\n # from a Numpy ndarray, using keyword arguments\n my_chart = Chart(data = numpy_array, series_type = 'line')\n\n # from a Numpy ndarray, using the .from_array() method\n my_chart = Chart.from_array(data = numpy_array, series_type = 'line')\n\n # from a JavaScript file\n my_chart = Chart.from_js_literal('my_js_literal.js')\n\n # from a JSON file\n my_chart = Chart.from_json('my_json.json')\n\n # from a Python dict\n my_chart = Chart.from_dict(my_dict_obj)\n\n # from a Pandas dataframe\n my_chart = Chart.from_pandas(df)\n\n # from a PySpark dataframe\n my_chart = Chart.from_pyspark(df,\n property_map = {\n 'x': 'transactionDate',\n 'y': 'invoiceAmt',\n 'id': 'id'\n },\n series_type = 'line')\n\n # from a CSV\n my_chart = Chart.from_csv('/some_file_location/filename.csv')\n\n # from a HighchartsOptions configuration object\n my_chart = Chart.from_options(my_options)\n\n # from a Series configuration, using keyword arguments\n my_chart = Chart(series = my_series)\n\n # from a Series configuration, using .from_series()\n my_chart = Chart.from_series(my_series)\n\n\n3. Configure Global Settings (optional)\n=============================================\n\n .. code-block:: python\n\n # Import SharedMapsOptions\n from highcharts_maps.global_options.shared_options import SharedMapsOptions\n\n # from a JavaScript file\n my_global_settings = SharedMapsOptions.from_js_literal('my_js_literal.js')\n\n # from a JSON file\n my_global_settings = SharedMapsOptions.from_json('my_json.json')\n\n # from a Python dict\n my_global_settings = SharedMapsOptions.from_dict(my_dict_obj)\n\n # from a HighchartsOptions configuration object\n my_global_settings = SharedMapsOptions.from_options(my_options)\n\n\n4. Configure Your Chart / Global Settings\n================================================\n\n .. code-block:: python\n\n from highcharts_core.options.title import Title\n from highcharts_core.options.credits import Credits\n\n # EXAMPLE 1.\n # Using dicts\n my_chart.title = {\n 'align': 'center',\n 'floating': True,\n 'text': 'The Title for My Chart',\n 'use_html': False,\n }\n\n my_chart.credits = {\n 'enabled': True,\n 'href': 'https://www.highchartspython.com/',\n 'position': {\n 'align': 'center',\n 'vertical_align': 'bottom',\n 'x': 123,\n 'y': 456\n },\n 'style': {\n 'color': '#cccccc',\n 'cursor': 'pointer',\n 'font_size': '9px'\n },\n 'text': 'Chris Modzelewski'\n }\n\n # EXAMPLE 2.\n # Using direct objects\n from highcharts_core.options.title import Title\n from highcharts_core.options.credits import Credits\n\n my_title = Title(text = 'The Title for My Chart',\n floating = True, \n align = 'center')\n my_chart.options.title = my_title\n\n my_credits = Credits(text = 'Chris Modzelewski', \n enabled = True, \n href = 'https://www.highchartspython.com')\n my_chart.options.credits = my_credits\n\n\n5. Generate the JavaScript Code for Your Chart\n=================================================\n\nNow having configured your chart in full, you can easily generate the JavaScript code\nthat will render the chart wherever it is you want it to go:\n\n .. code-block:: python\n\n # as a string\n js_as_str = my_chart.to_js_literal()\n\n # to a file (and as a string)\n js_as_str = my_chart.to_js_literal(filename = 'my_target_file.js')\n\n\n6. Generate the JavaScript Code for Your Global Settings (optional)\n=========================================================================\n\n .. code-block:: python\n\n # as a string\n global_settings_js = my_global_settings.to_js_literal()\n\n # to a file (and as a string)\n global_settings_js = my_global_settings.to_js_literal('my_target_file.js')\n\n\n7. Generate a Static Version of Your Chart\n==============================================\n\n .. code-block:: python\n\n # as in-memory bytes\n my_image_bytes = my_chart.download_chart(format = 'png')\n\n # to an image file (and as in-memory bytes)\n my_image_bytes = my_chart.download_chart(filename = 'my_target_file.png',\n format = 'png')\n\n8. Render Your Chart in a Jupyter Notebook\n===============================================\n\n .. code-block:: python\n\n my_chart.display()\n\n--------------\n\n***********************\nGetting Help/Support\n***********************\n\nThe **Highcharts for Python Toolkit** comes with all of the great support that \nyou are used to from working with the Highcharts JavaScript libraries. When you \nlicense the toolkit, you are welcome to use any of the following channels to get \nhelp using the toolkit:\n\n * Use the `Highcharts Forums <https://highcharts.com/forum>`__\n * Use `Stack Overflow <https://stackoverflow.com/questions/tagged/highcharts-for-python>`__ \n with the ``highcharts-for-python`` tag\n * `Report bugs or request features <https://github.com/highcharts-for-python/highcharts-maps/issues>`__ \n in the library's Github repository\n * `File a support ticket <https://www.highchartspython.com/get-help>`__ with us\n * `Schedule a live chat or video call <https://www.highchartspython.com/get-help>`__ \n with us\n\n**FOR MORE INFORMATION:** https://www.highchartspython.com/get-help\n\n-----------------\n\n*********************\nContributing\n*********************\n\nWe welcome contributions and pull requests! For more information, please see the\n`Contributor Guide <https://maps-docs.highchartspython.com/en/latest/contributing.html>`__. \nAnd thanks to all those who've already contributed!\n\n-------------------\n\n*********************\nTesting\n*********************\n\nWe use `TravisCI <https://travisci.com>`_ for our build automation and\n`ReadTheDocs <https://readthedocs.com>`_ for our documentation.\n\nDetailed information about our test suite and how to run tests locally can be\nfound in our Testing Reference.\n",
"bugtrack_url": null,
"license": null,
"summary": "High-end Map Data Visualization for the Python Ecosystem",
"version": "1.7.0",
"project_urls": {
"Bug Tracker": "https://github.com/highcharts-for-python/highcharts-maps/issues",
"Demo": "https://github.com/highcharts-for-python/highcharts-for-python-demos",
"Documentation": "https://maps-docs.highchartspython.com/en/latest/",
"History": "https://github.com/highcharts-for-python/highcharts-maps/blob/master/CHANGES.rst",
"Homepage": "https://www.highchartspython.com",
"Source Code": "https://github.com/highcharts-for-python/highcharts-maps",
"Sponsor": "https://github.com/sponsors/highcharts-for-python",
"Support": "https://www.highchartspython.com/get-help"
},
"split_keywords": [
"charts",
" data visualization",
" data viz",
" geospatial",
" gis",
" graphing",
" highcharts",
" highcharts maps",
" maps",
" plotting"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1f6bcf03a7f0f8e00ff2541ce7ac9b1cfb99e26986734cf9867cab0a356c553d",
"md5": "3fdbc72e658e0a5dc50b35b2083253b3",
"sha256": "c57556bce237c7acd7ca2caa5b183c33825e82cab3c406c9cf18955c065ec1b3"
},
"downloads": -1,
"filename": "highcharts_maps-1.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3fdbc72e658e0a5dc50b35b2083253b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 198265,
"upload_time": "2024-04-07T21:38:14",
"upload_time_iso_8601": "2024-04-07T21:38:14.414232Z",
"url": "https://files.pythonhosted.org/packages/1f/6b/cf03a7f0f8e00ff2541ce7ac9b1cfb99e26986734cf9867cab0a356c553d/highcharts_maps-1.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4d1850134987d97366cc23487b1586e9e3d586f57d7d5d4a8d4655fc81630090",
"md5": "3a1df63688c71188caa0f630fa441811",
"sha256": "410c49ab6ec7ef45ea2fc0272ce1c2eb31d4bc8b2f056fa9bb8ae606b1d09d67"
},
"downloads": -1,
"filename": "highcharts_maps-1.7.0.tar.gz",
"has_sig": false,
"md5_digest": "3a1df63688c71188caa0f630fa441811",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 11951104,
"upload_time": "2024-04-07T21:38:17",
"upload_time_iso_8601": "2024-04-07T21:38:17.525499Z",
"url": "https://files.pythonhosted.org/packages/4d/18/50134987d97366cc23487b1586e9e3d586f57d7d5d4a8d4655fc81630090/highcharts_maps-1.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-07 21:38:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "highcharts-for-python",
"github_project": "highcharts-maps",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "highcharts-maps"
}
JSON
