# takes a dataframe and returns the same dataframe with two extra columns for colours and position
generate_distance_colour_map = function(plotdf,
                                        xvar_colname = "position",
                                        yvar_colname = 'duet_scaled',
                                        lig_dist_colname = "ligand_distance",
                                        lig_dist_colours = c("green", "yellow", "orange", "red"),
                                        #tpos0 = 0,
                                        #tpos1 = 0,
                                        #tpos2 = 0,
                                        #tpos3 = 0,
                                        debug = FALSE
)
{
  #-------------------
  # x and y axis
  # range, scale, etc
  #-------------------
  my_xlim = length(unique(plotdf[[yvar_colname]])); my_xlim
  ymin    = min(plotdf[[yvar_colname]]); ymin
  ymax    = max(plotdf[[yvar_colname]]); ymax
  
  #if (tpos0 == 0){
  #  tpos0 = ymin-0.5
  #}
  #if (tpos1 == 0){
  #  tpos1 = ymin-0.65
  #}
  #if (tpos2 == 0){
  #  tpos2 = ymin-0.75
  #}
  #if (tpos3 == 0){
  #  tpos3 = ymin-0.85
  #}
  if (debug) {
    cat("\nAnnotating x-axis ~", lig_dist_colname, "requested...")
  }
  #-------------------------------------
  # round column values: to colour by
  #--------------------------------------
  #plotdf = plotdf[order(plotdf[[lig_dist_colname]]),]
  plotdf['lig_distR'] = round(plotdf[[lig_dist_colname]], digits = 0)
  #head(plotdf['lig_distR'])
  
  #-------------------------------------
  # ligand distance range, min, max, etc
  #--------------------------------------
  lig_min  = min(round(plotdf[[lig_dist_colname]]), na.rm = T); lig_min
  lig_max  = max(round(plotdf[[lig_dist_colname]]), na.rm = T); lig_max 
  lig_mean = round(mean(round(plotdf[[lig_dist_colname]]), na.rm = T)); lig_mean
  
  #-------------------------------------
  # Create mapping colour key
  #--------------------------------------
  # sorting removes NA, so that n_colours  ==  length(ligD_valsR)
  n_colours  = length(sort(unique(round(plotdf[[lig_dist_colname]], digits = 0)))); n_colours
  
  lig_cols = colorRampPalette(lig_dist_colours)(n_colours); lig_cols
  ligD_valsR = sort(unique(round(plotdf[[lig_dist_colname]], digits = 0))); ligD_valsR
  length(ligD_valsR)
  
  if (debug) {
    if (n_colours == length(ligD_valsR)) {
      cat("\nStarting: mapping b/w"
          , lig_dist_colname
          , "and colours")
    }else{
      cat("\nCannot start mapping b/w", lig_dist_colname, "and colours..."
          , "\nLength mismatch:"
          , "No. of colours: ", n_colours
          , "\nValues to map:", length(ligD_valsR))
    }
  }
  
  ligDcolKey <- data.frame(ligD_colours = lig_cols
                           , lig_distR = ligD_valsR); ligDcolKey
  names(ligDcolKey)
  if (debug) {
    cat("\nSuccessful: Mapping b/w", lig_dist_colname, "and colours")
  }
  #-------------------------------------
  # merge colour key with plotdf
  #-------------------------------------- 
  plotdf = merge(plotdf, ligDcolKey, by = 'lig_distR')
  
  plotdf_check = as.data.frame(cbind(position    = plotdf[[xvar_colname]]
                                     , ligD      = plotdf[[lig_dist_colname]]
                                     , ligDR     = plotdf$lig_distR
                                     , ligD_cols = plotdf$ligD_colours))
  return(plotdf)
}

generate_distance_legend = function(plotdf,
                                    yvar_colname,
                                    xvar_colname = 'position',
                                    lig_dist_colname = "ligand_distance",
                                    legend_title = "Ligand\nDistance"
                                    )
{
  # build legend for ligand distance "heat bar"
  lig_min  = min(round(plotdf[[lig_dist_colname]]), na.rm = T); lig_min
  lig_max  = max(round(plotdf[[lig_dist_colname]]), na.rm = T); lig_max 
  lig_mean = round(mean(round(plotdf[[lig_dist_colname]]), na.rm = T)); lig_mean
  
  labels  = seq(lig_min, lig_max, len = 5); labels
  labelsD = round(labels, digits = 0); labelsD
  
  get_legend(ggplot(plotdf, aes_string(x = sprintf("factor(%s)", xvar_colname)
                            , y = yvar_colname)) +
    
    geom_tile(aes(fill = .data[[lig_dist_colname]])
              , colour = "white") +
    scale_fill_gradient2(midpoint = lig_mean
                         , low  = "green"
                         , mid  = "yellow"
                         , high = "red"
                         , breaks = labels
                         , limits = c(lig_min, lig_max)
                         , labels = labelsD
                         , name   = legend_title)
    )
}