{"id":15520230,"url":"https://github.com/statsmaths/ggmaptile","last_synced_at":"2025-08-05T09:31:55.431Z","repository":{"id":79631596,"uuid":"247347512","full_name":"statsmaths/ggmaptile","owner":"statsmaths","description":"Add Map Images from a Tile Server with ggplot2","archived":false,"fork":false,"pushed_at":"2023-10-28T18:49:42.000Z","size":19353,"stargazers_count":8,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-27T00:04:28.633Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statsmaths.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2020-03-14T20:20:59.000Z","updated_at":"2024-08-07T17:23:16.000Z","dependencies_parsed_at":"2023-05-14T00:45:17.957Z","dependency_job_id":null,"html_url":"https://github.com/statsmaths/ggmaptile","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statsmaths%2Fggmaptile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statsmaths%2Fggmaptile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statsmaths%2Fggmaptile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statsmaths%2Fggmaptile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statsmaths","download_url":"https://codeload.github.com/statsmaths/ggmaptile/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228725718,"owners_count":17963164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T10:25:03.504Z","updated_at":"2024-12-08T11:42:01.466Z","avatar_url":"https://github.com/statsmaths.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ggmaptile: Map Layer for ggplot2\n\n**Author:** Taylor B. Arnold\u003cbr/\u003e\n**License:** [GPL-2](https://opensource.org/licenses/GPL-2.0)\n\n[![CRAN Version](http://www.r-pkg.org/badges/version/ggmaptile)](https://CRAN.R-project.org/package=ggmaptile) [![Travis-CI Build Status](https://travis-ci.org/statsmaths/ggmaptile.svg?branch=master)](https://travis-ci.org/statsmaths/ggmaptile) ![Downloads](http://cranlogs.r-pkg.org/badges/ggmaptile)\n[![Codecov test coverage](https://codecov.io/gh/statsmaths/ggimg/branch/master/graph/badge.svg)](https://codecov.io/gh/statsmaths/ggmaptile?branch=master)\n\n## Installation\n\nThe package is currently only available on GitHub and can be installed with\n\n```{r}\nremotes::install_github(\"statsmaths/ggmaptile\")\n```\n\nIt is planned to submit the package to CRAN by the end of the month\n(March 2020).\n\n## Overview\n\nThere are two datasets included with the package. The first gives the location\nof the largest 58 cities in France. We will start by using this dataset to\nillustrate how the package works.\n\nThe main function in **ggmaptile** is called `stat_maptiles`, which\nautomatically adds map tiles to a plot. To use it, simply construct a ggplot\nobject where a longitude is assigned to the x aesthetic and a latitude is\nassigned to the y aesthetic. The function will cover the region spanned by the\ndata. Here, we grab tiles to cover the region of the largest 58 cities in\nFrance.\n\n```{r}\nlibrary(ggplot2)\nlibrary(ggmaptile)\nlibrary(dplyr)\n\nfrench_city %\u003e%\n  ggplot(aes(x = lng, y = lat)) +\n    stat_maptiles()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/simple-map-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\n\nOften, with a map, it is best to hide the axes and reserve the entire plot\nregion for the map itself. The function `mapview` included with the package,\nalong with ggplot2's theme `theme_void`, make this relatively easy.\n\n```{r}\nfrench_city %\u003e%\n  ggplot(aes(x = lng, y = lat)) +\n    stat_maptiles() +\n    theme_void() +\n    mapview()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/mapview-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nAdditional layers can be added on top of the map tiles. So, for example, we can\nadd points associated with each of the cities and color them according their\nadministrative region.\n\n```{r}\nfrench_city %\u003e%\n  ggplot(aes(x = lng, y = lat)) +\n    stat_maptiles() +\n    geom_point(aes(color = admin_name), size = 3, show.legend = FALSE) +\n    theme_void() +\n    mapview()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/points-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nAnd that's it! In the following sections, options and guidance for how to use\n`stat_maptiles` are highlighted to optimise the package for various use cases.\n\n## Common maptile options\n\nThere are several options built into the `stat_maptiles` function that can be\nadjusted to control how map tiles are selected and shown on your plot. By\ndefault, a zoom level will be determined for your plot in order to approximately\ncover the region in 25 tiles. Providing a positive or negative integer to the\noption `zoom_adj` can adjust this default to zoom in (positive value) or out\n(negative) value. Here is our previous map zoomed out one level.\n\n```{r}\nfrench_city %\u003e%\n  ggplot(aes(x = lng, y = lat)) +\n    stat_maptiles(\n      zoom_adj = -1\n    ) +\n    geom_point(aes(color = admin_name), size = 3, show.legend = FALSE) +\n    theme_void() +\n    mapview()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/zoom-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nIn this case, the zoomed out map actually looks quite nice and provides more\nreadable labels for the countries and major landmarks. Be careful when zooming\nin too much beyond the default as it can require downloading and displaying a\nvery large number of tiles. It is also possible to set an explicit zoom level\nfrom 1 to 19 using the parameter `zoom`.\n\n By default, map tiles come from the \"toner-lite\" category supplied by\n [Stamen Design, under CC BY 3.0.](http://maps.stamen.com/#toner/). To use a\n different set of tiles, supply a string to the parameter `url` to describe\n how to grab tiles. Here, for example, are the \"terrain\" map tiles from Stamen.\n We also need to set the option `force = TRUE`; by default the package\n caches downloaded tiles within a session and would reuse the \"toner-lite\"\n tiles that were previously downloaded.\n\n ```{r}\n french_city %\u003e%\n   ggplot(aes(x = lng, y = lat)) +\n     stat_maptiles(\n       url = \"http://tile.stamen.com/terrain/%d/%d/%d.png\",\n       force = TRUE\n     ) +\n     geom_point(aes(color = admin_name), size = 3, show.legend = FALSE) +\n     theme_void() +\n     mapview()\n ```\n\n \u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/terrain-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nYou can also supply a value to the option `alpha` to control the opacity of the\ntiles. This is useful when using bright tiles, such as the terrain ones, to\nmake sure your other layers are not lost in the colors of the map itself.\nNote that we do not need to set `force = TRUE` here because the correct tiles\nare already downloaded from the previous code block.\n\n```{r}\nfrench_city %\u003e%\n  ggplot(aes(x = lng, y = lat)) +\n    stat_maptiles(\n      url = \"http://tile.stamen.com/terrain/%d/%d/%d.png\",\n      alpha = 0.4\n    ) +\n    geom_point(aes(color = admin_name), size = 3, show.legend = FALSE) +\n    theme_void() +\n    mapview()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/alpha-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nBy default, downloaded tiles are stored in a local temporary directory. This\npersists within an R session but is lost when closing R. To set an alternative\nlocal directory, which can be stored between sessions to avoid the constant\nre-downloading of tiles, set the parameter `cache_dir` to the desired root of\nyour cache location. Here is its usage with the \"watercolor\" tiles:\n\n```{r}\nfrench_city %\u003e%\n  ggplot(aes(x = lng, y = lat)) +\n    stat_maptiles(\n      url = \"http://tile.stamen.com/watercolor/%d/%d/%d.jpg\",\n      alpha = 0.6,\n      cache_dir = \"cache\"\n    ) +\n    geom_point(aes(color = admin_name), size = 3, show.legend = FALSE) +\n    theme_void() +\n    mapview()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/cache-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nCombining these options can produce a myriad of interesting plots to help\nvisualize and communicate your spatial data. One final option, which requires\na bit more discussion, is included in the section below.\n\n## Aspect ratio and facets\n\nOne of the more subtle issues with grabbing map tiles to visualize a dataset\nis determining what tiles to use to cover a given set of data. At the root of\nthe difficulty is that there is generally a fixed aspect ratio that must be\npreserved to avoid distorting the tile images. This means that the number of\ntiles depends on the desired aspect ratio of plotting device, which is difficult\nto always know ahead of time when grabbing map tiles. By default, the function\n`stat_maptiles` grabs just enough tiles to cover the given data and constrains\nthe plot to fit these tiles with the desired aspect ratio. While often,\nparticularly when working data roughly distributed in a square area as with\nthe major France cities, the default behavior works fine. Here, we see how\nto modify this behavior.\n\nThe second dataset provided in the package provides information about the\nParisian metro system. It is a good dataset to illustrate the issue with aspect\nratios because metro lines tend to extend in one direction (north-south or\neast-west) and offer several different ways that we may want to control the\ndimensions of the output.\n\nHere, we will start by looking at the default map constructed for the M4 metro\nline. The dataset includes the metro path and canonical colors associated with\neach line. We will use `geom_segment` the `scale_color_identity` to show these\nfeatures on top of the map.\n\n```{r}\nparis_metro %\u003e%\n  filter(ligne == 4) %\u003e%\n  ggplot(aes(lon, lat)) +\n    stat_maptiles() +\n    geom_point(\n      aes(color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    geom_segment(\n      aes(xend = lon_fin, yend = lat_fin, color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    scale_color_identity() +\n    theme_void() +\n    mapview()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/metro-all-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nThe default output looks quite nice. It does a good job of determining the\nrequired number of tiles. It also makes sure that the plotted map tiles are not\ndistorted by only using part of the plot region for the map.\n\nWhat if we wanted to fill out the white region with map tiles? They are not\nneeded to show the data, but if (for whatever reason) we need to have a square\nplot it makes sense to use this space to give more context to our data. To do\nthis we can set the parameter `aspect_ratio` to control the desired aspect\nratio of the selected tiles. This will add additional tiles either the x or y\n(as needed) dimension to produce a plot of the desired aspect ratio. Here, we\nset the aspect ratio to 1, to have an equal number of x and y tiles.\n\n```{r}\nparis_metro %\u003e%\n  filter(ligne == 4) %\u003e%\n  ggplot(aes(lon, lat)) +\n    stat_maptiles(\n      aspect_ratio = 1\n    ) +\n    geom_point(\n      aes(color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    geom_segment(\n      aes(xend = lon_fin, yend = lat_fin, color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    scale_color_identity() +\n    theme_void() +\n    mapview()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/metro-4-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nNote that, because the tiles are discrete, the aspect ratio of the output may\nonly be approximate.\n\nShowing a number of the metro lines on the same map is interesting, but can get\na bit messy:\n\n```{r}\nparis_metro %\u003e%\n  filter(ligne \u003c= 9) %\u003e%\n  ggplot(aes(lon, lat)) +\n    stat_maptiles(\n      alpha = 0.6\n    ) +\n    geom_point(\n      aes(color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    geom_segment(\n      aes(xend = lon_fin, yend = lat_fin, color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    scale_color_identity() +\n    theme_void() +\n    mapview()\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/metro-4-square-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nAn alternative approach is to use ggplot2's facets to show each line in its\nown small plot. Here, we have two options. First, you could use a\nconsistent plot region for all of the maps with fixed scales (the default of\n`facet_wrap`). We will set the option `quiet = TRUE` to avoid printing a\nstatus message for each facet and zoom each image out by a factor of 1, since\nthe default algorithm assumes each map is being printed\n\n```{r}\nparis_metro %\u003e%\n  filter(ligne \u003c= 9) %\u003e%\n  ggplot(aes(lon, lat)) +\n    stat_maptiles(\n      zoom_adj = -1,\n      quiet = TRUE\n    ) +\n    geom_point(\n      aes(color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    geom_segment(\n      aes(xend = lon_fin, yend = lat_fin, color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    theme_void() +\n    mapview() +\n    facet_wrap(~ligne)\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/metro-facet-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nIt is also possible to allow the scales to float freely so that each region can\ndisplay a different map. However, in this case you will need to set the aspect\nratio to a fixed value (otherwise the images will becomes distorted):\n\n```{r}\nparis_metro %\u003e%\n  filter(ligne \u003c= 12) %\u003e%\n  ggplot(aes(lon, lat)) +\n    stat_maptiles(\n      aspect_ratio = 1,\n      zoom_adj = -1,\n      quiet = TRUE\n    ) +\n    geom_point(\n      aes(color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    geom_segment(\n      aes(xend = lon_fin, yend = lat_fin, color = ligne_couleur),\n      show.legend = FALSE\n    ) +\n    theme_void() +\n    mapview() +\n    facet_wrap(~ligne, scale = \"free\", ncol = 4)\n```\n\n\u003cimg src=\"https://raw.githubusercontent.com/statsmaths/ggmaptile/master/vignettes/figs/metro-facet-free-1.png\" alt=\"fig\"\u003e\u003c/img\u003e\n\nUsing free scales are particularly useful when you want to facet by different\nregions of the plot, such as showing the french cities data with a facet for\neach region.\n\n## Citation\n\nIf you make use of the package in your work, please cite it as follows:\n\n```\n@Manual{,\n  title = {ggmaptile},\n  author = {Taylor B. Arnold},\n  year = {2020},\n  note = {R package version 0.1.0},\n  url = {https://github.com/statsmaths/ggmaptile},\n}\n```\n\n## Contributing\n\nContributions, including bug fixes and new features, to the package are\nwelcome. When contributing to this repository, please first discuss the change\nyou wish to make via a GitHub issue or email with the maintainers of this\nrepository before making a change. Small bug fixes can be given directly\nas pull requests.\n\nPlease note that this project is released with a\n[Contributor Code of Conduct](CONDUCT.md). By participating in this project\nyou agree to abide by its terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatsmaths%2Fggmaptile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatsmaths%2Fggmaptile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatsmaths%2Fggmaptile/lists"}