Merge pull request #332 from 4DModeller/328-joss-review-documentation

Functionality documentation

Author: mnky9800n

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,
@@ -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(

R/shiny_modelbuilder.R

@@ -1,15 +1,15 @@
 #' Interactively set and see the result of different priors
 #'
-#' @param spatial_data Spatial data
-#' @param measurement_data Measurement data
-#' @param time_variable Time variable in measurement_data
-#' @param mesh INLA mesh
+#' @param spatial_data Spatial data (must be SpatialPoints or SpatialPointsDataFrame)
+#' @param measurement_data Measurement data (data.frame, SpatialPointsDataFrame, SpatialPolygonsDataFrame with a named time column and at least 1 named feature column with measurements)
+#' @param time_variable Time variable name in measurement_data
+#' @param mesh INLA/fmesher mesh
 #' @param data_distribution Data distribution, Poisson or Gaussian
-#' @param log_folder Folder to write out logs
+#' @param log_folder Folder to write out logs (character)
 #'
 #' @importFrom INLA f
 #'
-#' @return shiny::app
+#' @return shiny::app with model builder functionality
 #' @keywords internal
 model_builder_shiny <- function(spatial_data,
                                 measurement_data,
@@ -697,12 +697,12 @@ model_builder_shiny <- function(spatial_data,
 #' Interactively set and see the result of different priors
 #'
 #' @param spatial_data Spatial data
-#' @param measurement_data Measurement data
-#' @param time_variable Time variable in measurement_data
-#' @param mesh INLA mesh
-#' @param log_folder Folder to write logs to
+#' @param measurement_data Measurement data (data.frame, SpatialPointsDataFrame, SpatialPolygonsDataFrame with a named time column and at least 1 named feature column with measurements)
+#' @param time_variable Time variable name in measurement_data
+#' @param mesh INLA/fmesher mesh
+#' @param log_folder Folder to write logs to (character)
 #'
-#' @return shiny::app
+#' @return shiny::app with model builder functionality
 #' @export
 model_builder <- function(spatial_data, measurement_data, time_variable, mesh, data_distribution = "Poisson", log_folder = NULL) {
   shiny::runApp(model_builder_shiny(spatial_data = spatial_data, measurement_data = measurement_data, time_variable = time_variable, mesh = mesh, data_distribution = data_distribution, log_folder = log_folder))

R/shiny_modelviewer.R

@@ -1,13 +1,13 @@
 #' Parse inlabru model output
 #'
-#' @param model_output INLA model output
-#' @param mesh INLA mesh
-#' @param measurement_data Measurement data
+#' @param model_output INLA/inlabru model output
+#' @param mesh INLA/fmesher mesh
+#' @param measurement_data Measurement data (can be data.frame, SpatialPoints/SpatialPointsDataFrame, or simple feature collection)
 #' @param data_distribution Type of data, Poisson or Gaussian
 #'
 #' @importFrom magrittr %>%
 #'
-#' @return shiny::app
+#' @return shiny::app with model viewer functionality
 #' @keywords internal
 model_viewer_shiny <- function(model_output, mesh, measurement_data, data_distribution) {
   busy_spinner <- get_busy_spinner()
@@ -297,12 +297,12 @@ model_viewer_shiny <- function(model_output, mesh, measurement_data, data_distri
 
 #' Model viewing shiny app. Visualises INLA model output, plots the posterior distributions of model parameters and prediction statistics.
 #'
-#' @param model_output INLA model output
-#' @param mesh INLA mesh
-#' @param measurement_data Measurement data
-#' @param data_distribution Type of data, Poisson or Gaussian
+#' @param model_output INLA/inlabru model output
+#' @param mesh INLA/fmesher mesh used for the run
+#' @param measurement_data Measurement data used for the run (can be data.frame, SpatialPoints/SpatialPointsDataFrame, or simple feature collection)
+#' @param data_distribution Type of data, Poisson or Gaussian (character)
 #'
-#' @return shiny::app
+#' @return shiny::app with model viewer functionality
 #' @export
 model_viewer <- function(model_output, mesh, measurement_data, data_distribution = "Poisson") {
   shiny::runApp(model_viewer_shiny(model_output = model_output, mesh = mesh, measurement_data = measurement_data, data_distribution = data_distribution))