Nothing
#' Plotting goodness-of-fit results
#' @description
#' These plot methods plot goodness of fit objects created using
#' `RSiena::sienaGOF()`, `MoNAn::monanGOF()`, or the 'ergm' package's gof() function.
#' Internally, the GOF object is translated into a common class (`ag_gof`),
#' which has its own plot method to ensure a consistent look and feel.
#' It is not expected that users will create `ag_gof` class objects themselves.
#'
#' The plot shows a violin plot of the distribution of statistics from the
#' simulations, with a boxplot inside the violin to show the interquartile range,
#' and dashed lines connecting the 5th and 95th percentiles.
#' The boxplot also shows outliers as crosses.
#' The observed statistics are shown as points and connected by a line.
#' The observed statistics are also labelled with their value.
#' If a p-value is available (as in the case of `RSiena::sienaGOF()`),
#' it is shown beneath the x-axis.
#' @details
#' Since these plots methods are in `{autograph}`,
#' the plots are automatically themed according to the current theme
#' set using `stocnet_theme()`.
#' The function uses the highlight colour defined in the current theme
#' to highlight the observed statistics.
#' The function also uses the base colour defined in the current theme
#' to draw the violin and box plots.
#'
#' It is however completely customisable.
#' While a title is automatically generated so that the graph is informative,
#' this can be customised by specifying the `main` argument in the plotting function,
#' or added after the fact using `{ggplot2}` functions such as
#' `ggtitle()` or `labs()`.
#'
#' The user can choose whether to plot the statistics cumulatively or not.
#' This is typically handled within `RSiena::sienaGOF()`,
#' but for `MoNAn::monanGOF()` and the 'ergm' package's gof() function
#' the cumulative option is handled here.
#' The default is to plot the non-cumulative statistics.
#' This is because the non-cumulative statistics are often more interpretable,
#' and the cumulative statistics can be obtained by setting `cumulative = TRUE`.
#'
#' The function also checks whether any of the statistics have zero variance
#' across the simulations, and if so, these statistics are not plotted,
#' with a message to the user indicating which statistics were omitted.
#'
#' Note that these methods overwrite any plot methods for these classes
#' that may be provided by the original packages.
#' You may receive such a warning in the console when loading the package.
#' Please load `{autograph}` after these other packages to ensure the plotting
#' methods included in this package are used,
#' or specify the package when calling the plotting method directly,
#' e.g., `autograph:::plot.sienaGOF(res_siena_gof)`.
#' @name plot_gof
#' @param x An object of class "sienaGOF", "gof.stats.monan", or "gof.ergm".
#' @param cumulative Logical, indicating whether the statistics should be
#' plotted cumulatively (default FALSE).
#' This is typically treated in `sienaGOF()` for `{RSiena}`,
#' but treated within the plotting function for `{MoNAn}` and 'ergm'.
#' @param ... Other parameters to be passed to the plotting function,
#' for example `main = "Title"` for a different title than the default.
#' @returns A violin plot showing the distribution of statistics from the
#' simulations and a line joining points showing the observed statistics.
#' @references
#' Hintze, J. L. and Nelson, R. D. 1998.
#' "Violin plots: A box plot-density trace synergism".
#' _The American Statistician_, 52:181–184.
#' \doi{10.1080/00031305.1998.10480559}
#' @export
plot.ag_gof <- function(x, ...){
obs <- x[[1]]
sims <- x[[2]]
if(all(!is.na(suppressWarnings(as.numeric(sims$name))))){
obs <- obs |> dplyr::mutate(name = .to_factor(name))
sims <- sims |> dplyr::mutate(name = .to_factor(name))
}
main <- x[[3]]
p_value <- x[[4]]
# Compute quantiles for each x
if("ego" %in% names(obs)) {
bounds <- sims |>
dplyr::group_by(name, ego) |>
dplyr::summarise(
q05 = stats::quantile(value, 0.05),
q95 = stats::quantile(value, 0.95),
.groups = "drop")
} else {
bounds <- sims |>
dplyr::group_by(name) |>
dplyr::summarise(
q05 = stats::quantile(value, 0.05),
q95 = stats::quantile(value, 0.95),
.groups = "drop")
}
p <- ggplot2::ggplot(sims, aes(x = name, y = value)) +
ggplot2::geom_violin(scale = "width", trim = FALSE, color = ag_base()) +
ggplot2::geom_boxplot(width = 0.1, outlier.shape = 4,
fill = ag_base()) +
ggplot2::geom_line(data = bounds, aes(x = name, y = q05, group = 1),
linetype = "dashed") +
ggplot2::geom_line(data = bounds, aes(x = name, y = q95, group = 1),
linetype = "dashed") +
ggplot2::geom_point(data = obs, aes(x = name, y = value),
color = ag_highlight()) +
ggplot2::geom_text(data = obs, aes(label = value),
hjust = 0.05, nudge_x = 0.10,
color = ag_highlight()) +
ggplot2::geom_line(data = obs, aes(x = name, y = value),
group = 1,
color = ag_highlight()) +
ag_theme_minimal() +
ggplot2::labs(y = "Statistic", title = main,
x = if(is.null(p_value)) "" else
paste("p:", round(p_value, 3), collapse = " "))
if("ego" %in% names(obs)) {
p <- p + ggplot2::facet_wrap(ggplot2::vars(ego)) +
ggplot2::labs(x = "Alter")
if(!is.null(p_value)) {
p <- p + ggplot2::labs(caption = paste("p:", round(p_value, 3),
collapse = " "))
}
}
p
}
#' @rdname plot_gof
#' @family MoNAn
#' @examples
#' plot(monan_gof)
#' @export
plot.gof.stats.monan <- function(x, cumulative = FALSE, ...) {
args <- list(...)
if (is.null(args$main)) {
main = "Goodness of fit"
} else {
main = args$main
}
obs <- dplyr::tibble(name = as.factor(1:length(x$observed)),
value = x$observed)
simsMat <- Reduce(rbind, x$simulated)
sims.min <- apply(simsMat, 2, min)
sims.max <- apply(simsMat, 2, max)
no_vary <- sims.min == x$observed & sims.min == sims.max
if (any(no_vary)) {
statkeys <- as.character(which(no_vary))
simsMat <- simsMat[,!no_vary]
obs <- obs[!no_vary, ]
.inform_no_variance(statkeys)
}
colnames(simsMat) <- obs$name
rownames(simsMat) <- 1:nrow(simsMat)
sims <- dplyr::tibble(as.data.frame(as.table(simsMat)))
names(sims) <- c("sim", "name", "value")
p_value <- NULL
if(cumulative){
sims <- sims |> dplyr::group_by(sim) |>
dplyr::mutate(value = cumsum(.data$value)) |>
dplyr::ungroup()
obs <- obs |>
mutate(value = cumsum(.data$value))
}
out <- list(obs, sims, main, p_value)
class(out) <- "ag_gof"
plot.ag_gof(out)
}
#' @rdname plot_gof
#' @family RSiena
#' @examples
#' plot(siena_gof, cumulative = TRUE)
#' @export
plot.sienaGOF <- function(x, cumulative = FALSE, ...){
args <- list(...)
if (is.null(args$main)) {
statName <- tolower(add_spaces(attr(x, "auxiliaryStatisticName")))
main <- paste("Goodness of fit of", statName)
if (!attr(x, "joined")) {
main <- paste(main, "Period", period)
}
} else {
main = args$main
}
EA <- attr(x, "EgoAlter")
if(is.null(EA)) EA <- FALSE
if (attr(x, "joined")) {
x <- x[[1]]
} else {
x <- x[[period]]
}
sims <- x$Simulations
sims.min <- apply(sims, 2, min)
sims.max <- apply(sims, 2, max)
if(is.null(colnames(sims)) & !is.null(attr(x, "key"))){
colnames(sims) <- attr(x, "key") # required for GOFs pre RSiena 1.3.20
}
obs <- x$Observations
no_vary <- sims.min == obs & sims.min == sims.max
if (any((diag(stats::var(rbind(sims, obs))) == 0))) {
statkeys <- attr(x, "key")[which(diag(stats::var(rbind(sims, obs))) == 0)]
.inform_no_variance(statkeys)
}
itns <- nrow(sims)
n.obs <- nrow(obs)
sims <- sims[,!no_vary]
sims <- as.data.frame(sims) |> dplyr::mutate(sim = 1:nrow(sims))
sims <- stats::reshape(sims, varying = list(colnames(sims)[-ncol(sims)]),
v.names = "value", timevar = "name", times = colnames(sims)[-ncol(sims)],
idvar = "sim", direction = "long") |>
dplyr::tibble() |> dplyr::arrange(sim)
obs <- obs[!no_vary]
obs <- data.frame(name = sims$name[!duplicated(sims$name)], value = obs)
# if(!cumulative){
# sims <- sims |> dplyr::group_by(sim) |>
# dplyr::mutate(value = c(.data$value[1], diff(.data$value))) |>
# dplyr::ungroup()
# obs <- obs |>
# mutate(value = c(.data$value[1], diff(.data$value)))
# }
if(EA){
if(!all(nchar(obs[,"name"])==2))
manynet::snet_abort("Ego-alter GOF statistic names should be two characters long,",
" but some are not. Please check the number or names in the GOF object.")
obs <- obs |> dplyr::mutate(ego = paste("Ego", substr(name, 1, 1)),
name = substr(name, 2, 2)) |>
dplyr::mutate(ego = .to_factor(ego), name = .to_factor(name))
sims <- sims |> dplyr::mutate(ego = paste("Ego", substr(name, 1, 1)),
name = substr(name, 2, 2)) |>
dplyr::mutate(ego = .to_factor(ego), name = .to_factor(name))
}
out <- list(obs, sims, main, x$p)
class(out) <- "ag_gof"
plot(out)
}
#' @rdname plot_gof
#' @family ergm
#' @param statistic Character, indicating which statistic to plot.
#' Since 'ergm' package GOFs include goodness of fit on multiple statistics,
#' the user must specify which statistic to plot.
#' Options are `"deg"` (degree distribution), `"espart"` (edgewise shared partners),
#' and `"dist"` (geodesic distance).
#' The default is `"deg"`.
#' @examples
#' plot(ergm_gof, statistic = "espart")
#' @export
plot.gof.ergm <- function(x, cumulative = FALSE,
statistic = c("degree","odegree","idegree",
"b1degree","b2degree",
"espartners","dspartners",
# "triadcensus",
"distance"), ...){
statistic <- match.arg(statistic)
args <- list(...)
if(statistic == "degree" && (any(grepl("odeg", names(x))))){
statistic <- "odegree"
manynet::snet_minor_info("Changing to 'odegree' based on available statistics.")
}
if(statistic == "degree" && (any(grepl("b1deg", names(x))))){
statistic <- "b1degree"
manynet::snet_minor_info("Changing to 'b1degree' based on available statistics.")
}
if (is.null(args$main)) {
statdescription <- switch(statistic,
degree = "degree distribution",
idegree = "in-degree distribution",
odegree = "out-degree distribution",
b1degree = "mode 1 degree distribution",
b2degree = "mode 2 degree distribution",
espartners = "edgewise shared partners",
dspartners = "dyadwise shared partners",
# triadcensus = "triad census",
distance = "geodesic distance")
main = paste("Goodness of fit of", statdescription)
} else {
main = args$main
}
if(statistic == "degree") statistic <- "deg"
if(statistic == "idegree") statistic <- "ideg"
if(statistic == "odegree") statistic <- "odeg"
if(statistic == "b1degree") statistic <- "b1deg"
if(statistic == "b2degree") statistic <- "b2deg"
if(statistic == "espartners") statistic <- "espart"
if(statistic == "dspartners") statistic <- "dspart"
if(statistic == "distance") statistic <- "dist"
obs <- data.frame(name = names(x[[paste0("obs.",statistic)]]),
value = x[[paste0("obs.",statistic)]],
stringsAsFactors = FALSE) |>
dplyr::tibble()
if(nrow(obs) == 0){
manynet::snet_abort("Note: {statdescription} {.code {statistic}} is not available in this GOF object.")
}
simsMat <- x[[paste0("sim.",statistic)]]
sims.min <- apply(simsMat, 2, min)
sims.max <- apply(simsMat, 2, max)
no_vary <- sims.min == obs$value & sims.min == sims.max
if (any(no_vary)) {
statkeys <- names(no_vary)[which(no_vary)]
simsMat <- simsMat[,!no_vary]
obs <- obs[!no_vary, ]
.inform_no_variance(statkeys)
}
obs <- obs |> dplyr::mutate(name = .to_factor(name))
sims <- as.data.frame(simsMat, check.names = FALSE)
sims$sim <- 1:nrow(sims)
sims <- stats::reshape(sims,
direction = "long",
varying = list(colnames(sims)[-ncol(sims)]),
v.names = "value",
timevar = "name",
times = colnames(sims)[-ncol(sims)],
idvar = "sim") |>
dplyr::tibble() |>
dplyr::mutate(name = .to_factor(name)) |>
dplyr::arrange(sim)
p_value <- NULL
if(cumulative){
sims <- sims |> dplyr::group_by(sim) |>
dplyr::mutate(value = cumsum(.data$value)) |>
dplyr::ungroup()
obs <- obs |>
mutate(value = cumsum(.data$value))
}
out <- list(obs, sims, main, p_value)
class(out) <- "ag_gof"
plot.ag_gof(out)
}
.to_factor <- function(x) {
# Try coercion to numeric
num_x <- suppressWarnings(as.numeric(x))
# Check if coercion succeeded (no new NAs introduced)
if (!any(is.na(num_x) & !is.na(x))) {
# If coercible, convert to numeric first, then factor
factor(num_x)
} else {
# Otherwise, convert directly to factor
factor(x)
}
}
# Statistics that never vary across the simulations produce a degenerate violin,
# so they are dropped from the plot. Said in one place because three of the GOF
# plot methods have to report it.
.inform_no_variance <- function(statkeys) {
snet_info("Not plotting the statistic{?s} {.val {statkeys}},",
"because {?it does/they do} not vary across the simulations,",
"so there is no distribution to show.")
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.