Package 'tphconv'

Convert Transport Opportunities CSV to a Raster

Description

Reads a CSV file (optionally gzipped) of public transport accessibility data, reprojects point coordinates, and rasterizes the data onto a regular grid. Optionally, it can add a second raster layer containing INSPIRE-compliant grid cell IDs.

Usage

tph_to_raster(
  input_file,
  out_column_name = NULL,
  crs_src = 4326,
  crs_dst = 3035,
  x_offset = 0,
  y_offset = 0,
  resolution_m = 1000,
  out_raster_file = NULL,
  add_id = TRUE
)

Arguments

input_file	Character. Path to the input CSV (gzipped) containing at least columns 'lon', 'lat', and one numeric data column.
out_column_name	Character or NULL. Name to assign to the data column in the output raster. If NULL (default), the original column name from the CSV is used.
crs_src	Integer or character. Source CRS (EPSG code or WKT); default is 4326.
crs_dst	Integer or character. Destination CRS (EPSG code or WKT); default is 3035.
x_offset	Numeric. An offset subtracted from the projected x-coordinate. This is used to convert the source point's reference (e.g., a lower-left corner) to the cell's theoretical centroid. For centroid-based data like GISCO, the default of 0 is correct.
y_offset	Numeric. An offset subtracted from the projected y-coordinate, similar to x_offset.
resolution_m	Numeric. Cell size in units of the destination CRS; default is 1000 (1 km).
out_raster_file	Character or NULL. Output filename for the raster. If provided, the raster is written to this file (creating directories as needed) and the filename is returned. If NULL (default), the SpatRaster is returned directly.
add_id	Logical. If TRUE (the default), a second layer named "id" is added to the raster. This is a factor layer where the labels correspond to the INSPIRE-compliant grid cell ID for each cell.

Value

If out_raster_file is NULL, a terra::SpatRaster object. This will be a multi-layer raster if add_id = TRUE. If out_raster_file is provided, a character string of the file path is returned.

Examples

tph_file <- system.file(
 "extdata",
 "ver1_0_LU_1km_pt_ppl_within_10-20_min.csv.gz",
 package = "tphconv"
)
library(terra)

# Convert a CSV to a raster with the ID layer (default)
r_with_id <- tph_to_raster(input_file = tph_file)
plot(r_with_id)

---

Generate a Table of Grid IDs and Values from a TPH CSV

Description

Reads a transport opportunities CSV file and efficiently generates a table containing the corresponding INSPIRE/GISCO grid cell IDs and data values.

Usage

tph_to_table(
  input_file,
  out_column_name = NULL,
  crs_src = 4326,
  crs_dst = 3035,
  x_offset = -500,
  y_offset = -500,
  resolution_m = 1000,
  add_centroid_coords = FALSE,
  add_gisco_corner_coords = FALSE
)

Arguments

input_file	Character. Path to the input CSV (gzipped) containing at least columns 'lon', 'lat', and one numeric data column.
out_column_name	Character or NULL. Name to assign to the data column in the output raster. If NULL (default), the original column name from the CSV is used.
crs_src	Integer or character. Source CRS (EPSG code or WKT); default is 4326.
crs_dst	Integer or character. Destination CRS (EPSG code or WKT); default is 3035.
x_offset	Numeric. An offset subtracted from the projected x-coordinate. This is used to convert the source point's reference (e.g., a lower-left corner) to the cell's theoretical centroid. For centroid-based data like GISCO, the default of 0 is correct.
y_offset	Numeric. An offset subtracted from the projected y-coordinate, similar to x_offset.
resolution_m	Numeric. Cell size in units of the destination CRS; default is 1000 (1 km).
add_centroid_coords	Logical. If TRUE, adds the original lon and lat as well as the projected centroid coordinates (x_centroid, y_centroid) to the output table. Defaults to FALSE.
add_gisco_corner_coords	Logical. If TRUE, adds the projected lower-left (south-west) corner coordinates (x_ll, y_ll) of the grid cell to the output table. Defaults to FALSE.

Details

This function is the fastest method for converting TPH data, as it operates directly on coordinates and avoids creating any intermediate spatial objects (rasters, polygons, or sf points).

Value

A data.frame with the gisco_id, the data value, and optional coordinate columns.

Examples

tph_file <- system.file(
  "extdata",
  "ver1_0_LU_1km_pt_ppl_within_10-20_min.csv.gz",
  package = "tphconv"
)

# Generate a table with both centroid and corner coordinates
full_table <- tph_to_table(
  tph_file,
  add_centroid_coords = TRUE,
  add_gisco_corner_coords = TRUE
)
head(full_table)

---

Convert Transport Opportunities CSV to a Spatial Vector Object (Direct Method)

Description

Reads a CSV file of public transport accessibility data and converts it into a spatial vector format (sf or terra::SpatVector). This function builds polygon geometries directly from the point coordinates in a vectorized manner using the sfheaders package, which can be faster for sparse datasets than methods requiring an intermediate raster.

Usage

tph_to_vector(
  input_file,
  out_column_name = NULL,
  crs_src = 4326,
  crs_dst = 3035,
  x_offset = -500,
  y_offset = -500,
  resolution_m = 1000,
  out_vector_file = NULL,
  return_as = c("sf", "SpatVector"),
  add_id = TRUE
)

Arguments

input_file	Character. Path to the input CSV (gzipped) containing at least columns 'lon', 'lat', and one numeric data column.
out_column_name	Character or NULL. Name to assign to the data column in the output raster. If NULL (default), the original column name from the CSV is used.
crs_src	Integer or character. Source CRS (EPSG code or WKT); default is 4326.
crs_dst	Integer or character. Destination CRS (EPSG code or WKT); default is 3035.
x_offset	Numeric. An offset subtracted from the projected x-coordinate. This is used to convert the source point's reference (e.g., a lower-left corner) to the cell's theoretical centroid. For centroid-based data like GISCO, the default of 0 is correct.
y_offset	Numeric. An offset subtracted from the projected y-coordinate, similar to x_offset.
resolution_m	Numeric. Cell size in units of the destination CRS; default is 1000 (1 km).
out_vector_file	Character or NULL. If a file path is provided (e.g., "data/luxembourg.gpkg"), the output is written to that file using sf::st_write, and the file path is returned. If NULL (the default), the function returns an in-memory spatial object.
return_as	Character. Specifies the class of the returned object when out_vector_file is NULL. Can be either "sf" (the default) or "SpatVector". This argument is ignored if out_vector_file is not NULL.
add_id	Logical. If TRUE (the default), an INSPIRE-compliant grid cell ID is generated and added as a column named "id". Set to FALSE to omit this step.

Value

Depending on the arguments:

• If out_vector_file is NULL, returns an sf object (default) or a SpatVector object (if return_as = "SpatVector") with polygon geometries.

• If out_vector_file is a character string, the path to the created file is returned.

Examples

# This function requires the 'sfheaders' package
if (requireNamespace("sfheaders", quietly = TRUE)) {
  tph_file <- system.file(
    "extdata",
    "ver1_0_LU_1km_pt_ppl_within_10-20_min.csv.gz",
    package = "tphconv"
  )

  # Convert a CSV file to an sf object using the direct method
  sf_obj_direct <- tph_to_vector(input_file = tph_file)
  plot(sf_obj_direct)
}

---