MC_analysis_GRID.R

##################################################################################
# NAME:         MC_analysis_GRID.R
# AUTHOUR:      Alan Davies
# DATE:         05/12/2017
# INSTITUTION:  Interaction Analysis and Modelling Lab (IAM), University of Manchester
# DESCRIPTION:  Markov chain analysis of bi-gram transition for the second ECG 
#               experiement. Analsis using AOIs generated by grid using DBSCAN.
#               Uses the Jensen-Shannon distance and the Hellinger distance
#               metrics that can be chosen (input at runtime).
#               Analysis for HPC vs no HPC for those seeing either first.
##################################################################################

#---------------------------------------------------------------------------------
# FUNCTION:     openDataFiles()
# INPUT:        String, vector
# OUTPUT:       list
# DESCRIPTION:  Returns a list of data files accessable by label
#                
#---------------------------------------------------------------------------------
openDataFiles <- function(file_path, conditions)
{
    data_files <- list()
 
    for(i in 1:length(conditions))
    {
        # load the file
        data_file <- read.csv(paste0(file_path, conditions[i]), 
                              header = TRUE, na.strings = c(" ", "NA", "-"))
        
        # store it in list by label
        data_files[[paste0("condition_", i)]] <- data_file
    }

    return(data_files)
}

#---------------------------------------------------------------------------------
# FUNCTION:     openDataFile()
# INPUT:        String
# OUTPUT:       data.frame
# DESCRIPTION:  Returns a data frame of the requested file
#                
#---------------------------------------------------------------------------------
openDataFile <- function(file_path)
{
    data_file <- read.csv(paste0(file_path), header = TRUE, na.strings = c(" ", "NA", "-"))
    return(data_file)
}

#---------------------------------------------------------------------------------
# FUNCTION:     getPresentationSequence()
# INPUT:        data.frame, String
# OUTPUT:       vector
# DESCRIPTION:  Returns a vector of participant ID's for a specified presentation
#               sequence
#---------------------------------------------------------------------------------
getPresentationSequence <- function(data, presentation_seq)
{
    data <- data[!duplicated(data$Participant), ]
    return(as.vector(data[data$PresentationSequence == presentation_seq, "Participant"]))
}

#---------------------------------------------------------------------------------
# FUNCTION:     loadPackages(package.args)
# INPUT:        vector
# OUTPUT:       void
# DESCRIPTION:  Loads required packages.
#                
#---------------------------------------------------------------------------------
loadPackages <- function(package.args)
{ 
    for(i in package.args)
    {
        if(!is.element(i, .packages(all.available = TRUE)))
        {
            #cat("\nPackage <", i, "> not found, attempting to add it...\n\n")
            install.packages(i)
        }
        library(i, character.only = TRUE)
    }
}

#---------------------------------------------------------------------------------
# FUNCTION:     initialize()
# INPUT:        void
# OUTPUT:       void
# DESCRIPTION:  Set up function for adding packages and other source data
#               
#---------------------------------------------------------------------------------
initialize <- function()
{
    # required packages list
    package.args <- c("ggplot2", "crayon", "dplyr", "plyr", "tidyr") #, "grDevices", "lattice", "plotrix", 
                      
    
    # load packages and set working dir
    loadPackages(package.args)
    setwd(path.expand("~"))
}

#---------------------------------------------------------------------------------
# FUNCTION:     convertToMatrix()
# INPUT:        data.frame, BOOL
# OUTPUT:       matrix
# DESCRIPTION:  Returns matrix representing probabilty of AOI transitions
#               
#---------------------------------------------------------------------------------
convertToMatrix <- function(data, diagonal = TRUE)
{
    tmp0 <- data
    tmp <- tmp0 %>% group_by(participant) %>% mutate(to = lead(AOI))
    tmp2 <- tmp[complete.cases(tmp), ]
    with(tmp2, table(AOI, to))
    out_mat <- as.matrix(with(tmp2, table(AOI, to)))
    
    # can remove diagonal
    if(!diagonal) diag(out_mat) <- 0
    
    # produce probability matrix
    prob_mat <- out_mat / rowSums(out_mat)
    return(prob_mat)
}

