GeoPublicHealth

Version QGIS License Test Status

A QGIS Plugin for Epidemiology and Public Health GIS Analysis

📚 Table of Contents

✨ Overview

GeoPublicHealth provides a simplified interface within QGIS, tailored for users in epidemiology and public health. It builds upon the foundation laid by the GeoHealth Plugin (developed by Etienne Trimaille) and incorporates additional methods highly relevant for applying GIS in public health research and practice.

This plugin aims to integrate and enhance methods similar to those found in the pioneering SIGEpi software, leveraging the power and flexibility of the modern QGIS platform.

Key analysis tools include:

✅ Prerequisites

Before installing the GeoPublicHealth plugin, you need:

  1. QGIS: Version 3.42.x or newer is required. Tested with:
  2. Python Dependencies: The plugin relies on specific Python libraries that must be correctly installed within your QGIS environment:
    • gdal (usually included with QGIS/OSGeo4W, version ~3.10.2 or newer) - Required
    • libpysal (version ~4.3.0) - Required
    • numba (latest compatible version) - Required
    • matplotlib (latest compatible version) - Optional (enables graphing/plotting features)

Note: The installation methods below are designed to help ensure these dependencies are met. See DEPENDENCIES.md for detailed dependency information.

🚀 Quick Start

  1. Install QGIS 3.42+ for your platform.
  2. Run install_dependencies_console.py from the QGIS Python Console.
  3. Restart QGIS.
  4. Open Plugins → GeoPublicHealth.

Latest Version: v0.3.1 (2026-01-28) - Installation stability and processing tests

🧭 Installation

Installation has two steps: install QGIS, then run the dependency installer script.

Step 1: Install QGIS

Version Release Type Windows macOS Linux
3.44.6 ‘Solothurn’ Latest Release (Recommended) Download Download See distro links
3.40.14 ‘Bratislava’ Long Term Release (LTR) Download Not Available* See distro links
OSGeo4W Installer Network Installer (All versions) Download - -

* macOS users should use QGIS 3.44, which is stable and recommended for macOS.

🪟 Windows (OSGeo4W recommended)

  1. Download and run the OSGeo4W installer.
  2. Choose Advanced Install → Install from Internet.
  3. Select packages:
    • qgis (Desktop)
    • gdal (Libs)
    • python3-libpysal (Libs)
  4. Complete installation and launch QGIS once.

Video walkthrough: OSGeo4W install.

🍎 macOS

  1. Install QGIS from the macOS installer.
  2. Open QGIS once (right‑click → Open on first run).
  3. Use the QGIS Python Console for dependencies (do not use system Python).

For the full macOS walkthrough and advanced troubleshooting, see:

🐧 Linux

Install QGIS from your distro packages and ensure python3-gdal, python3-libpysal (or python3-pysal), and python3-numba are available to QGIS.

Step 2: Run the Dependency Installer Script

Run the same script on all platforms:

  1. Download install_dependencies_console.py from the repo or direct link.
  2. Open Plugins → Python Console.
  3. Click Show Editor → Open Script → select install_dependencies_console.py.
  4. Click Run Script and watch progress messages.
  5. Restart QGIS.

The script will:

Logs are written to ~/GeoPublicHealth/ (Windows: %TEMP%).

Step 3: Install the Plugin (Fallback Only)

Use these steps only if the script did not install the plugin after restart.

Option A: Repository

  1. Open Plugins → Manage and Install Plugins… → Settings.
  2. Enable Show also experimental plugins.
  3. Add repository:
    • Name: GeoPublicHealth
    • URL: https://raw.githubusercontent.com/ePublicHealth/GeoPublicHealth/main/docs/plugins.xml
  4. Search for geopublichealth and install.

Option B: ZIP

  1. Download the latest release from GitHub Releases.
  2. Plugins → Install from ZIP → select geopublichealth.zip.

🧪 Verification

After restarting QGIS, run this in the Python Console:

import libpysal, esda, numba
print(f"✓ libpysal {libpysal.__version__}, esda {esda.__version__}, numba {numba.__version__}")

🎨 Optional: Matplotlib

Matplotlib enables plots in analysis dialogs. You can also re-run install_dependencies_console.py, which installs it automatically.

Run the snippet below as a script in the QGIS Python Editor (Show Editor → Run Script):

import subprocess
from pathlib import Path
from qgis.core import QgsApplication

prefix = Path(QgsApplication.prefixPath())

candidates = [
    prefix / "Contents" / "MacOS" / "python3.12",
    prefix / "Contents" / "MacOS" / "bin" / "python3",
    prefix / "Contents" / "bin" / "python3",
]

