Merge pull request #41 from FluvialGeomorph/add_L2_report_b

Add l2 report b

NEWS.md

@@ -1,3 +1,15 @@
+# FluvialGeomorph v0.2.3 (Release date: 2024-06-28)
+
+## Major Changes
+* Added the report `Report - L2 b` that displays cross sections plots disaggregated by extent. 
+* Added the report `XS Compare Plot, L2` that plots XS points for a specified extent of the cross section. 
+
+## Bug Fixes
+* Updated tool documentation to add many missing parameter descriptions. 
+
+***
+
+
 # FluvialGeomorph v0.2.2 (Release date: 2024-05-26)
 
 ## Major Changes

Readme.md

@@ -6,7 +6,7 @@ The FluvialGeomorph ArcGIS toolbox provides a set of tools for extracting river
 [![Maturing](https://img.shields.io/badge/lifecycle-maturing-blue.svg)](https://www.tidyverse.org/lifecycle)
 [![Project Status: Active The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
 [![packageversion](https://img.shields.io/badge/Package%20version-0.2.3-orange.svg?style=flat-square)](commits/master)
-[![Last-changedate](https://img.shields.io/badge/last%20change-2024--06--04-yellowgreen.svg)](/commits/master)
+[![Last-changedate](https://img.shields.io/badge/last%20change-2024--06--28-yellowgreen.svg)](/commits/master)
 [![Licence](https://img.shields.io/badge/licence-CC0-blue.svg)](http://choosealicense.com/licenses/cc0-1.0/)
 
 ## Description

report/_Level_2_Report_b.R

@@ -0,0 +1,140 @@
+#' @title Level 2 Report b
+#' 
+#' @description  Creates the FluvialGeomorph Level 2 report b.
+#'
+#' @export
+#' @param stream             character; The stream name. The stream name must
+#'                           match a stream name in `ReachName` field in the
+#'                           other parameters.
+#' @param flowline_fc        character; The path to a `flowline` feature class.
+#' @param xs_fc              character; The path to the cross section feature
+#'                           class.
+#' @param xs_dims_fc         character; The path to a Level 2 cross section
+#'                           feature class.
+#' @param xs_points_1        character; The path to a `xs_points` feature
+#'                           class for the "base year".
+#' @param xs_points_2        character; The path to a `xs_points` feature
+#'                           class for the second time period.
+#' @param xs_points_3        character; The path to a `xs_points` feature
+#'                           class for the third time period.
+#' @param xs_points_4        character; The path to a `xs_points` feature
+#'                           class for the fourth time period.
+#' @param survey_name_1      character: The name or date of the "base year"
+#'                           survey.
+#' @param survey_name_2      character: The name or date of the second survey.
+#' @param survey_name_3      character: The name or date of the third survey.
+#' @param survey_name_4      character: The name or date of the fourth survey.
+#' @param features_fc        character; The path to a `features` feature class.
+#' @param channel_fc         character; The path to the `channel` polygon
+#'                           feature class.
+#' @param floodplain_fc      character; The path to the `floodplain` polygon
+#'                           feature class.
+#' @param dem                character; The path to the DEM raster.
+#' @param bf_estimate        numeric; Detrended bankfull estimate (units:
+#'                           detrended feet).
+#' @param regions            character vector; Regions to calculate hydraulic
+#'                           dimensions for. See the `RegionalCurve` package for
+#'                           a list of regions.
+#' @param label_xs           logical; Label cross sections?
+#' @param show_xs_map        logical; Add the cross section maps to the report?
+#' @param profile_units      character; The units of the longitudinal profile.
+#'                           One of "kilometers", "meters", "miles", or "feet".
+#' @param aerial             logical; Display an overview map with an aerial
+#'                           photo background?
+#' @param elevation          logical; Display an overview map with an elevation
+#'                           background?
+#' @param xs_label_freq      numeric; An integer indicating the frequency of
+#'                           cross section labels.
+#' @param exaggeration       numeric; The degree of terrain exaggeration.
+#' @param extent_factor      numeric; The amount the extent is expanded around
+#'                           the cross section feature class. Values greater
+#'                           than one zoom out, values less than one zoom in.
+#' @param output_dir         character; The path to the folder in which to
+#'                           write the report.
+#' @param output_format      character; The file format of the report. One of
+#'                           "html_document", "word_document", "pdf_document".
+#'
+#' @return Produces a FluvialGeomorph Level 2 Report b in the `output_dir` in 
+#' the requested file format.
+#'
+tool_exec <- function(in_params, out_params) {
+    # Declare location of script within the toolbox
+    here::i_am("report/_Level_2_Report_b.R")
+    # Load utility R functions
+    fg_utils <- here::here("install", "FG_utils.R")
+    source(fg_utils)
+    message("Sourced utility functions: ", fg_utils)
+    # Load required libraries
+    load_packages(c("sf", "tmap", "rmarkdown", "ggplot2", "maptiles", 
+                    "terrainr", "terra", "tibble", "fluvgeo"))
+
+    # Ensure pandoc can be found
+    message("Setting pandoc directory...")
+    set_pandoc()
+
+    # gp tool parameters
+    stream             <- in_params[[1]]
+    flowline_fc        <- in_params[[2]]
+    xs_fc              <- in_params[[3]]
+    xs_dims_fc         <- in_params[[4]]
+    xs_points_1        <- in_params[[5]]
+    xs_points_2        <- in_params[[6]]
+    xs_points_3        <- in_params[[7]]
+    xs_points_4        <- in_params[[8]]
+    survey_name_1      <- in_params[[9]]
+    survey_name_2      <- in_params[[10]]
+    survey_name_3      <- in_params[[11]]
+    survey_name_4      <- in_params[[12]]
+    features_fc        <- in_params[[13]]    
+    channel_fc         <- in_params[[14]]
+    floodplain_fc      <- in_params[[15]]
+    dem                <- in_params[[16]]
+    bf_estimate        <- in_params[[17]]
+    regions            <- c(in_params[[18]], recursive = TRUE)
+    label_xs           <- in_params[[19]]
+    show_xs_map        <- in_params[[20]]
+    profile_units      <- in_params[[21]]
+    aerial             <- in_params[[22]]
+    elevation          <- in_params[[23]]
+    xs_label_freq      <- in_params[[24]]
+    exaggeration       <- in_params[[25]]
+    extent_factor      <- in_params[[26]]
+    output_dir         <- in_params[[27]]
+    output_format      <- in_params[[28]]
+
+    # Verify parameters
+    ## Create list of parameters (named using the parameter names)
+    param_list <- tibble::lst(stream, flowline_fc, xs_fc, xs_dims_fc,
+                              xs_points_1, xs_points_2,
+                              xs_points_3, xs_points_4,
+                              survey_name_1, survey_name_2,
+                              survey_name_3, survey_name_4,
+                              features_fc, channel_fc, floodplain_fc,
+                              dem, 
+                              bf_estimate, regions, label_xs, 
+                              show_xs_map, profile_units,
+                              aerial, elevation, 
+                              xs_label_freq, exaggeration, extent_factor,
+                              output_dir, output_format)
+
+    ## Get parameter verification table
+    message("Compare input tool parameters")
+    param_table <- compare_params(in_params, param_list)
+    print(tibble::as_tibble(param_table), n = 28)
+
+    # Render the report
+    fluvgeo::level_2_report_b(stream, flowline_fc, xs_fc, xs_dims_fc,
+                              xs_points_1, xs_points_2,
+                              xs_points_3, xs_points_4,
+                              survey_name_1, survey_name_2,
+                              survey_name_3, survey_name_4,
+                              features_fc, channel_fc, floodplain_fc,
+                              dem, 
+                              bf_estimate, regions, label_xs, 
+                              show_xs_map, profile_units,
+                              aerial, elevation, 
+                              xs_label_freq, exaggeration, extent_factor,
+                              output_dir, output_format)
+
+    return(out_params)
+}

report/_XS_Compare_Plot_L2.R

@@ -0,0 +1,77 @@
+#' @title Cross Section Compare Plot, Level 2
+#' 
+#' @description Produces a cross section profile plot for the specified cross
+#' section for the input surveys.
+#'     
+#' @export
+#' @param stream          character; The name of the stream.
+#' @param xs_number       integer; The cross section `Seq` number.
+#' @param xs_points_1     character; Path to the cross section points feature 
+#'                        class of the first survey.
+#' @param xs_points_2     character; Path to the cross section points feature 
+#'                        class of the second survey. 
+#' @param xs_points_3     character; Path to the cross section points feature 
+#'                        class of the third survey.
+#' @param xs_points_4     character; Path to the cross section points feature 
+#'                        class of the fourth survey.
+#' @param survey_name_1   character; the label to use for the first survey.
+#' @param survey_name_2   character; the label to use for the second survey.
+#' @param survey_name_3   character; the label to use for the third survey.
+#' @param survey_name_4   character; the label to use for the fourth survey.
+#' @param bf_elevation    numeric; The detrended bankfull elevation (in
+#'                        feet) that is used to calculate hydraulic
+#'                        geometry.
+#' @param aspect_ratio    numeric; The aspect ratio of the graph.
+#' @param extent          character; The extent of the cross section to
+#'                        plot. One of "all", "floodplain", or "channel".
+#' 
+#' @return A ggplot object
+#'
+tool_exec <- function(in_params, out_params) {
+    # Declare location of script within the toolbox
+    here::i_am("report/_XS_Compare_Plot_L2.R")
+    # Load utility R functions
+    fg_utils <- here::here("install", "FG_utils.R")
+    source(fg_utils)
+    message("Sourced utility functions: ", fg_utils)
+    # Load required libraries
+    load_packages(c("dplyr", "purrr", "ggplot2"))
+
+    # gp tool parameters
+    stream          <- in_params[[1]]
+    xs_number       <- in_params[[2]]
+    xs_points_1     <- in_params[[3]]
+    xs_points_2     <- in_params[[4]]
+    xs_points_3     <- in_params[[5]]
+    xs_points_4     <- in_params[[6]]
+    survey_name_1   <- in_params[[7]]
+    survey_name_2   <- in_params[[8]]
+    survey_name_3   <- in_params[[9]]
+    survey_name_4   <- in_params[[10]]
+    bf_elevation    <- in_params[[11]]
+    aspect_ratio    <- in_params[[12]]
+    extent          <- in_params[[13]]
+
+    # Create list of survey paths
+    xs_points_paths <- list(xs_points_1, xs_points_2, xs_points_3, xs_points_4)
+
+    # Name the survey paths list by their survey names
+    survey_names <- c(survey_name_1, survey_name_2, survey_name_3, survey_name_4)
+    xs_points_paths <- setNames(xs_points_paths, survey_names)
+
+    # Eliminate empty surveys
+    xs_points_paths <- purrr::discard(xs_points_paths, is.null)
+
+    # Convert list of survey paths to list of sf objects
+    xs_pts_sf_list <- purrr::map(xs_points_paths, fluvgeo::fc2sf)
+
+    # Call the graph function
+    print(fluvgeo::xs_compare_plot_L2(stream = stream,
+                                      xs_number = xs_number,
+                                      xs_pts_sf_list = xs_pts_sf_list,
+                                      bankfull_elevation = bf_elevation,
+                                      aspect_ratio = aspect_ratio,
+                                      extent = extent))
+
+    return(out_params)
+}