#---------------------------------------------------------------------------------
# FUNCTION:     convertToPrior()
# INPUT:        matrix
# OUTPUT:       matrix
# DESCRIPTION:  Bayesian prior (Dirichlet) method
#               
#---------------------------------------------------------------------------------
convertToPrior <- function(data)
{
    m <- 0
    matrix_len <- nrow(data) 
    for(i in 1:matrix_len)
    {
        m <- sum(data[i, ] * 10)
        for(j in 1:matrix_len)
            data[i, j] <- ((data[i, j] * 10) + 1) / (m + matrix_len)
    }
    return(data)
}

#---------------------------------------------------------------------------------
# FUNCTION:     calculateJSDistance()
# INPUT:        matrix, matrix
# OUTPUT:       double
# DESCRIPTION:  Computes correct Jensen-Shannon distance between two matrices
#               
#---------------------------------------------------------------------------------
calculateJSDistance <- function(m1, m2)
{
    results <- list()
    JS_distance <- 0
    summed_JS_distance <- 0
    matrix_length <- nrow(m1)
    coeff1 <- 0
    coeff2 <- 0
    
    for(i in 1:matrix_length)
    {
        for(j in 1:matrix_length)
        {
            # calculate KLD per row
            coeff1 <- coeff1 + (m1[i, j] * log(m1[i, j] / (0.5 * (m1[i, j] + m2[i, j]))))
            coeff2 <- coeff2 + (m2[i, j] * log(m2[i, j] / (0.5 * (m1[i, j] + m2[i, j])))) 
        }
        JS_distance <- sqrt(0.5 * (coeff1 + coeff2))
        summed_JS_distance <- summed_JS_distance + JS_distance
        JS_distance <- 0
        coeff1 <- 0
        coeff2 <- 0
    }
    average_distance <- summed_JS_distance / matrix_length
    return(average_distance)
}

#---------------------------------------------------------------------------------
# FUNCTION:     calculateHellingerDistance()
# INPUT:        matrix, matrix
# OUTPUT:       Summed Hellinger Distance
# DESCRIPTION:  Defined as: 1/sqrt(2) * sqrt(sum(square(sqrt(pi - squrt(qi))))
#---------------------------------------------------------------------------------
calculateHellingerDistance <- function(m1, m2)
{
    length_of_matrix <- nrow(m1)
    HPQ <- 0
    HJ <- 0
    
    for(i in 1:length_of_matrix)
    {
        for(j in 1:length_of_matrix)
        {
            HJ <- HJ + ((sqrt(m1[i, j]) - sqrt(m2[i, j])) ^ 2)
        }
        HPQ <- HPQ + ((1 / sqrt(2)) * sqrt(HJ))
        HJ <- 0
    }
    return(HPQ / length_of_matrix) 
}

#---------------------------------------------------------------------------------
# FUNCTION:     calculatePvalue()
# INPUT:        vector, vector
# OUTPUT:       void
# DESCRIPTION:  Calculate p-value (% of values > correct/incorrect value)
#               
#---------------------------------------------------------------------------------
calculatePvalue <- function(correct_and_incorrect, shuffled_distances)
{
    gtr <- length(shuffled_distances[shuffled_distances > correct_and_incorrect])
    pvalue <- gtr / length(shuffled_distances) 
    return(pvalue)
}

#---------------------------------------------------------------------------------
# FUNCTION:     generateDensityPlot()
# INPUT:        double, vector, list, list
# OUTPUT:       void
# DESCRIPTION:  Output density plot (distribution plot) for the results of the
#               permutation test. Purple line indicates primary group distance
#---------------------------------------------------------------------------------
generateDensityPlot <- function(distance_result, shuffled_distances, stimuli_data, settings)
{
    metric <- ifelse(settings$distance_metric == 1, "Jensen-Shannon Distance", "Hellinger Distance")
    density_plot <- density(shuffled_distances)
    plot(density_plot, type = "n", main = stimuli_data$label, xlab = metric, panel.first = grid())
    polygon(density_plot, col = "lightgray", border = "grey")
    rug(shuffled_distances, col = ifelse(shuffled_distances == distance_result, 'blue', 'red'))
    print(abline(v = distance_result, col = "purple"))
    print(density_plot)
}

