Package {gridHR}

Title:	Grid-Based Home-Range Analysis and Radial Space-Use Profiles
Version:	1.0.0
Description:	Tools for estimating and exploring animal home ranges from geographical locations using regular spatial grids of square or hexagonal cells; see Ford and Krumme (1979) <doi:10.1016/0022-5193(79)90366-7>. The package includes grid-based home-range estimation across different cell sizes, analyses of the relationship between grid-cell size and home-range area and spatial connectivity, and rarefaction analyses to evaluate how home-range estimates change with increasing numbers of locations. It also introduces a novel radial approach for characterizing the internal organization of space use by quantifying how space-use intensity changes with increasing distance from the centre toward the periphery of the home range.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.3
Imports:	dplyr, ggplot2, sf
Depends:	R (≥ 4.1)
LazyData:	true
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-09-10 08:47:46 UTC; norberello
Author:	Norberto Asensio [aut, cre]
Maintainer:	Norberto Asensio <norberto.asensio@ehu.eus>
Repository:	CRAN
Date/Publication:	2026-09-18 11:20:08 UTC

Gibbon movement locations from Khao Yai National Park

Description

Movement locations recorded at approximately 5-m intervals throughout 2003 for a group of white-handed gibbons (Hylobates lar) in Khao Yai National Park, Thailand.

Usage

gibbons

Format

An sf object containing 18,098 point locations.

Details

The dataset contains 18,098 spatial locations represented as an sf point object. Coordinates are provided in UTM zone 47N (EPSG:32647).

The dataset was originally used to examine short-term core-area use in white-handed gibbons.

References

Asensio, N., Brockelman, W. Y., Malaivijitnond, S. & Reichard, U. H. (2014). White-handed Gibbon (Hylobates lar) Core Area Use Over a Short-Time Scale. Biotropica, 46, 461-469.

Examples

data(gibbons)

grid_hr(
  gibbons,
  cell_area = 5000,
  fill_by = "radial",
  show_legend = FALSE,
  title = "Radial space-use intensity of a gibbon group
  (1 hex = 0.5 ha)"
)

Grid-based home-range estimation

Description

Estimates home-range size by overlaying animal locations with a regular spatial grid and identifying the occupied cells. The function supports both hexagonal and square cells and can display spatial variation in space-use intensity using either the number of locations recorded in each cell or a radial space-use profile.

Usage

grid_hr(
  points,
  cell_area = 5000,
  title = "",
  cell_shape = "hex",
  show_locations = FALSE,
  location_fill = "black",
  location_outline = "white",
  location_size = 1.2,
  location_alpha = 0.6,
  show_gradient = TRUE,
  fill_by = "locations",
  low_colour = "lightblue",
  high_colour = "darkblue",
  cell_fill = "lightblue",
  cell_outline = NA,
  linewidth = 0.4,
  show_centroid = TRUE,
  centroid_colour = "red",
  centroid_size = 5,
  show_legend = FALSE,
  text_size = 13
)

Arguments

Details

When fill_by = "locations", each occupied cell is coloured according to the number of recorded locations it contains. This represents the conventional grid-based spatial distribution of location density.

When fill_by = "radial", the occupied cells are grouped into radial rings according to their distance from the centre of the home range. Cells belonging to the same ring are assigned the same colour, representing the normalized space-use intensity of that ring. Radial intensity is calculated as the number of locations recorded in a ring divided by the number of occupied cells in that ring. This provides a spatial representation of the radial space-use profile produced by radial_plot().

The centre used for the radial representation is the centre of the grid cell containing the geometric centroid of all observed locations.

Value

A list containing:

hr_size_m2

Home-range area in square metres.

hr_size_ha

Home-range area in hectares.

n_cells

Number of occupied grid cells.

grid

An sf object containing the occupied home-range cells.

hr_centroid

The geometric centroid of all locations.

central_cell_center

The centre of the grid cell containing the location centroid.

hr_plot

The resulting ggplot2 home-range map.

Examples

data(gibbons)

grid_hr(
  gibbons,
  cell_area = 5000,
  fill_by = "locations",
  show_legend = TRUE,
  title = "Grid-based space-use intensity of a gibbon group"
)

grid_hr(
  gibbons,
  cell_area = 5000,
  fill_by = "radial",
  show_legend = TRUE,
  title = "Radial space-use intensity of a gibbon group (0.5-ha hexagons)"
)

Home-range size across grid cell sizes

Description

Calculates grid-based home-range size across a sequence of cell areas. For each cell size, the function overlays the animal locations with a regular grid, identifies occupied cells, and calculates home-range size as the number of occupied cells multiplied by the area of each cell.

Usage

hr_cell_size(
  points,
  min = 100,
  max = 1000,
  interval = 100,
  cell_shape = "hex",
  show_plot = TRUE,
  line_colour = "#08519C",
  point_colour = "#08519C",
  linewidth = 1.2,
  point_size = 3,
  text_size = 13,
  title = ""
)

