# Install necessary R packages if you haven't already. 
# Ensure you have an active internet connection for installation.
install.packages("pheatmap") # For generating beautiful heatmaps
install.packages("viridisLite") # For color palettes (optional, but recommended for perceptually uniform colors)

# Load the installed libraries into your R session.
# This step must be executed every time you start a new R session for heatmap generation.
library(pheatmap)
library(viridisLite) # Optional, but good practice if using viridis colors

# Engineer a synthetic protein similarity matrix for demonstration.
# In a real scenario, you would load your actual similarity data (e.g., from a CSV or tab-delimited file).
# Assume protein IDs as row and column names.
set.seed(123) # For reproducibility of the random matrix
num_proteins <- 20 # Define the number of proteins for our example

# Create a symmetric matrix (similarity of P1 to P2 is same as P2 to P1)
# Diagonal elements (similarity of a protein to itself) are typically 1 or max similarity.
protein_names <- paste0("Prot_", 1:num_proteins)
sim_matrix <- matrix(runif(num_proteins^2, min = 0, max = 1), 
                     nrow = num_proteins, ncol = num_proteins)

# Ensure the matrix is symmetric and has 1s on the diagonal for self-similarity
sim_matrix[lower.tri(sim_matrix)] <- t(sim_matrix)[lower.tri(sim_matrix)]
diag(sim_matrix) <- 1 

# Assign meaningful row and column names for clarity.
rownames(sim_matrix) <- protein_names
colnames(sim_matrix) <- protein_names

# Inspect the first few rows and columns of your engineered matrix.
head(sim_matrix[, 1:6])

# You might load your data from a file instead:
# sim_matrix_real <- read.csv("your_protein_similarity_data.csv", row.names = 1)
# Or for tab-separated files:
# sim_matrix_real <- read.delim("your_protein_similarity_data.txt", row.names = 1)

# Ensure your matrix is numerical and suitable for heatmap plotting.
# If you have non-numerical columns (e.g., IDs not used as row names), remove them.
# You might need to convert data types if R reads them as factors or characters.
# sim_matrix_real <- as.matrix(sim_matrix_real)

# Using the 'sim_matrix' created in the previous step.

# Forge your inaugural heatmap with default settings.
# This basic command will generate a clustered heatmap with dendrograms.
pheatmap(sim_matrix,
         main = "Basic Protein Similarity Heatmap") # Add a descriptive title

# Customize the heatmap for enhanced clarity.
# We control clustering, show/hide dendrograms, and adjust color.
# 'cluster_rows' and 'cluster_cols' determine if rows/columns are clustered.
# 'show_rownames' and 'show_colnames' manage label visibility.
# 'color' argument defines the color palette. Using viridis for better perception.
# 'fontsize' and 'fontsize_row/col' control label sizes.

pheatmap(sim_matrix,
         color = viridis(50), # A palette of 50 colors from viridis
         cluster_rows = TRUE, # Cluster proteins by similarity for rows
         cluster_cols = TRUE, # Cluster proteins by similarity for columns
         show_rownames = TRUE, # Display row names (protein IDs)
         show_colnames = TRUE, # Display column names (protein IDs)
         fontsize = 8, # Overall font size for annotations and legend
         fontsize_row = 6, # Specific font size for row labels
         fontsize_col = 6, # Specific font size for column labels
         main = "Clustered Protein Similarity Heatmap (Viridis Palette)",
         border_color = NA # Remove cell borders for cleaner look
)

# Decode the visual output:
# - Dendrograms: These tree-like structures illustrate the hierarchical clustering.
#   Closely related proteins are grouped together, indicating shared ancestry or function.
# - Color Gradient: Observe the color changes. Typically, darker/hotter colors indicate higher similarity,
#   while lighter/cooler colors denote lower similarity. The legend provides the precise mapping.
# - Blocks/Squares: Look for distinct blocks of uniform color. These represent clusters of proteins
#   that are highly similar to each other, forming potential functional groups or families.
# - Off-diagonal patterns: These can indicate specific relationships between different clusters.

