# takes a dataframe and returns the same dataframe with two extra columns for colours and position
generate_distance_colour_map = function(plot_df,
                                        xvar_colname = "position",
                                        lig_dist_colname = "ligand_distance",
                                        #lig_dist_colours = c("green", "yellow", "orange", "red"),
                                        lig_dist_colours = c("tan", "black"),
                                        debug = TRUE
)
{
  if (debug) {
    cat("\nAnnotating x-axis ~", lig_dist_colname, "requested...")
  }
  
  plot_df['lig_distR'] = round(plot_df[[lig_dist_colname]], digits = 0)
  
  lig_min  = min(round(plot_df[[lig_dist_colname]]), na.rm = T); lig_min
  lig_max  = max(round(plot_df[[lig_dist_colname]]), na.rm = T); lig_max 
  lig_mean = round(mean(round(plot_df[[lig_dist_colname]]), na.rm = T)); lig_mean
  
  # Create mapping colour key
  n_colours  = length(sort(unique(round(plot_df[[lig_dist_colname]], digits = 0)))); n_colours
  
  lig_cols = colorRampPalette(lig_dist_colours)(n_colours); lig_cols
  ligD_valsR = sort(unique(round(plot_df[[lig_dist_colname]], digits = 0))); ligD_valsR
  
  if (debug) {
    length(ligD_valsR)
    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
  if (debug) {
    names(ligDcolKey)
    cat("\nSuccessful: Mapping b/w", lig_dist_colname, "and colours")
  }
  #-------------------------------------
  # merge colour key with plot_df
  #-------------------------------------- 
  plot_df = merge(plot_df, ligDcolKey, by = 'lig_distR')
  
  # plot_df_check = as.data.frame(cbind(position    = plot_df[[xvar_colname]]
  #                                     , ligD      = plot_df[[lig_dist_colname]]
  #                                     , ligDR     = plot_df$lig_distR
  #                                     , ligD_cols = plot_df$ligD_colours))
  return(plot_df)
}

generate_distance_legend = function(plot_df,
                                    xvar_colname = 'position',
                                    lig_dist_colname = "ligand_distance",
                                    legend_title = "Ligand\nDistance"
)
{
  # build legend for ligand distance "heat bar"
  lig_min  = min(round(plot_df[[lig_dist_colname]]), na.rm = T); lig_min
  lig_max  = max(round(plot_df[[lig_dist_colname]]), na.rm = T); lig_max 
  lig_mean = round(mean(round(plot_df[[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(plot_df, aes_string(x = sprintf("factor(%s)", xvar_colname), y=0)) +
      
      geom_tile(aes(fill = .data[[lig_dist_colname]])
                , colour = "white") +
      scale_fill_gradient2(midpoint = lig_mean
                           , low  = "tan"
                           , mid  = "grey50"
                           , high = "black"
                           , breaks = labels
                           , limits = c(lig_min, lig_max)
                           , labels = labelsD
                           , name   = legend_title)
  )
}