{"id":33187088,"url":"https://srkobakian.github.io/sugarbag/","last_synced_at":"2025-11-25T18:00:38.876Z","repository":{"id":43918145,"uuid":"148102617","full_name":"srkobakian/sugarbag","owner":"srkobakian","description":"An R package to create tessellated hexagon maps of Australia.","archived":false,"fork":false,"pushed_at":"2023-07-12T23:14:54.000Z","size":50478,"stargazers_count":42,"open_issues_count":0,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-10-22T05:03:21.362Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://srkobakian.github.io/sugarbag/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srkobakian.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-09-10T05:17:03.000Z","updated_at":"2025-06-02T22:47:30.000Z","dependencies_parsed_at":"2024-01-18T03:48:22.303Z","dependency_job_id":null,"html_url":"https://github.com/srkobakian/sugarbag","commit_stats":{"total_commits":318,"total_committers":6,"mean_commits":53.0,"dds":"0.23270440251572322","last_synced_commit":"ca61ca9bcce89215142fb9211e89137eafac2b4b"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/srkobakian/sugarbag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srkobakian%2Fsugarbag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srkobakian%2Fsugarbag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srkobakian%2Fsugarbag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srkobakian%2Fsugarbag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srkobakian","download_url":"https://codeload.github.com/srkobakian/sugarbag/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srkobakian%2Fsugarbag/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286079811,"owners_count":27282121,"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","status":"online","status_checked_at":"2025-11-25T02:00:05.816Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":"2025-11-16T05:00:30.371Z","updated_at":"2025-11-25T18:00:38.864Z","avatar_url":"https://github.com/srkobakian.png","language":"R","funding_links":[],"categories":["Spatial"],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from this README.Rmd. Please edit this file --\u003e\n\n```{r setup, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  message = FALSE,\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# sugarbag \u003cimg src='man/figures/logo.png' align=\"right\" height=\"138.5\" /\u003e\n\n[![CRAN\\_Status\\_Badge](http://www.r-pkg.org/badges/version/sugarbag)](https://cran.r-project.org/package=sugarbag)\n[![Downloads](http://cranlogs.r-pkg.org/badges/sugarbag?color=brightgreen)](https://cran.r-project.org/package=sugarbag)\n\nThe **sugarbag** package creates tessellated hexagon maps for visualising\ngeo-spatial data. Hexagons of equal size are positioned to best preserve\nrelationships between individual areas and the closest focal point, and\nminimise distance from their actual location. This method provides an\nalternative to cartograms that allows all regions to be compared on the same visual scale.\n\nMaps containing regions with a few small and densely populated areas are\nextremely distorted in cartograms. An example of this is a population\ncartogram of Australia, which distorts the map into an unrecognisable\nshape. The technique implemented in this package is particularly useful\nfor these regions.\n\n## Installation\n\nYou can install the CRAN release version of sugarbag from [CRAN](https://CRAN.R-project.org) with:\n\n```{r install, eval = FALSE}\ninstall.packages(\"sugarbag\")\n```\n\nYou can install the development version from GitHub using:\n\n```{r github, eval = FALSE}\ninstall.packages(\"remotes\")\nremotes::install_github(\"srkobakian/sugarbag\")\n```\n\n## Getting started\n\nThere are two ways of creating hexagon maps using sugarbag: \n\n1. Use `geom_sugarbag()`; OR\n2. Assemble the map manually.\n\nBoth methods are outlined below. `geom_sugarbag()` is easier but less customisable than assembling the map manually.\n\nWe show how to create a map of Tasmania using each method. Tasmania is the southern-most state of Australia, consisting of one large land\nmass and several smaller islands. We will use the Australian Bureau of Statistics’ ESRI shape files to build our map. The shapefile has been filtered to contain only Tasmania. \n\nThe package contains these shapefiles of Tasmania - `tas_lga` for local government areas, and `tas_sa2` for ABS Statistical Area Level 2 - for example purposes. \n\n```{r}\nlibrary(sugarbag)\nlibrary(dplyr)\nlibrary(tidyr)\nlibrary(tibble)\nlibrary(ggplot2)\nlibrary(ggthemes)\n```\n\n### Making a map with `geom_sugarbag()`\n\nThe `geom_sugarbag()` function provides a simplified way to make sugarbag tesselated hexagon maps. Here's an example:\n\n```{r}\ntas_lga %\u003e%\n  ggplot(aes(fill = lga_code_2016)) +\n  geom_sf(alpha = 0.4, linewidth = 0) +\n  geom_sugarbag(aes(geometry = geometry)) +\n  scale_fill_viridis_d() +\n  theme_map() +\n  theme(legend.position = \"none\", aspect.ratio = 1)\n```\n\nNote that we first create a standard `geom_sf()` layer. This displays the actual polygons in the data, over which we lay the hexagons using `geom_sugarbag()`. \n\nAll you need for `geom_sugarbag()` is an SF dataframe - a dataframe of class \"sf\" that contains a geometry column that describes polygons. `geom_sugarbag()` will handle the process of converting those polygons to hexagons and placing them in the appropriate place. \n\n### Making a manual sugarbag map\n\n`geom_sugarbag()` (above) provides a streamlined way of making hexagon maps. But it is less configurable than making the sugarbag maps manually.\n\nTo make a sugarbag map manually, there are four key steps:\n\n1. Calculate the centroid of each polygon in your data;\n2. Create a grid of possible locations for the hexagons to be placed on your map;\n3. Allocate each polygon to one of the possible hexagon locations;\n4. Visualise the results, typically using `geom_polygon()`.\n\nThese steps are outlined below.\n\n#### Calculate centroids from polygons\n\nThe function `create_centroids` finds the central points of the polygons\nprovided as an argument.\n\n```{r}\n# Find the longitude and latitude centroid for each region or area\ncentroids \u003c- create_centroids(tas_lga, \"lga_code_2016\")\n```\n\n#### Create grid of possible hexagon locations\n\nTo tessellate correctly, all the hexagons must be evenly spaced. This\nfunction creates a grid of possible locations for the polygons.\n\n```{r}\ngrid \u003c- create_grid(centroids = centroids, hex_size = 0.2, buffer_dist = 1.2)\n```\n\nThe `sugarbag` package operates by creating a grid of possible hexagons\nto allocate electorates. The buffer extends the grid beyond the\ngeographical space, this is especially useful for densely populated\ncoastal areas or cities, such as Brisbane and Sydney in this case,\nHobart.\n\n#### Allocate polygon areas to hexagon locations\n\nEach polygon centroid will be allocated to the closest available hexagon\ngrid point. The capital cities data set will be used to preserve\nneighbourly relationships. The `allocate` function requires two inputs,\nthe centroids and the grid.\n\n```{r}\n# Allocate the centroids to the hexagon grid\n# We have the same amount of rows, as individual regions\nhex_allocated \u003c- allocate(\n  centroids = centroids,\n  hex_grid = grid,\n  hex_size = 0.2, # same size used in create_grid\n  hex_filter = 3,\n  focal_points = capital_cities,\n  width = 30, \n  verbose = TRUE\n)\n```\n\nThe function `fortify_hexagon` assists in plotting. We now have 6 points\nper region, one for each point of a hexagon. Connecting these points\nwill allow actual hexagons to be plotted.\n\nThe additional demographic information or data can now be added. This\ncan be used to allow plots to be coloured by region.\n\n#### Visualise\n```{r}\nhexagons \u003c- fortify_hexagon(data = hex_allocated, sf_id = \"lga_code_2016\", hex_size = 0.2)\n\npolygons \u003c- fortify_sfc(tas_lga) %\u003e% \n  mutate(poly_type = \"geo\")\n\nggplot(mapping = aes(fill = lga_code_2016)) +\n  geom_polygon(data = polygons, \n               aes(x=long, lat, \n    group = interaction(lga_code_2016, polygon)), \n               alpha = 0.4) +\n  geom_polygon(data = hexagons, \n               aes(x=long, lat, \n    group = interaction(lga_code_2016))) +\n  scale_fill_viridis_d() +\n  theme_map() +\n  theme(legend.position = \"none\", aspect.ratio = 1)\n```\n\nFor animations to move between geography and hexagons the `sf_id` must\nmatch, there also needs to be an identifier to separate the states to\nanimate between for `gganimate`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/srkobakian.github.io%2Fsugarbag%2F","html_url":"https://awesome.ecosyste.ms/projects/srkobakian.github.io%2Fsugarbag%2F","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/srkobakian.github.io%2Fsugarbag%2F/lists"}