Installation

The mapdata program is available on PyPI.

It can be installed with:

pip install mapdata

This will install mapdata.py as an executable Python script. Alternatively, you can download mapdata.py from the PyPI project page.

If mapdata is installed from PyPI, the following Python libraries will be automatically installed if they are not already present:

• jenkspy

• loess

• numpy

• matplotlib

• odfpy

• openpyxl

• pillow

• pymannkendall

• pynndescent

• pyproj

• scipy

• scikit-learn

• seaborn

• statsmodels

• tkintermapview

• umap-learn

• kneeliverse

• xlrd

If mapdata.py is downloaded from PyPI, then those libraries must be manually installed using pip.

If your system does not include the full version of Python, it may not include the Tkinter libraries, which are also needed. If that is the case, install the Tkinter libraries from your package manager. For example, for Debian systems (including Ubuntu) use:

sudo apt install python3-tk

and on Fedora systems use:

sudo dnf install python3-tkinter

On a Windows system, ensure that tcl/tk is installed with Python.

If you have other applications that use the libraries listed above, and wish to avoid any possibility of a version conflict, mapdata and its dependencies can be installed in a virtual environment using venv or pipx.

mapdata.py supports data import from a number of different database management systems (DBMSs), and because only one or two of those DMBSs are expected be used by any user, all of the database connector libraries are not automatically installed with mapdata.py. Instead, users must manually install the database connector libraries that they need using pip. The database connector libraries for the different DMBS are:

• PostgreSQL: psycopg2

• MariaDB and MySQL: pymysql

• DuckDB: duckdb

• SQL Server: pydobc

• Oracle: cx-Oracle

• Firebird: fdb

When mapdata.py is installed from PyPI, an annotated configuration file template and a set of bitmap symbols will also be installed. These will be placed in directories named “config” and “symbols” respectively. When using a virtual environment (venv), these directories will be directly beneath the top-level directory of the virtual environment. The symbols that are provided include all the built-in symbols as well as some extras (e.g., capital English letters). The configuration file template contains all sections and settings, with comments briefly describing the purpose of each setting. It also contains settings for selected Stamen, Stadia, and Mapbox maps, and attribution settings for each; an API key for each of these custom basemaps must be added for these to be shown in mapdata.

Mapdata.py is a single file, so as an alternative to installing it with pip, it can be downloaded from PyPI, unpacked from the download package, and placed wherever is desired. Dependencies may need to be manually installed with this appoach.

If you are going to install mapdata into a Python virtual environment (venv) on Linux with a custom-built version of Python (e.g., using Python 3.12 on a system where the native version is 3.10), then the following system packages should be installed (e.g., using apt on a Debian system) before building the custom Python version: libssl_dev, build-essential, libffi-dev, libsqlite3-dev, and tk-dev.