Calculate cost distances from receiver stations to all raster cells

Computes both cost-weighted and straight-line distances from each receiver station to all valid cells in a raster. Uses least-cost path analysis to account for landscape constraints on signal transmission.

Enhanced version that supports character station IDs and flexible column naming. Computes both cost-weighted and straight-line distances from each receiver station to all valid cells in a raster. Uses least-cost path analysis to account for landscape constraints on signal transmission.

Usage

calculate_station_distances(
  raster,
  receiver_frame,
  max_distance = NULL,
  station_col = "point_id"
)

calculate_station_distances(
  raster,
  receiver_frame,
  max_distance = NULL,
  station_col = "point_id"
)

Arguments

raster

A RasterLayer object representing the study area. Non-NA cells are treated as valid locations for distance calculations.

receiver_frame

An sf object or data frame containing receiver station locations. Must have a column for station identification (default is 'point_id').

max_distance

Numeric. Maximum distance (in map units) for calculations. Distances beyond this threshold are set to NA. Default is NULL (no limit).

station_col

Character. Name of the column containing station identifiers. Default is "point_id". Can be any column name with unique station IDs.

Value

A data frame in long format with the following columns:

cell_id

Unique identifier for each raster cell

x

X coordinate of the cell center

y

Y coordinate of the cell center

raster_value

Original value from the input raster

station_no

Station identifier from receiver_frame$point_id

cost_distance

Least-cost distance from station to cell

straight_distance

Euclidean distance from station to cell

tortuosity

Ratio of cost distance to straight distance

A data frame in long format with the following columns:

cell_id

Unique identifier for each raster cell

x

X coordinate of the cell center

y

Y coordinate of the cell center

raster_value

Original value from the input raster

station_no

Station identifier from receiver_frame (preserves original type)

cost_distance

Least-cost distance from station to cell

straight_distance

Euclidean distance from station to cell

tortuosity

Ratio of cost distance to straight distance

Details

This function uses the gdistance package to perform least-cost path analysis. The process involves:

1. Creating a uniform cost surface from the raster (all valid cells = 1)

2. Building a transition matrix with 8-directional connectivity

3. Calculating accumulated cost distances using accCost()

4. Computing straight-line distances for comparison

5. Converting results to long format for analysis

The tortuosity metric (cost/straight distance) indicates how much the least-cost path deviates from a straight line, with values > 1 indicating increased path complexity.

This enhanced version:

• Supports both numeric and character station IDs

• Allows flexible column naming via station_col parameter

• Preserves the original data type of station identifiers

• Maintains compatibility with existing workflows

The function uses the gdistance package to perform least-cost path analysis. The process involves:

1. Creating a uniform cost surface from the raster (all valid cells = 1)

2. Building a transition matrix with 8-directional connectivity

3. Calculating accumulated cost distances using accCost()

4. Computing straight-line distances for comparison

5. Converting results to long format for analysis

See also

generate_random_points, generate_spaced_points

generate_random_points, generate_spaced_points

Examples

if (FALSE) {
# Generate receiver stations with numeric IDs (default)
stations <- generate_random_points(depth_raster, n_points = 5, seed = 123)

# Calculate distances with default point_id column
distances <- calculate_station_distances(depth_raster, stations)

# Calculate distances with 1000m maximum
distances_limited <- calculate_station_distances(
  raster = depth_raster,
  receiver_frame = stations,
  max_distance = 1000
)

# Use with character station IDs
# Assuming stoney_rx_deploy has a 'station_id' column with character IDs
distances_char <- calculate_station_distances(
  raster = depth_raster,
  receiver_frame = stoney_rx_deploy,
  max_distance = 3000,
  station_col = "station_id"  # Specify the column with station IDs
)

# Analyze tortuosity patterns
library(dplyr)
tortuosity_summary <- distances %>%
  group_by(station_no) %>%
  summarise(
    mean_tortuosity = mean(tortuosity, na.rm = TRUE),
    max_cost_dist = max(cost_distance, na.rm = TRUE)
  )
}

if (FALSE) {
# With numeric station IDs (default)
stations_numeric <- generate_random_points(depth_raster, n_points = 5, seed = 123)
distances_numeric <- calculate_station_distances(depth_raster, stations_numeric)

# With character station IDs
stations_char <- stoney_rx_deploy  # Has character station_id column
distances_char <- calculate_station_distances(
  raster = depth_raster,
  receiver_frame = stations_char,
  max_distance = 3000,
  station_col = "station_id"
)

# Verify station ID preservation
unique(distances_char$station_no)  # Should show character IDs
}