Index Points to Lines

given an sf point geometry column, return id, aggregate_id (e.g. reachcode), and aggregate id measure for each point.

Usage

index_points_to_lines(
  x,
  points,
  search_radius = NULL,
  precision = NA,
  max_matches = 1,
  ids = NULL,
  aggregate_ids = NULL
)

# S3 method for class 'data.frame'
index_points_to_lines(
  x,
  points,
  search_radius = NULL,
  precision = NA,
  max_matches = 1,
  ids = NULL,
  aggregate_ids = NULL
)

# S3 method for class 'hy'
index_points_to_lines(
  x,
  points,
  search_radius = NULL,
  precision = NA,
  max_matches = 1,
  ids = NULL,
  aggregate_ids = NULL
)

Arguments

x

data.frame network compatible with hydroloom_names.

points

sf or sfc of type POINT in analysis projection. NOTE: x will be projected to the projection of the points layer.

search_radius

units distance for the nearest neighbor search to extend in analysis projection. If missing or NULL, and points are in a lon lat projection, a default of 0.01 degree is used, otherwise 200 m is used. Conversion to the linear unit used by the provided crs of points is attempted. See RANN nn2 documentation for more details.

precision

numeric the resolution of measure precision in the output in meters.

max_matches

numeric the maximum number of matches to return if multiple are found in search_radius

ids

vector of ids corresponding to flowline ids from x of the same length as and order as points. If included, index searching will be constrained to one and only one flowline per point.

search radius is still used with this option but max_matches is overridden.

aggregate_ids

vector of aggregate_ids corresponding to the aggregate_id field of x of the same length and order as points. If included, index searching for each point is constrained to the flowlines that carry its aggregate_id, so a point on a tributary is placed on the tributary and not the receiving river. Exclusive with ids.

Value

data.frame with up to six columns, point_id, id, id_measure, aggregate_id, aggregate_id_measure, and offset. point_id is the row or list element in the point input. id_measure is the interpolative measure along the matched flowline (0 at the outlet, 100 at the inlet) and is always returned. If an aggregate_id (e.g. mainstem or reachcode) is not included in x, it will not be included in the output. If from and to measures are not included for each id in x, aggregate measures will not be included in the output.

Details

Required attributes: id and sf linestring geometry

Note 1: Inputs are cast into LINESTRINGS. Because of this, the measure output of inputs that are true multipart lines may be in error.

Note 2: This algorithm finds the nearest node in the input flowlines to identify which flowline the point should belong to. As a second pass, it can calculate the measure to greater precision than the nearest flowline geometry node.

Note 3: Offset is returned in units consistent with the projection of the input points.

Note 4: See dfMaxLength input to sf::st_segmentize() for details of handling of precision parameter.

Note 5: "from" is downstream – 0 is the outlet "to" is upstream – 100 is the inlet

Note 6: This function does not assume that it has access to the complete aggregate feature. From and to aggregate id measures must be included for each flowline in order to have aggregate id measures (reachcode or mainstem measures) in the output.

Measures

id_measure is an interpolative measure along a single flowline: a percent of the line from its outlet, 0 at the outlet (downstream end) and 100 at the inlet (upstream, head end).

Examples

# \donttest{
if (require(hydrogeofetch)) {
  try(source(system.file("extdata", "sample_flines.R", package = "hydrogeofetch")))

  if (exists("sample_flines")) {
    if (!any(lengths(sf::st_geometry(sample_flines)) > 1))
      sample_flines <- sf::st_cast(sample_flines, "LINESTRING", warn = FALSE)

    point <- sf::st_sfc(sf::st_point(c(-76.87479, 39.48233)),
      crs = 4326)

    index_points_to_lines(sample_flines, point)

    point <- sf::st_transform(point, 5070)

    index_points_to_lines(sample_flines, point,
      search_radius = units::set_units(200, "m"))

    index_points_to_lines(sample_flines, point, precision = 30)

    points <- sf::st_sfc(list(sf::st_point(c(-76.86934, 39.49328)),
      sf::st_point(c(-76.91711, 39.40884)),
      sf::st_point(c(-76.88081, 39.36354))),
    crs = 4326)

    index_points_to_lines(sample_flines, points,
      search_radius = units::set_units(0.2, "degrees"),
      max_matches = 10)

    index_points_to_lines(sample_flines, points,
      search_radius = units::set_units(0.2, "degrees"),
      ids = c(11689926, 11690110, 11688990))
  }
}
#> Warning: crs of lines and points don't match. attempting st_transform of lines
#> Warning: crs of lines and points don't match. attempting st_transform of lines
#>   point_id    COMID id_measure      REACHCODE REACHCODE_measure       offset
#> 1        1 11689926 100.000000 02060003001467          100.0000 6.026811e-05
#> 2        2 11690110 100.000000 02060003001493          100.0000 7.424781e-03
#> 3        3 11688990   1.914437 02060003000515            1.9144 8.652186e-03
# }