#' 
#' @title Generates percents from counts returned by the function \code{table1d.ds}
#' @description this is an INTERNAL function required by the helper function
#' \code{table1dhelper4} functions. It generates percents from the count tables.
#' @details the function is not 'exported' and hence not visible to user and
#' is only called by \code{ds.table1d}
#' @param a.boolean a boolean that indicates whether or not all the studies are invalid
#' @param a.matrix a matrix containing study specific and overall (combined) tables of counts based ONLY
#' on data from studies where all table categories are VALID - this matrix is generated by the function \code{table1dhelper2}
#' @param a.list a list of primary outputs from ALL studies ("STUDY.NAME","IS.STUDY.DATA.VALID?","TABLE.MASKED.COUNTS")
#' @return a list that contains summary tables with columns and rows percents
#' @author Burton, P.; Gaye, A.
#'
table1dhelper3 <- function(a.boolean, a.matrix, a.list){ 

  # third script required by the function ds.table1d
  # generic function to combine equivalent data from different opals (when data are valid)
  
  # get required input
  zero.studies.valid <- a.boolean
  valid.output.matrix <- a.matrix
  valid.counts.matrix <- a.matrix
  final.output.list <- a.list

  # only enact if at least one study valid
  if(zero.studies.valid==FALSE)
  { 
    col.summation.matrix <- rep(1,dim(valid.counts.matrix)[2])
    row.total.vector <- valid.output.matrix%*%col.summation.matrix
    valid.counts.matrix <- cbind(valid.output.matrix,row.total.vector)
    row.summation.matrix <- rep(1,dim(valid.counts.matrix)[1])
    col.total.vector <- row.summation.matrix%*%valid.output.matrix
    col.total.vector <- c(col.total.vector,sum(col.total.vector))
    valid.counts.matrix <- rbind(valid.counts.matrix,col.total.vector)

    dimr <- dim(valid.counts.matrix)[1]
    dimc <- dim(valid.counts.matrix)[2]

    dimnames(valid.counts.matrix)[[1]][dimr] <- "TOTAL"
    dimnames(valid.counts.matrix)[[2]][dimc] <- "TOTAL"

    valid.colperc.matrix <- valid.counts.matrix
    valid.rowperc.matrix <- valid.counts.matrix
    valid.globalperc.matrix <- valid.counts.matrix

    # convert counts to column percents
    for(j in 1:dimc)
    {
      valid.colperc.matrix[,j] <- round(100*(valid.counts.matrix[,j]/valid.counts.matrix[dimr,j]),2)
    }

    # convert counts to row percents
    for(k in 1:dimr)
    {
      valid.rowperc.matrix[k,] <- round(100*(valid.counts.matrix[k,]/valid.counts.matrix[k,dimc]),2)
    }

    # convert counts to global percents
    for(j in 1:dimr)
    {
      for(k in 1:dimc)
      {
        valid.globalperc.matrix[j,k] <- round(100*(valid.counts.matrix[j,k]/valid.counts.matrix[dimr,dimc]),2)
        
      }
    }

    # retrurn key output objects to return:
    final.output.list <- list("valid.counts.matrix"=valid.counts.matrix,"valid.colperc.matrix"=valid.colperc.matrix,
                              "valid.rowperc.matrix"=valid.rowperc.matrix,"valid.globalperc.matrix"=valid.globalperc.matrix)
    return(final.output.list)
  }else{
  }
}  
