Merge pull request #344 from 4DModeller/devel

 merge devel into joss

Author: mnky9800n

CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- Removed non-numeric/non-logical variable features from `shiny_modelbuilder` - [PR #341](https://github.com/4DModeller/fdmr/pull/341)
+- Updated documentation for all functions to reflect better the inputs and outputs - [PR #332](https://github.com/4DModeller/fdmr/pull/332)
+- Fixed an error in `model_viewer` description - [PR #331](https://github.com/4DModeller/fdmr/pull/331)
+- Added to `retrieve_tutorial_data` an option to save tutorial data at a user-specified location or in a temporary directory as default - [PR #330](https://github.com/4DModeller/fdmr/pull/330)
 - Fixed `model_viewer` app to work with random effect models - [PR #317](https://github.com/4DModeller/fdmr/pull/317)
 - Updated `plot_map_leaflet` to feature the same selection of basemap tiles as `mapview` and fix features not appearing - [PR #310](https://github.com/4DModeller/fdmr/pull/310)
 

DESCRIPTION

@@ -16,7 +16,7 @@ BugReports: https://github.com/4DModeller/fdmr/issues
 License: GPL (>= 3)
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.3
+RoxygenNote: 7.3.2
 Additional_repositories: https://inla.r-inla-download.org/R/testing
 Imports: 
     colorspace,

R/meshing.R

@@ -1,10 +1,10 @@
 # This function taken from https://groups.google.com/g/r-inla-discussion-group/c/z1n1exlZrKM/m/8vYNr2D8BwAJ
 #' Convert an INLA mesh to a SpatialPolygonsDataFrame
 #'
-#' @param mesh Mesh
-#' @param crs Coordinate Reference System as proj4string
+#' @param mesh Mesh object from INLA or fmesher (only R2 manifolds are valid)
+#' @param crs Coordinate Reference System as proj4string, does not support geocentric coordinates
 #'
-#' @return SpatialPolygonsDataFrame
+#' @return SpatialPolygonsDataFrame with mesh triangles
 #' @export
 mesh_to_spatial <- function(mesh, crs) {
   if (!is.character(crs)) {

R/meshing_checks.R

@@ -3,8 +3,8 @@
 #' 2. A greater number of mesh triangles than observations
 #' 3. Isolated triangles in mesh
 #'
-#' @param mesh INLA mesh
-#' @param observations Observations data to be used woith model
+#' @param mesh INLA/fmesher mesh
+#' @param observations Observations data to be used with model (can be data.frame, SpatialPoints/SpatialPointsDataFrame, or simple feature collection)
 #'
 #' @return list: Named list containing errors
 #' @export

R/model_parse.R

@@ -1,9 +1,9 @@
 #' Parses inlabru::bru model output to create a list of model parameters
 #'
 #' @param model_output Output from running inlabru::bru
-#' @param measurement_data Measurement data
+#' @param measurement_data Measurement data (can be data.frame, SpatialPoints/SpatialPointsDataFrame, or simple feature collection)
 #'
-#' @return list
+#' @return Creates a list of model outputs for the first timestep, including fitted mean and sd, mean of fixed effects, mean and sd of random effects, posterior hyperparameters, and DIC
 #' @keywords internal
 parse_model_output_bru <- function(model_output, measurement_data) {
   fitted_mean_post <- model_output$summary.fitted.values$mean[seq_len(nrow(measurement_data))]
@@ -33,11 +33,11 @@ parse_model_output_bru <- function(model_output, measurement_data) {
 
 #' Parse model output to create a list of model parameters
 #'
-#' @param model_output Data returned by model
-#' @param measurement_data Measurement data
-#' @param model_type Type of model, we currently support inlabru
+#' @param model_output Output returned by model (currently only from running inlabru::bru)
+#' @param measurement_data Measurement data (can be data.frame, SpatialPoints/SpatialPointsDataFrame, or simple feature collection)
+#' @param model_type Type of model, we currently only support inlabru
 #'
-#' @return list
+#' @return Creates a list of model outputs, including fitted mean and sd, mean of fixed effects, mean and sd of random effects, posterior hyperparameters, and DIC
 #' @export
 parse_model_output <- function(model_output, measurement_data, model_type = "inlabru") {
   if (model_type == "inlabru") {
@@ -48,13 +48,13 @@ parse_model_output <- function(model_output, measurement_data, model_type = "inl
 
 #' Create a prediction field from the parsed model output and the mesh
 #'
-#' @param mesh INLA mesh
-#' @param plot_type Type of plot to create, "predicted_mean_fields" etc
-#' @param data_dist Type of data, "poisson" etc
-#' @param var_a Data for variable a, required for "predicted_mean_fields" and "random_effect_fields"
-#' @param var_b Data for variable b, required for "predicted_mean_fields"
+#' @param mesh INLA/fmesher mesh
+#' @param plot_type Type of plot to create, "predicted_mean_fields" or "random_mean_fields"
+#' @param data_dist Type of data, "poisson" or "gaussian"
+#' @param var_a Data for variable a (numeric), required for "predicted_mean_fields" and "random_effect_fields"; normally, random effect field from "summary.random$f"
+#' @param var_b Data for variable b (numeric), required for "predicted_mean_fields"; normally, fixed effect from "summary.fixed"
 #'
-#' @return data.frame
+#' @return data.frame with mesh node latlong coordinates (x, y) and the selected field values at the mesh nodes (z)
 #' @export
 create_prediction_field <- function(mesh,
                                     plot_type = "predicted_mean_fields",

R/plot_graph.R

@@ -1,9 +1,9 @@
 #' Plot a bar chart using ggplot2
 #'
-#' @param data Data to plot
-#' @param x x-axis data
+#' @param data Data to plot (all data types recognised by ggplot2::geom_bar() like data.frame)
+#' @param x x-axis data, must be a Date object
 #' @param y y-axis data
-#' @param breaks Break points
+#' @param breaks Break points, must be a sequence of dates
 #' @param x_label x-axis label
 #' @param y_label y-axis label
 #' @param fill Fill colour
@@ -47,10 +47,10 @@ plot_barchart <- function(data, x, y, breaks, x_label, y_label, fill = "pink", c
 
 #' Plot a boxplot using ggplot2
 #'
-#' @param data Data to plot
-#' @param x x-axis data
+#' @param data Data to plot (all data types recognised by ggplot2::geom_boxplot() like data.frame)
+#' @param x x-axis data, must be a Date object
 #' @param y y-axis data
-#' @param breaks Break points
+#' @param breaks Break points, must be a sequence of dates
 #' @param x_label x-axis label
 #' @param y_label y-axis label
 #'
@@ -82,19 +82,19 @@ plot_boxplot <- function(data, x, y, breaks, x_label, y_label) {
 
 #' Plot timeseries data
 #'
-#' @param data Data to plot
-#' @param x Name of column to plot on x-axis, should be datetime, will be converted to Dates using as.Date
+#' @param data Data to plot (data.frame with x-axis column a character convertible to Date)
+#' @param x Name of column to plot on x-axis
 #' @param y Name of column to plot on y-axis
-#' @param breaks Date break points
+#' @param breaks Date break points, must be a sequence of dates
 #' @param x_label x-axis label
 #' @param y_label y-axis label
 #' @param title Figure title
 #' @param line_width Line width
 #' @param line_colour Line colour
 #' @param horizontal_y y-intercept for horizontal line
 #' @param vertical_x x-intercept for vertical line
-#' @param x_lim Limits for x-axis continous scale, vector passed to scale_x_continuous
-#' @param y_lim Limits for y-axis continuous scale, vector passed to scale_y_continous
+#' @param x_lim Limits for x-axis continuous scale, vector passed to scale_x_continuous
+#' @param y_lim Limits for y-axis continuous scale, vector passed to scale_y_continuous
 #'
 #' @return ggplot
 #' @export
@@ -172,12 +172,12 @@ plot_timeseries <- function(data,
 
 #' Create a line plot with a confidence interval.
 #'
-#' @param data Data to plot
-#' @param x x-axis data
+#' @param data Data to plot (all data types recognised by ggplot2::geom_line() like data.frame)
+#' @param x x-axis data, must be a Date object
 #' @param y1 y1 line data - solid
 #' @param y2 y2 line data - dashed
 #' @param y3 y3 line data - dashed
-#' @param breaks Breaks vector
+#' @param breaks Breaks vector, must be a sequence of dates
 #' @param x_label x-axis label
 #' @param y_label y-axis label
 #' @param y1_colour Colour for y1

R/plot_mapping.R

@@ -6,10 +6,10 @@
 #' The leaflet backend will work for most use cases and is recommended.
 #' For plotting of maps with UTM coordinates, the mapview backend is recommended.
 #'
-#' @param polygon_data Polygon data
-#' @param raster_data Raster datas
-#' @param domain Domain data to be passed to leaflet::colorNumeric and leaflet::addLegend
-#' @param markers Markers to display on map. A named list with latitude, longitude and label names must be given.
+#' @param polygon_data Polygon data (SpatialPolygon or SpatialPolygonDataFrame)
+#' @param raster_data Raster data (RasterLayer or SpatialRaster)
+#' @param domain Domain data (numeric or factor) to be passed to leaflet::colorNumeric and leaflet::addLegend
+#' @param markers Markers to display on map. A named list or data.frame with latitude, longitude and label names must be given.
 #' @param palette Palette to be used for colours, defaults to viridis
 #' @param legend_title Title for legend
 #' @param add_scale_bar Add scale bar if TRUE
@@ -71,10 +71,10 @@ plot_map <- function(polygon_data = NULL,
 
 #' Create a simple Leaflet map from data
 #'
-#' @param polygon_data Polygon data
-#' @param raster_data Raster data
-#' @param domain Domain data to be passed to leaflet::colorNumeric and leaflet::addLegend
-#' @param markers Markers to display on map. A named list with latitude, longitude and label names must be given.
+#' @param polygon_data Polygon data (SpatialPolygon or SpatialPolygonDataFrame)
+#' @param raster_data Raster data (RasterLayer or SpatialRaster)
+#' @param domain Domain data (numeric or factor) to be passed to leaflet::colorNumeric and leaflet::addLegend
+#' @param markers Markers to display on map. A named list or data.frame with latitude, longitude and label names must be given.
 #' @param palette Palette to be used for colours, defaults to viridis
 #' @param legend_title Title for legend
 #' @param add_scale_bar Add scale bar if TRUE

R/plot_mesh.R

@@ -1,14 +1,14 @@
 #' Plot a mesh on a Leaflet map
 #'
-#' @param mesh Mesh data
+#' @param mesh Mesh object from INLA or fmesher
 #' @param spatial_data Spatial data, either a SpatialPolygonsDataFrame, SpatialPointsDataFrame or an object
 #' that can be converted to a data.frame with longitude and latitude columns
-#' @param longitude_column Longitude column in spatial_data
-#' @param latitude_column Latitude column in spatial_data name
+#' @param longitude_column Longitude column name in spatial_data
+#' @param latitude_column Latitude column name in spatial_data
 #' @param markers Markers to display on top of mesh. A named list with latitude, longitude and label names must be given.
 #' Expects longitude name to be longitude, latitude name to be latitude, label name to be label.
 #'
-#' @return leaflet::leaflet
+#' @return leaflet::leaflet with mesh and markers
 #' @export
 plot_mesh <- function(mesh, spatial_data = NULL, longitude_column = "LONG", latitude_column = "LAT", markers = NULL) {
   expected_crs <- "+proj=longlat +datum=WGS84"

R/plot_priors.R

@@ -1,10 +1,11 @@
 #' Plot line comparison for stdev etc
 #'
-#' @param data Parsed model output
+#' @param data List of parsed model outputs from "parse_model_output" (a list of lists)
 #' @param to_plot Type of data to plot, "Range for f" etc
+#' @param title Title of the plot, defaults to the value of "to_plot"
 #'
-#' @return ggplot2::ggplot
-plot_line_comparison <- function(data, to_plot, title) {
+#' @return ggplot2::ggplot of the selected hyperparameter posterior distribution
+plot_line_comparison <- function(data, to_plot, title = to_plot) {
   parsed_data <- purrr::map(data, function(x) as.data.frame(x$pars[[to_plot]]))
   single_df <- dplyr::bind_rows(parsed_data, .id = "Run")
   if (nrow(single_df) == 0) {
@@ -19,9 +20,9 @@ plot_line_comparison <- function(data, to_plot, title) {
 
 #' Create boxplots from priors run data
 #'
-#' @param data
+#' @param data A list of parsed model output from "parse_model_output" (a list of lists)
 #'
-#' @return graphics::boxplot
+#' @return graphics::boxplot of fitted values
 plot_priors_boxplot <- function(data) {
   # TODO - I'm sure this can be done in a nicer functional way
   fitted_mean_post <- purrr::map(data, function(x) x$fitted_mean_post)
@@ -34,10 +35,10 @@ plot_priors_boxplot <- function(data) {
 #' Plot density function
 #'
 #'
-#' @param data Parsed model outputs
-#' @param measurement_data Measurement data
+#' @param data List of parsed model outputs from "parse_model_output" (a list of lists)
+#' @param measurement_data Measurement data (can be data.frame, SpatialPoints/SpatialPointsDataFrame, or simple feature collection)
 #'
-#' @return ggplot2::ggplot
+#' @return ggplot2::ggplot of measurement density by value
 plot_priors_density <- function(data, measurement_data) {
   # Can this be done in a cleaner way? Just create a dataframe from the lists?
   fitted_values <- unlist(purrr::map(data, function(x) x$fitted_mean_post))
@@ -56,9 +57,9 @@ plot_priors_density <- function(data, measurement_data) {
 
 #' Plot Deviance Information Criterion (DIC) values
 #'
-#' @param data
+#' @param data List of parsed model outputs from "parse_model_output" (a list of lists)
 #'
-#' @return ggplot2::ggplot
+#' @return ggplot2::ggplot with DIC values shown as points
 plot_dic <- function(data) {
   infocri <- base::cbind.data.frame(
     priors = unlist(purrr::map(seq(1, length(data)), function(x) paste("Run", x))),

R/shiny_meshbuilder.R

@@ -1,6 +1,6 @@
 #' Mesh building shiny app
 #'
-#' @param spatial_data Spatial data
+#' @param spatial_data Spatial data (must be a data.frame, SpatialPointsDataFrame or SpatialPolygonsDataFrame)
 #' @param obs_data Measurement data
 #' @param crs CRS as a proj4string
 #' @param offset Specifies the size of the inner and outer extensions around data locations, passed to fmesher::fm_mesh_2d_inla
@@ -11,7 +11,7 @@
 #'
 #' @importFrom magrittr %>%
 #'
-#' @return shiny::app
+#' @return shiny::app with meshbuilder functionality
 #' @keywords internal
 meshbuilder_shiny <- function(
     spatial_data,
@@ -55,10 +55,10 @@ meshbuilder_shiny <- function(
     stop("Cannot read latitude and longitude data from spatial data. Please ensure given names are correct.")
   }
 
-  default_max_edge_min <- 0.01
-  default_max_edge_max <- 0.3
+  default_max_edge_min <- 0.9
+  default_max_edge_max <- 1.8
   default_offset_min <- 0.02
-  default_offset_max <- 0.2
+  default_offset_max <- 2
   default_cutoff <- 0.02
   # TODO - these defaults need changing?
   if (!is.null(max_edge)) {
@@ -234,7 +234,7 @@ meshbuilder_shiny <- function(
         spatial_data
       }
     })
-
+    
     output$map <- leaflet::renderLeaflet({
       map_tiles <- c("OpenStreetMap", "Esri.WorldImagery", "OpenTopoMap")
       m <- mapview::mapview(mesh_spatial(), layer.name = "Mesh", col.regions = "#548C2F", map.types = map_tiles) + mapview::mapview(spatial(), layer.name = "Spatial")
@@ -270,7 +270,7 @@ meshbuilder_shiny <- function(
 
 #' Mesh building shiny app. Creates and visualises a mesh from some spatial data.
 #'
-#' @param spatial_data Spatial data
+#' @param spatial_data Spatial data (must be a data.frame, SpatialPointsDataFrame or SpatialPolygonsDataFrame)
 #' @param obs_data Measurement data
 #' @param crs CRS as a proj4string
 #' @param offset Specifies the size of the inner and outer extensions around data locations, passed to fmesher::fm_mesh_2d_inla
@@ -279,7 +279,7 @@ meshbuilder_shiny <- function(
 #' @param y_coord Name of the latitude column in the spatial data
 #' @param x_coord Name of the longitude column in the spatial data
 #'
-#' @return shiny::app
+#' @return shiny::app with meshbuilder functionality
 #' @export
 mesh_builder <- function(spatial_data, obs_data = NULL, crs = NULL, max_edge = NULL, offset = NULL, cutoff = NULL, y_coord = "LAT", x_coord = "LONG") {
   shiny::runApp(meshbuilder_shiny(