Help for package traudem

Title:

Use TauDEM

Version:

1.0.3

Description:

Simple trustworthy utility functions to use TauDEM (Terrain Analysis Using Digital Elevation Models https://hydrology.usu.edu/taudem/taudem5/) command-line interface. This package provides a guide to installation of TauDEM and its dependencies GDAL (Geopatial Data Abstraction Library) and MPI (Message Passing Interface) for different operating systems. Moreover, it checks that TauDEM and its dependencies are correctly installed and included to the PATH, and it provides wrapper commands for calling TauDEM methods from R.

License:

MIT + file LICENSE

URL:

https://lucarraro.github.io/traudem/, https://github.com/lucarraro/traudem

BugReports:

https://github.com/lucarraro/traudem/issues

Imports:

cli, purrr, rlang, sys, tools, withr

Suggests:

knitr, rmarkdown, testthat (≥ 3.0.0), terra, shapefiles, sf, elevatr, fs

VignetteBuilder:

knitr

Config/testthat/edition:

Config/Needs/website:

usethis

Encoding:

UTF-8

RoxygenNote:

7.3.1

NeedsCompilation:

Packaged:

2024-04-24 14:59:30 UTC; carrarlu

Author:

Luca Carraro [cre, aut], University of Zurich [cph, fnd], Maëlle Salmon

[aut], Wael Sadek [aut], Kirill Müller

[aut]

Maintainer:

Luca Carraro <Luca.Carraro@eawag.ch>

Repository:

CRAN

Date/Publication:

2024-04-24 16:20:02 UTC

traudem: Use TauDEM

Description

Author(s)

Maintainer: Luca Carraro Luca.Carraro@eawag.ch

Authors:

Maëlle Salmon maelle@cynkra.com (ORCID)
Wael Sadek
Kirill Müller kirill@cynkra.com (ORCID)

Other contributors:

University of Zurich [copyright holder, funder]

D8 Contributing Area

Description

D8 Contributing Area

Usage

taudem_aread8(
  input_d8flowdir_grid,
  output_contributing_area_grid = NULL,
  check_edge_contamination = TRUE,
  n_processes = getOption("traudem.n_processes", 1),
  wg_file = NULL,
  outlet_file = NULL,
  outlet_layer_name = NULL,
  outlet_layer_number = NULL,
  quiet = getOption("traudem.quiet", FALSE)
)

Arguments

input_d8flowdir_grid

Input flow directions grid.

output_contributing_area_grid

Output contributing area grid.

check_edge_contamination

Whether to check for edge contamination.

n_processes

Number of processes for mpiexec. If NULL TauDEM is called without mpiexec.

wg_file

Input weight grid (optional).

outlet_file

Input outlets file (OGR readable dataset, optional).

outlet_layer_name

OGR layer name if outlets are not the first layer in outlet_file (optional). Layer name and layer number should not both be specified.

outlet_layer_number

OGR layer number if outlets are not the first layer in outlet_file (optional). Layer name and layer number should not both be specified.

quiet

If FALSE output from TauDEM CLI is suppressed.

Details

See https://hydrology.usu.edu/taudem/taudem5/help53/D8ContributingArea.html

Value

Path to output file (invisibly).

Examples


test_dir <- withr::local_tempdir()
dir.create(test_dir)
 file.copy(
   system.file("test-data", "DEM.tif", package = "traudem"),
   file.path(test_dir, "DEM.tif")
 )

filled_pit <- taudem_pitremove(file.path(test_dir, "DEM.tif"))
outputs <- taudem_d8flowdir(filled_pit)
outputs
contributing_area_grid <- taudem_aread8(outputs$output_d8flowdir_grid)
contributing_area_grid

D8 Flow Directions

Description

D8 Flow Directions

Usage

taudem_d8flowdir(
  input_elevation_grid,
  output_d8flowdir_grid = NULL,
  output_d8slopes_grid = NULL,
  n_processes = getOption("traudem.n_processes", 1),
  quiet = getOption("traudem.quiet", FALSE)
)

Arguments

input_elevation_grid

Pit filled elevation input data.

output_d8flowdir_grid

D8 flow directions output.

output_d8slopes_grid

D8 slopes output.

n_processes

Number of processes for mpiexec. If NULL TauDEM is called without mpiexec.

quiet

If FALSE output from TauDEM CLI is suppressed.

Details

See https://hydrology.usu.edu/taudem/taudem5/help53/D8FlowDirections.html

Value

List with the two output filenames.

Examples


test_dir <- withr::local_tempdir()
dir.create(test_dir)
 file.copy(
   system.file("test-data", "DEM.tif", package = "traudem"),
   file.path(test_dir, "DEM.tif")
 )
filled_pit <- taudem_pitremove(file.path(test_dir, "DEM.tif"))
outputs <- taudem_d8flowdir(filled_pit)
outputs

Call TauDEM

Description

Call TauDEM

Usage

taudem_exec(
  program,
  args,
  ...,
  n_processes = getOption("traudem.n_processes", 1),
  quiet = getOption("traudem.quiet", FALSE)
)

Arguments

program

TauDEM command (character). See examples.

args

Character vector of arguments. See examples.

...

These dots are for future extensions and must be empty. As a consequence, all following arguments must be fully named (see examples).

n_processes

Number of processes for mpiexec. If NULL TauDEM is called without mpiexec.

quiet

If FALSE output from TauDEM CLI is suppressed.

Details

You can use this function to call more TauDEM methods than the ones with dedicated wrappers in this package. Please refer to the relative TauDEM function documentation for the syntax used to specify optional arguments. See also examples.

Value

TRUE if the call was successful, FALSE otherwise.

Examples


test_dir <- withr::local_tempdir()
dir.create(test_dir)
file.copy(
   system.file("test-data", "DEM.tif", package = "traudem"),
   file.path(test_dir, "DEM.tif")
 )
 # Default name for output file, only input command and input filename.
taudem_exec("pitremove", file.path(test_dir, "DEM.tif"))

# syntax for user-attributed output file name
taudem_exec(
  "pitremove",
  c(
    "-z", file.path(test_dir, "DEM.tif"),
    "-fel", file.path(test_dir,"filled_pits.tif")
  )
)

Move Outlets To Streams

Description

Move Outlets To Streams

Usage

taudem_moveoutletstostream(
  input_d8flowdir_grid,
  input_stream_raster_grid,
  output_moved_outlets_file = NULL,
  om_layer_name = NULL,
  max_dist = NULL,
  outlet_file,
  outlet_layer_name = NULL,
  outlet_layer_number = NULL,
  n_processes = getOption("traudem.n_processes", 1),
  quiet = getOption("traudem.quiet", FALSE)
)

Arguments

input_d8flowdir_grid

File name for D8 flow direction grid (input).

input_stream_raster_grid

File name for stream raster grid (input).

output_moved_outlets_file

Output OGR file where outlets have been moved.

om_layer_name

layer name in movedoutletsfile (optional).

max_dist

maximum number of grid cells to traverse in moving outlet points (optional).

outlet_file

input outlets file (OGR readable dataset).

outlet_layer_name

OGR layer name if outlets are not the first layer in outlet_file (optional). Layer name and layer number should not both be specified.

outlet_layer_number

OGR layer number if outlets are not the first layer in outlet_file (optional). Layer name and layer number should not both be specified.

n_processes

Number of processes for mpiexec. If NULL TauDEM is called without mpiexec.

quiet

If FALSE output from TauDEM CLI is suppressed.

Details

See https://hydrology.usu.edu/taudem/taudem5/help53/MoveOutletsToStreams.html

Value

Path to output file (invisibly).

Pit Remove

Description

Pit Remove

Usage

taudem_pitremove(
  input_elevation_grid,
  output_elevation_grid = NULL,
  only_4way_neighbors = FALSE,
  n_processes = getOption("traudem.n_processes", 1),
  depmask = NULL,
  quiet = getOption("traudem.quiet", FALSE)
)

Arguments

input_elevation_grid

Input elevation grid file.

output_elevation_grid

Output elevation grid file.

only_4way_neighbors

Whether to consider only 4 way neighbors.

n_processes

Number of processes for mpiexec. If NULL TauDEM is called without mpiexec.

depmask

Depression mask file (optional).

quiet

If FALSE output from TauDEM CLI is suppressed.

Details

See https://hydrology.usu.edu/taudem/taudem5/help53/PitRemove.html

Value

Path to output file (invisibly).

Examples


test_dir <- withr::local_tempdir()
dir.create(test_dir)
 file.copy(
   system.file("test-data", "DEM.tif", package = "traudem"),
   file.path(test_dir, "DEM.tif")
 )
output <- taudem_pitremove(file.path(test_dir, "DEM.tif"))
output

TauDEM situation report

Description

Checks installation of TauDEM and provides useful hints.

Usage

taudem_sitrep()

can_register_taudem()

Value

For taudem_sitrep(): None.

For can_register_taudem(): A logical scalar.

TauDEM installation and registration

Once you have installed TauDEM, add an environment variable pointing to the correct path. For instance on Ubuntu it could be adding this line in .Renviron (see usethis::edit_r_environ()) and then re-starting R:

TAUDEM_PATH='/usr/local/taudem'

or, for just the session, running this line of R code:

Sys.setenv(TAUDEM_PATH = "/usr/local/taudem")

Examples


try(taudem_sitrep(), silent = TRUE)

can_register_taudem()

Stream Definition By Threshold

Description

Stream Definition By Threshold

Usage

taudem_threshold(
  input_area_grid,
  output_stream_raster_grid = NULL,
  mask_file = NULL,
  threshold_parameter = 100,
  n_processes = getOption("traudem.n_processes", 1),
  quiet = getOption("traudem.quiet", FALSE)
)

Arguments

input_area_grid

File name for grid to be thresholded.

output_stream_raster_grid

File name for stream raster grid.

mask_file

File name for grid used to mask the output stream raster, or general thresholded grid.

threshold_parameter

Threshold parameter.

n_processes

Number of processes for mpiexec. If NULL TauDEM is called without mpiexec.

quiet

If FALSE output from TauDEM CLI is suppressed.

Details

See https://hydrology.usu.edu/taudem/taudem5/help53/StreamDefinitionByThreshold.html

Value

Path to output file (invisibly).

Examples


test_dir <- withr::local_tempdir()
dir.create(test_dir)
file.copy(
   system.file("test-data", "DEM.tif", package = "traudem"),
   file.path(test_dir, "DEM.tif")
 )
filled_pit <- taudem_pitremove(file.path(test_dir, "DEM.tif"))
outputs <- taudem_d8flowdir(filled_pit)
outputs
contributing_area_grid <- taudem_aread8(outputs$output_d8flowdir_grid)
contributing_area_grid
thresholded <- taudem_threshold(contributing_area_grid)
thresholded

traudem: Use TauDEM

Description

Author(s)

See Also

D8 Contributing Area

Description

Usage

Arguments

Details

Value

Examples

D8 Flow Directions

Description

Usage

Arguments

Details

Value

Examples

Call TauDEM

Description

Usage

Arguments

Details

Value

Examples

Move Outlets To Streams

Description

Usage

Arguments

Details

Value

Pit Remove

Description

Usage

Arguments

Details

Value

Examples

TauDEM situation report

Description

Usage

Value

TauDEM installation and registration

Examples

Stream Definition By Threshold

Description

Usage

Arguments

Details

Value

Examples