ssn_import | R Documentation |
SSN
objectThis function reads spatial data from a .ssn folder
and creates an SSN
object.
ssn_import(
path,
include_obs = TRUE,
predpts,
format_additive = FALSE,
names_additive = NULL,
overwrite = FALSE
)
path |
Filepath to the .ssn directory. See details. |
include_obs |
default = |
predpts |
Vector of shapefile basenames for prediction sites found within the .ssn folder. |
format_additive |
Logical indicating whether the columns containing
the addtive function values should be formated for
|
names_additive |
Character vector of column names in observed and
prediction site datasets containing additive function values.
Must be defined if |
overwrite |
default = |
The importSSN
function imports spatial data from a .ssn
folder to create an SSN
object. The information contained in the
.ssn folder can be generated using a number of proprietary and
open source software tools:
The Spatial Tools for the Analysis of River Systems (STARS) tools for ArcGIS Desktop versions 9.3x-10.8x (Peterson and Ver Hoef 2014). This custom ArcGIS toolset is designed to work with existing streams data in vector format.
The openSTARS package (Kattwinkel et al. 2020) extends the functionality of the STARS toolset, which makes use of R and GRASS GIS. It is open source and designed to derive streams in raster format from a digital elevation model (DEM).
The SSNbler package (currently in development as of September 2023) is an open source version of the STARS toolset, which makes use of the functionality found in the sf package to process streams data in vector format.
When spatial data are processed using one of these software tools, a .ssn directory is output which contains all of the spatial, topological and attribute data needed to fit a spatial statistical stream network model to streams data. This includes:
An edges shapefile of lines that represent the stream network.
A sites shapefile of points where observed data were collected on the stream network.
Prediction sites shapefile(s) of locations where predictions will be made.
netID.dat files for each distinct network, which store the topological relationships of the line segments in edges.
A more detailed description of the .ssn directory and its contents is provided in Peterson and Ver Hoef (2014).
The ssn_import
imports the edges, observed sites, and
prediction sites as sf data.frame
objects. A new column named 'netgeom'
is created to store important data that represents
topological relationships in a spatial stream network
model. These data are stored in character format, which is less
likely to be inadvertantly changed by users. See
ssn_get_netgeom
for a more detailed description of
the format and contents of 'netgeom'.
The information contained in the netID text files is imported
into an SQLite database, binaryID.db, which is stored in the .ssn
directory. This information is used internally by
ssn_create_distmat
,
ssn_lm
and
ssn_glm
to calculate the data necessary
to fit a spatial statistical model to stream network data. If
overwrite = TRUE
(overwrite = FALSE
is the default) and a binaryID.db
file already exists within the .ssn directory, it will be
overwriten when the SSN
object is created.
At a minimum, an SSN
object must always contain streams, which
are referred to as edges. The SSN
object would also typically
contain a set of observed sites, where measurements have been
collected and only one observed dataset is permitted. When
include_obs=FALSE
, an SSN
object is created without
observations. This option provides flexibility for users who
would like to simulate data on a set of artifical sites on an
existing stream network. Note that observation sites must be
included in the SSN
object in order to fit models using
ssn_lm
or ssn_glm
. The SSN
object may contain
multiple sets of prediction points (or none), which are stored as
separate shapefiles in the .ssn directory. The
ssn_import_predpts
function allows users to import additional
sets of prediction sites to a an existing SSN
object.
ssn_import
returns an object of class SSN, which is a list
with four elements containing:
edges
: An sf data.frame
containing the stream network,
with an additional 'netgeom' column.
obs
: An sf data.frame containing observed site locations,
with an additional 'netgeom' column. NA if include_obs =
FALSE
.
preds
: A list of sf data.frames containing prediction
site locations. The names of the preds list correspond to the
basenames of the prediction site shapefiles (without the .shp
extension) specified in predpts
. Empty list if predpts
is not provided.
path: The local file to the .ssn directory associated with the SSN
object.
Kattwinkel, M., Szocs, E., Peterson, E., and Schafer, R.B. (2020) Preparing GIS data for analysis of stream monitoring data: The R package openSTARS. PLOS One 15(9), e0239237. Peterson, E., and Ver Hoef, J.M. (2014) STARS: An ArcGIS toolset used to calculate the spatial information needed to fit spatial statistical stream network models to stream network data. Journal of Statistical Software 56(2), 1–17.
ssn_get_netgeom
## Create local temporary copy of MiddleFork04.ssn found in
# SSN2/lsndata folder. Only necessary for this example.
copy_lsn_to_temp()
## Import SSN object with no prediction sites
mf04 <- ssn_import(paste0(tempdir(), "/MiddleFork04.ssn"),
overwrite = TRUE
)
## Import SSN object with 3 sets of prediction sites
mf04p <- ssn_import(paste0(tempdir(), "/MiddleFork04.ssn"),
predpts = c(
"pred1km.shp",
"CapeHorn.shp",
"Knapp.shp"
),
overwrite = TRUE
)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.