Arguments

Details

This function can be used to examine how sensitive grid-based home-range estimates are to the spatial resolution of the grid. Both hexagonal and square cells are supported.

Value

A list containing:

results

A data frame containing the cell area, number of occupied cells, and estimated home-range size in square metres and hectares for each cell size.

plot

The resulting ggplot2 plot.

cell_shape

The shape of the grid cells used.

min_cell

The minimum cell area evaluated.

max_cell

The maximum cell area evaluated.

interval

The increment between successive cell areas.

Examples

hr_cell_size(
  spider_monkeys,
  min = 10000,
  max = 50000,
  interval = 10000,
  cell_shape = "hex",
  title = "Grid-based home-range size according to cell area"
)

Grid-based home-range rarefaction

Description

Evaluates how grid-based home-range size changes with increasing numbers of animal locations. Random permutations of the locations are used to generate accumulated samples, and home-range size is calculated at successive sample sizes as the number of occupied grid cells multiplied by the area of each cell.

Usage

hr_rare(
  points,
  cell_area = 5000,
  cell_shape = "hex",
  n_reps = 1000,
  step = 1,
  seed = NULL,
  show_plot = TRUE,
  ribbon_colour = "#08519C",
  line_colour = "#08519C",
  linewidth = 1.1,
  text_size = 13
)

Arguments

Details

Repeated random permutations of the locations are used to estimate the mean and variability of home-range size at each sample size. The resulting rarefaction curve can be used to assess how home-range estimates change with sampling effort and whether they approach an asymptotic value as the number of locations increases.

The step argument controls the resolution of the rarefaction curve. For example, step = 25 evaluates home-range size every 25 locations. Smaller values provide a more detailed curve but require more computation, particularly for large datasets.

The home range is defined as the set of grid cells containing at least one sampled location. Consequently, estimated home-range area depends on the specified cell size and cell shape.

For each rarefaction replicate, the locations are randomly reordered and progressively accumulated. At each selected sample size, the number of unique occupied grid cells is recorded and multiplied by the cell area to obtain the grid-based home-range estimate.

Sampling is performed without replacement within each replicate. The variability among replicates therefore represents the effect of the order in which locations are accumulated rather than uncertainty arising from different spatial locations being sampled independently.

Because grid-based home-range area is based on occupied cells, rarefaction results depend on both sampling effort and the chosen grid resolution. The curve can therefore be used to examine whether additional locations continue to increase the estimated home-range area under a specified grid configuration.

Value

A list containing:

rarefaction_df

A data frame containing the number of locations evaluated, mean home-range size, and standard deviation across rarefaction replicates, expressed in square metres and hectares.

rarefaction_plot

The resulting ggplot2 rarefaction plot.

grid

An sf object containing the grid used for the analysis.

n_total

Number of locations included in the analysis.

cell_area

Area of each grid cell in square metres.

cell_shape

Shape of the grid cells used in the analysis.

Examples

data(spider_monkeys)

# A reduced number of replicates is used here to keep the example
# computationally light. Larger values are recommended for analysis.
hr_rare(
  spider_monkeys,
  cell_area = 10000,
  cell_shape = "hex",
  n_reps = 99,
  step = 25,
  seed = 123
)

Macaque group locations

Description

Spatial locations of a macaque group (Macaca leonina) recorded at Khao Yai National Park, Thailand, from July 2012 to June 2013. The group was followed for five to eight full days per month, from sleeping site to sleeping site, using a handheld GPS. Locations were recorded at approximately 30-minute intervals.

Format

An sf object containing 16,478 macaque group locations.

Details

Coordinates are provided in UTM zone 47N using the WGS84 datum.

Source

José-Domínguez, J. M., Huynen, M.-C., García, C. J., Albert-Daviaud, A., Savini, T., & Asensio, N. (2015). Non-territorial Macaques Can Range Like Territorial Gibbons When Partially Provisioned With Food. Biotropica, 47, 733–744. doi:10.1111/btp.12256

Examples

grid_hr(
  macaques,
  cell_area = 25000,
  fill_by = "locations",
  title = "Macaque home range with radial space-use pattern",
  low_colour = "grey90",
  high_colour = "grey10"
)

Minimum grid-cell size based on home-range connectivity

Description

Evaluates the topological connectivity of a grid-based home range across a sequence of grid-cell sizes. Animal locations are overlaid on grids of increasing cell area, occupied cells are identified, and their connectivity is evaluated based on shared cell edges.

Usage

min_cell(
  points,
  min = 100,
  max = 1000,
  interval = 100,
  cell_shape = "hex",
  show_plot = TRUE,
  line_colour = "#08519C",
  point_colour = "#08519C",
  linewidth = 1.2,
  point_size = 3,
  text_size = 13
)

Arguments

Details

Connectivity is expressed as the proportion of occupied cells belonging to the largest topologically connected component. Cells that touch only at a corner are not considered connected. The function also identifies the smallest tested cell size at which all occupied cells form a single connected component.

