Package 'sugarbag' reference manual

Title:	Create Tessellated Hexagon Maps
Description:	Create a hexagon tile map display from spatial polygons. Each polygon is represented by a hexagon tile, placed as close to it's original centroid as possible, with a focus on maintaining spatial relationship to a focal point. Developed to aid visualisation and analysis of spatial distributions across Australia, which can be challenging due to the concentration of the population on the coast and wide open interior.
Authors:	Dianne Cook [aut, cre, ths] , Stephanie Kobakian [aut] , Matt Cowgill [ctb]
Maintainer:	Dianne Cook <[email protected]>
License:	MIT + file LICENSE
Version:	0.1.8
Built:	2024-11-04 03:49:12 UTC
Source:	https://github.com/srkobakian/sugarbag

Allocate polygon centroids to hexagons in a grid

Description

Chooses a hexagon centroid for each polygon in the shape file, from a grid spanning the longitudes and latitudes in the expanded bounding box.

Usage

allocate(
  centroids,
  hex_grid,
  sf_id = names(centroids)[1],
  hex_size,
  hex_filter,
  focal_points = NULL,
  order_sf_id = NULL,
  width = 30,
  verbose
)
allocate(
  centroids,
  hex_grid,
  sf_id = names(centroids)[1],
  hex_size,
  hex_filter,
  focal_points = NULL,
  order_sf_id = NULL,
  width = 30,
  verbose
)

Arguments

`centroids`	a data frame with centroids of non empty polygons
`hex_grid`	a data frame containing all possible hexagon points
`sf_id`	a string to indicate the column to identify individual polygons
`hex_size`	a float value in degrees for the diameter of the hexagons
`hex_filter`	amount of hexagons around centroid to consider
`focal_points`	a data frame of reference locations when allocating hexagons, capital cities of Australia are used in the example
`order_sf_id`	a string to indicate the column used to order polygons
`width`	a numeric indicating the angle used to filter the hexagon grid
`verbose`	a boolean to indicate whether to show polygon id

Value

a data frame of all allocated hexagon points

Examples

# Create centroids set
centroids <- create_centroids(tas_lga, sf_id = "lga_code_2016")
# Smaller set for faster example
centroids <- centroids[1:10,] 
# Create hexagon location grid
data(capital_cities)
grid <- create_grid(centroids = centroids, hex_size = 0.2, buffer_dist = 1.2)
# Allocate polygon centroids to hexagon grid points
hex_allocated <- allocate(
  centroids = centroids,
  hex_grid = grid,
  hex_size = 0.2, # same size used in create_grid
  hex_filter = 3,
  focal_points = capital_cities,
  width = 30, 
  verbose = TRUE
)
# NEXT: 
# create a set of hexagon points for plotting
# using fortify_hexagon, and
# plot the hexagons with geom_polygon, see vignette
# Create centroids set
centroids <- create_centroids(tas_lga, sf_id = "lga_code_2016")
# Smaller set for faster example
centroids <- centroids[1:10,] 
# Create hexagon location grid
data(capital_cities)
grid <- create_grid(centroids = centroids, hex_size = 0.2, buffer_dist = 1.2)
# Allocate polygon centroids to hexagon grid points
hex_allocated <- allocate(
  centroids = centroids,
  hex_grid = grid,
  hex_size = 0.2, # same size used in create_grid
  hex_filter = 3,
  focal_points = capital_cities,
  width = 30, 
  verbose = TRUE
)
# NEXT: 
# create a set of hexagon points for plotting
# using fortify_hexagon, and
# plot the hexagons with geom_polygon, see vignette

The point locations of Australian capital cities.

Description

A dataset containing the longitude and latitude values of Australian capital cities.

Usage

capital_cities
capital_cities

Format

A data frame with 8 rows and 3 variables:

points: name of cities
longitude: location of point in longitude degrees
latitude: location of point in latitude degrees

For the polygon provided, find the closest focal point in the set provided

Description

For one row of an sf data frame, calculate the distance to the closest focal point. Return the name of the focal point, and the angle between focal point and centroid.

Usage

closest_focal_point(centroid, focal_points)
closest_focal_point(centroid, focal_points)

Arguments

`centroid`	a data frame describing one centroid
`focal_points`	a data frame of the longitude and latitude values

Value

data frame containing the name and location of the closest focal

Examples

# Create a set of polygon centroids
centroids <- create_centroids(tas_sa2, "sa2_5dig_2016")