#---------------------------------------------------------------------------------
# FUNCTION:     generateReport()
# INPUT:        list, list, list
# OUTPUT:       void
# DESCRIPTION:  Output results of distance and p-value 
#               
#---------------------------------------------------------------------------------
generateReport <- function(settings, stimuli_data, report_args)
{
    cat("\n\nData:", stimuli_data$label, "\n")
    
    if(settings$distance_metric == "1")
    {
        df <- data.frame(Jsd = report_args$distance, p.value = report_args$pvalue, Permutations = settings$num_perms)
    }
    else
    {
        df <- data.frame(Hd = report_args$distance, p.value = report_args$pvalue, Permutations = settings$num_perms)
    }
    print(df) 
    cat("\nGroup 1 (n):", report_args$groupsize1)
    cat("\nGroup 2 (n):", report_args$groupsize2, "\n\n")  
}

#---------------------------------------------------------------------------------
# FUNCTION:     generateSettingsReport()
# INPUT:        list
# OUTPUT:       void
# DESCRIPTION:  Output relevant settings used for the study 
#               
#---------------------------------------------------------------------------------
generateSettingsReport <- function(settings)
{
    cat("\n\nStudy settings:\n\n")
    cat("Number of permutations:", settings$num_perms)
    cat("\nDistance:", ifelse(settings$distance_metric == "1", "Jensen_Shannon", "Hellinger"))
    if(settings$distance_metric == "1") cat("\nPrior:", toupper(settings$prior))
    cat("\nDiagonal transitions removed:", toupper(settings$diagonal), "\n\n")
}

#---------------------------------------------------------------------------------
# FUNCTION:     promptForSettings()
# INPUT:        void
# OUTPUT:       list
# DESCRIPTION:  Prompt the user to enter settings for the various test
#               parameters
#---------------------------------------------------------------------------------
promptForSettings <- function()
{
    settings <- list()
    cat(cyan(rep("-", 40)))
    cat(cyan("\nPlease enter test perameters (HPC = History of Presenting Complaint)\n"))
    cat(cyan(rep("-", 40)), "\n")
    settings[["num_perms"]] <- readline("Enter number of permutations: ")  
    settings[["diagonal"]] <- readline("Remove diagonal transitions (y/n): ")  
    settings[["distance_metric"]] <- readline("Enter 1 for Jensen-Shannon or 2 for Hellinger distance: ")  
    settings[["density_plots"]] <- readline("Output distribution plots (y/n): ")
    if(settings[["distance_metric"]] == "1")
        settings[["prior"]] <- readline("Apply Bayesian prior [Dirichlet method] (y/n): ")  
    
    return(settings)
}

#---------------------------------------------------------------------------------
# FUNCTION:     getUniqueData()
# INPUT:        data.frame, String
# OUTPUT:       vector
# DESCRIPTION:  Returns a vector of unique values from a specified data frame
#               i.e. all participants or stimuli in a data set
#---------------------------------------------------------------------------------
getUniqueData <- function(data, parameter)
{
    return(as.vector(unlist(data[!duplicated(data[[parameter]]), parameter], use.names = FALSE)))
}

#---------------------------------------------------------------------------------
# FUNCTION:     addAOIlabels()
# INPUT:        int
# OUTPUT:       void
# DESCRIPTION:  Lables from alphabet i.e. A-Z then AA etc. 
#               
#---------------------------------------------------------------------------------
addAOIlabels <- function(letter_len) 
{
    a <- rep(LETTERS, length.out = letter_len)
    grp <- cumsum(a == "A")
    vapply(seq_along(a), function(x) paste(rep(a[x], grp[x]), collapse = ""), character(1L))
}

