R/DPSD.R

In nklange/fullDPROC: Fitting Dual-Process model to recognition and source memory data

#' Wrapper for fitting the dual-process model to recognition and source memory rating data
#'
#' This function fits the univariate DPSD model (Yonelinas, 1999) to recognition or source memory item-level rating data.
#'
#' The optimization can be attempted by by minimizing the total squared difference (SSE) between observed and
#' predicted cumulative hit and false alarm rates by setting "fitROC = TRUE" (default is fitROC = FALSE) or by minimzing the
#' negative log-likelihood for rating frequencies by setting "fitROC = FALSE". In both cases, fitting is done using the
#' Broyden-Fletcher-Goldfarb-Shanno (BFGS) algorithm in \code{\link{optim}}.
#'
#' When setting fitROC = TRUE, the data is transformed into cumulative hit/fa rates (via cumRates.R) prior to fitting. When
#' setting fitROC = FALSE, the data is transformed into frequency data (via ratingFreq.R) prior to fitting.
#'
#' Arguments in the function allow the user to specify if they are fitting recognition or source memory data,
#' an equal- or unequal-variance model and when fitting source memory data, if a single recollection parameter equal for both
#' sources or two separate recollection parameters are to be estimated.
#'
#' Recollection is bounded to be between 0 and 1, Familiarity and the standard deviation of the target distribution to be positive.
#' Criteria are unbounded, for MLE, criteria are ordered.
#'
#' Each model is fit to each data set for a set number of times (default is iterations = 200), and the iteration with the minimum minimized value
#' is output.
#'
#' @author Nicholas Lange, \email{lange.nk@gmail.com}
#' @param responseScale An vector containing  possible levels of confidence rating responses ordered from highest to lowest (e.g. 6:1).
#' @param confidenceRatings An vector containing participant confidence rating responses to individual items.
#' @param TargetLure An vector coding containing information whether each individual item is a Target or Lure item (e.g. Old, New, Old, Old)
#' @param targetLabel A string/integer designating the label for the target items in TargetLure
#' @param lureLabel A string/integer designating the label for the lure items in TargetLure
#' @param iterations A numeric value specifying the number of iterations. Default is set to 200.
#' @param eqRecollection A boolean value specifying if recollection is set equal for the target and lure source (TRUE) or is estimates separately for both sources (FALSE). Default is set to FALSE.
#' @param eqVar A boolean value specifying if the standard deviation of the target distribution is equal to that of the lure distribution (i.e. = 1) (TRUE) or estimated separately (FALSE). Default is set to TRUE.
#' @param fitSource A boolean value specifying if the model is being fitted to source memory data (TRUE) or recognition memory data (FALSE). Default is set to TRUE
#' @param fitROC A boolean specifying if the model is fitted by minimizing SSE to ROCs or by MLE to rating frequencies
#' @return The function returns a dataframe with components:
#' \item{(parameters)}{The estimated parameters (recollection_target, recollection_lure, familiarity, sd_target, criteria) for the iteration with the lowest SSE or likelihood}
#' \item{SSE if fitROC = TRUE}{Minimum sum square error}
#' \item{negLL if fitROC = FALSE}{negative Log Likelihood}
#' @references Yonelinas, A. P. (1999). The Contribution of Recollection and Familiarity to Recognition and Source-Memory Judgments: A Formal Dual-Process Model and an Analysis of Receiver Operating Characteristics. Journal of Experimental Psychology: Learning, Memory, and Cognition, 25(6), 1415 - 1434. http://doi.org/10.1037//0278-7393.25.6.1415
#' @keywords ROC recollection familiarity DPSD
#' @export
#'
DPSD <- function(responseScale, confidenceRatings, TargetLure, targetLabel, lureLabel,
                 iterations = 200, eqVar = TRUE, eqRecollection = FALSE, fitSource = TRUE, fitROC = FALSE){

  rates   <- cumRates(responseScale, confidenceRatings, TargetLure, targetLabel, lureLabel)
  frequencies   <- ratingFreq(responseScale, confidenceRatings, TargetLure, targetLabel, lureLabel)

  if (fitSource == TRUE & fitROC == TRUE) {
    results <- fitDPSDROCsource(rates$fa, rates$hit, iterations = iterations, eqVar = eqVar, eqRecollection = eqRecollection)
  }
  else if (fitSource == FALSE & fitROC == TRUE){
    results <- fitDPSDROC(rates$fa, rates$hit, iterations = iterations, eqVar = eqVar)
  }
  else if (fitSource == FALSE & fitROC == FALSE){
    results <- fitDPSD(frequencies$fa,frequencies$hit, iterations = iterations, eqVar = eqVar)
  }
  else if (fitSource == TRUE & fitROC == FALSE){
    results <- fitDPSDsource(frequencies$fa,frequencies$hit, iterations = iterations, eqVar = eqVar, eqRecollection = eqRecollection)
  }


  return(results)
}