R/plot_gof.R

Defines functions .inform_no_variance .to_factor plot.gof.ergm plot.sienaGOF plot.gof.stats.monan plot.ag_gof

Documented in plot.ag_gof plot.gof.ergm plot.gof.stats.monan plot.sienaGOF

#' 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.")
}

Try the autograph package in your browser

Any scripts or data that you put into this service are public.

autograph documentation built on Nov. 16, 2026, 5:08 p.m.