Package 'fwatlasbc'

Title: Freshwater Atlas British Columbia
Description: What the package does (one paragraph).
Authors: Joe Thorley [aut, cre] , Sebastian Dalgarno [aut] , Poisson Consulting [cph, fnd]
Maintainer: Joe Thorley <[email protected]>
License: MIT + file LICENSE
Version: 0.0.1.9018
Built: 2024-10-29 04:19:09 UTC
Source: https://github.com/poissonconsulting/fwatlasbc

Help Index


Add Blue Line Key to Longitude and Latitude

Description

Adds integer blue line key (blk) and numeric river meter (rm) column and sfc point (geometry) column of the closest point on the stream network (by default within 5 km) to the point specified by the lon and lat (WGS84).

Usage

fwa_add_blk_to_lon_lat(
  x,
  tolerance = 5000,
  limit = 1,
  epsg = getOption("fwa.epsg", 3005),
  nocache = getOption("fwa.nocache", FALSE)
)

Arguments

x

A data frame with numeric longitude (long) and latitude (lat) columns.

tolerance

A number of the tolerance in m.

limit

A positive whole number indicating the maximum number of features to return.

epsg

A positive whole number of the EPSG projection for the geometry.

nocache

A flag specifying whether or not to cache results.

Details

If a match isn't found the row is dropped.

Value

An sf tibble with the columns of x plus integer column blk, real columns rm and distance_to_lon_lat and sfc point column geometry

Examples

## Not run: 
fwa_add_blk_to_lon_lat(data.frame(lon = -132.26, lat = 53.36))

## End(Not run)

Add Blue Line Key(s) to Stream Name

Description

Adds blue line keys (blk) to stream names. There may be more than one stream with the same name.

Usage

fwa_add_blks_to_stream_name(x, stream_name = fwatlasbc::fwa_stream_name)

Arguments

x

A data frame with character column stream_name.

stream_name

A data frame with whole numeric column blk and character column stream_name.

Value

A tibble with the columns of x plus an integer column blk.

Examples

fwa_add_blks_to_stream_name(data.frame(stream_name = "Sangan River"))

Add Collection to Polygon

Description

Adds collection to a polygon such as a watershed. If the active sfc polygon column is called geometry it is replaced by the geometry column of the collection. If the collection includes a blue_line_key column the values are copied to column blk replacing any existing values.

Usage

fwa_add_collection_to_polygon(
  x,
  collection = "stream_network",
  intersect = FALSE,
  filter = NULL,
  limit = 10000,
  offset = 0,
  properties = NULL,
  transform = NULL,
  epsg = getOption("fwa.epsg", 3005),
  nocache = getOption("fwa.nocache", FALSE)
)

fwa_add_collection_to_watershed(
  x,
  collection = "stream_network",
  intersect = FALSE,
  filter = NULL,
  limit = 10000,
  offset = 0,
  properties = NULL,
  transform = NULL,
  epsg = getOption("fwa.epsg", 3005),
  nocache = getOption("fwa.nocache", FALSE)
)

Arguments

x

A sf object with an active sfc polygon column.

collection

A character string of the collection.

intersect

A logical vector specifying whether to intersect the individual features with the polygon as opposed to just including the features that intersect it.

filter

A named vector or list of the filter(s) to apply, where the list names correspond to column names and the list values correspond to the desired value, e.g. list(gnis_name = "Sangan River").

limit

A positive whole number indicating the maximum number of features to return.

offset

A positive whole number indicating the offset of start of returned results.

properties

A vector of strings of the column names to include. If NULL (default), all columns are retained.

transform

A character vector with the name of the valid transform function followed by the parameter values (e.g. c("ST_Simplify", 100))

epsg

A positive whole number of the epsg to transform features to.

nocache

A flag specifying whether or not to cache results.

Value

An sf object

Functions

  • fwa_add_collection_to_watershed(): [Superseded]

    Deprecated for fwa_add_collection_to_polygon().

See Also

fwapgr::fwa_collection().

Examples