Because the grid is recreated independently at each cell size, connectivity is not necessarily monotonic with increasing cell size. The complete connectivity profile is therefore returned rather than assuming that connectivity, once achieved, is maintained at larger cell sizes.

For each cell size, the function counts the number of locations in each grid cell and retains occupied cells as the grid-based home range. Topological connectivity is then evaluated using shared cell edges. The resulting connectivity value is the proportion of occupied cells belonging to the largest connected component.

A connectivity value of 1 indicates that all occupied cells belong to a single connected component. The corresponding fully_connected value is TRUE.

The analysis is useful for evaluating whether a particular grid resolution produces a spatially compact representation of the observed home range and for identifying the smallest tested cell size at which the occupied grid becomes fully connected.

Value

A list containing:

results

A data frame containing the connectivity results for every tested cell size.

plot

The resulting ggplot2 connectivity plot.

cell_shape

The grid-cell shape used in the analysis.

minimum_connected

The smallest tested cell area at which all occupied cells form a single connected component. Returns NA if no tested cell size is fully connected.

min_cell

The minimum cell area specified for the analysis.

max_cell

The maximum cell area specified for the analysis.

interval

The increment between tested cell areas.

Examples

min_cell(
  macaques,
  min = 5000,
  max = 40000,
  interval = 10000,
  cell_shape = "hex"
)

Radial space-use profile of a grid-based home range

Description

Calculates and plots the relationship between space-use intensity and distance from the centre to the periphery of a grid-based home range.

Usage

radial_plot(
  points,
  cell_area = 5000,
  title = "",
  cell_shape = "hex",
  smooth = FALSE,
  loess_span = 0.8,
  show_points = FALSE,
  point_colour = "#08519C",
  point_size = 2,
  point_alpha = 0.8,
  line_colour = "#08519C",
  linewidth = 1.3,
  text_size = 13
)

Arguments

Details

The function divides the occupied home-range cells into radial rings according to their distance from the centre. The centre is defined as the centre of the grid cell containing the geometric centroid of all observed locations. For each radial ring, space-use intensity is calculated as the total number of recorded locations divided by the number of occupied cells in that ring.

This approach provides a cell-based description of how space-use intensity is organized spatially from the centre toward the periphery, while accounting for differences in the number of occupied cells represented at different distances.

Both distance and space-use intensity are normalized from 0 to 1. Normalized distance represents the position of each radial ring between the centre and the outermost occupied ring, whereas normalized space-use intensity represents relative intensity, with the most intensively used ring assigned a value of 1.

The resulting profile describes how the intensity of space use changes with increasing distance from the centre of the home range. A decreasing profile indicates relatively greater use toward the centre, whereas an increasing profile indicates relatively greater use toward the periphery. The function can display either the observed radial profile or a LOESS-smoothed curve.

Space-use intensity is calculated separately for each radial ring as the total number of locations recorded in the ring divided by the number of occupied cells comprising that ring. This prevents rings containing more occupied cells from automatically having higher intensity simply because they cover a larger number of cells.

The grid is constructed using the specified cell area and shape. Only cells containing at least one recorded location are considered part of the home range. Radial distance is measured from the centre of the central grid cell to the centres of the occupied grid cells.

The radial profile is therefore based on the spatial organization of observed locations within the grid rather than on a kernel density estimate. No spatial smoothing is applied unless smooth = TRUE is specified.

Value

A list containing:

ring_summary

A data frame containing the radial rings, number of locations, number of occupied cells, space-use intensity, distance from the centre, and normalized distance and intensity.

central_cell_center

The centre of the grid cell containing the geometric centroid of the observed locations.

radial_plot

A ggplot object showing the radial space-use profile.

Examples

radial_plot(
  gibbons,
  cell_area = 5000,
  cell_shape = "hex",
  title = "Radial space-use profile of a gibbon group (0.5-ha hexagons)"
)

Spider monkey subgroup locations

Description

Spatial locations of spider monkey subgroups recorded at approximately 30-minute intervals from 2005 to 2008 in a regenerating tropical forest. Coordinates are provided in UTM zone 16N using the WGS84 datum (EPSG:32616).

Usage

spider_monkeys

Format

An sf object containing spider monkey subgroup locations.

Details

The dataset was used to investigate the effects of roads on spider monkey home-range size and mobility in a heterogeneous regenerating forest.

Source

Asensio, N., Murillo-Chacon, E., Schaffner, C. M. & Aureli, F. (2017). doi:10.1111/btp.12441

References

Asensio, N., Murillo-Chacon, E., Schaffner, C. M. & Aureli, F. (2017). The effect of roads on spider monkeys' home range and mobility in a heterogeneous regenerating forest. Biotropica. doi:10.1111/btp.12441

Examples

data(spider_monkeys)

grid_hr(
  spider_monkeys,
  cell_area = 10000,
  fill_by = "radial",
  title = "Radial space-use intensity of a spider monkey group (1 ha hexagons)"
)