| Type: | Package |
| Title: | Streamlines the Process of Fitting Areal Spatial Models |
| Version: | 1.1.2 |
| Maintainer: | Kevin Horan <kevin.horan.2021@mumail.ie> |
| Description: | Helpers for addressing the issue of disconnected spatial units. It allows for convenient adding and removal of neighbourhood connectivity between areal units prior to modelling, with the visual aid of maps. Post-modelling, it reduces the human workload for extracting, tidying and mapping predictions from areal models. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| LazyData: | true |
| Imports: | dplyr, ggplot2, methods, purrr, sf, spdep, stats, stringr, tidyr, broom.mixed, lifecycle |
| Suggests: | mgcv, testthat (≥ 3.0.0) |
| RoxygenNote: | 7.3.2 |
| URL: | https://github.com/horankev/sfislands, https://horankev.github.io/sfislands/ |
| BugReports: | https://github.com/horankev/sfislands/issues |
| Depends: | R (≥ 4.1.0) |
| Config/Needs/website: | rmarkdown |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2025-03-02 16:43:04 UTC; kevinhoran |
| Author: | Kevin Horan  [aut,
cre, cph],
Katarina Domijan
[aut, ths],
Chris Brunsdon
[aut, ths] |
| Repository: | CRAN |
| Date/Publication: | 2025-03-03 09:50:02 UTC |
Augment dataframe with predictions of model
Description
Augment dataframe with predictions of model
Usage
st_augment(model, df)
Arguments
model |
an 'mgcv', 'lme4' or 'nlme' model. |
df |
an 'sf' data frame to be augmented with model predictions. |
Value
An augmented 'sf' data frame with extra columns showing estimates of random effects from model.
Examples
prepdata <- st_bridges(uk_election,"constituency_name")
mgcv::gam(health_not_good ~
s(constituency_name, bs='mrf', xt=list(nb=prepdata$nb), k=100),
data=prepdata, method="REML") |>
st_augment(uk_election)
Create first-order queen contiguity neighbourhood structure with additional connections when islands are present, ensuring that there are no unconnected units
Description
Create first-order queen contiguity neighbourhood structure with additional connections when islands are present, ensuring that there are no unconnected units
Usage
st_bridges(
df,
row_identifier,
remove_islands = FALSE,
link_islands_k = 1,
nb_structure = "list",
add_to_dataframe = TRUE,
threshold = 1.001,
geom_col_name = lifecycle::deprecated()
)
Arguments
df |
an 'sf' or 'sfc' object. |
row_identifier |
name of a column from 'df' containing names (or unique identifiers) for each row. |
remove_islands |
default 'FALSE'. Whether or not to omit islands from contiguity construction. |
link_islands_k |
an integer, k. The number of nearest units to which each island should be connected. |
nb_structure |
default '"list"'. Can also be '"matrix"'. The format in which to return the named contiguity structure. |
add_to_dataframe |
default 'TRUE'. Whether or not to augment existing df with contiguity output as '"nb"' column. 'FALSE' returns only the contiguity structure. |
threshold |
default 1.001. factor by which to change the size of buffer automatically generated around islands to account for imprecisions which may arise from sf::st_buffer() functionality. This can be increased if connections to islands are not occurring as expected. |
geom_col_name |
name of a column from 'df' containing names (or unique identifiers) for each row. This argument is now deprecated and the new "row_identifier" argument replaces it with the same functionality. |
Value
Either a named neighbourhood list or matrix, or an 'sf' dataframe with list or matrix included as '"nb"' column.
Examples
st_bridges(uk_election,"constituency_name")
Examine contiguity actions which have been performed on islands by 'st_bridges()'
Description
Examine contiguity actions which have been performed on islands by 'st_bridges()'
Usage
st_check_islands(data)
Arguments
data |
an 'sf' dataframe with a neighbourhood column called '"nb"' such as the output of 'st_bridges()'. |
Value
A dataframe reporting non-contiguous connections made by 'st_bridges()'.
Examples
st_bridges(uk_election,"constituency_name") |>
st_check_islands()
Remove contiguity between pairs of areas
Description
Remove contiguity between pairs of areas
Usage
st_force_cut_nb(nb, x = NULL, y = NULL, xy_df = NULL)
Arguments
nb |
a neighbourhood '"list"' or '"matrix"', or an 'sf' dataframe with a neighbourhood column called '"nb"'. |
x |
name or number of first area (optional if 'xy_df' is provided). |
y |
name or number of second area (optional if 'xy_df' is provided). |
xy_df |
(optional) a dataframe with two columns: 'x' and 'y', containing the names or numbers of areas to cut. |
Value
An amended neighbourhood '"list"', '"matrix"', or 'sf' dataframe with a neighbourhood column called '"nb"'.
Examples
# For individual x and y
st_bridges(uk_election,"constituency_name") |>
st_force_cut_nb(x = "Llanelli", y = "Swansea West")
# For multiple x and y pairs
st_bridges(uk_election,"constituency_name") |>
st_force_cut_nb(xy_df = data.frame(
x = c("Llanelli", "Swansea West"),
y = c("Bridgend", "Vale Of Glamorgan")))
Enforce contiguity between pairs of areas
Description
Enforce contiguity between pairs of areas
Usage
st_force_join_nb(nb, x = NULL, y = NULL, xy_df = NULL)
Arguments
nb |
a neighbourhood '"list"' or '"matrix"', or an 'sf' dataframe with a neighbourhood column called '"nb"'. |
x |
name or number of first area (optional if 'xy_df' is provided). |
y |
name or number of second area (optional if 'xy_df' is provided). |
xy_df |
(optional) a dataframe with two columns: 'x' and 'y', containing the names or numbers of areas to join. |
Value
An amended neighbourhood '"list"', '"matrix"', or 'sf' dataframe with a neighbourhood column called '"nb"'.
Examples
# For individual x and y
st_bridges(uk_election,"constituency_name") |>
st_force_join_nb(x = "Gower", y = "Bridgend")
# For multiple x and y pairse") |>
st_bridges(uk_election,"constituency_name") |>
st_force_join_nb(xy_df = data.frame(
x = c("Gower", "Llanelli"),
y = c("Bridgend", "Vale Of Glamorgan")))
Manual remove contiguity between two areas
Description
Manual remove contiguity between two areas
Usage
st_manual_cut_nb(nb, x, y)
Arguments
nb |
a neighbourhood '"list"' or '"matrix"', or an 'sf' dataframe with a neighbourhood column called '"nb"'. |
x |
name or number of first area. |
y |
name or number of second area. |
Value
An amended neighbourhood '"list"', '"matrix"', or 'sf' dataframe with a neighbourhood column called '"nb"'.
Examples
st_bridges(uk_election,"constituency_name") |>
st_manual_cut_nb("Ynys Mon","Arfon") |>
st_manual_cut_nb(292,378)
Manually enforce contiguity between two areas
Description
Manually enforce contiguity between two areas
Usage
st_manual_join_nb(nb, x, y)
Arguments
nb |
a neighbourhood '"list"' or '"matrix"', or an 'sf' dataframe with a neighbourhood column called '"nb"'. |
x |
name or number of first area. |
y |
name or number of second area. |
Value
An amended neighbourhood '"list"', '"matrix"', or 'sf' dataframe with a neighbourhood column called '"nb"'.
Examples
st_bridges(uk_election,"constituency_name") |>
st_manual_join_nb("Gower","St Ives")
Visualise a neighbourhood structure on a map
Description
Visualise a neighbourhood structure on a map
Usage
st_quickmap_nb(
nbsf,
linkcol = "dodgerblue",
bordercol = "gray7",
pointcol = "darkred",
fillcol = "gray95",
linksize = 0.2,
bordersize = 0.1,
pointsize = 0.8,
title = NULL,
subtitle = NULL,
nodes = "point",
numericsize = 5,
numericcol = "black",
concavehull = FALSE,
hullratio = 0.8,
hullcol = "darkgreen",
hullsize = 0.5
)
Arguments
nbsf |
an 'sf' dataframe with a neighbourhood column called "nb", such as the output of 'st_bridges()' |
linkcol |
colour of lines connecting neighbours. |
bordercol |
colour of boundary lines between areas. |
pointcol |
colour of centroid points if nodes are '"point"'. |
fillcol |
fill of areas. |
linksize |
linewidth of lines connecting neighbours. |
bordersize |
linewidth of borders between areas. |
pointsize |
size of centroid points if nodes are '"point"'. |
title |
plot title. |
subtitle |
plot subtitle. |
nodes |
default '"point"'. Can also be '"numeric"'. |
numericsize |
font size if nodes are '"numeric"'. |
numericcol |
font colour if nodes are '"numeric"'. |
concavehull |
default 'FALSE'. Whether or not to show concave hulls. |
hullratio |
value between 0 and 1. 1 returns the convex hulls, 0 maximally concave hulls. |
hullcol |
colour of concave hull lines. |
hullsize |
line width of concave hull lines. |
Value
A 'ggplot' showing areas and neighbourhood structure.
Examples
st_bridges(uk_election,"constituency_name") |>
st_quickmap_nb()
Visualise the predictions generated by the 'st_augment()' function
Description
Visualise the predictions generated by the 'st_augment()' function
Usage
st_quickmap_preds(
output,
scale_low = "firebrick4",
scale_mid = "white",
scale_high = "darkblue",
scale_midpoint = 0,
borderwidth = 0.05,
bordercol = "black",
legendlimits = "individual",
titlesize = 12,
subtitlesize = 10,
framefill = "white",
frameline = "black",
framesize = 1
)
Arguments
output |
an augmented 'sf' dataframe produced by 'st_augment()'. |
scale_low |
fill of lowest extreme of scale. |
scale_mid |
fill of midpoint of scale. |
scale_high |
fill of highest extreme of scale. |
scale_midpoint |
value of midpoint of scale. |
borderwidth |
linewidth of borders between units. |
bordercol |
colour of borders between units. |
legendlimits |
default '"individual"'. legend of each plot scaled within its own limits. '"minmax"' means all plot have common legend limits according to the global min-max. |
titlesize |
font size for title. |
subtitlesize |
font size for subtitle. |
framefill |
colour for background fill. |
frameline |
colour for frame. |
framesize |
line width of frame. |
Value
A list of ggplots.
Examples
prepdata <- st_bridges(uk_election,"constituency_name")
mgcv::gam(health_not_good ~
s(constituency_name, bs='mrf', xt=list(nb=prepdata$nb), k=100), data=prepdata, method="REML") |>
st_augment(uk_election) |>
st_quickmap_preds()
UK election data
Description
Swing and socio-economic data for England, Scotland & Wales Census and voting data sourced from parlitools R package Spatial data sourced from UK government geoportal
Usage
uk_election
Format
## 'uk_election' An sf and data.frame object with 632 rows and 9 columns
- degree_educated
Percentage of constituency population with level 4 qualifications or higher, scaled to mean 0 and standard deviation 1
- health_not_good
Percentage of constituency of population reporting health to be fair, bad, or very bad, scaled to mean 0 and standard deviation 1
- white
Percentage of constituency of population of exclusively white ethnicity, scaled to mean 0 and standard deviation 1
- con_swing
Butler swing to the Conservative Party from the Labour Party from election 2019 to election 2019
- population
Constituency population
- region
Regions
- county
Counties
- constituency_name
Westminster parliamentary constituencies, as of 2019
- geometry
sfc polygons column
...
Source
<https://geoportal.statistics.gov.uk/datasets/ons::wpc-dec-2019-ultra-generalised-clipped-boundaries-uk>, <https://docs.evanodell.com/parlitools/>