mapai

An R package for Supervised Learning for Positional Accuracy Improvement of Vector Maps

https://github.com/kvantas/mapai

Science Score: 49.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 3 DOI reference(s) in README
✓
Academic publication links
Links to: zenodo.org
○
Academic email domains
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (19.2%) to scientific vocabulary

Last synced: 6 months ago · JSON representation

Repository

An R package for Supervised Learning for Positional Accuracy Improvement of Vector Maps

Basic Info

Host: GitHub
Owner: kvantas
License: other
Language: R
Default Branch: master
Homepage: https://kvantas.github.io/mapAI/
Size: 12.9 MB

Statistics

Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Releases: 6

Created 9 months ago · Last pushed 7 months ago

Metadata Files

Readme License Codemeta

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# mapAI


[![packageversion](https://img.shields.io/badge/Package%20version-0.4.0-orange.svg?style=flat-square)](https://github.com/kvantas/mapAI)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.15767080.svg)](https://doi.org/10.5281/zenodo.15767080)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![R-CMD-check](https://github.com/kvantas/mapAI/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/kvantas/mapAI/actions/workflows/R-CMD-check.yaml)


The `mapAI` package is designed to provide a comprehensive and accessible PAI (positional accuracy improvement) framework for vector geospatial data.

## Overview

The `mapAI` package provides a comprehensive and accessible framework
for Positional Accuracy Improvement (PAI) of vector geospatial data.
This package’s main contributions  are: 

(a) the unification
of a set of PAI methods from classical adjustments to statistical and machine
learning algorithms,
within a framework engineered to modify the geometry of spatial
features; 

(b) the application of modern best practices regarding
predictive accuracy assessment using;

(c) the integration of distortion analysis into the PAI workflow, providing
powerful diagnostics.

## Installation

You can install the development version of `mapAI` from [GitHub](https://github.com/) using the `pak` package:

``` r
# install.packages("pak")
pak::pak("kvantas/mapAI")
```

## Core Workflow: A Complete Example

This example demonstrates the primary workflow. We will first generate a synthetic dataset representing a distorted map and then use the package's functions to correct it.

### 1. Load Libraries and Create Demo Data

We begin by using `create_demo_data()` to generate a test case with complex, noisy distortions.

```{r setup}
library(mapAI)
library(sf)
library(ggplot2)

# Generate a shapefile and a GCPs CSV with complex noisy distortions
# The function returns a list containing the paths to these new files.
demo_files <- create_demo_data(type = "complex", seed = 42)
```

### 2. Read Data and Train a Model

We load the generated files and train a **Generalized Additive Model (`gam`)**, which is ideal for capturing the smooth, non-linear distortions present in the demo data.

```{r load-and-train}
# Load the homologous points (GCPs) and the distorted vector map
gcp_data <- read_gcps(gcp_path = demo_files$gcp_path)
map_to_correct <- read_map(shp_path = demo_files$shp_path)

# Train the GAM model using the GCPs
gam_model <- train_pai_model(gcp_data, pai_method = "gam")
```

### 3. Apply Correction and Visualize

We apply the trained model to our distorted grid. The resulting plot, which overlays the corrected grid on the original, provides a clear visual confirmation of what the model does to the distorted map.

```{r apply-and-visualize, fig.show='hold'}
# Apply the model to the distorted map
corrected_map <- apply_pai_model(gam_model, map_to_correct)

# For easy plotting, add a 'status' column and combine the maps
map_to_correct$status <- "Original (Distorted)"
corrected_map$status <- "Corrected"
comparison_data <- rbind(map_to_correct[, "status"], corrected_map[, "status"])

# Create the final comparison plot
ggplot(comparison_data) +
  geom_sf(aes(color = status, linetype = status), fill = NA, linewidth = 0.7) +
  scale_color_manual(name = "Map Status", values = c("Original (Distorted)" = "grey50", "Corrected" = "#e41a1c")) +
  scale_linetype_manual(name = "Map Status", values = c("Original (Distorted)" = "dashed", "Corrected" = "solid")) +
  labs(title = "Positional Correction of a Distorted Grid",
       subtitle = "Overlay of original (dashed) and mapAI-corrected (solid) geometries") +
  theme_minimal()
```

---

## From Correction to Explanation: Advanced Distortion Analysis

A key challenge with data-driven models is understanding *what* they have learned. `mapAI` directly addresses this by providing tools to "open the black box" and analyze the properties of the learned transformation.

### 4. Quantify and Visualize the Distortion Field

The `analyze_distortion()` function computes local distortion metrics across the map space. This allows us to move from a simple visual assessment to a quantitative map of the distortion.

```{r advanced-analysis, message=FALSE, warning=FALSE}
# 1. Create a grid of points for analysis using the pipe (%>%)
library(magrittr)
analysis_points <- sf::st_make_grid(gcp_data, n = c(25, 25)) %>%
  sf::st_centroid() %>%
  sf::st_sf()

# 2. Analyze the distortion using our trained GAM model
distortion_results <- analyze_distortion(gam_model, analysis_points)

# 3. Plot the distortion surfaces
plot_area <- plot_distortion_surface(
  distortion_results, metric = "log2_area_scale", diverging = TRUE
) + labs(title = "Areal Distortion (log2σ)")

plot_shear <- plot_distortion_surface(
  distortion_results, metric = "max_shear"
) + labs(title = "Maximum Shear Distortion (°)")

# Show the plots
plot_area
plot_shear
```

## Meta

* Bug reports, suggestions, and code are welcome.

* License:
    + All code is licensed MIT.

Owner

Name: Konstantinos Vantas
Login: kvantas
Kind: user
Location: Greece
Company: orestias

Website: https://kvantas.orestias.gr/
Repositories: 117
Profile: https://github.com/kvantas

PhD Engineer

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "mapAI",
  "description": "An R package for Positional Accuracy Improvement of Vector Maps that uses supervised learning algorithms. It uses as input a csv file with homologous points and a vector map of the area of interest in order to correct it.",
  "name": "mapAI: An R Package for Positional Accuracy Improvement of Vector Maps",
  "codeRepository": "https://github.com/kvantas/mapAI",
  "issueTracker": "https://github.com/kvantas/mapAI/issues",
  "license": "https://spdx.org/licenses/MIT",
  "version": "0.4.0",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.5.0 (2025-04-11)",
  "author": [
    {
      "@type": "Person",
      "givenName": "Konstantinos",
      "familyName": "Vantas",
      "email": "kon.vantas@gmail.com",
      "@id": "https://orcid.org/0000-0001-6387-8791"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Konstantinos",
      "familyName": "Vantas",
      "email": "kon.vantas@gmail.com",
      "@id": "https://orcid.org/0000-0001-6387-8791"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "mockery",
      "name": "mockery",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=mockery"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "withr",
      "name": "withr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=withr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "version": ">= 3.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "dplyr",
      "name": "dplyr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=dplyr"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "magrittr",
      "name": "magrittr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=magrittr"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "mgcv",
      "name": "mgcv",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=mgcv"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "rlang",
      "name": "rlang",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rlang"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "sf",
      "name": "sf",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=sf"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "ranger",
      "name": "ranger",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ranger"
    },
    "7": {
      "@type": "SoftwareApplication",
      "identifier": "fields",
      "name": "fields",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=fields"
    },
    "8": {
      "@type": "SoftwareApplication",
      "identifier": "units",
      "name": "units",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=units"
    },
    "9": {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggplot2"
    },
    "10": {
      "@type": "SoftwareApplication",
      "identifier": "viridis",
      "name": "viridis",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=viridis"
    },
    "11": {
      "@type": "SoftwareApplication",
      "identifier": "e1071",
      "name": "e1071",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=e1071"
    },
    "12": {
      "@type": "SoftwareApplication",
      "identifier": "R",
      "name": "R",
      "version": ">= 3.5"
    },
    "SystemRequirements": null
  },
  "fileSize": "613.38KB",
  "citation": [
    {
      "@type": "CreativeWork",
      "datePublished": "2025",
      "author": [
        {
          "@type": "Person",
          "givenName": "Vantas",
          "familyName": "Konstantinos"
        }
      ],
      "name": "mapAI: An R Package for Positional Accuracy Improvement of Vector Geospatial Data",
      "identifier": "https://doi.org/10.5281/zenodo.15767080",
      "@id": "https://doi.org/10.5281/zenodo.15767080",
      "sameAs": "https://doi.org/10.5281/zenodo.15767080"
    }
  ],
  "readme": "https://github.com/kvantas/mapAI/blob/master/README.md",
  "contIntegration": [
    "https://codecov.io/gh/kvantas/mapAI",
    "https://github.com/kvantas/mapAI/actions/workflows/R-CMD-check.yaml"
  ],
  "developmentStatus": "https://lifecycle.r-lib.org/articles/stages.html#stable"
}

GitHub Events

Total

Release event: 2
Push event: 80
Create event: 5

Last Year

Release event: 2
Push event: 80
Create event: 5

Dependencies

DESCRIPTION cran

dplyr * imports
rlang * imports
sf * imports
testthat >= 3.0.0 suggests

.github/workflows/R-CMD-check.yaml actions

actions/checkout v4 composite
r-lib/actions/check-r-package v2 composite
r-lib/actions/setup-pandoc v2 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite

.github/workflows/pkgdown.yaml actions

JamesIves/github-pages-deploy-action v4.5.0 composite
actions/checkout v4 composite
r-lib/actions/setup-pandoc v2 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite

.github/workflows/test-coverage.yaml actions

actions/checkout v4 composite
actions/upload-artifact v4 composite
codecov/codecov-action v5 composite
r-lib/actions/setup-r v2 composite
r-lib/actions/setup-r-dependencies v2 composite

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Source Science