## Not run: 
watershed <- fwa_add_watershed_to_blk(data.frame(blk = 356308001))
fwa_add_collection_to_polygon(watershed)

## End(Not run)

Add Cut to River Meter

Description

Adds value(s) in cut column in y to to column of same name in x based on blk and rm_start and rm_end in y.

Usage

fwa_add_cut_to_rms(x, y, cut = "cut")

Arguments

x

A data frame with integer columns blk and rm.

y

A data frame with integer columns blk, rm_start, rm_end and column specified in cut.

cut

A string of the name of the column in y with the values.

Value

A tibble of x with cut column from y.


Add Split to River Meter

Description

Splits river meters with parent_blk and parent_rm columns into upstream (TRUE) versus not (FALSE).

Usage

fwa_add_downstream_split_to_rms(x, y)

Arguments

x

A data frame with integer columns blk, rm, parent_blk and parent_rm.

y

A data frame with integer columns blk and rm and character column name.

Value

A tibble of x with a logical column for each name in name.


Add Google Maps Elevation to Point

Description

Add Google Maps Elevation to Point

Usage

fwa_add_gm_elevation_to_point(
  x,
  chunk_size = 300L,
  digits = 7,
  key = Sys.getenv("GOOGLE_MAPS_ELEVATION_API_KEY")
)

Arguments

x

An sf object of spatial points.

chunk_size

The number of rows to include in each API query.

digits

The number of digits to round the latitude and longitude by before querying the elevation from the API

key

A string of the Google Maps Elevation API key.

Value

An updated version of x with numeric column elevation.

See Also

googleway::google_elevation()

Examples

## Not run: 
rm <- fwa_add_rms_to_blk(data.frame(blk = 356308001))
fwa_add_gm_elevation_to_point(rm)

## End(Not run)

Add Intersection to Geometry

Description

Adds a logical column for each name in name in y indicating whether each element of x intersects with the element of y.

Usage

fwa_add_intersection_to_geometry(x, y)

Arguments

x

An sf data frame.

y

An sf data frame with character column name.

Value

A copy of x with a logical column for each name in name indicating whether each element of x intersects with the element of y.


Add New Blue Line Key and River Meter to Blue Line Key and River Meter

Description

Adds new blk and rm values to existing blk and rm values based on look up in second data frame.

Usage

fwa_add_new_blk_rm_to_blk_rm(
  x,
  y,
  blk = "blk",
  rm = "rm",
  blk2 = "blk",
  rm2 = "rm",
  new_blk = "new_blk",
  new_rm = "new_rm",
  new_blk_to = new_blk,
  new_rm_to = new_rm
)

Arguments

x

A tibble (or sf object) with blk and rm columns.

y

A tibble (or sf object) with unique blk and rm columns and new blk (optional) and rm columns.

blk

A string of the name of the blk column in x.

rm

A string of the name of the rm column in x.

blk2

A string of the name of the blk column in y.

rm2

A string of the name of the rm column in y.

new_blk

An optional string of the name of the new blk column in y. If NULL it is not used in the join.

new_rm

A string of the name of the new rm column in y.

new_blk_to

A string specifying the name to rename the new blk column with.

new_rm_to

A string specifying the name to rename the new blk column with.

Value

An updated version of x with additional columns for the new blk and rm columns.

See Also

⁠[fwa_add_new_rm_to_blk_rm()]⁠


Add River Meters to Blue Line Key

Description

Adds distances (rm) and spatial coordinates (geometry) of regularly spaced points along blue line key (blk). All distances which are in meters are from the river mouth.

Usage

fwa_add_rms_to_blk(
  x,
  interval = 1000,
  start = 0,
  end = Inf,
  epsg = getOption("fwa.epsg", 3005),
  nocache = getOption("fwa.nocache", FALSE)
)

Arguments

x

A data frame with integer column blk.

interval

A whole numeric of the distance between points.

start

A whole numeric of the start distance.

end

An integer of the end distance.

epsg

A positive whole number of EPSG projection for the coordinates.

nocache