#---------------------------------------------------------------------------------
# FUNCTION:     detectCellHits()
# INPUT:        int, int, list
# OUTPUT:       int
# DESCRIPTION:  Detect the number of hits for the current stimulus in the
#               designated grid cell area
#---------------------------------------------------------------------------------
detectCellHits <- function(cell_x, cell_y, cell_len, data)
{
    # extract data
    fixation_data <- data[1, c("PosX", "PosY")]
    fixation_x <- (fixation_data[1, 1] + data[1, "MediaPosX"])
    fixation_y <- (fixation_data[1, 2] + data[1, "MediaPosY"])

    # if any are NA return NA
    if((is.null(fixation_x) || is.null(fixation_y)) || (is.na(fixation_x) || is.na(fixation_y)))
        return(FALSE)

    # check present inside cell 
    if((fixation_x > cell_x && fixation_x < (cell_x + cell_len)) && 
       (fixation_y > cell_y && fixation_y < (cell_y + cell_len)))
    {
        return(TRUE)
    }
    return(FALSE)
}

#---------------------------------------------------------------------------------
# FUNCTION:     getAOIHits()
# INPUT:        data.frame, list
# OUTPUT:       data.frame
# DESCRIPTION:  Get the locations for each fixation within the stimulus 
#               
#---------------------------------------------------------------------------------
getAOIHits <- function(data, grid_args) 
{
    data_frames <- NULL #list()
    hit_data <- NULL
    participant_vector <- NULL
    media_vector <- NULL
    AOI_vector <- NULL
    mat <- matrix(addAOIlabels(grid_args$num_cells), nrow = grid_args$num_rows, ncol = grid_args$num_cols, byrow = TRUE)
    print(mat)
    participants <- getUniqueData(data, "ParticipantName")
    stimuli <- getUniqueData(data, "MediaName")
    colnames(data)[4] <- "MediaPosX"
    colnames(data)[5] <- "MediaPosY"
    colnames(data)[12] <- "PosX"
    colnames(data)[13] <- "PosY"
    
    for(k in 1:length(stimuli))
    {
        print(stimuli[k])
        current_stimuli <- data[data$MediaName == stimuli[k], ]
        
        grid_args$stimuli <- factor(grid_args$stimuli)
        current_grid_args <- grid_args[grid_args$stimuli == stimuli[k], ]
        current_grid_args <- as.list(current_grid_args)
       
        for(i in 1:length(participants))
        {
            # get participant
            participant_data <- current_stimuli[current_stimuli$ParticipantName == participants[i], ]
            
            for(j in 1:nrow(participant_data))
            {
                for(m in current_grid_args$num_rows:1)
                {
                    for(n in 1:current_grid_args$num_cols)
                    {
                        # calculate relative position of cell
                        cell_x <- current_grid_args$images_offsets_x + current_grid_args$grid_offsets_x + (current_grid_args$dims * (n - 1))
                        cell_y <- current_grid_args$images_offsets_y + current_grid_args$grid_offsets_y + (current_grid_args$dims * (m - 1))
                        
                        # detect hit inside cell
                        hit <- detectCellHits(cell_x, cell_y, current_grid_args$dims, participant_data[j, ])
                        if(hit)
                        {
                            AOI_vector <- c(AOI_vector, mat[m, n])
                        }
                    }
                }
            }
            AOIs <- addAOIlabels(current_grid_args$num_cells)
            participant_vector <- rep(participants[i], length(AOI_vector))
            media_vector <- rep(stimuli[k], length(AOI_vector))
            df <- data.frame(participant = participant_vector, MediaName = media_vector, AOI = AOI_vector)
         
            # add data frame to list
            #data_frames[[i]] <- df
            hit_data <- rbind(hit_data, df)
            participant_data <- NULL
            participant_vector <- NULL
            media_vector <- NULL
            AOI_vector <- NULL
        }
    }
    #hit_data <- ldply(data_frames, data.frame)
    
    return(hit_data) 
}