# Advanced customization for biological relevance and detailed insights.

# 1. Add annotations to rows/columns for additional biological context.
# Create annotation data frames. Ensure row names match your matrix's row/column names.
annotation_row <- data.frame(
  Protein_Class = sample(c("Enzyme", "Receptor", "Structural", "Transporter"), num_proteins, replace = TRUE),
  Pathways = sample(c("Metabolic", "Signaling", "Immune", "Development"), num_proteins, replace = TRUE)
)
rownames(annotation_row) <- protein_names

# Create a similar annotation for columns if needed (often the same for symmetric matrices)
annotation_col <- annotation_row # For a symmetric matrix, row and column annotations are often identical

# Define colors for annotations (optional, pheatmap will pick defaults if not provided).
# Ensure names match the levels in your annotation data frames.
ann_colors <- list(
  Protein_Class = c(Enzyme = "#E6AB02", Receptor = "#66A61E", Structural = "#7570B3", Transporter = "#D95F02"),
  Pathways = c(Metabolic = "#1B9E77", Signaling = "#E7298A", Immune = "#6A3D9A", Development = "#A6761D")
)

# Plot heatmap with row and column annotations
pheatmap(sim_matrix,
         color = viridis(50),
         cluster_rows = TRUE, cluster_cols = TRUE,
         show_rownames = FALSE, show_colnames = FALSE, # Hide labels if too many, rely on annotations
         annotation_row = annotation_row,
         annotation_col = annotation_col,
         annotation_colors = ann_colors, # Apply custom annotation colors
         main = "Protein Similarity Heatmap with Biological Annotations",
         fontsize = 8,
         border_color = NA
)

# 2. Customizing color breaks for specific value ranges.
# This is crucial when certain similarity thresholds have biological significance.
# For example, values > 0.8 are 'high', > 0.5 are 'medium', < 0.5 are 'low'.
breaks <- c(0, 0.5, 0.8, 1) # Define specific break points
colors_custom <- c("lightgrey", "lightblue", "darkblue") # Define colors for each range

# Plot with custom breaks and colors
pheatmap(sim_matrix,
         color = colors_custom, # Use custom color vector
         breaks = breaks,       # Apply custom break points
         cluster_rows = TRUE, cluster_cols = TRUE,
         main = "Protein Similarity Heatmap with Custom Color Breaks",
         border_color = NA
)

# 3. Exporting the heatmap for publications.
# It's vital to save high-resolution images for reports and presentations.
# Common formats: PDF (vector graphic, scalable) or PNG (raster, good for web).

# To PDF (vector graphic, best for print/high-res):
pdf("protein_similarity_heatmap_annotated.pdf", width = 10, height = 10)
pheatmap(sim_matrix,
         color = viridis(50),
         cluster_rows = TRUE, cluster_cols = TRUE,
         show_rownames = FALSE, show_colnames = FALSE,
         annotation_row = annotation_row,
         annotation_col = annotation_col,
         annotation_colors = ann_colors,
         main = "Protein Similarity Heatmap for Publication",
         fontsize = 8,
         border_color = NA
)
dev.off() # Close the PDF device

# To PNG (raster graphic, good for web/presentations):
png("protein_similarity_heatmap_custom_colors.png", width = 1200, height = 1200, res = 300) # res=300 for high resolution
pheatmap(sim_matrix,
         color = colors_custom,
         breaks = breaks,
         cluster_rows = TRUE, cluster_cols = TRUE,
         main = "Protein Similarity Heatmap for Web",
         border_color = NA
)
dev.off() # Close the PNG device

# Common pitfalls & troubleshooting:
# - Too many labels: Set show_rownames/colnames to FALSE, rely on annotation or interactive tools.
# - Sparse matrices: Consider different clustering metrics or binarizing similarity if exact values are less important than presence/absence.
# - Interpretation: Always correlate visual clusters with known biological functions or categories to validate insights.