A flag specifying whether or not to cache results.

Value

An sf tibble with the columns of x plus integer column rm and sf column geometry.

Examples

## Not run: 
fwa_add_rms_to_blk(data.frame(blk = 356308001))

## End(Not run)

Add Section to River Meter

Description

Adds section column in y to x based on blk and end rm in y. All rms in x up to and including the end rm but before the previous end rm are assigned the section column value (which can be missing).

Usage

fwa_add_section_to_rms(x, y, section = "section")

Arguments

x

A data frame with integer columns blk and rm.

y

A data frame with integer columns blk and rm and column specified in section.

section

A string of the name of the column in y (can include missing values).

Value

A tibble of x with section column from y.


Add Blue Line Key(s) to Stream Name

Description

Adds blue line keys (blk) to stream names. There may be more than one stream with the same name.

Usage

fwa_add_stream_names_to_blk(x, stream_name = fwatlasbc::fwa_stream_name)

Arguments

x

A data frame with whole numeric column blk.

stream_name

A data frame with whole numeric column blk and character column stream_name.

Value

A tibble with the columns of x plus an integer column blk.

Examples

fwa_add_stream_names_to_blk(data.frame(blk = 360886335L))

Add Split to River Meter

Description

Splits river meters with parent_blk and parent_rm columns into upstream (TRUE) versus not (FALSE).

Usage

fwa_add_upstream_split_to_rms(x, y)

fwa_add_split_to_rms(x, y)

Arguments

x

A data frame with integer columns blk, rm, parent_blk and parent_rm.

y

A data frame with integer columns blk and rm and character column name.

Value

A tibble of x with a logical column for each name in name.

Functions

  • fwa_add_split_to_rms(): Soft-deprecated [Deprecated]


Add Watershed to Blue Line Key

Description

Adds polygon (geometry) of aggregated fundamental watersheds to blue line key (blk). The rm distances which is in meters is from the river mouth.

Usage

fwa_add_watershed_to_blk(
  x,
  exclude = FALSE,
  epsg = getOption("fwa.epsg", 3005),
  nocache = getOption("fwa.nocache", FALSE)
)

Arguments

x

An sf object with a polygon sfc column specifying watersheds and an optional rm column specfying the river meter. The rm is set to be 0 if missing.

exclude

A logical vector specifying whether to exclude the fundamental watershed in which the start falls.

epsg

A positive whole number of the epsg to transform features to.

nocache

A flag specifying whether or not to cache results.

Value

An sf tibble with the columns of x plus sf column geometry.

A sf object

See Also

fwapgr::fwa_watershed_at_measure().

Examples

## Not run: 
fwa_add_watershed_to_blk(data.frame(blk = 356308001))

## End(Not run)

Collection Name

Description

A tibble of collection names.

Usage

fwa_collection_name

Format

An object of class spec_tbl_df (inherits from tbl_df, tbl, data.frame) with 12 rows and 2 columns.

Examples

fwa_collection_name

Convert River Metres to Streams

Description

Casts river metre points to linestrings by blk.

Usage

fwa_convert_rms_to_streams(x)

Arguments

x

An point sf object with whole numeric columns blk and rm.

Value

A linestring sf object with whole numeric columns blk and rm.


Converts Stream Names to Blue Line Keys

Description

Each stream name is converted to a blue line key by calculating it's integer hash.

Usage

fwa_convert_stream_names_to_blks(names)

Arguments

names

A character vector of stream names.

Details

This function is only expected to be used when a blue line key does not already exist.

Value

An positive integer vector of blue line keys.

Examples

fwa_convert_stream_names_to_blks(c("a stream name", "a stream name2"))

Convert Stream Network to River Meters

Description

Converts a tibble of a BC stream network to river meters.

Usage

fwa_convert_stream_network_to_rms(x, interval = 5, tolerance = 0.1)

Arguments

x

An sf tibble of a stream network.

interval

A whole number of the distance between points.

tolerance

A number of the acceptable discrepancy in meters in the network lengths.

Value

