| Title: | Urban Habitat Connectivity Analysis |
|---|---|
| Description: | Analyse and visualise habitat connectivity in urban landscapes, accounting for barriers and buffer distances. Includes Shiny app for interactive analysis and report generation. Based on methods developed by Kirk et al (2023) <doi:10.1016/j.mex.2022.101989>. |
| Authors: | Nicholas Tierney [aut, cre] (ORCID: <https://orcid.org/0000-0003-1460-8722>), Holly Kirk [aut, cph] (ORCID: <https://orcid.org/0000-0002-8724-3210>) |
| Maintainer: | Nicholas Tierney <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.1.0.9000 |
| Built: | 2026-06-05 07:21:37 UTC |
| Source: | https://github.com/urbio-ecology/urbioconnect |
Adds an area layer to the raster of the area of each patch.
add_patch_area(raster)add_patch_area(raster)
raster |
terra SpatRaster. In the workflow, this is the patch ID raster. |
terra SpatRaster with two layers: patch_id and area.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered_habitat <- habitat_buffer(lizard_habitat, 5) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) fragment_patches <- assign_patches_to_fragments( remaining_habitat = remaining_habitat, fragment = fragmented ) library(terra) add_patch_area(fragment_patches)lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered_habitat <- habitat_buffer(lizard_habitat, 5) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) fragment_patches <- assign_patches_to_fragments( remaining_habitat = remaining_habitat, fragment = fragmented ) library(terra) add_patch_area(fragment_patches)
Aggregate a raster with connected patch areas into a data frame where each row is a unique patch, and its area and area squared.
aggregate_connected_patches(raster)aggregate_connected_patches(raster)
raster |
terra SpatRaster. Raster with patch_id and area layers. |
Data frame with patch areas and areas squared.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered_habitat <- habitat_buffer(lizard_habitat, 5) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) fragment_patches <- assign_patches_to_fragments( remaining_habitat = remaining_habitat, fragment = fragmented ) library(terra) patch_areas <- add_patch_area(fragment_patches) aggregate_connected_patches(patch_areas)lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered_habitat <- habitat_buffer(lizard_habitat, 5) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) fragment_patches <- assign_patches_to_fragments( remaining_habitat = remaining_habitat, fragment = fragmented ) library(terra) patch_areas <- add_patch_area(fragment_patches) aggregate_connected_patches(patch_areas)
Assign patches to fragments
assign_patches_to_fragments(remaining_habitat, fragment)assign_patches_to_fragments(remaining_habitat, fragment)
remaining_habitat |
Terra SpatRaster. Remaining habitat. |
fragment |
Terra SpatRaster. Fragment geometry. |
Terra SpatRaster with patch IDs.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered_habitat <- habitat_buffer(lizard_habitat, 5) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) fragment_patches <- assign_patches_to_fragments( remaining_habitat = remaining_habitat, fragment = fragmented ) library(terra) plot(fragment_patches)lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered_habitat <- habitat_buffer(lizard_habitat, 5) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) fragment_patches <- assign_patches_to_fragments( remaining_habitat = remaining_habitat, fragment = fragmented ) library(terra) plot(fragment_patches)
Many shape files contain errors, places where the edges of a polygon cross over or polygons which overlap. This helps remove some of those errors by smoothing the edges of polygons, removing corners, and dissolving edges where polygons overlap. This reduces the complexity of the shape file, making future steps faster.
clean(spatial_data, ...)clean(spatial_data, ...)
spatial_data |
spatial data frame from sf. |
... |
extra options (currently not used) |
An sf object with simplified and validated geometry.
lizard_barrier_shp <- example_barrier_shp() clean(lizard_barrier_shp)lizard_barrier_shp <- example_barrier_shp() clean(lizard_barrier_shp)
Convert color name to hexadecimal
col2hex(color_name)col2hex(color_name)
color_name |
Character. Color name recognized by R. |
Character. Hexadecimal color code.
col2hex("forestgreen") col2hex("blue")col2hex("forestgreen") col2hex("blue")
We can measure the connectivity of a given habitat and barrier with
habitat_connectivity(). We can also compare the connectivity, say for
example if you have the same area habitat and barrier, but you want to
understand what the change in connectedness is when you remove, or add
some habitat, or some barrier(s), or both. This function help you do that.
compare_connectivity(area_new, area_baseline, interpatch_distance, species)compare_connectivity(area_new, area_baseline, interpatch_distance, species)
area_new |
Numeric vector. Area of a connected patch. |
area_baseline |
Numeric vector. Baseline area of a connected patch. |
interpatch_distance |
Numeric. The distance (in meters) where habitat
patches are considered connected. E.g., if set to 500, patches 498m apart
are connected, those 501m apart are not connected. This is passed
internally to a spatial operation known as "buffering", where this
distance is used as a radius from the edge of the habitat zone. This means
the specified |
species |
name of species |
tibble with "scenario", "interpatch_distance", "species", "n_patches", "effective_mesh_ha", and "prob_connectedness".
# for demonstration purposes - let's imagine the area decreases by 20% baseline_areas <- round(lizard_areas_connected$area) new_areas <- baseline_areas[-1] * 0.8 compare_connectivity( area_new = new_areas, area_baseline = baseline_areas, interpatch_distance = 10, species = "blue-tongued lizard" )# for demonstration purposes - let's imagine the area decreases by 20% baseline_areas <- round(lizard_areas_connected$area) new_areas <- baseline_areas[-1] * 0.8 compare_connectivity( area_new = new_areas, area_baseline = baseline_areas, interpatch_distance = 10, species = "blue-tongued lizard" )
Computes the probability two randomly chosen points within habitat
are connected, accounting for fragmentation. This requires the effective
mesh size (via effective_mesh_size()), and the area of patches. This means
that you can calculate the change in connectivity if you calculate the
effective mesh size of a new habitat/barrier plan, and then use the baseline
connectivity_probability(effective_mesh_size, area_baseline)connectivity_probability(effective_mesh_size, area_baseline)
effective_mesh_size |
As calculated by |
area_baseline |
Numeric vector. Area of a connected patch. This argument is called "baseline" as when you are doing design scenarios you must refer to the baseline area when calculating connectivity probability. See vignette, TODO. |
Numeric. Probability of connectedness (0-1).
effective_mesh <- effective_mesh_size( area = lizard_areas_connected$area ) connectivity_probability( effective_mesh_size = effective_mesh, area_baseline = lizard_areas_connected$area ) # if you wanted to compare to a scenario, you would consider the effective # mesh size to be the new scenario level, and the baseline as so: connectivity_probability( # scenario 1 effective_mesh_size = effective_mesh, area_baseline = lizard_areas_connected$area )effective_mesh <- effective_mesh_size( area = lizard_areas_connected$area ) connectivity_probability( effective_mesh_size = effective_mesh, area_baseline = lizard_areas_connected$area ) # if you wanted to compare to a scenario, you would consider the effective # mesh size to be the new scenario level, and the baseline as so: connectivity_probability( # scenario 1 effective_mesh_size = effective_mesh, area_baseline = lizard_areas_connected$area )
Converts a barrier layer into a multiplier mask for connectivity analysis. Takes a raster where barriers are coded as 1 (and non-barriers as NA), and inverts it to produce a mask with NA values where barriers exist and 1 elsewhere. This format allows barriers to be applied by multiplying the mask with connectivity surfaces, effectively blocking movement through barrier cells.
create_barrier_mask(barrier)create_barrier_mask(barrier)
barrier |
Terra SpatRaster. Barrier layer with 1 = barrier, NA = no barrier. |
Terra SpatRaster. Mask with 1 where movement is allowed, NA where barriers exist.
lizard_barrier <- example_barrier() create_barrier_mask(lizard_barrier)lizard_barrier <- example_barrier() create_barrier_mask(lizard_barrier)
Essentially just performs a terra::mask() operation, to remove the habitat
parts that are under the mask.
drop_habitat_under_barrier(habitat, barrier_mask)drop_habitat_under_barrier(habitat, barrier_mask)
habitat |
Terra SpatRaster. Habitat layer. |
barrier_mask |
Terra SpatRaster. Barrier mask. |
Terra SpatRaster with habitat remaining after barrier removal.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() barrier_mask <- create_barrier_mask(lizard_barrier) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) remaining_habitatlizard_habitat <- example_habitat() lizard_barrier <- example_barrier() barrier_mask <- create_barrier_mask(lizard_barrier) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) remaining_habitat
Computes the effective mesh size metric for habitat connectivity, This
represents the probability that two randomly chosen points within habitat
remain connected. Intended for usage from objects created by
habitat_connectivity(). See examples below.
effective_mesh_size(area, area_baseline = area)effective_mesh_size(area, area_baseline = area)
area |
Numeric vector. Area of connected patches. |
area_baseline |
Optional. Defaults to |
Numeric. Effective mesh size, in hectares.
effective_mesh_size(lizard_areas_connected$area)effective_mesh_size(lizard_areas_connected$area)
Create Empty terra raster grid
empty_grid(habitat, resolution = 10)empty_grid(habitat, resolution = 10)
habitat |
SF object or terra SpatRaster. |
resolution |
Numeric. Cell size in meters (default: 10). |
Terra SpatRaster. Empty raster grid.
lizard_barrier_shp <- example_barrier_shp() empty_grid(lizard_barrier_shp, resolution = 10)lizard_barrier_shp <- example_barrier_shp() empty_grid(lizard_barrier_shp, resolution = 10)
We provide Habitat and Barrier data on various lizard species (nominally, Blue-tongued Lizard). The data was collected from Darebin Creek in Melbourne, which runs between Preston and West Heidelberg. For analysis purposes, a interpatch distance of 200 metres is recommended for lizard connectivity assessments.
example_habitat() example_barrier_shp() example_barrier()example_habitat() example_barrier_shp() example_barrier()
We provide helper functions to load the raster and shapefile data. These are required due to how the raster and vector data are stored. These functions provide easy access to example raster and shapefile data included with the package:
example_habitat() Returns a raster of lizard habitat data.
example_barrier_shp() Returns a shapefile of lizard barrier data as
an SF object.
example_barrier() Returns a raster of lizard barrier data.
A terra raster object or sf object depending on the function called
library(terra) # Load habitat raster lizard_habitat <- example_habitat() plot(lizard_habitat, col = "darkgreen", legend = FALSE, main = "Lizard Habitat") # Load barrier shapefile lizard_barrier_shp <- example_barrier_shp() plot(lizard_barrier_shp) # Load barrier raster lizard_barrier <- example_barrier() plot(lizard_barrier, col = c("grey", "white"), legend = FALSE, main = "Lizard Barriers") plot(lizard_barrier, col = c("grey", "white"), legend = FALSE, main = "Lizard Habitat and Barrier") plot(lizard_habitat, col = "darkgreen", legend = FALSE, add = TRUE)library(terra) # Load habitat raster lizard_habitat <- example_habitat() plot(lizard_habitat, col = "darkgreen", legend = FALSE, main = "Lizard Habitat") # Load barrier shapefile lizard_barrier_shp <- example_barrier_shp() plot(lizard_barrier_shp) # Load barrier raster lizard_barrier <- example_barrier() plot(lizard_barrier, col = c("grey", "white"), legend = FALSE, main = "Lizard Barriers") plot(lizard_barrier, col = c("grey", "white"), legend = FALSE, main = "Lizard Habitat and Barrier") plot(lizard_habitat, col = "darkgreen", legend = FALSE, add = TRUE)
Takes a barrier mask (created with create_barrier_mask()) and fragments
up the habitat where they intersect.
fragment_habitat(buffered_habitat, barrier_mask)fragment_habitat(buffered_habitat, barrier_mask)
buffered_habitat |
Terra SpatRaster. Buffered habitat. |
barrier_mask |
Terra SpatRaster. Barrier mask. |
Terra SpatRaster with fragmented habitat.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered_habitat <- habitat_buffer(lizard_habitat, 5) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask)lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered_habitat <- habitat_buffer(lizard_habitat, 5) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask)
Creates a parameterised Quarto report from connectivity analysis results.
generate_connectivity_report( species_name, interpatch_distances, results_connect_habitat, areas_connected, habitat = NULL, barrier = NULL, habitat_raster = NULL, data_resolution = 10, target_resolution = 500, output_file = NULL, output_format = c("html", "pdf", "both"), output_dir = getwd() )generate_connectivity_report( species_name, interpatch_distances, results_connect_habitat, areas_connected, habitat = NULL, barrier = NULL, habitat_raster = NULL, data_resolution = 10, target_resolution = 500, output_file = NULL, output_format = c("html", "pdf", "both"), output_dir = getwd() )
species_name |
Character. Name of the species being analysed. |
interpatch_distances |
Numeric. The distances (in meters) where habitat
patches are considered connected. E.g., if set to 500, patches 498m apart
are connected, those 501m apart are not connected. This is passed
internally to a spatial operation known as "buffering", where this
distance is used as a radius from the edge of the habitat zone. This means
the specified |
results_connect_habitat |
Data frame. Connectivity summary results. |
areas_connected |
List of data frames. Connected patch areas for each interpatch distance. |
habitat |
SF object. Habitat spatial data (optional, for mapping). |
barrier |
SF object. Barrier spatial data (optional, for mapping). |
habitat_raster |
Terra SpatRaster. Habitat raster (optional, for mapping). |
data_resolution |
Numeric. Data resolution in meters. |
target_resolution |
Numeric. Target resolution in meters. |
output_file |
Character. Output filename (without extension). |
output_format |
Character. Output format: "html" (default), "pdf", or "both". |
output_dir |
Character. Directory to save the report (default: current directory). |
Character vector of generated report file path(s).
## Not run: report_path <- generate_connectivity_report( species_name = "Superb Fairy Wren", interpatch_distances = c(100, 250, 400), results_connect_habitat = results_df, areas_connected = patches_list, output_format = "html" ) ## End(Not run)## Not run: report_path <- generate_connectivity_report( species_name = "Superb Fairy Wren", interpatch_distances = c(100, 250, 400), results_connect_habitat = results_df, areas_connected = patches_list, output_format = "html" ) ## End(Not run)
Creates a visualisation of habitat, interpatch distance zone, and barriers using terra rasters.
gg_barrier_habitat_interpatch_dist( barrier, buffered, habitat, interpatch_distance, species, col_barrier, col_interpatch_dist, col_habitat, col_paper = NA )gg_barrier_habitat_interpatch_dist( barrier, buffered, habitat, interpatch_distance, species, col_barrier, col_interpatch_dist, col_habitat, col_paper = NA )
barrier |
Terra SpatRaster. Barrier layer (e.g., roads). |
buffered |
Terra SpatRaster. Buffered habitat layer. |
habitat |
Terra SpatRaster. Original habitat layer. |
interpatch_distance |
Numeric. The distance (in meters) where habitat
patches are considered connected. E.g., if set to 500, patches 498m apart
are connected, those 501m apart are not connected. This is passed
internally to a spatial operation known as "buffering", where this
distance is used as a radius from the edge of the habitat zone. This means
the specified |
species |
Character. Species name for plot title. |
col_barrier |
Character. Color for barrier layer. |
col_interpatch_dist |
Character. Color for interpatch distance zone. |
col_habitat |
Character. Color for habitat patches. |
col_paper |
Character. Background color (default: "white"). |
A ggplot2 object.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() lizard_buffered <- habitat_buffer(lizard_habitat, buffer_radius =10) gg_bar_hab_buf <- gg_barrier_habitat_interpatch_dist( barrier = lizard_barrier, buffered = lizard_buffered, habitat = lizard_habitat, interpatch_distance = 10, species = "Blue Tongue Lizard", col_barrier = "black", col_interpatch_dist = "lightgreen", col_habitat = "seagreen" ) gg_bar_hab_buf # add north arrow and scale bar with ggspatial library(ggspatial) library(tidyterra) gg_bar_hab_buf + annotation_north_arrow( style = north_arrow_fancy_orienteering() ) + annotation_scale()lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() lizard_buffered <- habitat_buffer(lizard_habitat, buffer_radius =10) gg_bar_hab_buf <- gg_barrier_habitat_interpatch_dist( barrier = lizard_barrier, buffered = lizard_buffered, habitat = lizard_habitat, interpatch_distance = 10, species = "Blue Tongue Lizard", col_barrier = "black", col_interpatch_dist = "lightgreen", col_habitat = "seagreen" ) gg_bar_hab_buf # add north arrow and scale bar with ggspatial library(ggspatial) library(tidyterra) gg_bar_hab_buf + annotation_north_arrow( style = north_arrow_fancy_orienteering() ) + annotation_scale()
Buffer around the habitat a given distance in metres using
terra::focalMat(d = buffer_radius, type = "circle"). This operation is
used to identify connected patches of habitat. Two patches will connect
when their edge-to-edge gap is <= 2 * buffer radius. So, we recommend
you specify the buffer_radius value to be half the interpatch distance,
which is the distance past which habitat patches are no longer considered
connected. For example, if your interpatch distance is 500m, set
buffer_radius = 250.
habitat_buffer(habitat, buffer_radius)habitat_buffer(habitat, buffer_radius)
habitat |
Terra SpatRaster. Habitat raster. |
buffer_radius |
Numeric. The radius in metres around the habitat.
Since patches of habitat will be connected when their edge-to-edge gap is
<= 2 * |
Terra SpatRaster with buffered habitat.
vignette("interpatch-distance-and-resolution") for the
relationship between interpatch distance, buffer radius, and resolution.
lizard_habitat <- example_habitat() library(terra) plot(lizard_habitat, col = "darkgreen", legend = FALSE) # run with a small buffer radius lizard_buff <- habitat_buffer(lizard_habitat, buffer_radius = 10) plot(lizard_buff, col = "lightgreen", legend = FALSE) plot(lizard_habitat, col = "darkgreen", legend = FALSE, add = TRUE)lizard_habitat <- example_habitat() library(terra) plot(lizard_habitat, col = "darkgreen", legend = FALSE) # run with a small buffer radius lizard_buff <- habitat_buffer(lizard_habitat, buffer_radius = 10) plot(lizard_buff, col = "lightgreen", legend = FALSE) plot(lizard_habitat, col = "darkgreen", legend = FALSE, add = TRUE)
This performs the entire connectivity workflow, returning a dataframe output. The steps are:
create_barrier_mask(): Creating barrier mask.
drop_habitat_under_barrier(): Removes Habitat underneath barrier.
habitat_buffer(): Buffers the habitat layer by the interpatch distance (m).
fragment_habitat(): Fragments habitat layer along barrier intersection.
assign_patches_to_fragments(): Assign patch ID to fragments.
aggregate_connected_patches(): Summarise area in each patch.
habitat_connectivity( habitat, barrier, interpatch_distance = NULL, buffer_radius = NULL, verbose = TRUE )habitat_connectivity( habitat, barrier, interpatch_distance = NULL, buffer_radius = NULL, verbose = TRUE )
habitat |
Terra SpatRaster. Habitat raster. |
barrier |
Terra SpatRaster. Barrier raster. |
interpatch_distance |
Numeric. The distance (in meters) where habitat
patches are considered connected. E.g., if set to 500, patches 498m apart
are connected, those 501m apart are not connected. This is passed
internally to a spatial operation known as "buffering", where this
distance is used as a radius from the edge of the habitat zone. This means
the specified |
buffer_radius |
Numeric. The radius in metres around the habitat.
Since patches of habitat will be connected when their edge-to-edge gap is
<= 2 * |
verbose |
Logical. Display progress messages (default: TRUE). |
Data frame with connectivity metrics per patch.
vignette("interpatch-distance-and-resolution") for the
relationship between interpatch distance, buffer radius, and resolution.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() connectivity <- habitat_connectivity( habitat = lizard_habitat, barrier = lizard_barrier, interpatch_distance = 10 ) connectivitylizard_habitat <- example_habitat() lizard_barrier <- example_barrier() connectivity <- habitat_connectivity( habitat = lizard_habitat, barrier = lizard_barrier, interpatch_distance = 10 ) connectivity
Like habitat_connectivity(), but also returns the intermediate rasters
(buffered habitat, patch ID raster, barrier mask, remaining habitat) useful
for mapping and reporting.
habitat_connectivity_full( habitat, barrier, interpatch_distance = NULL, buffer_radius = NULL, verbose = TRUE )habitat_connectivity_full( habitat, barrier, interpatch_distance = NULL, buffer_radius = NULL, verbose = TRUE )
habitat |
Terra SpatRaster. Habitat raster. |
barrier |
Terra SpatRaster. Barrier raster. |
interpatch_distance |
Numeric. The distance (in meters) where habitat
patches are considered connected. E.g., if set to 500, patches 498m apart
are connected, those 501m apart are not connected. This is passed
internally to a spatial operation known as "buffering", where this
distance is used as a radius from the edge of the habitat zone. This means
the specified |
buffer_radius |
Numeric. The radius in metres around the habitat.
Since patches of habitat will be connected when their edge-to-edge gap is
<= 2 * |
verbose |
Logical. Display progress messages (default: TRUE). |
Named list with elements: buffered_habitat, patch_id_raster,
areas_connected, barrier_mask, remaining_habitat.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() result <- habitat_connectivity_full( lizard_habitat, lizard_barrier, interpatch_distance = 10, verbose = FALSE ) names(result)lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() result <- habitat_connectivity_full( lizard_habitat, lizard_barrier, interpatch_distance = 10, verbose = FALSE ) names(result)
Pre-computed output of habitat_connectivity() run on the lizard example
data at a 50 metre interpatch distance. Contains one row per connected
habitat patch.
lizard_areas_connected lizard_areas_connectedlizard_areas_connected lizard_areas_connected
A data frame with columns:
Integer. Connected fragment ID.
Numeric. Total area of the connected patch in square metres.
Numeric. Squared area, used in connectivity metrics.
An object of class tbl_df (inherits from tbl, data.frame) with 59 rows and 3 columns.
Generated from example_habitat() and example_barrier() at
50 metre interpatch distance.
habitat_connectivity(), summarise_connectivity()
# This was the code that was run to create this object. We don't run it # as it takes some time to run ## Not run: lizard_areas_connected <- habitat_connectivity( habitat = example_habitat(), barrier = example_barrier(), interpatch_distance = 50, verbose = FALSE ) ## End(Not run) lizard_areas_connected# This was the code that was run to create this object. We don't run it # as it takes some time to run ## Not run: lizard_areas_connected <- habitat_connectivity( habitat = example_habitat(), barrier = example_barrier(), interpatch_distance = 50, verbose = FALSE ) ## End(Not run) lizard_areas_connected
This is just a wrapper around mean(), however it is written to clearly
identify it's usage in the context of the area data. Intended for usage
from objects created by habitat_connectivity(). See examples below.
mean_patch_size(area, ...)mean_patch_size(area, ...)
area |
Numeric vector. Area of a connected patch. |
... |
extra arguments to pass to |
Numeric. Mean patch size.
mean_patch_size(lizard_areas_connected$area)mean_patch_size(lizard_areas_connected$area)
Identify the number of habitat patches. A wrapper around length(), but
named to establish its context. Intended for usage from objects created by
habitat_connectivity(). See examples below.
n_patches(area)n_patches(area)
area |
Numeric vector. Area of a connected patch. |
Integer. Number of patches.
n_patches(lizard_areas_connected$area)n_patches(lizard_areas_connected$area)
Saved a plot created by gg_barrier_habitat_interpatch_dist() to file.
plot_barrier_habitat_interpatch_dist( barrier, buffered, habitat, interpatch_distance, species, col_barrier, col_interpatch_dist, col_habitat, col_paper )plot_barrier_habitat_interpatch_dist( barrier, buffered, habitat, interpatch_distance, species, col_barrier, col_interpatch_dist, col_habitat, col_paper )
barrier |
barrier layer |
buffered |
buffered layer |
habitat |
habitat layer |
interpatch_distance |
Numeric. The distance (in meters) where habitat
patches are considered connected. E.g., if set to 500, patches 498m apart
are connected, those 501m apart are not connected. This is passed
internally to a spatial operation known as "buffering", where this
distance is used as a radius from the edge of the habitat zone. This means
the specified |
species |
character, species name, e.g., "Superb Fairy Wren" |
col_barrier |
colour to colour the barrier layer |
col_interpatch_dist |
colour to colour the interpatch distance layer |
col_habitat |
colour to colour the habitat layer |
col_paper |
colour to colour the paper layer of ggplot |
Named character vector. The file path, named by the interpatch distance.
## Not run: lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered <- habitat_buffer(lizard_habitat, interpatch_distance = 10) # Creates plot-barrier-interpatch-dist-habitat-*.png in the working directory plot_barrier_habitat_interpatch_dist( barrier = lizard_barrier, buffered = buffered, habitat = lizard_habitat, interpatch_distance = 10, species = "Blue-tongued Lizard", col_barrier = "white", col_interpatch_dist = "lightgreen", col_habitat = "seagreen", col_paper = "grey50" ) ## End(Not run)## Not run: lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() buffered <- habitat_buffer(lizard_habitat, interpatch_distance = 10) # Creates plot-barrier-interpatch-dist-habitat-*.png in the working directory plot_barrier_habitat_interpatch_dist( barrier = lizard_barrier, buffered = buffered, habitat = lizard_habitat, interpatch_distance = 10, species = "Blue-tongued Lizard", col_barrier = "white", col_interpatch_dist = "lightgreen", col_habitat = "seagreen", col_paper = "grey50" ) ## End(Not run)
Creates faceted line plots showing how connectivity metrics change with different interpatch distances. This works best when you have multiple interpatch distances, otherwise it will just be a plot with one point.
plot_connectivity(results_connect_habitat)plot_connectivity(results_connect_habitat)
results_connect_habitat |
Data frame. Connectivity summary results with columns for species, interpatch distance, and various metrics. |
A ggplot2 object with faceted plots of connectivity metrics.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() results <- purrr::map( c(10, 20), function(d) { full <- habitat_connectivity_full(lizard_habitat, lizard_barrier, interpatch_distance = d, verbose = FALSE) summarise_connectivity( area = full$areas_connected$area, interpatch_distance = d, target_resolution = 500, data_resolution = 10, aggregation_factor = 50, species = "Blue-tongued Lizard" ) } ) |> purrr::list_rbind() plot_connectivity(results)lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() results <- purrr::map( c(10, 20), function(d) { full <- habitat_connectivity_full(lizard_habitat, lizard_barrier, interpatch_distance = d, verbose = FALSE) summarise_connectivity( area = full$areas_connected$area, interpatch_distance = d, target_resolution = 500, data_resolution = 10, aggregation_factor = 50, species = "Blue-tongued Lizard" ) } ) |> purrr::list_rbind() plot_connectivity(results)
Visualizes habitat patches colored by their connected fragment ID.
plot_patches(patch_id, interpatch_distance, species = "Species", n_cols = 7)plot_patches(patch_id, interpatch_distance, species = "Species", n_cols = 7)
patch_id |
Terra SpatRaster. Raster with patch IDs. |
interpatch_distance |
Numeric. The distance (in meters) where habitat
patches are considered connected. E.g., if set to 500, patches 498m apart
are connected, those 501m apart are not connected. This is passed
internally to a spatial operation known as "buffering", where this
distance is used as a radius from the edge of the habitat zone. This means
the specified |
species |
Character. Species name (default: "Species"). |
n_cols |
Integer. Number of colors to cycle through (default: 7). |
A ggplot2 object showing patches with distinct colors.
lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() interpatch_distance <- 20 buffer_radius <- interpatch_distance / 2 buffered_habitat <- habitat_buffer(lizard_habitat, buffer_radius) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) fragment_patches <- assign_patches_to_fragments( remaining_habitat = remaining_habitat, fragment = fragmented ) |> add_patch_area() plot_patches(fragment_patches, interpatch_distance = interpatch_distance) #' add north arrow and scale bar with ggspatial library(ggspatial) library(tidyterra) plot_patches(fragment_patches, interpatch_distance = interpatch_distance) + annotation_north_arrow( style = north_arrow_fancy_orienteering() ) + annotation_scale()lizard_habitat <- example_habitat() lizard_barrier <- example_barrier() interpatch_distance <- 20 buffer_radius <- interpatch_distance / 2 buffered_habitat <- habitat_buffer(lizard_habitat, buffer_radius) barrier_mask <- create_barrier_mask(lizard_barrier) fragmented <- fragment_habitat(buffered_habitat, barrier_mask) remaining_habitat <- drop_habitat_under_barrier( habitat = lizard_habitat, barrier = lizard_barrier ) fragment_patches <- assign_patches_to_fragments( remaining_habitat = remaining_habitat, fragment = fragmented ) |> add_patch_area() plot_patches(fragment_patches, interpatch_distance = interpatch_distance) #' add north arrow and scale bar with ggspatial library(ggspatial) library(tidyterra) plot_patches(fragment_patches, interpatch_distance = interpatch_distance) + annotation_north_arrow( style = north_arrow_fancy_orienteering() ) + annotation_scale()
Convert vector (shapefile) SF habitat and barrier objects into rasters.
prepare_rasters( habitat, barrier, data_resolution = 10, target_resolution = 500 )prepare_rasters( habitat, barrier, data_resolution = 10, target_resolution = 500 )
habitat |
SF object. Habitat spatial data. |
barrier |
SF object. Barrier spatial data. |
data_resolution |
Numeric. Fine resolution in meters. Default, 10. |
target_resolution |
Numeric. Coarse resolution in meters. Default, 500. |
List with habitat_raster and barrier_raster elements.
lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() prepare_rasters(lizard_habitat_sf, lizard_barrier_shp)lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() prepare_rasters(lizard_habitat_sf, lizard_barrier_shp)
Reads a shapefile and extracts only the spatial geometry, discarding attribute data.
read_geometry(shapefile) ## S3 method for class 'sf' read_geometry(shapefile) ## Default S3 method: read_geometry(shapefile)read_geometry(shapefile) ## S3 method for class 'sf' read_geometry(shapefile) ## Default S3 method: read_geometry(shapefile)
shapefile |
Character. File path to a shapefile, or an SF object. |
An sfc object containing only the spatial geometry.
# Read geometry from a file path barrier_path <- system.file("ex/lizard_barrier.shp", package = "urbioconnect") barrier_geom <- read_geometry(barrier_path) # Can also pass an existing SF object barrier_sf <- sf::st_read(barrier_path, quiet = TRUE) barrier_geom <- read_geometry(barrier_sf)# Read geometry from a file path barrier_path <- system.file("ex/lizard_barrier.shp", package = "urbioconnect") barrier_geom <- read_geometry(barrier_path) # Can also pass an existing SF object barrier_sf <- sf::st_read(barrier_path, quiet = TRUE) barrier_geom <- read_geometry(barrier_sf)
Launches the connectivity analysis Shiny application.
run_connectivity_app()run_connectivity_app()
No return value, called for side effects (launches Shiny app)
## Not run: run_connectivity_app() ## End(Not run)## Not run: run_connectivity_app() ## End(Not run)
Add patch area column
sf_add_patch_area(patches)sf_add_patch_area(patches)
patches |
SF object. Habitat patches. |
SF object with added area column in square meters.
lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() ## Not run: lizard_barrier_shp <- example_barrier_shp() buffered <- sf_habitat_buffer(lizard_habitat_sf, buffer_radius = 10) fragments <- sf_fragment_habitat(buffered, lizard_barrier_shp) remaining <- sf_drop_habitat_under_barrier(lizard_habitat_sf, lizard_barrier_shp) patches <- sf_assign_patches_to_fragments(remaining, fragments) sf_add_patch_area(patches) ## End(Not run)lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() ## Not run: lizard_barrier_shp <- example_barrier_shp() buffered <- sf_habitat_buffer(lizard_habitat_sf, buffer_radius = 10) fragments <- sf_fragment_habitat(buffered, lizard_barrier_shp) remaining <- sf_drop_habitat_under_barrier(lizard_habitat_sf, lizard_barrier_shp) patches <- sf_assign_patches_to_fragments(remaining, fragments) sf_add_patch_area(patches) ## End(Not run)
Groups habitat patches by their connected fragment ID and calculates total and squared areas for connectivity metrics.
sf_aggregate_connected_patches(patch_areas)sf_aggregate_connected_patches(patch_areas)
patch_areas |
SF object. Habitat patches with area column. |
Data frame with patch_id, area, and area_squared columns.
lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() ## Not run: buffered <- sf_habitat_buffer(lizard_habitat_sf, buffer_radius = 10) fragments <- sf_fragment_habitat(buffered, lizard_barrier_shp) remaining <- sf_drop_habitat_under_barrier(lizard_habitat_sf, lizard_barrier_shp) patches <- sf_assign_patches_to_fragments(remaining, fragments) |> sf_add_patch_area() sf_aggregate_connected_patches(patches) ## End(Not run)lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() ## Not run: buffered <- sf_habitat_buffer(lizard_habitat_sf, buffer_radius = 10) fragments <- sf_fragment_habitat(buffered, lizard_barrier_shp) remaining <- sf_drop_habitat_under_barrier(lizard_habitat_sf, lizard_barrier_shp) patches <- sf_assign_patches_to_fragments(remaining, fragments) |> sf_add_patch_area() sf_aggregate_connected_patches(patches) ## End(Not run)
Determines which connected fragment each remaining habitat patch belongs to based on spatial intersection.
sf_assign_patches_to_fragments(remaining, fragment_id)sf_assign_patches_to_fragments(remaining, fragment_id)
remaining |
SF object. Remaining habitat patches after barrier removal. |
fragment_id |
SF object. Fragment geometries with IDs. |
SF object with habitat patches labeled by their fragment ID.
lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() ## Not run: buffered <- sf_habitat_buffer(lizard_habitat_sf, buffer_radius = 10) fragments <- sf_fragment_habitat(buffered, lizard_barrier_shp) remaining <- sf_drop_habitat_under_barrier(lizard_habitat_sf, lizard_barrier_shp) sf_assign_patches_to_fragments(remaining, fragments) ## End(Not run)lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() ## Not run: buffered <- sf_habitat_buffer(lizard_habitat_sf, buffer_radius = 10) fragments <- sf_fragment_habitat(buffered, lizard_barrier_shp) remaining <- sf_drop_habitat_under_barrier(lizard_habitat_sf, lizard_barrier_shp) sf_assign_patches_to_fragments(remaining, fragments) ## End(Not run)
Removes all habitat areas that intersect with barriers and splits multipolygons into individual patches.
sf_drop_habitat_under_barrier(habitat, barrier)sf_drop_habitat_under_barrier(habitat, barrier)
habitat |
SF object. Original habitat geometry. |
barrier |
SF object. Barrier geometry. |
SF object with habitat patches that don't intersect barriers.
lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() sf_drop_habitat_under_barrier(lizard_habitat_sf, lizard_barrier_shp)lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() sf_drop_habitat_under_barrier(lizard_habitat_sf, lizard_barrier_shp)
Removes barrier areas from buffered habitat and splits the result into individual polygon fragments.
sf_fragment_habitat(habitat_buffered, barrier)sf_fragment_habitat(habitat_buffered, barrier)
habitat_buffered |
SF object. Buffered habitat geometry. |
barrier |
SF object. Barrier geometry (e.g., roads). |
SF object with individual habitat fragments, each with a unique ID.
lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() ## Not run: buffered <- sf_habitat_buffer(lizard_habitat_sf, interpatch_distance = 10) sf_fragment_habitat(buffered, lizard_barrier_shp) ## End(Not run)lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() lizard_barrier_shp <- example_barrier_shp() ## Not run: buffered <- sf_habitat_buffer(lizard_habitat_sf, interpatch_distance = 10) sf_fragment_habitat(buffered, lizard_barrier_shp) ## End(Not run)
Creates a buffer around habitat polygons and unions overlapping areas into
a single polygon, using sf::st_buffer(). Unlike the raster
habitat_buffer(), this works in continuous coordinate space, so there is
no resolution constraint: any buffer_radius produces an exact buffer
and the sub-cell "no buffer" problem of the raster path does not apply. The
buffer arc is approximated by nQuadSegs straight segments per quarter
circle (here 5, i.e. a 20-sided polygon), which affects the smoothness of
the outline, not whether the buffer forms. See
vignette("interpatch-distance-and-resolution").
sf_habitat_buffer(habitat, buffer_radius)sf_habitat_buffer(habitat, buffer_radius)
habitat |
SF object. Habitat spatial data. |
buffer_radius |
Numeric. The radius in metres around the habitat.
Specify it as half the interpatch distance (see |
SF object with buffered and unioned habitat geometry.
lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() ## Not run: sf_habitat_buffer(lizard_habitat_sf, buffer_radius = 10) ## End(Not run)lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() ## Not run: sf_habitat_buffer(lizard_habitat_sf, buffer_radius = 10) ## End(Not run)
Performs complete habitat connectivity analysis using vector-based spatial operations. Buffers habitat, fragments it along barriers, and calculates areas of connected patches.
sf_habitat_connectivity( habitat, barrier, interpatch_distance = NULL, buffer_radius = NULL )sf_habitat_connectivity( habitat, barrier, interpatch_distance = NULL, buffer_radius = NULL )
habitat |
SF object. Original habitat spatial data. |
barrier |
SF object. Barrier spatial data (e.g., roads, waterways). |
interpatch_distance |
Numeric. The distance (in meters) where habitat
patches are considered connected. E.g., if set to 500, patches 498m apart
are connected, those 501m apart are not connected. This is passed
internally to a spatial operation known as "buffering", where this
distance is used as a radius from the edge of the habitat zone. This means
the specified |
buffer_radius |
Numeric. The radius in metres around the habitat.
Since patches of habitat will be connected when their edge-to-edge gap is
<= 2 * |
Data frame with connectivity metrics for each connected patch,
including patch_id, area, and area_squared.
lizard_barrier_shp <- example_barrier_shp() lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() result <- sf_habitat_connectivity(lizard_habitat_sf, lizard_barrier_shp, interpatch_distance = 10) resultlizard_barrier_shp <- example_barrier_shp() lizard_habitat_sf <- terra::as.polygons(example_habitat(), dissolve = TRUE) |> sf::st_as_sf() result <- sf_habitat_connectivity(lizard_habitat_sf, lizard_barrier_shp, interpatch_distance = 10) result
Calculates a comprehensive set of habitat connectivity metrics including
effective mesh size, probability of connectedness, and patch statistics.
Intended for usage from objects created by habitat_connectivity().
See examples below.
summarise_connectivity( area, area_baseline = NULL, interpatch_distance, target_resolution, data_resolution, aggregation_factor, species )summarise_connectivity( area, area_baseline = NULL, interpatch_distance, target_resolution, data_resolution, aggregation_factor, species )
area |
Numeric vector. Areas of connected patches. |
area_baseline |
Numeric vector. Areas of connected patch baseline. |
interpatch_distance |
Numeric. The distance (in meters) where habitat
patches are considered connected. E.g., if set to 500, patches 498m apart
are connected, those 501m apart are not connected. This is passed
internally to a spatial operation known as "buffering", where this
distance is used as a radius from the edge of the habitat zone. This means
the specified |
target_resolution |
Numeric. Target resolution in meters. |
data_resolution |
Numeric. Data resolution in meters. |
aggregation_factor |
Numeric. Factor by which Data resolution was aggregated. |
species |
Character. Name of species analysed. |
A tibble with connectivity metrics including number of patches, probability of connectedness, effective mesh size, mean and total patch areas.
summarise_connectivity( area = lizard_areas_connected$area, interpatch_distance = 10, target_resolution = 500, data_resolution = 10, aggregation_factor = 50, species = "Blue-tongued Lizard" )summarise_connectivity( area = lizard_areas_connected$area, interpatch_distance = 10, target_resolution = 500, data_resolution = 10, aggregation_factor = 50, species = "Blue-tongued Lizard" )
Calculate the total habitat area in hectars. A wrapper around summing the
area and multiplying by 0.0001 to give the units in hectares. Intended
for usage from objects created by habitat_connectivity(). See examples
below.
total_habitat_area(area)total_habitat_area(area)
area |
Numeric vector. Area of a connected patch. |
Numeric. Total habitat area in hectares.
total_habitat_area(lizard_areas_connected$area)total_habitat_area(lizard_areas_connected$area)