python_exec = next((p for p in candidates if p.exists()), None)
if not python_exec:
    raise FileNotFoundError(f"No QGIS Python found in: {prefix}")

subprocess.run([str(python_exec), "-m", "pip", "install", "matplotlib"])

Restart QGIS after installation. See DEPENDENCIES.md and UNINSTALL_INSTRUCTIONS.md for advanced scenarios and cleanup.

🛠️ Troubleshooting

🧩 Plugin Not Appearing After Installation

If the plugin doesn’t appear after installation:

  1. Restart QGIS first:
    • Settings changes (experimental plugins, repositories) require a full QGIS restart
    • After running install_dependencies_console.py, always restart QGIS completely
  2. Check experimental plugins are enabled:
    • Go to Plugins → Manage and Install Plugins → Settings
    • Ensure [x] Show also experimental plugins is checked
  3. Clear cache and reinstall: 
    # macOS
rm -rf ~/Library/Application\ Support/QGIS/QGIS3/profiles/default/python/plugins/geopublichealth
rm -rf ~/Library/Application\ Support/QGIS/QGIS3/profiles/default/cache
   
# Linux
rm -rf ~/.local/share/QGIS/QGIS3/profiles/default/python/plugins/geopublichealth
rm -rf ~/.local/share/QGIS/QGIS3/profiles/default/cache
   
# Windows
rmdir /s /q "%APPDATA%\QGIS\QGIS3\profiles\default\python\plugins\geopublichealth"
rmdir /s /q "%APPDATA%\QGIS\QGIS3\profiles\default\cache"
  4. Restart QGIS and reinstall the plugin

🧪 ModuleNotFoundError

If you see errors about missing modules:

🧰 Python Console Installation Issues

Important: When using the QGIS Python Console:

📌 Other Issues

🧭 Usage

Once installed, the GeoPublicHealth plugin tools and algorithms can typically be accessed via:

Refer to specific documentation or tutorials for detailed workflows using the plugin’s features.

👩‍💻 Development

🧑‍💻 For Developers

See AGENTS.md for development guidelines and coding standards.

See RELEASE.md for information on the release process.

✅ Running Tests

# Run all tests (QGIS Python environment required)
python test_suite.py

# Run a single test
python -m unittest src.test.test_pep8.TestPep8.test_pep8

# Run processing algorithm tests
make processing-test

# Run PEP8 style check
make pep8

For macOS, make processing-test uses QGIS bundled Python automatically (default path: /Applications/QGIS.app).

If QGIS is installed elsewhere, override paths:

QGIS_APP="/path/to/QGIS.app" make processing-test
# or
QGIS_PYTHON="/path/to/QGIS.app/Contents/MacOS/python3.12" make processing-test

Building the Plugin

The plugin is automatically built and released using GitHub Actions. To manually build:

# See RELEASE.md for detailed build instructions

🤝 Contributing

Contributions are welcome! Please review the Contribution Guidelines before starting.

  1. Fork the repository on GitHub.
  2. Create your feature branch: git checkout -b my-new-feature
  3. Make your changes following the code style guidelines
  4. Run tests: python test_suite.py, make processing-test, and make pep8
  5. Commit your changes: git commit -am 'Add some feature'
  6. Push to the branch: git push origin my-new-feature
  7. Open a Pull Request

🐛 Reporting Issues

Found a bug? Please help us fix it by submitting a detailed issue report.

Before Submitting A Bug Report

How to Submit a Good Bug Report

Create an issue on the repository issues page and provide as much detail as possible:

🙏 Credits and Authorship

GeoPublicHealth Plugin:

Based on the original GeoHealth Plugin:

🗓️ Changelog

v0.3.0 (2026-01-25)

v0.2.24 (2026-01-25)

v0.2.22 (2026-01-23)

v0.2.21 (2026-01-23)

v0.2.20 (2026-01-23)

v0.2.19 (2026-01-23)

v0.2.18 (2026-01-23)

v0.2.17–0.2.3 (2026-01-22 to 2026-01-23)

v0.2.2 (2026-01-22)

v0.2.1 (2026-01-22)

v0.2.0 (2025-05-01)

See all releases for complete version history.

📖 Documentation

🧭 Installation Guides

Installation Scripts:

👩‍💻 Development

💬 Support

📄 License

This project is licensed under the terms specified in the LICENSE file.

Copyright (c) 2017-2026 The GeoPublicHealth Contributors and Original Authors.

This site is open source. Improve this page.