Calculate cost distances from receiver stations to all raster cells (Enhanced)

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 hybrid distance calculation that employs straight-line distance in open water and least-cost paths around barriers, eliminating grid artifacts while preserving meaningful tortuosity.

Usage

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 (preserves original type)

cost_distance

Hybrid distance: straight-line when no barriers present, least-cost when barriers encountered. Eliminates grid artifacts in open water.

straight_distance

Euclidean distance from station to cell

tortuosity

Ratio of cost distance to straight distance. Values ~1.0 indicate open water paths, values >1.0 indicate barrier navigation.

crosses_barrier

Logical flag indicating whether the straight-line path between station and cell crosses NA cells (barriers)

Details

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 a hybrid distance calculation approach:

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

2. Builds a transition matrix with 8-directional connectivity

3. Calculates accumulated cost distances using accCost()

4. Computes straight-line (Euclidean) distances

5. Detects barrier crossings via ray-casting along straight-line paths

6. Uses straight distance when no barriers present, cost distance when barriers encountered

7. Converts results to long format for analysis

The hybrid approach eliminates radial grid artifacts in open water while preserving meaningful tortuosity around actual barriers. The output cost_distance column contains straight-line distance for open water paths and least-cost distance for barrier-crossing paths. Tortuosity values ~1.0 indicate open water, while values >1.0 indicate navigation around barriers.

See also

generate_random_points, generate_spaced_points

Examples

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
}