pheatmap參數詳解：掌控R語言熱圖可視化的每一個細節
在R語言的數據可視化領域，pheatmap包因其能夠生成美觀、高度可定製的熱圖而廣受歡迎。熱圖作為一種強大的工具，廣泛應用於基因表達、蛋白質組學、微生物組學等高維數據分析中，用於揭示數據內部的模式、聚類關係和共表達/共存在現象。然而，要真正發揮pheatmap的潛力，深入理解並靈活運用其眾多參數是必不可少的。本文將對pheatmap函數的核心參數進行詳細、具體的解析，幫助您從入門走向精通，全面掌控熱圖的每一個細節。
通過本文的講解，您將學會如何根據數據特性和分析目標，精確調整熱圖的布局、顏色、聚類、註釋、標籤等方方面面，最終繪製出兼具科學準確性與視覺美感的數據可視化圖表。
pheatmap函數核心參數詳解
pheatmap函數提供了一系列豐富的參數，允許用戶對熱圖進行細緻入微的控制。下面我們將逐一解析這些關鍵參數。
1. 數據輸入與基本顯示
mat：矩陣數據
用途：這是pheatmap函數最核心的輸入參數，指定用於繪製熱圖的數值型矩陣。
類型：matrix（數值型矩陣）
詳解：矩陣的行通常代表樣本或特徵（如基因），列代表特徵或樣本。pheatmap將根據矩陣中的數值大小，通過顏色映射來顯示數據的強度。確保您的數據是數值型的，且行名和列名（如果需要顯示）是明確的。
show_rownames / show_colnames：是否顯示行/列名
用途：控制熱圖是否顯示矩陣的行名和列名。
類型：logical（布爾值，TRUE或FALSE）
默認值：TRUE
詳解：當數據矩陣的行或列數量非常大時，關閉顯示可以避免標籤重疊，使熱圖更清晰。
main：圖表主標題
用途：為熱圖添加一個主標題。
類型：character（字元串）
默認值：NULL
詳解：一個好的標題能夠簡潔地概括熱圖所展示的內容。
2. 數據縮放與顏色映射
scale：數據縮放方法
用途：指定對矩陣數據進行縮放的方式，以更好地在顏色上進行區分。
類型：character（字元串）
可選值："row"（按行縮放）、"column"（按列縮放）、"none"（不縮放）
默認值："none"
詳解：
"row"：對每行數據進行標準化（均值為0，標準差為1）。這常用於基因表達數據，以便比較不同樣本中單個基因的相對表達水平。這意味著高表達和低表達的基因在熱圖上都能被清晰地看出其在不同樣本間的波動。"column"：對每列數據進行標準化。適用於比較不同特徵在單個樣本中的相對水平。"none"：不進行縮放。直接使用原始數據的值進行顏色映射。適用於原始數值的絕對差異具有意義的場景，例如計數數據，或者您希望顏色直接反映原始值的範圍。
"row"縮放；當您更關心不同樣本之間（列）的整體模式時，"none"或"column"可能更合適。
color：顏色漸變條
用途：指定熱圖單元格的顏色方案。
類型：colorRampPalette對象或顏色向量
默認值：viridis包提供的顏色漸變
詳解：您可以使用colorRampPalette()函數創建一個顏色漸變函數，例如：
color = colorRampPalette(c("navy", "white", "firebrick3"))(50)breaks：顏色斷點
用途：當您需要精確控制顏色映射的數值範圍時，使用此參數。
類型：numeric vector（數值向量）
默認值：NULL（自動根據數據範圍和顏色數量生成）
詳解：
breaks向量的長度應比color向量的長度多1。- 例如，如果您想將數據範圍[-2, 2]映射到50個顏色，可以這樣設置：
breaks = seq(-2, 2, length.out = 51) - 與
color參數結合使用，可以創建自定義的顏色映射規則，例如，將特定範圍內的值映射到特定顏色，或者強調某個閾值以上/以下的數據點。
na_col：缺失值顏色
用途：指定矩陣中缺失值（NA）的顯示顏色。
類型：character（顏色字元串，如"grey"）
默認值：NA（不繪製，顯示為透明）
詳解：通常設置為灰色或其他不與數據顏色混淆的顏色，以便識別數據中的缺失區域。
3. 聚類與距離計算
cluster_rows / cluster_cols：是否對行/列進行聚類
用途：控制是否對矩陣的行或列進行層級聚類，並顯示聚類樹（dendrogram）。
類型：logical（布爾值，TRUE或FALSE）
默認值：TRUE
詳解：設置為FALSE時，行或列將按照原始輸入矩陣的順序顯示。您也可以傳入一個hclust對象或dendrogram對象來自定義聚類結果。
clustering_distance_rows / clustering_distance_cols：行/列聚類距離度量
用途：指定在進行行/列聚類時使用的距離計算方法。
類型：character（字元串）或自定義距離函數
可選值："correlation"（默認，1 - Pearson相關係數）、"euclidean"（歐氏距離）、"maximum"、"manhattan"、"canberra"、"binary"、"minkowski"。您也可以傳入自定義函數。
默認值："correlation"
詳解：
"correlation"：基於皮爾遜相關係數的距離，常用於基因表達數據，因為其衡量的是數據模式的相似性而非絕對數值差異。"euclidean"：歐氏距離，衡量的是數據點在多維空間中的直線距離。- 選擇合適的距離度量取決於您的數據類型和分析目的。
clustering_method：聚類鏈接方法
用途：指定在層級聚類中，如何計算簇與簇之間的距離（鏈接方法）。
類型：character（字元串）
可選值："average"（默認，組平均法）、"ward.D2"（最小方差法）、"single"（最短距離法）、"complete"（最長距離法）、"mcquitty"、"median"、"centroid"。
默認值："average"
詳解：
"average"：通過計算兩個簇中所有點之間的平均距離來合併簇。通常產生平衡的簇。"ward.D2"：嘗試最小化簇內方差的增加。常用於基因表達數據，傾向於生成大小相似的球形簇，對離群值敏感。- 不同的鏈接方法會產生不同的聚類樹形狀，進而影響熱圖的排序。
treeheight_row / treeheight_col：行/列聚類樹高度
用途：控制熱圖左側/頂部的聚類樹（dendrogram）的顯示高度。
類型：numeric（數值）
默認值：50
詳解：設置為0則不顯示聚類樹。調整此值可以優化熱圖的布局，尤其是在聚類樹非常複雜或非常簡單時。
4. 註釋信息
熱圖的一個強大功能是能夠添加額外的註釋信息，以豐富對數據模式的理解。
annotation_row / annotation_col：行/列註釋數據
用途：為熱圖的行或列添加額外的分類或數值註釋信息。
類型：data.frame（數據框）
默認值：NULL
詳解：
- 數據框的行名必須與熱圖矩陣的行名（對於
annotation_row）或列名（對於annotation_col）完全匹配。 - 數據框的每一列代表一個註釋變數，可以是因子（分類變數）或數值。
pheatmap會根據這些註釋變數的類型自動生成顏色條或漸變色。
annotation_colors：註釋顏色映射
用途：自定義annotation_row或annotation_col中分類變數的顏色。
類型：list（列表）
默認值：NULL（自動生成顏色）
詳解：
- 列表的每個元素都是一個命名向量，其中名稱是註釋數據框中的列名（即註釋變數名），向量本身是將該變數的不同分類值映射到顏色的命名向量。
- 例如：
annotation_colors = list( Group = c(A = "red", B = "blue"), Treatment = c(Control = "green", Treated = "purple") ) - 對於數值型註釋，也可以通過
colorRampPalette來指定顏色漸變。
annotation_legend：是否顯示註釋圖例
用途：控制註釋信息是否顯示圖例。
類型：logical（布爾值）
默認值：TRUE
annotation_names_row / annotation_names_col：是否顯示註釋名稱
用途：控制是否在註釋條旁邊顯示註釋變數的名稱。
類型：logical（布爾值）
默認值：TRUE
5. 文本與標籤
fontsize：全局字體大小
用途：設置熱圖文本的整體字體大小（包括標題、圖例、註釋標籤等）。
類型：numeric（數值）
默認值：10
fontsize_row / fontsize_col：行/列標籤字體大小
用途：單獨控制熱圖行名和列名的字體大小。
類型：numeric（數值）
默認值：fontsize的值
詳解：當行/列名過多導致重疊時，可以適當減小這些字體大小。
labels_row / labels_col：自定義行/列標籤
用途：用自定義的字元串向量替換矩陣的原始行名/列名作為熱圖標籤。
類型：character vector（字元串向量）
默認值：NULL（使用矩陣的原始行/列名）
詳解：向量的長度必須與矩陣的行數/列數相同。
display_numbers：是否顯示數值
用途：在熱圖的每個單元格中顯示對應的數值。
類型：logical（布爾值）或matrix（自定義顯示內容矩陣）
默認值：FALSE
詳解：當設置為TRUE時，熱圖單元格內會顯示原始矩陣的數值。如果傳入一個與mat相同維度的矩陣，則顯示該矩陣的內容。這在矩陣較小、需要精確查看數值時很有用。
number_format：數值顯示格式
用途：當display_numbers為TRUE時，控制數值的顯示格式。
類型：character（格式字元串，如"%.2f"表示兩位小數）
默認值："%.2f"
fontsize_number / number_color：顯示數值的字體大小與顏色
用途：分別控制單元格內顯示數值的字體大小和顏色。
類型：numeric / character
默認值：0.8 * fontsize / "grey30"
6. 布局與外觀
cellwidth / cellheight：單元格寬度/高度
用途：指定熱圖中每個單元格的固定寬度和高度。
類型：numeric（數值）
默認值：NULL（自動調整）
詳解：當矩陣非常大時，設置較小的單元格尺寸可以使熱圖更緊湊。但請注意，設置這些值會使熱圖尺寸固定，而width和height參數則控制整個輸出圖的尺寸。
border_color：單元格邊框顏色
用途：設置熱圖單元格的邊框顏色。
類型：character（顏色字元串）
默認值："grey60"
詳解：設置為NA或FALSE可以去除邊框。
gaps_row / gaps_col：自定義行/列間隙
用途：在熱圖中指定行或列之間添加視覺上的間隙，常用於區分不同的數據組。
類型：numeric vector（數值向量）
默認值：NULL
詳解：
- 向量中的數值代表在哪些行/列之後添加間隙。例如，
gaps_row = c(5, 10)會在第5行和第10行之後添加間隙。 - 這對於手動劃分熱圖的區域非常有用，即使沒有進行聚類也能實現邏輯分組的展示。
7. 圖例控制
legend：是否顯示主圖例
用途：控制是否顯示顏色映射的主圖例。
類型：logical（布爾值）
默認值：TRUE
legend_breaks / legend_labels：主圖例斷點與標籤
用途：自定義主圖例上顯示的數值斷點和對應的標籤。
類型：numeric vector / character vector
默認值：NULL（自動生成）
詳解：legend_breaks的長度應與legend_labels的長度相同。
8. 文件輸出
filename：保存文件名
用途：指定熱圖保存的文件路徑和名稱。如果提供此參數，熱圖將直接保存到文件而不是在R的圖形設備中顯示。
類型：character（字元串）
默認值：NULL
詳解：支持多種文件格式，如.pdf, .png, .jpeg, .tiff等，通過文件擴展名自動識別。
width / height：保存文件寬度/高度
用途：當filename參數被指定時，控制輸出圖像的寬度和高度。
類型：numeric（數值）
默認值：根據熱圖內容自動調整
詳解：單位通常是英寸，可以根據需要調整以獲得合適的圖像尺寸和解析度。
9. 其他高級參數
silent：是否靜默模式
用途：控制pheatmap在生成熱圖時是否列印消息（如聚類信息）。
類型：logical
默認值：FALSE
drop_empty_rows / drop_empty_cols：是否刪除空行/列
用途：在繪製熱圖前，是否刪除所有值為NA的行或列。
類型：logical
默認值：TRUE
callback：回調函數
用途：一個高級參數，允許用戶傳入一個自定義函數，該函數會在生成熱圖前被調用，並接收聚類結果作為參數。這使得用戶能夠對聚類結果進行二次處理，例如重新排序或裁剪聚類樹。
類型：function
默認值：NULL
詳解：這個參數對於需要高度自定義聚類輸出的用戶非常有用。例如，您可以利用它來根據某種標準從聚類樹中裁剪齣子樹，然後將其作為新的聚類結果返回給pheatmap。
總結與最佳實踐
pheatmap提供了極大的靈活性，讓用戶能夠根據具體的數據類型和分析目標，繪製出高度定製化的熱圖。掌握這些參數不僅能夠美化您的圖表，更重要的是，它能幫助您更準確、更清晰地表達數據中的生物學或科學信息。
在實際應用中，建議您：
- 從小處著手：先用默認參數生成熱圖，然後逐步調整，觀察每個參數對熱圖外觀的影響。
- 明確分析目的：您希望通過熱圖展示什麼？是數據的絕對值分佈，還是不同樣本/特徵間的相對變化？這會影響您對
scale和color參數的選擇。 - 善用註釋：有效地利用
annotation_row和annotation_col可以極大地增強熱圖的信息量和可讀性。 - 迭代優化：熱圖的繪製往往是一個迭代的過程，不斷嘗試不同的參數組合，直到達到最佳可視化效果。
常見問題（FAQ）
如何為pheatmap添加自定義顏色條或註釋顏色？
要為pheatmap添加自定義顏色條或註釋顏色，您需要使用annotation_row或annotation_col參數提供註釋數據框，然後使用annotation_colors參數來指定這些註釋變數的顏色映射。annotation_colors是一個列表，其名稱對應註釋數據框的列名，值則是將該列中的分類值（或數值範圍）映射到特定顏色的命名向量（或顏色漸變函數）。
為何我的pheatmap聚類結果不理想或沒有顯示聚類樹？
如果聚類結果不理想，首先檢查clustering_distance_rows/cols和clustering_method參數，選擇與您的數據類型和分析目標更匹配的距離計算和鏈接方法。例如，對於基因表達數據，"correlation"距離和"ward.D2"方法常被推薦。如果聚類樹沒有顯示，請檢查cluster_rows和cluster_cols是否都設置為TRUE，以及treeheight_row和treeheight_col是否為非零值。
如何在pheatmap熱圖上顯示具體數值？
要在熱圖單元格中顯示具體的數值，您可以將display_numbers參數設置為TRUE。默認情況下，它將顯示原始矩陣的數值。您還可以通過number_format參數控制數值的格式（如小數位數），通過fontsize_number和number_color參數調整顯示數值的字體大小和顏色，以確保其清晰可見。
為何我的pheatmap保存圖片時尺寸或解析度不合適？
當您使用filename參數將熱圖保存到文件時，width和height參數決定了輸出圖像的尺寸（通常以英寸為單位）。如果輸出圖片尺寸不合適，請調整這兩個參數的值。對於PDF輸出，通常矢量圖具有無限解析度。對於PNG或JPEG等點陣圖格式，較大的width和height值會增加圖片的解析度和文件大小，以獲得更清晰的細節。
scale參數有什麼作用，我應該何時使用它？
scale參數用於對熱圖的輸入矩陣進行數據縮放，其作用是標準化數據，使其在不同行或列之間具有可比性。當設置為"row"時，每行數據會被獨立地標準化（通常為均值0，標準差1），這適用於比較不同樣本中單個特徵（如基因）的相對變化。當設置為"column"時，每列數據被標準化，適用於比較不同特徵在單個樣本中的相對水平。當設置為"none"時，數據保持原始狀態。您應該根據您的分析目的來選擇：如果要比較相對變化模式，使用"row"或"column"；如果原始數值的絕對差異具有意義，則使用"none"。
