AfriAtlas: an R package for automating the visualization of African bird atlas project data

1 Introduction

The mobilization of biodiversity data has become a global priority for tracking progress toward conservation targets, detecting ecological change, and guiding evidence-based decision-making (Meyer et al., 2015; Convention on Biological Diversity [CBD], 2022). The African Bird Atlas Project (ABAP) integrates multiple national initiatives, including the Southern African Bird Atlas Project 2 (SABAP2), Kenya Bird Map, and the Nigerian Bird Atlas Project (Tende et al., 2024), all of which adopt the standardized SABAP2 protocol. Using a continentally consistent sampling design based on 5′ × 5′ grid cells (“pentads”), these atlases compile vetted citizen-science records with associated survey-effort information across Africa’s heterogeneous landscapes (Brooks et al., 2022; Lee et al., 2022). This coordinated framework enables robust assessments of biodiversity change, including shifts in bird distributions, patterns of local turnover, and long-term trends across the region (Nussbaumer et al., 2024), while supporting biodiversity monitoring, conservation planning, policy development, and assessments of species patterns across managed and human-modified landscapes (Ivande et al., 2026; Iniunam et al., 2026; Danmallam et al., 2025).

Statement of Need: Although raw atlas data is accessible through the BirdMap web portal (https://www.birdmap.africa), their use for advanced analysis remains technically demanding. Researchers must often download GeoJSON files manually, resolve inconsistencies in file structures and naming conventions, obtain matching administrative boundary datasets, and conduct additional GIS processing before results can be visualized or interpreted within a spatial context. These steps can create substantial barriers to efficient and reproducible workflows.

Several R packages associated with African Bird Atlas Project already provide important functionality for accessing and processing atlas datasets (Cervantes et al., 2024). For example, tools such as rabm, ABAP, and ABDtools support data retrieval, environmental annotation, and ecological modeling workflows. However, these packages generally focus on specific analytical components rather than integrated visualization pipelines, highlighting the need for more streamlined tools for African bird atlas data processing and visualization.

At present, there remains a need for a dedicated tool that standardizes the complete workflow from atlas data acquisition to publication-ready visualization. Here, we introduce AfriAtlas (v0.1.0), an open-source R package developed to automate the workflow from API query to final map production. By streamlining the retrieval, standardization, and visualization of both survey effort and species occurrence data, AfriAtlas reduces technical barriers and facilitates reproducible and efficient processing of atlas data for ecological analyses.

2 Software description and architecture

AfriAtlas is released under the MIT License and is implemented using the S3 object-oriented system in R, with support for R version 3.5 or later. Its design follows current best practices in spatial data science and draws on a modern dependency stack that includes sf for vector data handling (Pebesma, 2018), ggplot2 for visualization (Wickham, 2016), and rnaturalearth for retrieving up-to-date administrative boundaries.

2.1 Comparison with existing tools

Several R packages have been developed to facilitate access to and processing of African Bird Atlas datasets, including rabm, ABAP, and ABDtools. These packages provide important functionality for querying atlas records, extracting environmental variables, and preparing data for ecological modeling workflows (Cervantes et al., 2024). However, their primary objectives differ from those of AfriAtlas and they generally focus on specific components of the analytical pipeline rather than integrated visualization workflows. For example, rabm primarily supports retrieval of atlas records by species, observer, date, and region, including multi-species queries. The ABAP package extends functionality by supporting retrieval of card-level and pentad-level data and preparation of detection/non-detection datasets for occupancy modeling frameworks such as unmarked and spOccupancy. Similarly, ABDtools provides functionality for integration with Google Earth Engine (GEE), enabling extraction and annotation of environmental covariates for ecological analyses. By contrast, AfriAtlas was specifically developed to automate retrieval, spatial standardization, effort contextualization, and generation of publication-ready visual outputs (Table 1). AfriAtlas therefore complements existing software by addressing a different analytical need: the production of standardized spatial outputs directly from atlas datasets with minimal manual GIS processing.

Table 1. Comparison of functionality among AfriAtlas and existing African bird atlas-related R packages.

Key:

✓ = implemented.

◐ = partially implemented/indirect support.

✗ = not implemented.

2.2 Core functions

The package workflow (Figure 1) supports a structured pipeline that guides users from species selection to final spatial output. The architecture is organized into three logical phases.

2.2.1 Species selection and validation

African Bird Atlas Project species are referenced using numeric codes, which can be difficult to locate without appropriate lookup tools. AfriAtlas addresses this through two helper functions:

• get_species_code() retrieves the code associated with a given scientific or common name of species.
• explore_species_codes() provides a table for browsing species list and associated species codes.

Users assemble the results into a species_codes vector, which is validated using show_codes() before proceeding. An internal logic gate ensures that requests do not exceed the recommended batch limit of ≤ 10 species, which promotes efficient data retrieval and prevents excessive API resource consumption.

2.2.2 Parallel visualization

Following validation, the workflow divides into two independent visualization streams, each beginning with an API query. Upon data retrieval, AfriAtlas performs automated spatial processing using sf and rnaturalearth to align pentad coordinates with national administrative boundaries.

• map_coverage()generates standardized survey-effort maps that summarize total hours recorded per pentad and produces accompanying summary statistics.
• map_species()retrieves species-occurrence data and generates species distribution maps by combining species occurrence records with survey-coverage information.

Both functions use ggplot2, cowplot, and ggspatial for final map rendering. Error handling is implemented through tryCatch(), allowing the workflow to manage temporary API delays without interrupting batch operations.

2.2.3 Synthesis and export

Species occurrence and survey coverage outputs are combined to enable interpretation of species distribution patterns in the context of survey effort. The map_species()function generates and exports species distribution-coverage maps, while map_coverage()generates and exports survey effort maps as PNG files and summary statistics, including the number of pentads per effort category and the mean ± SE of accumulated hours, as CSV files to the working directory.

2.2 The Widespreadness index

A distinctive feature of AfriAtlas is the calculation of a Widespreadness Index (W), which assists users in interpreting whether a species is broadly distributed or range restricted within a given region. The index is defined as the proportion of full protocol pentads in which a species was recorded relative to the total number of surveyed full protocol pentads within a defined region, multiplied by 100:

W=Nobservation Ncoverage×100

Where N_observation is the number of full protocol pentads in which a species was recorded, and N_coverage is the total number of pentads with full protocol survey effort. By restricting the formula to full protocol pentads, the metric standardizes comparisons by controlling for spatial variation in observer effort. This approach provides a coarse, effort-conditioned measure of species widespreadness that is distinct from formal occupancy modeling explicitly account for imperfect detection (MacKenzie et al., 2002), but remains informative for broad-scale comparisons of species occurrence patterns.

2.4 Survey effort across regions

To demonstrate the versatility of AfriAtlas, the package was applied to visualize survey effort and species distributions across three major atlas regions: Nigeria (Nigeria Bird Atlas), Kenya (Kenya Bird Map), and South Africa (SABAP2).

2.5 Visualizing survey effort

Understanding spatial sampling bias is essential for interpreting species distributions. The map_coverage() function dynamically categorizes survey hours per pentad and generates standardized effort maps (Figure 2):

library(AfriAtlas)

# Generate effort maps

nigeria_map<- map_coverage(“Nigeria”)

kenya_map<- map_coverage(“Kenya”)

southafrica_map<- map_coverage(“South Africa”)

2.6 Species-level case studies

To evaluate the package’s utility for conservation and migratory monitoring, two ecologically distinct species were mapped: the Critically Endangered Hooded Vulture (Necrosyrtes monachus) (Figure 3) and the Palearctic migrant Barn Swallow (Hirundo rustica) (Figure 4).

# Retrieve codes

vulture_code<- get_species_code(“Hooded Vulture”)

swallow_code<- get_species_code(“Barn Swallow”)

# Generate distribution maps

map_species(vulture_code, country = “Nigeria”)

map_species(swallow_code, country = “South Africa”)

#… (repeated for other countries)

2.7 Software sustainability and versioning

AfriAtlas (v0.1.0) is distributed through GitHub and uses version-controlled releases to support transparent development and reproducibility. Package dependencies are managed through the package DESCRIPTION file, ensuring compatibility with required spatial and visualization libraries. As AfriAtlas relies on the BirdMap API for data retrieval, functionality depends partly on external API structure and availability. Changes to API endpoints or underlying data formats may require corresponding updates to maintain package compatibility and functionality.

3 Results

3.1 Technical performance and reproducibility

AfriAtlas supports real-time visualization of BirdMap data, allowing outputs to reflect newly submitted citizen-science observations as they are incorporated into the underlying database. Processing performance depends primarily on internet connectivity, BirdMap server responsiveness, and the volume of records retrieved, with larger regions or datasets generally requiring longer processing times. To improve robustness, the package incorporates error-handling through tryCatch(), reducing disruptions associated with temporary API interruptions or server delays. Reproducibility is supported through script-based workflows in R using standardized procedures and user-defined parameters. However, because AfriAtlas retrieves data from a continuously updated database, outputs may vary over time as new observations are added or existing records are updated.

3.2 Survey effort across regions

Survey‐effort maps revealed clear differences in sampling intensity across the three countries (Figure 2; Appendix A). South Africa showed the highest coverage, with 1,613 pentads receiving 101–999 hours of effort (mean = 281.99 ± 4.99 SE) and 249 pentads exceeding 1,000 hours (mean = 2,352.64 ± 123.35 SE). Effort was also substantial in the 4–7 hour category (2,835 pentads, mean = 5.10 ± 0.02 SE). Kenya exhibited low-moderate sampling, with most coverage concentrated in the 2–3 hour range (549 pentads, mean = 2.53 ± 0.02 SE) and only 7 pentads surpassing 1,000 hours (mean = 1,424.29 ± 149.25 SE). Nigeria was also dominated by low-moderate effort categories, including 3,798 pentads with 2–3 hours (mean = 2.39 ± 0.01 SE) and 1,548 pentads with 4–7 hours (mean = 4.93 ± 0.02 SE) (Appendix A).

3.3 Species-level case studies

Hooded Vulture showed low W values across all regions, with Nigerian pentads showing notably low values (2.8 percent) (Figure 3), consistent with documented population declines in West Africa. Barn Swallow exhibited a clear latitudinal trend: low W in Nigeria (4.7%), moderate in Kenya (54.9%), and high saturation in South Africa (73.0%) (Figure 4).

4 Discussion

4.1 Ecological interpretation of AfriAtlas outputs

AfriAtlas generated outputs that reflected large-scale distribution patterns forHooded Vulture and Barn Swallow, demonstrating the utility of the package for biodiversity analyses. The Widespreadness Index (W) showed patterns consistent with existing ecological knowledge and species assessments. For example, lower values of W for the Hooded Vulture aligned with documented population declines in West Africa associated with poisoning and illegal trade (Ogada et al., 2016; BirdLife International, 2022). Likewise, outputs for the Barn Swallow reflected expected wintering distributions consistent with known migratory patterns across Africa (BirdLife International, 2019).This findings highlight the value of citizen science in generating large-scale species distribution data and supporting long-term biodiversity monitoring (Ringim et al., 2022; Tende et al., 2024).

Coverage disparities among South Africa, Kenya, and Nigeria highlight the importance of using effort-corrected metrics when interpreting atlas data. By automating the retrieval and visualization of effort patterns, AfriAtlas helps account for these biases and supports more reliable cross-regional comparisons. As atlas datasets expand across Africa, such tools will be critical for highlighting ecological insights from unevenly sampled landscapes.

4.2 Workflow efficiency

Before AfriAtlas, producing pentad-level maps required extensive manual processing in desktop GIS software. The workflow is streamlined into a series of function calls that generate maps within seconds, facilitating rapid biodiversity reporting and supporting reproducible workflows across a range of projects.

4.3 Limitations

The analyses presented here were run using R 4.2.3 and AfriAtlas v0.1.0. The package’s performance depends on internet connectivity and BirdMap server responsiveness, although implemented error-handling mechanisms reduce temporary disruptions. The Widespreadness Index should be interpreted strictly as a descriptive, effort-conditioned indicator of species widespreadness rather than species reporting rate or a formal estimate of occupancy (MacKenzie et al., 2002). Although the metric standardizes comparisons using full protocol survey effort, it does not account for imperfect detection, observer heterogeneity, or non-random spatial sampling inherent in citizen-science datasets (MacKenzie et al., 2002; Dickinson et al., 2010). Detectability may vary among habitats, with species potentially easier to detect in open landscapes than in dense vegetation, while differences in observer experience and reporting behavior across regions or countries may further influence observed patterns. Consequently, the index is most appropriate for broad-scale comparisons and exploratory analyses and should not replace formal occupancy approaches that explicitly model detection processes.

4.4 Conclusion

AfriAtlas provides an integrated framework for accessing, processing, and visualizing African Bird Atlas data by combining API retrieval with standardized spatial outputs and publication-ready visualizations. By reducing multiple manual processing steps, the package simplifies the transition from raw atlas data to interpretable results. The examples presented here demonstrate its capacity to generate ecologically plausible spatial patterns and support reproducible analyses. It facilitates standardized visualization of survey effort and species occurrence data and can assist in identifying spatial patterns and survey coverage gaps across atlas datasets. As such, AfriAtlas provides a useful tool for biodiversity research, monitoring, and related applications using African atlas data.

Generative AI statement

The author(s) declared that generative AI was used in the creation of this manuscript. The author(s) verify and take full responsibility for the use of generative AI. Gemini Pro was used solely for debugging and refining code, assisting in structuring the vignette, and performing grammatical editing. No generative AI system contributed to data analysis, interpretation of results, scientific reasoning, or the generation of scholarly content. All conclusions and interpretations are entirely those of the authors.

Any alternative text (alt text) provided alongside figures in this article has been generated by Frontiers with the support of artificial intelligence and reasonable efforts have been made to ensure accuracy, including review by the authors wherever possible. If you identify any issues, please contact us.

Publisher’s note

All claims expressed in this article are solely those of the authors and do not necessarily represent those of their affiliated organizations, or those of the publisher, the editors and the reviewers. Any product that may be evaluated in this article, or claim that may be made by its manufacturer, is not guaranteed or endorsed by the publisher.

Supplementary material

The Supplementary Material for this article can be found online at: https://www.frontiersin.org/articles/10.3389/fbirs.2026.1765968/full#supplementary-material

Supplementary material Supplementary material at the source

Footnotes

Edited by: Piotr Tryjanowski, Poznan University of Life Sciences, Poland

Reviewed by: René Bolom-Huet, Universidad Autónoma del Estado de México, Mexico

Pelin Özden, Izmir Kavram Meslek Yuksekokulu, Türkiye