Package 'traudem' reference manual

Title:	Use TauDEM
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.
Authors:	Luca Carraro [cre, aut], University of Zurich [cph, fnd], Maëlle Salmon [aut] , Wael Sadek [aut], Kirill Müller [aut]
Maintainer:	Luca Carraro <[email protected]>
License:	MIT + file LICENSE
Version:	1.0.3
Built:	2025-02-18 04:57:00 UTC
Source:	https://github.com/lucarraro/traudem

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)
)
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

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)
)
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

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)
)
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")
  )
)

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)
)
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)
)
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

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()
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()
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)
)
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

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

Package 'traudem'

Help Index

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