# Find the closest capital city for the first centroid
closest_focal_point(centroids[1, ], capital_cities)
# Create a set of polygon centroids
centroids <- create_centroids(tas_sa2, "sa2_5dig_2016")

# Find the closest capital city for the first centroid
closest_focal_point(centroids[1, ], capital_cities)

Expand points to extend beyond the outermost centroids

Description

Called from within create_grid function, this function takes the bounding box of a group of polygons, or a specific table of minimum and maximum longitudes and latitudes to create points for each polygon to be allocated to that will tessellate into hexagons.

Usage

create_buffer(centroids, grid, hex_size, buffer_dist, verbose = FALSE)
create_buffer(centroids, grid, hex_size, buffer_dist, verbose = FALSE)

Arguments

`centroids`	data frame of centroids to be allocated
`grid`	data frame of hexagon centroids
`hex_size`	a float value in degrees for the diameter of the hexagons
`buffer_dist`	distance to extend beyond the geometry provided
`verbose`	a boolean to indicate whether to show function progress

Value

data frame of hexagon centroids

Examples

lga_centroids <- create_centroids(sugarbag::tas_lga, "lga_code_2016")
lga_grid <- create_grid(lga_centroids, hex_size = 0.2, buffer_dist = 1.2)

lga_centroids <- create_centroids(sugarbag::tas_lga, "lga_code_2016")
lga_grid <- create_grid(lga_centroids, hex_size = 0.2, buffer_dist = 1.2)

Create a data frame of longitude and latitude centroids of each polygon.

Description

Create a data frame of longitude and latitude centroids of each polygon.

Usage

create_centroids(shp_sf, sf_id, largest = TRUE, verbose = FALSE)
create_centroids(shp_sf, sf_id, largest = TRUE, verbose = FALSE)

Arguments

`shp_sf`	an sf object, a data set with a simple feature list column
`sf_id`	a string to indicate the column to identify individual polygons
`largest`	logical; for `st_centroid`: if `TRUE`, return centroid of the largest subpolygon of a `MULTIPOLYGON` rather than the whole `MULTIPOLYGON`
`verbose`	a boolean to indicate whether to show function progress

Value

a tibble containing longitude and latitude

Examples

centroids <- create_centroids(tas_lga, "lga_code_2016")
centroids <- create_centroids(tas_lga, "lga_code_2016")

Create a grid of evenly spaced points to allow hexagons to tessellate

Description

This function takes the output from the create_centroids function, or a set of centroids in a table with the columns latitude and longitude

Usage

create_grid(
  centroids,
  hex_size,
  buffer_dist,
  latitude = "latitude",
  longitude = "longitude",
  verbose = FALSE
)
create_grid(
  centroids,
  hex_size,
  buffer_dist,
  latitude = "latitude",
  longitude = "longitude",
  verbose = FALSE
)

Arguments

`centroids`	data frame of centroids to be allocated, this should have columns for longitude and latitude value of centroids, as
`hex_size`	a float value in degrees for the diameter of the hexagons
`buffer_dist`	distance to extend beyond the geometry provided
`latitude`	the column name for the latitude values of the centroids
`longitude`	the column name for the longitude values of the centroids
`verbose`	a boolean to indicate whether to show function progress

Value

grid

Examples

# Create a set of centroids for grid to overlay
centroids <- create_centroids(tas_lga, "lga_code_2016")
# Create the grid
grid <- create_grid(centroids = centroids, hex_size = 0.2, buffer_dist = 1.2, verbose = FALSE)

# Create a set of centroids for grid to overlay
centroids <- create_centroids(tas_lga, "lga_code_2016")
# Create the grid
grid <- create_grid(centroids = centroids, hex_size = 0.2, buffer_dist = 1.2, verbose = FALSE)

Create a tessellated hexagon map from a set of polygons

Description

Allocates each polygon in a shape file to a grid point to create a map of tessellated hexagons. The spatial relationships of areas are preserved while the geographic shape of each area is lost.

Usage

create_hexmap(
  shp,
  sf_id,
  hex_size = NULL,
  buffer_dist = NULL,
  hex_filter = 10,
  f_width = 30,
  focal_points = NULL,
  order_sf_id = NULL,
  export_shp = FALSE,
  verbose = FALSE
)
create_hexmap(
  shp,
  sf_id,
  hex_size = NULL,
  buffer_dist = NULL,
  hex_filter = 10,
  f_width = 30,
  focal_points = NULL,
  order_sf_id = NULL,
  export_shp = FALSE,
  verbose = FALSE
)