An sf tibble with the columns of x plus integer column rm and sf column geometry.

See Also

fwa_convert_streams_to_rms()

Examples

## Not run: 
watershed <- fwa_add_watershed_to_blk(data.frame(blk = 356308001, rm = 1000))
network <- fwa_add_collection_to_polygon(watershed)
fwa_convert_stream_network_to_rms(network, interval = 100)

## End(Not run)

Convert Streams to River Meters

Description

Converts a tibble of streams to river meters. Unlike fwa_convert_stream_network_to_rms() it only requires the linestrings and the unique integer identifier for each stream.

Usage

fwa_convert_streams_to_rms(
  x,
  interval = 5,
  gap = 1,
  end = NULL,
  elevation = FALSE,
  reverse = integer()
)

Arguments

x

An sf tibble with a column blk and linestrings of streams.

interval

A positive whole number of the distance (m) between points.

gap

A positive real number specifying the maximum gap (m) between the mouth of stream and its parent stream to be considered connected.

end

A positive whole number indicating how far (m) the end of the stream linestring has to be from the last interval to be included. To default end = NULL (equivalent to end = interval + 1) excludes ends.

elevation

A flag specifying whether to use the elevation from Google Maps to determine stream direction (or use the direction of the provided linestrings)

reverse

A whole numeric vector of streams to reverse direction ignoring elevation.

Value

An sf tibble with the columns blk, integer column rm and sf column point geometry.

See Also

fwa_convert_stream_network_to_rms()

Examples

## Not run: 
watershed <- fwa_add_watershed_to_blk(data.frame(blk = 356308001, rm = 1000))
network <- fwa_add_collection_to_polygon(watershed)
network <- select(network, blk = blue_line_key)
fwa_convert_streams_to_rms(network, interval = 100)

## End(Not run)

Find Stream Names

Description

Finds gnis stream names that match regular expression.

Usage

fwa_find_stream_names(pattern = ".*", ignore_case = TRUE)

Arguments

pattern

A string of a regular expression.

ignore_case

A flag specifying whether to ignore case when matching the regular expression to gnis stream names.

Value

A tibble with character column stream_name of the names of all the streams that match the regular expression.

Examples

fwa_find_stream_names("sangan")

Get Section from River Meter

Description

Gets sf tibble of section blk, rm, length and geometry where sections are defined by the their most upstream point.

Usage

fwa_get_section_from_rms(x, section = "section")

Arguments

x

A data frame with integer columns blk and rm.

section

A string of the name of the column in x that specifies the sections.

Value

A sf tibble with integer columns blk, rm, length and a geometry where rm and geometry are the upstream end of the section.


Get Segment from River Meter

Description

Gets sf tibble of section blk, rm_start, rm_end, segment and line geometry.

Usage

fwa_get_segment_from_rms(x, segment = "segment")

Arguments

x

A data frame with integer columns blk and rm.

segment

A string of the name of the column in x, which must be a character or factor vector, that specifies which segment each rms belongs to.

Value

A sf tibble with integer columns blk, rm_start, rm_end, character/factor segment and a line geometry.


Join Stream Segments

Description

Converts a tibble of stream segment linestrings to stream linestrings.

Usage

fwa_join_stream_segments(x, elevation = FALSE, reverse = integer())

Arguments

x

An sf tibble with a column blk and linestrings of stream segments.

elevation

A flag specifying whether to use the elevation from Google Maps to determine stream direction (or use the direction of the provided linestrings)

reverse

A whole numeric vector of streams to reverse direction ignoring elevation.

Value

An sf tibble with the columns blk and sfc column point geometry.

See Also

fwa_convert_streams_to_rms()

Examples

## Not run: 
watershed <- fwa_add_watershed_to_blk(data.frame(blk = 356308001, rm = 1000))
network <- fwa_add_collection_to_polygon(watershed)
network <- select(network, blk = blue_line_key)
fwa_join_stream_segments(network)

## End(Not run)

Map View

Description