#---------------------------------------------------------------------------------
# FUNCTION:     randomPermutations()
# INPUT:        data.frame, list, int, int
# OUTPUT:       vector
# DESCRIPTION:  Generate 2 random sub groups the same size as the original groups
#               and compare distances for the selected amout of permutations.
#---------------------------------------------------------------------------------
randomPermutations <- function(data, settings, group1_size, stimuli)
{
    progress <- 0
    distance <- NULL
    perms <- as.numeric(settings$num_perms)
    
    print(data)
    cat("\n\nGroup 1 size = ", group1_size, "\n\n")
    
    # create progress bar
    pb_title <- paste0("Computing Distances ", stimuli$label)
    progress_bar <- winProgressBar(title = pb_title, min = 0, max = perms, width = 300)
    getWinProgressBar(progress_bar)
    
    # loop over the permutations  
    for(i in 1:perms) 
    {
        participants <- as.data.frame(data[!duplicated(data$participant), "participant"])
        colnames(participants) <- "participant"
        
        # get a random subset of participants and store in group 1 whatever is left put in second group
        group1_participants <- participants[sample(unique(nrow(participants)), group1_size), ]
        group2_participants <- as.vector(participants[!(participants$participant %in% group1_participants), ])   
        
        # get the selected groups data
        group1 <- data[which(data$participant %in% group1_participants), ]
        group2 <- data[which(data$participant %in% group2_participants), ]
        
        # build Markov chains
        mat_diag <- ifelse(settings$diagonal == "y", FALSE, TRUE)
        chain_1 <- convertToMatrix(group1, mat_diag)
        chain_2 <- convertToMatrix(group2, mat_diag)
        
        # trim rows and cols containing 0 in both matrices
        #trimed_mats <- trimMatrixZeros(chain_1, chain_2)
        #chain_1 <- trimed_mats[[1]]
        #chain_2 <- trimed_mats[[2]]
        
        # remove any NaN
        chain_1[is.na(chain_1)] <- 0
        chain_2[is.na(chain_2)] <- 0
        
        # get distance 
        if(settings$distance_metric == "1")
        {
            if(settings$prior == "y")
            {
                # convert to prior
                chain_1 <- convertToPrior(chain_1)
                chain_2 <- convertToPrior(chain_2)                       
            }
            
            # Jensen-Shannon
            distance_results <- calculateJSDistance(chain_1, chain_2)
        }
        else
        {
            # Hellinger
            distance_results <- calculateHellingerDistance(chain_1, chain_2)
        }
        
        # store computed distance in vector and return
        distance <- c(distance, distance_results)
        
        # display progress bar
        setWinProgressBar(progress_bar, i, title = paste(round(i / perms * 100, 0), "% processed [Computing Distance]"))
    }
    
    # close the progress bar & return result
    close(progress_bar)
    return(distance)
}

#---------------------------------------------------------------------------------
# FUNCTION:     determineGridOffset()
# INPUT:        int, int, int
# OUTPUT:       vector (x, y offset)
# DESCRIPTION:  Determine the x and y offsets to put division remainder 
#               on the edge of the stimulus
#---------------------------------------------------------------------------------
determineGridOffset <- function(width, height, grid_len)
{
    x_offset <- (width / grid_len) - floor(width / grid_len)
    y_offset <- (height / grid_len) - floor(height / grid_len)
    return(c(x_offset, y_offset))
}