Arguments

`shp`	a shape file, if class is SPDF, will be converted to sf
`sf_id`	name of a unique column that distinguishes areas
`hex_size`	a float value in degrees for the diameter of the hexagons
`buffer_dist`	distance in degrees to extend beyond the geometry provided
`hex_filter`	amount of hexagons around centroid to consider
`f_width`	the angle used to filter the grid points around a centroid
`focal_points`	a data frame of reference locations when allocating hexagons, capital cities of Australia are used in the example
`order_sf_id`	a string name of a column to order by for allocating
`export_shp`	export the simple features set
`verbose`	a boolean to indicate whether to show function progress

Value

a data set containing longitude and latitude of allocated hexagon points for each non null geometry passed in the shape file

Examples


data(tas_lga)
# Smaller set for faster example
tas_lga_sub <- tas_lga[1:10,] 
data(capital_cities)
hexmap <- create_hexmap(
  shp = tas_lga_sub,
  sf_id = "lga_code_2016",
  hex_filter = 3,
  focal_points = capital_cities, 
  verbose = TRUE)

data(tas_lga)
# Smaller set for faster example
tas_lga_sub <- tas_lga[1:10,] 
data(capital_cities)
hexmap <- create_hexmap(
  shp = tas_lga_sub,
  sf_id = "lga_code_2016",
  hex_filter = 3,
  focal_points = capital_cities, 
  verbose = TRUE)

Filter full set of grid points for those within range of original point

Description

Takes only the closest available gridpoints as possible hexagon centroids to allocate polygons.

Usage

filter_grid_points(
  f_grid,
  f_centroid,
  focal_points = NULL,
  f_dist = filter_dist,
  angle_width = width,
  h_size = hex_size
)
filter_grid_points(
  f_grid,
  f_centroid,
  focal_points = NULL,
  f_dist = filter_dist,
  angle_width = width,
  h_size = hex_size
)

Arguments

`f_grid`	complete grid of hexagon centroids
`f_centroid`	the longitude and latitude values for the current centroid
`focal_points`	a tibble of focal locations, an optional argument that allows allocation of polygons to hexagon centroids in ascending order of the distance to the closest focal point. It also filters the grid points to those within a 30 degree range of the angle from focal point to centroid. The default "capitals" uses the locations of the Australian capital cities as focal points.
`f_dist`	a distance in degrees, used as a boundary to filter the hexagon centroids considered for each polygon centroid to be allocated.
`angle_width`	a numeric used to filter the hexagon grid
`h_size`	a float value in degrees for the diameter of the hexagons

Value

a tibble of filtered grid points

Creates the points that define a hexagon polygon for plotting

Description

Creates the points that define a hexagon polygon for plotting

Usage

fortify_hexagon(data, sf_id, hex_size)
fortify_hexagon(data, sf_id, hex_size)

Arguments

`data`	a data frame created by the allocate function
`sf_id`	a string to indicate the column to identify individual polygons
`hex_size`	a float value in degrees for the diameter of the hexagons

Value

a data frame of the seven points used to draw a hexagon

Examples

# same column is used in create_centroids
fortify_hexagon(data = tas_lga_hexctr, sf_id = "lga_code_2016", hex_size = 0.2)
# same column is used in create_centroids
fortify_hexagon(data = tas_lga_hexctr, sf_id = "lga_code_2016", hex_size = 0.2)

Convert a simple features tibble to tibble for plotting.

Description

This will contain individual points for plotting the polygon, indicating the longitude and latitude, order of points, if a hole is present, the piece, id and group.

Usage

fortify_sfc(sfc_df, keep = NULL)
fortify_sfc(sfc_df, keep = NULL)

Arguments

`sfc_df`	a simples features data set
`keep`	ratio of points to keep

Value

a tibble point of long lat points used to plot polygons

2019 Australian Federal election data: First preference votes for candidates (House of Representatives) in each electorate.

Description

A dataset containing first preference vote counts, candidate names, and other results for the House of Representatives from the 2016 Australian federal election. The data were obtained from the Australian Electoral Commission, and downloaded from https://results.aec.gov.au/24310/Website/Downloads/HouseFirstPrefsByPartyDownload-24310.csv

Usage

fp19
fp19

Format

A data frame with the following variables:

StateAbAbbreviation for state name
UniqueIDnumeric identifier that links the electoral division with Census and other election datasets.
DivisionNmElectoral division name
BallotPositionCandidate's position on the ballot
CandidateIDCandidate ID
SurnameCandidate surname
GivenNmCandidate given name
PartyAbAbbreviation for political party name
PartyNmPolitical party name
ElectedWhether the candidate was elected (Y/N)
HistoricElectedWhether the candidate is the incumbent member
OrdinaryVotesNumber of ordinary votes cast at the electorate for the candidate
PercentPercentage of ordinary votes for the candidate

geom_sugarbag

Description

geom_sugarbag() provides a convenient way to create tesselated hexagon maps using the sugarbag algorithm.

Usage

geom_sugarbag(
  mapping = NULL,
  data = NULL,
  stat = "sugarbag",
  position = "identity",
  hex_size = 0.2,
  na.rm = FALSE,
  ...
)
geom_sugarbag(
  mapping = NULL,
  data = NULL,
  stat = "sugarbag",
  position = "identity",
  hex_size = 0.2,
  na.rm = FALSE,
  ...
)

Arguments

`mapping`	Set of aesthetic mappings created by `aes()`. If specified and `inherit.aes = TRUE` (the default), it is combined with the default mapping at the top level of the plot. You must supply `mapping` if there is no plot mapping.
`data`	The data to be displayed in this layer. There are three options: If `NULL`, the default, the data is inherited from the plot data as specified in the call to `ggplot()`. A `data.frame`, or other object, will override the plot data. All objects will be fortified to produce a data frame. See `fortify()` for which variables will be created. A `function` will be called with a single argument, the plot data. The return value must be a `data.frame`, and will be used as the layer data. A `function` can be created from a `formula` (e.g. `~ head(.x, 10)`).
`stat`	The statistical transformation to use on the data for this layer, either as a `ggproto` `Geom` subclass or as a string naming the stat stripped of the `stat_` prefix (e.g. `"count"` rather than `"stat_count"`)
`position`	Position adjustment, either as a string naming the adjustment (e.g. `"jitter"` to use `position_jitter`), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.
`hex_size`	Default is 0.2. Units are degrees, corresponding to the diameter of the hexagons. See `?allocate`.
`na.rm`	If `FALSE`, the default, missing values are removed with a warning. If `TRUE`, missing values are silently removed.
`...`	Other arguments passed on to `layer()`. These are often aesthetics, used to set an aesthetic to a fixed value, like `colour = "red"` or `size = 3`. They may also be parameters to the paired geom/stat.

Details

Create a sugarbag hex map

The sugarbag algorithm creates a hexagon tile map from spatial polygons. It represents each polygon with a hexagon, which is placed close to the polygon's centroid while also maintaining its spatial relationship to a focal point.

If geom_sugarbag() is used to make a map of Australia, the capital cities will be used as focal points. For non-Australian maps, a single focal point will be inferred from the data, as the centroid with the smallest total distance to its three nearest neighbours. To specify focal points manually, construct your hexagon grid manually – see ?allocate.

Examples


library(ggplot2)
# Map of Tasmanian local govt areas using built-in data
 tas_lga %>%
  ggplot(aes(fill = lga_name_2016)) +
  geom_sf(alpha = 0.1) +
  geom_sugarbag(aes(geometry = geometry)) +
  theme(legend.position = "none")
  
# Map of SIDS data from North Carolina
if (requireNamespace("sf", quietly = TRUE)) {
nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)

ggplot(nc,
  aes(fill = AREA)) +
  geom_sf(alpha = 0.1) +
  geom_sugarbag(aes(geometry = geometry))
}

library(ggplot2)
# Map of Tasmanian local govt areas using built-in data
 tas_lga %>%
  ggplot(aes(fill = lga_name_2016)) +
  geom_sf(alpha = 0.1) +
  geom_sugarbag(aes(geometry = geometry)) +
  theme(legend.position = "none")
  
# Map of SIDS data from North Carolina
if (requireNamespace("sf", quietly = TRUE)) {
nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)

ggplot(nc,
  aes(fill = AREA)) +
  geom_sf(alpha = 0.1) +
  geom_sugarbag(aes(geometry = geometry))
}

The amount of homeless people in each Statistical Area at Level 2 in 2016.

Description

A data frame of the Statistical Area at Level 2 names and amount of homeless

Usage

homeless
homeless

Format

A data frame with 545 rows and 2 variables:

homeless: amount of homeless people
sa2_name_2016: name of the Statistical Area at Level 2

Read in the shape file as sf object

Description

read_shape

Usage

read_shape(shp_path, simplify = TRUE, keep = 0.1)
read_shape(shp_path, simplify = TRUE, keep = 0.1)

Arguments

`shp_path`	character vector location of shape file, extension .shp
`simplify`	a boolean to decide whether to simplify the shape file using rmapshaper, keeping all shapes.
`keep`	ratio of points to keep

Value

an sf data frame, with a column of non null geometries

Examples


# Example of how a shape file is read
if (interactive()) {
shape <- read_shape(shp_path = file.choose())
}


# Example of how a shape file is read
if (interactive()) {
shape <- read_shape(shp_path = file.choose())
}

The polygons of Tasmanian Local Government Areas in 2016.

Description

A simple features dataset containing the polygons for all Australian LGAs in 2016.

Usage

tas_lga
tas_lga

Format

A simple features data frame with 39 rows and 6 variables:

lga_code_2016: code for the Local Government Area
lga_name_2016: name of the Local Government Area
ste_code_2016: code for the state containing the Local Government Area
ste_name_2016: name of the state containing the Local Government Area
areasqkm_2016: area contained in the polygon
geometry: describes where on Earth the polygon is located

The hexagon centres for polygons of Tasmanian Local Government Areas in 2016.

Description

A tibble dataset containing the processed data for all Australian LGAs in 2016. Each point corresponds to hexagon centre.

Usage

tas_lga_hexctr
tas_lga_hexctr

Format

A simple features data frame with 39 rows and 6 variables:

lga_code_2016: code for the Local Government Area
longitude, latitude: polygon centroid
points, focal_longitude, focal_latitude, focal_dist, focal_angle: Focal point (capital city) information used for each polygon/hexagon
rownumber: row number, in case it can be useful
hex_long, hex_lat, hex_id: hexagon centre and id

The polygons of Tasmanian Statistical Areas in 2016.

Description

A simple features dataset containing the polygons for all Tasmanian SA2s in 2016.

Usage

tas_sa2
tas_sa2

Format

A simple features data frame with 99 rows and 15 variables:

sa2_main_2016: complete code of the Statistical Area
sa2_5dig_2016: simple code for the Statistical Area
sa2_name_2016: name of the Statistical Area
sa3_code_2016: code for the SA3 containing the Statistical Area
sa3_name_2016: name of the SA3 containing the Statistical Area
sa4_code_2016: code for the SA4 containing the Statistical Area
sa4_name_2016: name of the SA4 containing the Statistical Area
gcc_code_2016: code for the Greater Capital City region containing the Statistical Area
gcc_name_2016: name of the Greater Capital City region containing the Statistical Area
ste_code_2016: code for the state containing the Statistical Area
ste_name_2016: name of the state containing the Statistical Area
areasqkm_2016: area contained in the polygon
id: distinguishes SA2 regions
population: amount of people living within the region
sa2_code_2016: code of the Statistical Area

Package 'sugarbag'

Help Index

Allocate polygon centroids to hexagons in a grid

Description

Usage

Arguments

Value

Examples

The point locations of Australian capital cities.

Description

Usage

Format

For the polygon provided, find the closest focal point in the set provided

Description

Usage

Arguments

Value

Examples

Expand points to extend beyond the outermost centroids

Description

Usage

Arguments

Value

Examples

Create a data frame of longitude and latitude centroids of each polygon.

Description

Usage

Arguments

Value

Examples

Create a grid of evenly spaced points to allow hexagons to tessellate

Description

Usage

Arguments

Value

Examples

Create a tessellated hexagon map from a set of polygons

Description

Usage

Arguments

Value

Examples

Filter full set of grid points for those within range of original point

Description

Usage

Arguments

Value

Creates the points that define a hexagon polygon for plotting

Description

Usage

Arguments

Value

Examples

Convert a simple features tibble to tibble for plotting.

Description

Usage

Arguments

Value

2019 Australian Federal election data: First preference votes for candidates (House of Representatives) in each electorate.

Description

Usage

Format

geom_sugarbag

Description

Usage

Arguments

Details

See Also

Examples

The amount of homeless people in each Statistical Area at Level 2 in 2016.

Description

Usage

Format

Read in the shape file as sf object

Description

Usage

Arguments

Value

Examples

The polygons of Tasmanian Local Government Areas in 2016.