A wrapper on mapview::mapview.sf() that allows the user to layer by a column and coerces hms columns to character (to avoid being dropped).

Usage

fwa_mapview(x, layer = NULL, zcol = NULL, legend = FALSE, ...)

Arguments

x

An sf data frame.

layer

A string of the column to layer the points by.

zcol

A string of the column to color points by.

legend

A flag specifying whether to plot a legend.

...

Additional arguments passed to mapview::mapview().


Map View River Meters

Description

Map View River Meters

Usage

fwa_mapview_rms(
  x,
  layer = NULL,
  zcol = "rm",
  legend = FALSE,
  npoint = 250,
  ...
)

Arguments

x

An sf data frame with unique integer columns blk and rm.

layer

A string of the column to layer the points by.

zcol

A string of the column to color points by.

legend

A flag specifying whether to plot a legend.

npoint

An indication of the total number of points to plot.

...

Additional arguments passed to mapview::mapview().


Map View River Meters

Description

Maps two alternative stream networks by adding links from each point in x to matching point in y.

Usage

fwa_mapview_rms_to_rms(x, y, zcol = "rm", npoint = 250)

Arguments

x

An sf data frame with unique integer columns blk and rm and integer column new_rm.

y

An sf data frame with unique integer columns blk and rm.

zcol

A string of the column to color points by.

npoint

An indication of the total number of points to plot.


Parent Blue Line Key

Description

Gets parent blue line key.

Usage

fwa_parent_blk_rms(x, rms)

Arguments

x

A whole numeric vector of one or more blue line keys.

rms

A data frame with integer columns blk and parent_blk. There must be only one parent_blk for each blk.

Value

A whole numeric vector of the parent blue line keys.


Parent Stream Name

Description

Gets parent stream name.

Usage

fwa_parent_stream_name_rms(x, rms, stream_name = fwatlasbc::fwa_stream_name)

Arguments

x

A character vector of one or more stream names.

rms

A data frame with integer columns blk and parent_blk. There must be only one parent_blk for each blk.

stream_name

A data frame with character column stream_name and integer column blk. There must be no more than one blk for the stream names specified.

Value

A character vector of the parent blue line keys.


Prune River Meter

Description

Removes river meters above rm values in y.

Usage

fwa_prune_rms(x, y)

Arguments

x

A data frame with integer columns blk, rm, parent_blk and parent_rm.

y

A data frame with integer columns blk and rm.

Value

A tibble of x with rows above the rms in y removed.


Snap River Meter to Point

Description

Assigns closest river meter to each spatial point. If the blue line key (blk) is missing then it is also assigned together with the distance to the river meter (distance_to_rm) in m.

Usage

fwa_snap_rm_to_point(x, rm, ...)

Arguments

x

An sf object of spatial points with optional integer column blk.

rm

An sf object of spatial point with blk and rm columns.

...

Additional columns to group by when assigning. Elements with missing values in rm are assigned to any value in x.

Value

An updated version of x with integer columns blk and rm and numeric column distance_to_rm.

Examples

rm <- fwa_add_rms_to_blk(data.frame(blk = 356308001))
x <- rm[rm$rm %in% c(0, 2000, 5000, 6000, 7000), ]
rm <- rm[rm$rm %in% c(1000, 3000, 4000, 8000, 9000, 10000), ]
fwa_snap_rm_to_point(x, rm)

Snap River Meter to River Meters

Description

Assigns closest river meter to river meters based on blue line keys. If x already includes new_rm column then non-missing values are preserved. The non-missing new_rm values must be ordered (with respect to x$rm) and must be present in rm$rm. If x already includes new_blk then river meters can be assigned to a creek with a different blue line key and/or river meters from multiple creeks can be assigned to the same creek (for example in the case of a previously unmapped side channel and the mainstem).

Usage

fwa_snap_rm_to_rms(x, rm, snap_mouths = FALSE)

Arguments

x

An sf object of spatial points with blk and rm columns and optional new_rm integer and new_blk columns.

rm

An sf object of spatial point with blk and rm columns.

snap_mouths