#---------------------------------------------------------------------------------
# FUNCTION:     generateGridParameters()
# INPUT:        data.frame, list, int
# OUTPUT:       list
# DESCRIPTION:  Setup the parameters for the grid for a given stimulus
#               
#---------------------------------------------------------------------------------
generateGridParameters <- function(data, grid_size)
{
    grid_args <- list()
    
    # rename cols
    colnames(data)[4] <- "MediaPosX"
    colnames(data)[5] <- "MediaPosY"
    
    # set parameters
    grid_args$stimuli <- toString(data[1, "MediaName"])
    grid_args$w <- data[1, "MediaWidth"] 
    grid_args$h <- data[1, "MediaHeight"]
    grid_args$dims <- grid_size
    
    # determine offsets
    grid_offsets <- determineGridOffset(grid_args$w, grid_args$h, grid_args$dims)
    grid_args$images_offsets_x <- data[1, "MediaPosX"]
    grid_args$images_offsets_y <- data[1, "MediaPosY"]
    grid_args$grid_offsets_x <- grid_offsets[1]
    grid_args$grid_offsets_y <- grid_offsets[2]
    
    # calculate the number of rows and columns in the grid 
    # (picking the largest value so as not to miss any data but maintain square)
    if(grid_args$h < grid_args$w)
    {
        # landscape 
        grid_args$num_rows <- floor((grid_args$w - grid_args$grid_offsets_x * 2) / grid_args$dims)
        grid_args$num_cols <- grid_args$num_rows
    } 
    else 
    {
        # portrait
        grid_args$num_rows <- floor((grid_args$h - grid_args$grid_offsets_y * 2) / grid_args$dims)
        grid_args$num_cols <- grid_args$num_rows
    }
    
    # determine the number of cells
    grid_args$num_cells <- grid_args$num_rows * grid_args$num_cols
    
    return(grid_args)
}

#---------------------------------------------------------------------------------
# FUNCTION:     unlistGridData()
# INPUT:        list
# OUTPUT:       data.frame
# DESCRIPTION:  Convert listed data into data frame format 
#               
#---------------------------------------------------------------------------------
unlistGridData <- function(grid_args)
{
    grid_args <- as.data.frame(grid_args)
    grid_args$stimuli <- unlist(grid_args$stimuli)
    grid_args$w <- unlist(grid_args$w)
    grid_args$h <- unlist(grid_args$h)
    grid_args$dims <- unlist(grid_args$dims)
    grid_args$images_offsets_x <- unlist(grid_args$images_offsets_x) 
    grid_args$images_offsets_y <- unlist(grid_args$images_offsets_y)
    grid_args$grid_offsets_x <- unlist(grid_args$grid_offsets_x)
    grid_args$grid_offsets_y <- unlist(grid_args$grid_offsets_y)
    grid_args$num_rows <- unlist(grid_args$num_rows)
    grid_args$num_cols <- unlist(grid_args$num_cols)
    grid_args$num_cells <- unlist(grid_args$num_cells)
    
    return(grid_args)
}

#---------------------------------------------------------------------------------
# FUNCTION:     trimMatrixZeros()
# INPUT:        matrix, matrix
# OUTPUT:       list
# DESCRIPTION:  Returns sub matrix removing rows/cols where rows and columns 
#               in both matrices  are all zeros
#---------------------------------------------------------------------------------
trimMatrixZeros <- function(m1, m2)
{
    matrix_list <- list()
    row_col_to_remove <- NULL
    
    for(x in 1:nrow(m1))
    {
        if((rowSums(m1)[x] == 0) && (rowSums(m2)[x] == 0))
        {  
            if((colSums(m1)[x] == 0) && (colSums(m2)[x] == 0))
            {
                row_col_to_remove <- c(row_col_to_remove, x)
            }
        }
    } 
    
    # removed the selected rows and columns
    m1 <- m1[-row_col_to_remove, ]; m1 <- m1[, -row_col_to_remove] 
    m2 <- m2[-row_col_to_remove, ]; m2 <- m2[, -row_col_to_remove] 
    
    # store in list entries
    matrix_list[[1]] <- m1
    matrix_list[[2]] <- m2
    
    return(matrix_list)
}

