pyguidos 2.3.1

Python interface to main GuidosToolbox (GTB) modules for spatial pattern analysis

pyguidos

A Python interface to the main GuidosToolbox (GTB) modules for spatial pattern analysis

Overview

pyguidos is a Python interface to the main modules of GuidosToolbox (GTB), a scientific software package for pattern spatial analysis of raster images. This Python module provides programmatic access to the core GTB analytical tools, enabling reproducible landscape analysis workflows in Python scripts, Jupyter notebooks, and automated pipelines.

Git Repository Contents

If you are cloning the source code directly from the official GitLab repository, the repository includes the following components for development, testing, and demonstration:

• /pyguidos: The core package directory containing the source code, geospatial monitoring algorithms, and Numba-optimized modules (This is what is installed via pip).
• /docs: Source files for automated Sphinx HTML documentation platform.
• /notebooks: Interactive Jupyter notebooks demonstrating data visualization and workflow examples.
• /tests: Comprehensive unit and integration test suites validating input parameters and mathematical integrity.

---

Modules

Function	Description
frag()	Fragmentation analysis
frag_change()	Fragmentation change
landmos()	Landscape Mosaic
spa()	Simplified Pattern Analysis
acc()	Foreground Patch Size Accounting
rss()	Restoration Status Summary
extract_by_polygon()	Extract raster by polygon features

---

Documentation

Full API documentation is available at https://jrc-forest.pages.code.europa.eu/guidos/pyguidos.

---

Requirements

• Python >= 3.10
• numpy >2.0
• rasterio >=1.4
• scipy >=1.15
• scikit-image>=0.26
• matplotlib >=3.10
• pyogrio >=0.10
• geopandas >=1.1
• shapely >=2.0
• pyproj >=3.4
• python-ternary >=1.0
• numba >0.62
• tbb >=2021.6.0; sys_platform == 'win32'
• intel-openmp; sys_platform == 'linux'

---

Installation

1. Standard Installation

For general use, install the latest stable version directly via pip:

pip install pyguidos

2. Development installation

To install the latest development version directly from the GitLab repository without cloning:

pip install git+https://code.europa.eu/jrc-forest/guidos/pyguidos.git

3. Editable Installation (Recommended for Testing)

To run the example notebooks or contribute to the source code, you must clone the repository and install it in "editable" mode. This allows changes in the code to be reflected immediately.

1. Clone the repository

git clone https://code.europa.eu/jrc-forest/guidos/pyguidos.git
cd pyguidos

2. Create and activate a virtual environment using Python.

• Windows

py -m venv myvenv
myvenv\Scripts\activate

• Linux/Mac

python -m venv myvenv
source myvenv/bin/activate

3. Install in editable mode with dependencies:

pip install -e .

This links module's source code directly to your Python environment, so any changes you make are immediately reflected without reinstallation.

---

Quick Start

Once installed, you can verify your setup and explore the available tools directly from your Python console or Jupyter Notebook.

import pyguidos as pg

# List all available analytical tools and their descriptions
pg.info()

# Get detailed documentation and methodology links for a specific tool
pg.info('landmos')

# Get full technical specification of a function
help(pg.landmos)

---

Usage Examples

import pyguidos as pg

# Fragmentation analysis
result = pg.frag(
    in_tiff="my_map.tif",
    method="FAD",
    window_size=27
)

# Fragmentation change
result = pg.frag_change(
    in_tiff_t1="my_map2018_frag_fad_27.tif",
    in_tiff_t2="my_map2025_frag_fad_27.tif"
)

# Landscape Mosaic
result = pg.landmos(
    in_tiff="my_landcover.tif",
    window_size=33
)

# Simplified Pattern Analysis (SPA)
result = pg.spa(
    in_tiff="my_map.tif",
    edge_width=1,
    classes=6
)

# Foreground Patch Size Accounting
result = pg.acc(
    in_tiff="my_map.tif",
    thresholds=[10, 100, 1000, 10000]
)

# Raster Spatial Statistics
result = pg.rss(in_tiff="my_map.tif")

# Extract raster by polygon
pg.extract_by_polygon(
    shapefile_path="regions.shp",
    geotiff_path="my_map.tif",
    output_dir="output/",
    id_field="NAME"
)

Example data and Jupyter notebooks with worked examples are available in the project repository.

---

Citation

If you use pyGuidos in your research, please cite both the GuidosToolbox software and this package:

GuidosToolbox:

• Vogt P. and Riitters K. (2017). GuidosToolbox: universal digital image object analysis. European Journal of Remote Sensing, 50, 1, pp. 352-361. doi: 10.1080/22797254.2017.1330650

pyGuidos:

• Caudullo G. and Vogt P. (2026). PyGuidos, A cross-platform Python interface to GuidosToolbox for landscape pattern analysis. In press.

Interactive Citation

You can get the plain-text citations directly in your Python console:

import pyguidos as pg
pg.citation()

---

Contributing

Contributions are welcome. Please follow these steps:

1. Fork the repository on GitLab
2. Create a new branch for your feature or fix:

   git checkout -b feature/your-feature-name
   

3. Make your changes and ensure existing tests pass:

   pytest tests/
   

4. Submit a merge request with a clear description of the changes and their motivation.

Please open an issue before starting work on significant changes, to allow discussion of the approach.

For bug reports, please include the pyGuidos version, Python version, operating system, and a minimal reproducible example.

---

Authors

• Giovanni Caudullo -- [e-mail]
• Peter Vogt -- [e-mail]

European Commission, Joint Research Centre (JRC)

---

License

This project is licensed under the European Union Public Licence v1.2 (EUPL-1.2). See the LICENSE file for details.