A flag specifying whether to snap pairs of streams at their mouths (rm = 0) where new_rm is not already set.

Details

The closest river meter is snapped to each rm (by blk = new_blk) and missing new_rm values are replaced with the corresponding rm value. The new_rm values are then ordered by adjusting the values so that firstly all previous values are not greater than each provided new_rm value and then all subsequent values are not less than the maximum previous value. Next all runs of two or more identical new_rm values that do not include a provided new_rm are interpolated between the previous and subsequent new_rm values based on the original rm spacing and then snapped to the closest rm value in rm.

To ensure that pairs of streams snap at their mouths set the new_rm to be 0 where the rm is 0 or set snap_mouths = TRUE

Value

An updated version of x with integer columns blk, rm, new_blk, new_rm and numeric column distance_to_new_rm.

Examples

rm <- fwa_add_rms_to_blk(data.frame(blk = 356308001))
x <- rm[rm$rm %in% c(0, 2000, 5000, 6000, 7000), ]
rm <- rm[rm$rm %in% c(1000, 3000, 4000, 8000, 9000, 10000), ]
fwa_snap_rm_to_rms(x, rm)

Snap River Meters to River Meters

Description

Assigns closest river meters to river meters by blue line keys using fwa_snap_rm_to_rms() rm must not have an existing new_rm column.

Usage

fwa_snap_rms_to_rms(x, rm, snap_mouths = FALSE)

Arguments

x

An sf object of spatial points with blk and rm columns and optional new_blk and new_rm integer column.

rm

An sf object of spatial point with blk and rm columns.

snap_mouths

A flag specifying whether to snap pairs of streams at their mouths (rm = 0) where new_rm is not already set.

Details

x is first snapped to rm then rm is snapped to x while ensuring that the links between x and rm are bidirectional as much as possible.

Value

A named list with an updated versions of x and rm with integer columns blk, new_blk, rm and new_rm and numeric column distance_to_new_rm.

See Also

fwa_snap_rm_to_rms()

Examples

rm <- fwa_add_rms_to_blk(data.frame(blk = 356308001))
x <- rm[rm$rm %in% c(0, 2000, 5000, 6000, 7000), ]
rm <- rm[rm$rm %in% c(1000, 3000, 4000, 8000, 9000, 10000), ]
fwa_snap_rms_to_rms(x, rm)

Snap Stream Measure to Point

Description

Assigns closest stream measure in m to each spatial point. If the blue line key (blk) is missing then it is also assigned together with the distance to the stream (distance_to_stream) in m.

Usage

fwa_snap_stream_measure_to_point(x, streams, ...)

Arguments

x

An sf object of spatial points with optional integer column blk.

streams

An sf object of spatial linestrings with blk column.

...

Additional columns to group by when assigning.

Value

An updated version of x with integer columns blk and stream_measure and numeric column distance_to_stream.

See Also

fwa_snap_rm_to_point()

Examples

## Not run: 
watershed <- fwa_add_watershed_to_blk(data.frame(blk = 356308001, rm = 1000))
network <- fwa_add_collection_to_polygon(watershed)
network$blk <- network$blue_line_key
streams <- fwa_join_stream_segments(network)
points <- fwa_add_rms_to_blk(data.frame(blk = 356308001))
fwa_snap_stream_measure_to_point(points, streams)

## End(Not run)

Stream Name

Description

A tibble of stream names with blue line keys.

Usage

fwa_stream_name

Format

An object of class tbl_df (inherits from tbl, data.frame) with 11606 rows and 2 columns.

Examples

fwa_stream_name

Swap Branches of River Meters

Description

Swaps two branches of river meters.

Usage

fwa_swap_branches_rms(x, y, adjust_points = TRUE)

Arguments

x

A data frame with integer columns blk, rm, parent_blk and parent_rm.

y

A data frame with integer column blk specifying the blue line key that currently begins at the confluence of the two branches.

adjust_points

A flag specifying whether to adjust the coordinates of points which move.

Value

A copy of x with the branches swapped.