#---------------------------------------------------------------------------------
# FUNCTION:     main()
# INPUT:        void
# OUTPUT:       void
# DESCRIPTION:  Main function. 
#               Makes all subsequent function calls.     
#---------------------------------------------------------------------------------
main <- function()
{
    grids <- NULL
    report_args <- list()
    primary_conditions <- c("cond1.csv", "cond2.csv")
    
    # eps values (radius) from DBSCAN
    gridsizes <- c(30, 30, 30, 40, 30, 30, 40, 30, 30) * 2 
    
    initialize()
    
    if(interactive()){
        settings <- promptForSettings()
    }
    
    # load additional source files with stimuli metadata
    common_source_data <- paste0(getwd(), "/Final-PHD-analysis/experiment_history.R")
    source(common_source_data) 
    
    # open the data files
    ECG_data_files <- openDataFiles(paste0(getwd(), "/Final-PHD-analysis/data/"), primary_conditions)
    
    # open the answers and the AOI locations
    given_answers <- openDataFile(paste0(getwd(), "/Final-PHD-analysis/data/gs/given_answers.csv"))
   
    # get the people that saw HPC first and those that say no HPC first
    saw_HPC <- getPresentationSequence(given_answers, "1-2")
    saw_noHPC <- getPresentationSequence(given_answers, "2-1")
    
    # get the data for the groups
    group_HPC <- ECG_data_files[[1]][which(ECG_data_files[[1]]$ParticipantName %in% saw_HPC), ]
    group_noHPC <- ECG_data_files[[2]][which(ECG_data_files[[2]]$ParticipantName %in% saw_noHPC), ]
    stimuli <- getUniqueData(group_HPC, "MediaName")
   
    for(i in 1:length(getStimuliList()))
    {
        current_stimuli <- group_HPC[group_HPC$MediaName == stimuli[i], ]
        grids <- rbind(grids, generateGridParameters(current_stimuli, gridsizes[i]))
    }

    # get the AOI hit sequence for each group
    grids <- unlistGridData(grids)
    group_1 <- getAOIHits(group_HPC, grids)
    group_2 <- getAOIHits(group_noHPC, grids)
        
    for(i in 1:length(getStimuliList()))
    {
        # get data for the current stimuli
        current_stimuli_metadata <- getExperimentSetupData(getStimuliList()[i])
        
        # extract stimulus data
        chain_1 <- group_1[group_1$MediaName == current_stimuli_metadata$file_name, c("participant", "AOI")]
        chain_2 <- group_2[group_2$MediaName == current_stimuli_metadata$file_name, c("participant", "AOI")]
        combined_data <- rbind(chain_1, chain_2)
        
        mat_diag <- ifelse(settings$diagonal == "y", FALSE, TRUE) 
     
        # convert to matrix form
        chain_1 <- convertToMatrix(chain_1, mat_diag)
        chain_2 <- convertToMatrix(chain_2, mat_diag)
        
        # trim cols and rows that are both 0 in both matrices
        #trimed_mats <- trimMatrixZeros(chain_1, chain_2)
        #chain_1 <-  trimed_mats[[1]]
        #chain_2 <-  trimed_mats[[2]]
        
        # remove any NA's from the chains
        chain_1[is.na(chain_1)] <- 0
        chain_2[is.na(chain_2)] <- 0
        
        if(settings$distance_metric == "1") 
        {
            if(settings$prior == "y")
            {
                # if using Jsd and a prior then convert to prior
                chain_1 <- convertToPrior(chain_1)
                chain_2 <- convertToPrior(chain_2)    
            }
            
            # calculate distance (Jsd)
            distance_result <- calculateJSDistance(chain_1, chain_2)
        }
        if(settings$distance_metric == "2")
        {
            # calculate distance (Hd)
            distance_result <- calculateHellingerDistance(chain_1, chain_2)
        }
        
        # run distance on random groups for n permutations
        shuffled_distances <- randomPermutations(combined_data, settings, length(saw_HPC), current_stimuli_metadata)
        
        if(settings$density_plots == "y")
        {
            # output a distribution plot
            generateDensityPlot(distance_result, shuffled_distances, current_stimuli_metadata, settings)
        }
        
        # build report arguments
        report_args$distance <- distance_result
        report_args$pvalue <- calculatePvalue(distance_result, shuffled_distances) 
        report_args$groupsize1 <- length(saw_HPC)
        report_args$groupsize2 <- length(saw_noHPC)
        
        # generate a textual report
        generateReport(settings, current_stimuli_metadata, report_args)
    }  
    
    # make a final report on the settings used for the study
    generateSettingsReport(settings)
}

# run main
main()