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

• 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, upgrade your system to the full version of Python.

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; API keys 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.