SSNbler (version 1.1.0)

ssn_assemble: Assemble an SSN object from an LSN

Description

Create an SSN (spatial stream network) object from a Landscape Network (LSN).

Usage

ssn_assemble(
  edges,
  lsn_path = NULL,
  obs_sites = NULL,
  preds_list = NULL,
  ssn_path,
  import = TRUE,
  check = TRUE,
  afv_col = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Value

The components of an SSN object are written to ssn_path (see Details). When import = TRUE, the function also returns an object of class SSN. If check = TRUE and verbose = TRUE, the validity of the returned SSN

object is checked using [ssn_check] and results are printed to the console.

Arguments

edges

An sf object with LINESTRING geometry created using lines_to_lsn (see Details).

lsn_path

Local pathname to a directory in character format specifying where relationships.csv resides, which is created using link{lines_to_lsn}.

obs_sites

Optional. A single sf object with POINT geometry created using link{sites_to_lsn} that represents the observation locations (i.e. where data were collected). Default = NULL (see Details).

preds_list

Optional. A list of one or more sf objects representing prediction sites.

ssn_path

Pathname to an output directory where output files will be stored. A .ssn extension will be added if it is not included.

import

Logical indicating whether the output files should be returned as an SSN object. Defaults to TRUE.

check

Logical indicating whether the validity of the SSN should be checked using [ssn_check] when both import = TRUE and verbose = TRUE. Default = TRUE.

afv_col

Character vector containing the name(s) of the additive function value column(s) that will be checked when check = TRUE. Columns must be present in edges, obs_sites and preds_list, if all are included. Default is NULL.

overwrite

Logical. If TRUE and ssn_path already exists, the contents of ssn_path will be overwritten. Defaults to FALSE.

verbose

Logical. Indicates whether messages about the function progress and object validity check (when check = TRUE) should be printed to the console. Defaults to TRUE.

Details

The SSNbler package is used to generate the spatial, topological, and attribute information needed to fit spatial stream-network models using the 'SSN2' package. The ssn_assemble function will often be the final step in the 'SSNbler' data-processing workflow and it is important that the previous processing steps have been followed. Prior to running ssn_assemble, the edges must be processed using link{lines_to_lsn}, link{updist_edges}, and link{afv_edges}. The obs_sites and prediction site datasets in preds_list must be processed with link{sites_to_lsn}, link{updist_sites}, and link{afv_sites}. In addition, the edges, obs_sites, and all of the sf objects in preds_list must be part of the same LSN.

The obs_sites and preds_list are optional arguments, with the Default = NULL. If obs_sites = NULL, an SSN object will be returned with NA stored in ssn.object$obs and a warning returned that ssn.object$obs is required for fitting spatial statistical models in 'SSN2'.

ssn_assemble stores the output locally in ssn_path. If ssn_path does not include the .ssn extension, it is added before the new directory is created. This directory contains:

• edges.gpkg: edges in GeoPackage format. A new network identifier, netID, is added that is unique to each subnetwork.

• sites.gpkg: observed sites in GeoPackage format (if present). Three new ID columns are added that are unique to the measurement (pid), the location (locID), and the network (netID).

• prediction datasets in GeoPackage format (if present). The prediction sites also contain pid, locID, and netID. The naming convention is taken from the names provided in preds_list.

• netID.dat files for each distinct network, which store the binaryID values for line segments in edges.

A more detailed description of the .ssn directory and its contents is provided in Peterson and Ver Hoef (2014).

Examples

# Get temporary directory, where the example LSN will be stored
# locally.
temp_dir <- tempdir()
# Build the LSN. When working with your own data, lsn_path will be
# a local folder of your choice rather than a temporary directory.
edges<- lines_to_lsn(
   streams = MF_streams,
   lsn_path = temp_dir,
   snap_tolerance = 1,
   check_topology = FALSE,
   overwrite = TRUE,
   verbose = FALSE
)

# Incorporate observed sites, MF_obs, into LSN
obs<- sites_to_lsn(
   sites = MF_obs,
   edges = edges,
   save_local = FALSE,
   snap_tolerance = 100,
   overwrite = TRUE,
   verbose = FALSE
)

# Incorporate prediction dataset, MF_preds, into LSN
preds<- sites_to_lsn(sites = MF_preds,
   edges = edges,
   save_local = FALSE,
   snap_tolerance = 1,
   overwrite = TRUE,
   verbose = FALSE
)

# Calculate the AFV for the edges using
# a column representing watershed area (h2oAreaKm2).
edges<- afv_edges(
   edges=edges,
   infl_col = "h2oAreaKm2",
   segpi_col = "areaPI",
   lsn_path = temp_dir,
   afv_col = "afvArea",
   overwrite = TRUE,
   save_local = FALSE
)

# Calculate the AFV for observed sites (obs) and prediction
# dataset, preds.
site.list<- afv_sites(
   sites = list(obs = obs,
                preds = preds),
   edges=edges,
   afv_col = "afvArea",
   save_local = FALSE,
   overwrite = TRUE
)

# Calculate upstream distance for edges
edges<- updist_edges(
   edges = edges,
   lsn_path = temp_dir,
   calc_length = TRUE,
   length_col = "Length",
   overwrite = TRUE,
   save_local = FALSE,
   verbose = FALSE
)

# Calculate upstream distance for observed sites (obs) and one
# prediction dataset (preds)
site.list<- updist_sites(
   sites = site.list,
   edges = edges,
   length_col= "Length",
   lsn_path = temp_dir,
   save_local = FALSE,
   overwrite = TRUE
)

# Assemble SSN object
ssn.obj<- ssn_assemble(
   edges = edges,
   lsn_path = temp_dir,
   obs_sites = site.list[["obs"]],
   preds_list = site.list[c("preds")],
   ssn_path = paste0(temp_dir, "/example.ssn"),
   import = TRUE,
   overwrite = TRUE
)

# Summarise SSN object
summary(ssn.obj)