consLettersUtils/R/pivotImp.R

In earlycapistran/miceNls: Conservation Letters Utilities

# =============================================================================
# pivotImp
# earlycapistran@comunidad.unam.mx - August 2020
# =============================================================================

#' @title Pivot imputed data
#' 
#' @description 
#' This function takes a 'mids' object, generated by package 'mice', and 
#' creates a data frame with one long column for all imputed values, a column 
#' indicating the corresponding value of the predictor variable, and a column 
#' indicating to which of the 'm' imputed datasets it belongs. This function is 
#' useful for time-series data, where predictor variable (time) is 
#' complete and response variable values are missing.
#'
#' @param mids A 'mids' object generated by 'mice'
#' @param data Original dataset with missing values
#' @param xVarName A character string with the name of the predictor variable
#' in the original dataset
#' @param yVarName A character string with the name of the response variable in
#' the 'mids' object
#' @return A data frame with three columns
#' @export
#' @usage 
#' pivotImp(mids, data, xVarName, yVarName)
#' 
#' @importFrom tidyr pivot_longer
#' @importFrom magrittr %>% 
#' @importFrom dplyr filter
#' @importFrom dplyr select
#' @importFrom mice is.mids
 
# To run this function, you must have 'dplyr' and 'mice' installed
pivotImp <- function(mids, data, xVarName, yVarName) {
  if (!is.mids(mids)) 
    stop("The data must have class 'mids'")
  if (!is.character(xVarName)) 
    stop("'xVarName' must be a character string")
  if (!is.character(yVarName)) 
    stop("'yVarName' must be a character string")
  # Find which values in predictor variable correspond to missing values 
  # for response variable
  pred_value <- data %>% 
      dplyr::filter(is.na(data[[yVarName]])) %>% 
      dplyr::select(xVarName)
  # Store imputed values as a data frame
  imp_data <- mids$imp
  imp_data <- imp_data[[yVarName]]
  # Bind with corresponding values for predictor variable
  imp_data <- cbind(imp_data, pred_value)
  # Pivot into one long column with all imputed values
  imp_data = imp_data %>% 
    tidyr::pivot_longer(-xVarName, 
                        names_to =  "imputedDataset", 
                        values_to = yVarName)
  colnames(imp_data) <- c(xVarName, "imputedDataset", yVarName)
  return(imp_data)
}