forked from jokergoo/ComplexHeatmap-reference
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ComplexHeatmap-reference.tex
6407 lines (5203 loc) · 360 KB
/
ComplexHeatmap-reference.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\documentclass[]{book}
\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\usepackage{fixltx2e} % provides \textsubscript
\ifnum 0\ifxetex 1\fi\ifluatex 1\fi=0 % if pdftex
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\else % if luatex or xelatex
\ifxetex
\usepackage{mathspec}
\else
\usepackage{fontspec}
\fi
\defaultfontfeatures{Ligatures=TeX,Scale=MatchLowercase}
\fi
% use upquote if available, for straight quotes in verbatim environments
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
% use microtype if available
\IfFileExists{microtype.sty}{%
\usepackage{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
\usepackage[margin=1in]{geometry}
\usepackage{hyperref}
\hypersetup{unicode=true,
pdftitle={ComplexHeatmap Complete Reference},
pdfauthor={Zuguang Gu},
pdfborder={0 0 0},
breaklinks=true}
\urlstyle{same} % don't use monospace font for urls
\usepackage{natbib}
\bibliographystyle{apalike}
\usepackage{color}
\usepackage{fancyvrb}
\newcommand{\VerbBar}{|}
\newcommand{\VERB}{\Verb[commandchars=\\\{\}]}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{commandchars=\\\{\}}
% Add ',fontsize=\small' for more characters per line
\usepackage{framed}
\definecolor{shadecolor}{RGB}{248,248,248}
\newenvironment{Shaded}{\begin{snugshade}}{\end{snugshade}}
\newcommand{\KeywordTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
\newcommand{\DataTypeTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{#1}}
\newcommand{\DecValTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\BaseNTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\FloatTok}[1]{\textcolor[rgb]{0.00,0.00,0.81}{#1}}
\newcommand{\ConstantTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\CharTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\SpecialCharTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\StringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\VerbatimStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\SpecialStringTok}[1]{\textcolor[rgb]{0.31,0.60,0.02}{#1}}
\newcommand{\ImportTok}[1]{#1}
\newcommand{\CommentTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
\newcommand{\DocumentationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\AnnotationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\CommentVarTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\OtherTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{#1}}
\newcommand{\FunctionTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\VariableTok}[1]{\textcolor[rgb]{0.00,0.00,0.00}{#1}}
\newcommand{\ControlFlowTok}[1]{\textcolor[rgb]{0.13,0.29,0.53}{\textbf{#1}}}
\newcommand{\OperatorTok}[1]{\textcolor[rgb]{0.81,0.36,0.00}{\textbf{#1}}}
\newcommand{\BuiltInTok}[1]{#1}
\newcommand{\ExtensionTok}[1]{#1}
\newcommand{\PreprocessorTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textit{#1}}}
\newcommand{\AttributeTok}[1]{\textcolor[rgb]{0.77,0.63,0.00}{#1}}
\newcommand{\RegionMarkerTok}[1]{#1}
\newcommand{\InformationTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\WarningTok}[1]{\textcolor[rgb]{0.56,0.35,0.01}{\textbf{\textit{#1}}}}
\newcommand{\AlertTok}[1]{\textcolor[rgb]{0.94,0.16,0.16}{#1}}
\newcommand{\ErrorTok}[1]{\textcolor[rgb]{0.64,0.00,0.00}{\textbf{#1}}}
\newcommand{\NormalTok}[1]{#1}
\usepackage{longtable,booktabs}
\usepackage{graphicx,grffile}
\makeatletter
\def\maxwidth{\ifdim\Gin@nat@width>\linewidth\linewidth\else\Gin@nat@width\fi}
\def\maxheight{\ifdim\Gin@nat@height>\textheight\textheight\else\Gin@nat@height\fi}
\makeatother
% Scale images if necessary, so that they will not overflow the page
% margins by default, and it is still possible to overwrite the defaults
% using explicit options in \includegraphics[width, height, ...]{}
\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
\IfFileExists{parskip.sty}{%
\usepackage{parskip}
}{% else
\setlength{\parindent}{0pt}
\setlength{\parskip}{6pt plus 2pt minus 1pt}
}
\setlength{\emergencystretch}{3em} % prevent overfull lines
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
\setcounter{secnumdepth}{5}
% Redefines (sub)paragraphs to behave more like sections
\ifx\paragraph\undefined\else
\let\oldparagraph\paragraph
\renewcommand{\paragraph}[1]{\oldparagraph{#1}\mbox{}}
\fi
\ifx\subparagraph\undefined\else
\let\oldsubparagraph\subparagraph
\renewcommand{\subparagraph}[1]{\oldsubparagraph{#1}\mbox{}}
\fi
%%% Use protect on footnotes to avoid problems with footnotes in titles
\let\rmarkdownfootnote\footnote%
\def\footnote{\protect\rmarkdownfootnote}
%%% Change title format to be more compact
\usepackage{titling}
% Create subtitle command for use in maketitle
\newcommand{\subtitle}[1]{
\posttitle{
\begin{center}\large#1\end{center}
}
}
\setlength{\droptitle}{-2em}
\title{ComplexHeatmap Complete Reference}
\pretitle{\vspace{\droptitle}\centering\huge}
\posttitle{\par}
\author{Zuguang Gu}
\preauthor{\centering\large\emph}
\postauthor{\par}
\predate{\centering\large\emph}
\postdate{\par}
\date{last revised on 2018-10-16}
\usepackage{booktabs}
\usepackage{amsthm}
\makeatletter
\def\thm@space@setup{%
\thm@preskip=8pt plus 2pt minus 4pt
\thm@postskip=\thm@preskip
}
\makeatother
\usepackage{amsthm}
\newtheorem{theorem}{Theorem}[chapter]
\newtheorem{lemma}{Lemma}[chapter]
\theoremstyle{definition}
\newtheorem{definition}{Definition}[chapter]
\newtheorem{corollary}{Corollary}[chapter]
\newtheorem{proposition}{Proposition}[chapter]
\theoremstyle{definition}
\newtheorem{example}{Example}[chapter]
\theoremstyle{definition}
\newtheorem{exercise}{Exercise}[chapter]
\theoremstyle{remark}
\newtheorem*{remark}{Remark}
\newtheorem*{solution}{Solution}
\begin{document}
\maketitle
{
\setcounter{tocdepth}{1}
\tableofcontents
}
\chapter*{About}\label{about}
\addcontentsline{toc}{chapter}{About}
This is the documentation of the
\href{http://bioconductor.org/packages/ComplexHeatmap/}{\textbf{ComplexHeatmap}}
package. Examples in the book are generated under version 1.99.0.
\textbf{Please note, this documentation is not completely compatible
with older versions (\textless{} 1.99.0, before Oct, 2018), the major
functionality keeps the same.}
If you use \textbf{ComplexHeatmap} in your publications, I am
appreciated if you can cite:
Gu, Z. (2016) Complex heatmaps reveal patterns and correlations in
multidimensional genomic data. DOI:
\href{https://doi.org/10.1093/bioinformatics/btw313}{10.1093/bioinformatics/btw313}
\begin{center}\includegraphics[width=34.44in]{complexheatmap-cover} \end{center}
\chapter{Introduction}\label{introduction}
Complex heatmaps are efficient to visualize associations between
different sources of data sets and reveal potential structures. Here the
\textbf{ComplexHeatmap} package provides a highly flexible way to
arrange multiple heatmaps and supports self-defined annotation graphics.
\section{General design}\label{general-design}
A single heatmap is composed of the heatmap body and the heatmap
components. The heatmap body can be split by rows and columns. The
heatmap components are titles, dendrograms, matrix names and
annotations, which are put on the four sides of the heamap body.
\begin{center}\includegraphics{01-introduction_files/figure-latex/unnamed-chunk-3-1} \end{center}
A heatmap list is concatenation of a list of heatmaps and heatmap
annotations. Surrounding the heatmap list, there are global-level titles
and legends.
One of the important things for the heatmap list is that rows for all
heatmaps and annotations (it is row annotation if the heatmap list is
horizontal.) are all adusted so that the same row in all heatmaps and
annotations corresponds to a same feature.
\begin{center}\includegraphics{01-introduction_files/figure-latex/unnamed-chunk-4-1} \end{center}
The heatmaps and annotations can also be arranged vertically.
\begin{center}\includegraphics{01-introduction_files/figure-latex/unnamed-chunk-5-1} \end{center}
The \textbf{ComplexHeatmap} package is implemented in an object-oriented
way. To describe a heatmap list, there are following classes:
\begin{itemize}
\tightlist
\item
\texttt{Heatmap} class: a single heatmap containing heatmap body,
row/column names, titles, dendrograms and column annotations.
\item
\texttt{HeatmapList} class: a list of heatmaps and heatmap
annotations.
\item
\texttt{HeatmapAnnotation} class: defines a list of row annotations
and column annotations. The heatmap annotations can be components of
heatmap, also they can be independent as heatmaps.
\end{itemize}
There are also several internal classes:
\begin{itemize}
\tightlist
\item
\texttt{SingleAnnotation} class: defines a single row annotation or
column annotation.
\item
\texttt{ColorMapping} class: mapping from values to colors.
\item
\texttt{AnnotationFunction} class: construct user-defined annotations.
\end{itemize}
\textbf{ComplexHeatmap} is implemented under \textbf{grid} system, so
users need to know basic \textbf{grid} functionality to get full use of
the package.
\section{A brief description of following
chapters}\label{a-brief-description-of-following-chapters}
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\tightlist
\item
\href{a-single-heatmap.html}{\textbf{A Single Heatmap}}
\end{enumerate}
This chapter describes the configurations of a single heatmap.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{1}
\tightlist
\item
\protect\hyperlink{heatmap-annotations.html}{\textbf{Heatmap
Annotations}}
\end{enumerate}
This chapter describes the concept of the heatmap annotation and
demonstrates how to make simple annotations as well as complex
annotations. Also, the chapter explains the difference between column
annotations and row annotations.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{2}
\tightlist
\item
\href{a-list-of-heatmaps.html}{\textbf{A List of Heatmaps}}
\end{enumerate}
This chapter describes how to concatenate a list of heatmaps and
annotations and how adjustment is applied to keep the correspondence of
the heatmaps.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{3}
\tightlist
\item
\href{legends.html}{\textbf{Legends}}
\end{enumerate}
This chapter describes how to configurate the heatmap legends and
annotation legends, also how to create self-defined legends.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{4}
\tightlist
\item
\href{heatmap-decoration.html}{\textbf{Heatmap Decoration}}
\end{enumerate}
This chapter describes methods to add more self-defined graphics to the
heatmaps after the heatmaps are generated.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{5}
\tightlist
\item
\href{oncoprint.html}{\textbf{OncoPrint}}
\end{enumerate}
This chapter describes how to make oncoPrints and how to integrate other
functionalities from \textbf{ComplexHeatmap} to oncoPrints.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{6}
\tightlist
\item
\href{other-high-level-plots.html}{\textbf{Other High-level Plots}}
\end{enumerate}
This chapter describes functions implemented in \textbf{ComplexHeatmap}
for specific use, e.g.~visualizing distributions.
\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\setcounter{enumi}{7}
\tightlist
\item
\href{more-examples.html}{\textbf{More Examples}}
\end{enumerate}
More simulated and real-world examples are shown in this chapter.
\chapter{A single Heatmap}\label{a-single-heatmap}
A single heatmap is the most used way for visualizing the data. Although
``the shining point'' of the \textbf{ComplexHeatmap} package is it can
visualize a list of heatmaps in parallel, as the basic unit of the
heatmap list, it is still very important to have the single heatmap
nicely configured.
First let's generate a random matrix where there are three groups by
columns and three groups by rows:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{set.seed}\NormalTok{(}\DecValTok{123}\NormalTok{)}
\NormalTok{nr1 =}\StringTok{ }\DecValTok{4}\NormalTok{; nr2 =}\StringTok{ }\DecValTok{8}\NormalTok{; nr3 =}\StringTok{ }\DecValTok{6}\NormalTok{; nr =}\StringTok{ }\NormalTok{nr1 }\OperatorTok{+}\StringTok{ }\NormalTok{nr2 }\OperatorTok{+}\StringTok{ }\NormalTok{nr3}
\NormalTok{nc1 =}\StringTok{ }\DecValTok{6}\NormalTok{; nc2 =}\StringTok{ }\DecValTok{8}\NormalTok{; nc3 =}\StringTok{ }\DecValTok{10}\NormalTok{; nc =}\StringTok{ }\NormalTok{nc1 }\OperatorTok{+}\StringTok{ }\NormalTok{nc2 }\OperatorTok{+}\StringTok{ }\NormalTok{nc3}
\NormalTok{mat =}\StringTok{ }\KeywordTok{cbind}\NormalTok{(}\KeywordTok{rbind}\NormalTok{(}\KeywordTok{matrix}\NormalTok{(}\KeywordTok{rnorm}\NormalTok{(nr1}\OperatorTok{*}\NormalTok{nc1, }\DataTypeTok{mean =} \DecValTok{1}\NormalTok{, }\DataTypeTok{sd =} \FloatTok{0.5}\NormalTok{), }\DataTypeTok{nr =}\NormalTok{ nr1),}
\KeywordTok{matrix}\NormalTok{(}\KeywordTok{rnorm}\NormalTok{(nr2}\OperatorTok{*}\NormalTok{nc1, }\DataTypeTok{mean =} \DecValTok{0}\NormalTok{, }\DataTypeTok{sd =} \FloatTok{0.5}\NormalTok{), }\DataTypeTok{nr =}\NormalTok{ nr2),}
\KeywordTok{matrix}\NormalTok{(}\KeywordTok{rnorm}\NormalTok{(nr3}\OperatorTok{*}\NormalTok{nc1, }\DataTypeTok{mean =} \DecValTok{0}\NormalTok{, }\DataTypeTok{sd =} \FloatTok{0.5}\NormalTok{), }\DataTypeTok{nr =}\NormalTok{ nr3)),}
\KeywordTok{rbind}\NormalTok{(}\KeywordTok{matrix}\NormalTok{(}\KeywordTok{rnorm}\NormalTok{(nr1}\OperatorTok{*}\NormalTok{nc2, }\DataTypeTok{mean =} \DecValTok{0}\NormalTok{, }\DataTypeTok{sd =} \FloatTok{0.5}\NormalTok{), }\DataTypeTok{nr =}\NormalTok{ nr1),}
\KeywordTok{matrix}\NormalTok{(}\KeywordTok{rnorm}\NormalTok{(nr2}\OperatorTok{*}\NormalTok{nc2, }\DataTypeTok{mean =} \DecValTok{1}\NormalTok{, }\DataTypeTok{sd =} \FloatTok{0.5}\NormalTok{), }\DataTypeTok{nr =}\NormalTok{ nr2),}
\KeywordTok{matrix}\NormalTok{(}\KeywordTok{rnorm}\NormalTok{(nr3}\OperatorTok{*}\NormalTok{nc2, }\DataTypeTok{mean =} \DecValTok{0}\NormalTok{, }\DataTypeTok{sd =} \FloatTok{0.5}\NormalTok{), }\DataTypeTok{nr =}\NormalTok{ nr3)),}
\KeywordTok{rbind}\NormalTok{(}\KeywordTok{matrix}\NormalTok{(}\KeywordTok{rnorm}\NormalTok{(nr1}\OperatorTok{*}\NormalTok{nc3, }\DataTypeTok{mean =} \FloatTok{0.5}\NormalTok{, }\DataTypeTok{sd =} \FloatTok{0.5}\NormalTok{), }\DataTypeTok{nr =}\NormalTok{ nr1),}
\KeywordTok{matrix}\NormalTok{(}\KeywordTok{rnorm}\NormalTok{(nr2}\OperatorTok{*}\NormalTok{nc3, }\DataTypeTok{mean =} \FloatTok{0.5}\NormalTok{, }\DataTypeTok{sd =} \FloatTok{0.5}\NormalTok{), }\DataTypeTok{nr =}\NormalTok{ nr2),}
\KeywordTok{matrix}\NormalTok{(}\KeywordTok{rnorm}\NormalTok{(nr3}\OperatorTok{*}\NormalTok{nc3, }\DataTypeTok{mean =} \DecValTok{1}\NormalTok{, }\DataTypeTok{sd =} \FloatTok{0.5}\NormalTok{), }\DataTypeTok{nr =}\NormalTok{ nr3))}
\NormalTok{ )}
\NormalTok{mat =}\StringTok{ }\NormalTok{mat[}\KeywordTok{sample}\NormalTok{(nr, nr), }\KeywordTok{sample}\NormalTok{(nc, nc)] }\CommentTok{# random shuffle rows and columns}
\KeywordTok{rownames}\NormalTok{(mat) =}\StringTok{ }\KeywordTok{paste0}\NormalTok{(}\StringTok{"row"}\NormalTok{, }\KeywordTok{seq_len}\NormalTok{(nr))}
\KeywordTok{colnames}\NormalTok{(mat) =}\StringTok{ }\KeywordTok{paste0}\NormalTok{(}\StringTok{"column"}\NormalTok{, }\KeywordTok{seq_len}\NormalTok{(nc))}
\end{Highlighting}
\end{Shaded}
Following command contains the minimal argument for the
\texttt{Heatmap()} function which just visualizes the matrix as a
heatmap with default settings. Very similar as other heatmap tools, it
draws the dendrograms, the row/column names and the heatmap legend. The
default color schema is ``blue-white-red'' which is mapped to the
minimal-mean-maximal values in the matrix. The title for the legend is
assigned by an internal index number.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/default-1} \end{center}
The title for the legend is taken from the ``name'' of the heatmap by
default. Each heatmap has a name which is like a unique identifier for
the heatmap, which is important when you have a list of heatmaps. In
later chapters, you will find the heatmap name is used for setting the
``main heatmap'' and is used for decoration of heatmaps. If the name is
not assigned, an internal name is assigned to the heatmap in a form of
\texttt{matrix\_\%d}. In following examples in this chapter, we give the
name \texttt{mat} to the heatmap (for which you will see the change of
the legend in the next plot).
\section{Colors}\label{colors}
For heatmap visualization, colors are the major representation of the
data matrix. In most cases, the heatmap visualizes a matrix with
continuous numeric values. In this case, users should provide a color
mapping function. A color mapping function should accept a vector of
values and return a vector of corresponding colors. \textbf{Users should
always use \texttt{circlize::colorRamp2()} function to generate the
color mapping function}. The two arguments for \texttt{colorRamp2()} is
a vector of break values and a vector of corresponding colors.
\texttt{colorRamp2()} linearly interpolates colors in every interval
through LAB color space. Also using \texttt{colorRamp2()} helps to
generate a legend with proper tick marks.
In following example, values between -2 and 2 are linearly interpolated
to get corresponding colors, values larger than 2 are all mapped to red
and values less than -2 are all mapped to green.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{library}\NormalTok{(circlize)}
\NormalTok{col_fun =}\StringTok{ }\KeywordTok{colorRamp2}\NormalTok{(}\KeywordTok{c}\NormalTok{(}\OperatorTok{-}\DecValTok{2}\NormalTok{, }\DecValTok{0}\NormalTok{, }\DecValTok{2}\NormalTok{), }\KeywordTok{c}\NormalTok{(}\StringTok{"green"}\NormalTok{, }\StringTok{"white"}\NormalTok{, }\StringTok{"red"}\NormalTok{))}
\KeywordTok{col_fun}\NormalTok{(}\KeywordTok{seq}\NormalTok{(}\OperatorTok{-}\DecValTok{3}\NormalTok{, }\DecValTok{3}\NormalTok{))}
\end{Highlighting}
\end{Shaded}
\begin{verbatim}
## [1] "#00FF00FF" "#00FF00FF" "#B1FF9AFF" "#FFFFFFFF" "#FF9E81FF" "#FF0000FF"
## [7] "#FF0000FF"
\end{verbatim}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{col =}\NormalTok{ col_fun)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-2-1} \end{center}
As you can see, the color mapping function exactly maps negative values
to green and positive values to red, even when the distribution of
negative values and positive values are not centric to zero. Also this
color mapping function is not affected by outliers. In following plot,
the clustering is heavily affected by the outlier but not the color
mapping.
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{mat2 =}\StringTok{ }\NormalTok{mat}
\NormalTok{mat2[}\DecValTok{1}\NormalTok{, }\DecValTok{1}\NormalTok{] =}\StringTok{ }\DecValTok{100000}
\KeywordTok{Heatmap}\NormalTok{(mat2, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{col =}\NormalTok{ col_fun)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-3-1} \end{center}
More importantly, \texttt{colorRamp2()} makes colors in multiple
heatmaps comparible if they are set with a same color mapping function.
If the matrix is continuous, you can simply provide a vector of colors
and colors will be linearly interpolated. But remember this method is
not robust to outliers because the mapping starts from the minimal value
in the matrix and ends with the maximal value. Following color mapping
setting is identical to
\texttt{colorRamp2(seq(min(mat),\ max(mat),\ length\ =\ 10),\ rev(rainbow(10)))}.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{col =} \KeywordTok{rev}\NormalTok{(}\KeywordTok{rainbow}\NormalTok{(}\DecValTok{10}\NormalTok{)))}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-4-1} \end{center}
If the matrix contains discrete values (either numeric or character),
colors should be specified as a named vector to make it possible for the
mapping from discrete values to colors. If there is no name for the
color, the order of colors corresponds to the order of
\texttt{unique(mat)}. Note now the legend is generated from the color
mapping vector.
Following sets colors for a discrete numeric matrix (you don't need to
convert it to a character matrix).
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{discrete_mat =}\StringTok{ }\KeywordTok{matrix}\NormalTok{(}\KeywordTok{sample}\NormalTok{(}\DecValTok{1}\OperatorTok{:}\DecValTok{4}\NormalTok{, }\DecValTok{100}\NormalTok{, }\DataTypeTok{replace =} \OtherTok{TRUE}\NormalTok{), }\DecValTok{10}\NormalTok{, }\DecValTok{10}\NormalTok{)}
\NormalTok{colors =}\StringTok{ }\KeywordTok{structure}\NormalTok{(}\DecValTok{1}\OperatorTok{:}\DecValTok{4}\NormalTok{, }\DataTypeTok{names =} \KeywordTok{c}\NormalTok{(}\StringTok{"1"}\NormalTok{, }\StringTok{"2"}\NormalTok{, }\StringTok{"3"}\NormalTok{, }\StringTok{"4"}\NormalTok{)) }\CommentTok{# black, red, green, blue}
\KeywordTok{Heatmap}\NormalTok{(discrete_mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{col =}\NormalTok{ colors)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-5-1} \end{center}
Or a character matrix:
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{discrete_mat =}\StringTok{ }\KeywordTok{matrix}\NormalTok{(}\KeywordTok{sample}\NormalTok{(letters[}\DecValTok{1}\OperatorTok{:}\DecValTok{4}\NormalTok{], }\DecValTok{100}\NormalTok{, }\DataTypeTok{replace =} \OtherTok{TRUE}\NormalTok{), }\DecValTok{10}\NormalTok{, }\DecValTok{10}\NormalTok{)}
\NormalTok{colors =}\StringTok{ }\KeywordTok{structure}\NormalTok{(}\DecValTok{1}\OperatorTok{:}\DecValTok{4}\NormalTok{, }\DataTypeTok{names =}\NormalTok{ letters[}\DecValTok{1}\OperatorTok{:}\DecValTok{4}\NormalTok{])}
\KeywordTok{Heatmap}\NormalTok{(discrete_mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{col =}\NormalTok{ colors)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/discrete_character_matrix-1} \end{center}
As you see in the two above examples, for the numeric matrix (no matter
the color is continuous mapping or discrete mapping), by default
clustering is applied on both dimensions while for character matrix,
clustering is turned off (but you can still clustering a character
matrix if you provide a proper distance metric for two character
vectors, see example in Section \ref{distance-methods}).
\texttt{NA} is allowed in the matrix. You can control the color of
\texttt{NA} by \texttt{na\_col} argument (by default it is grey for
\texttt{NA}). \textbf{The matrix that contains \texttt{NA} can also be
clustered by \texttt{Heatmap()}.}
Note the \texttt{NA} value is not presended in the legend.
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{mat_with_na =}\StringTok{ }\NormalTok{mat}
\NormalTok{na_index =}\StringTok{ }\KeywordTok{sample}\NormalTok{(}\KeywordTok{c}\NormalTok{(}\OtherTok{TRUE}\NormalTok{, }\OtherTok{FALSE}\NormalTok{), }\KeywordTok{nrow}\NormalTok{(mat)}\OperatorTok{*}\KeywordTok{ncol}\NormalTok{(mat), }\DataTypeTok{replace =} \OtherTok{TRUE}\NormalTok{, }\DataTypeTok{prob =} \KeywordTok{c}\NormalTok{(}\DecValTok{1}\NormalTok{, }\DecValTok{9}\NormalTok{))}
\NormalTok{mat_with_na[na_index] =}\StringTok{ }\OtherTok{NA}
\KeywordTok{Heatmap}\NormalTok{(mat_with_na, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{na_col =} \StringTok{"black"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-6-1} \end{center}
Color space is important for interpolating colors. By default, colors
are linearly interpolated in
\href{https://en.wikipedia.org/wiki/Lab_color_space}{LAB color space},
but you can select the color space in \texttt{colorRamp2()} function.
Compare following two plots. Can you see the difference?
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{f1 =}\StringTok{ }\KeywordTok{colorRamp2}\NormalTok{(}\KeywordTok{seq}\NormalTok{(}\KeywordTok{min}\NormalTok{(mat), }\KeywordTok{max}\NormalTok{(mat), }\DataTypeTok{length =} \DecValTok{3}\NormalTok{), }\KeywordTok{c}\NormalTok{(}\StringTok{"blue"}\NormalTok{, }\StringTok{"#EEEEEE"}\NormalTok{, }\StringTok{"red"}\NormalTok{))}
\NormalTok{f2 =}\StringTok{ }\KeywordTok{colorRamp2}\NormalTok{(}\KeywordTok{seq}\NormalTok{(}\KeywordTok{min}\NormalTok{(mat), }\KeywordTok{max}\NormalTok{(mat), }\DataTypeTok{length =} \DecValTok{3}\NormalTok{), }\KeywordTok{c}\NormalTok{(}\StringTok{"blue"}\NormalTok{, }\StringTok{"#EEEEEE"}\NormalTok{, }\StringTok{"red"}\NormalTok{), }
\DataTypeTok{space =} \StringTok{"RGB"}\NormalTok{)}
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat1"}\NormalTok{, }\DataTypeTok{col =}\NormalTok{ f1, }\DataTypeTok{column_title =} \StringTok{"LAB color space"}\NormalTok{)}
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat2"}\NormalTok{, }\DataTypeTok{col =}\NormalTok{ f2, }\DataTypeTok{column_title =} \StringTok{"RGB color space"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-8-1} \end{center}
In following figures, corresponding values change evenly on the folded
lines, you can see how colors change under different color spaces (the
plot is made by
\href{https://bioconductor.org/packages/release/bioc/html/HilbertCurve.html}{\textbf{HilbertCurve}
package}).
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-9-1} \end{center}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-9-2} \end{center}
Last but not the least, colors for the heatmap borders can be set by the
\texttt{border} and \texttt{rect\_gp} arguments. \texttt{border}
controls the global border of the heatmap body and \texttt{rect\_gp}
controls the border of the grids in the heatmap.
The value of \texttt{border} can be logical (\texttt{TRUE} corresponds
to \texttt{black}) or a character of color (e.g. \texttt{red}).
\texttt{rect\_gp} is a \texttt{gpar} object which means you can only set
it by \texttt{grid::gpar()}. Since the filled color is already
controlled by the heatmap color mapping, you can only set the
\texttt{col} parameter in \texttt{gpar()} to control the border of the
heatmap grids.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{border =} \OtherTok{TRUE}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-10-1} \end{center}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{rect_gp =} \KeywordTok{gpar}\NormalTok{(}\DataTypeTok{col =} \StringTok{"white"}\NormalTok{, }\DataTypeTok{lwd =} \DecValTok{2}\NormalTok{))}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-10-2} \end{center}
\section{Titles}\label{heatmap-titles}
The title of the heatmap basically tells what the plot is about. In
\textbf{ComplexHeatmap} package, you can set heatmap title either by the
row or/and by the column. Note at a same time you can only put
e.g.~column title either on the top or at the bottom of the heatmap.
The graphic parameters can be set by \texttt{row\_title\_gp} and
\texttt{column\_title\_gp} respectively. Please remember you should use
\texttt{gpar()} to specify graphic parameters.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{column_title =} \StringTok{"I am a column title"}\NormalTok{, }
\DataTypeTok{row_title =} \StringTok{"I am a row title"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/row_column_title-1} \end{center}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{column_title =} \StringTok{"I am a column title at the bottom"}\NormalTok{, }
\DataTypeTok{column_title_side =} \StringTok{"bottom"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/row_column_title-2} \end{center}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{column_title =} \StringTok{"I am a big column title"}\NormalTok{, }
\DataTypeTok{column_title_gp =} \KeywordTok{gpar}\NormalTok{(}\DataTypeTok{fontsize =} \DecValTok{20}\NormalTok{, }\DataTypeTok{fontface =} \StringTok{"bold"}\NormalTok{))}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/row_column_title-3} \end{center}
Rotations for titles can be set by \texttt{row\_title\_rot} and
\texttt{column\_title\_rot}, but only horizontal and vertical rotations
are allowed.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{row_title =} \StringTok{"row title"}\NormalTok{, }\DataTypeTok{row_title_rot =} \DecValTok{0}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/title_rotation-1} \end{center}
Row or column title supports as a template which is used when rows or
columns are split in the heatmap (because there will be multiple
row/column titles). This functionality is introduced in Section
\ref{heatmap-split}. A quick example would be:
\begin{Shaded}
\begin{Highlighting}[]
\CommentTok{# code only for demonstration}
\CommentTok{# row title would be cluster_1 and cluster_2}
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{row_km =} \DecValTok{2}\NormalTok{, }\DataTypeTok{row_title =} \StringTok{"cluster_%s"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
You can set \texttt{fill} parameter in \texttt{row\_title\_gp} and
\texttt{column\_title\_gp} to set the background color of titles.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{column_title =} \StringTok{"I am a column title"}\NormalTok{, }
\DataTypeTok{column_title_gp =} \KeywordTok{gpar}\NormalTok{(}\DataTypeTok{fill =} \StringTok{"red"}\NormalTok{, }\DataTypeTok{col =} \StringTok{"white"}\NormalTok{))}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-12-1} \end{center}
\section{Clustering}\label{clustering}
Clustering might be the key component of the heatmap visualization. In
\textbf{ComplexHeatmap} package, hierarchical clustering is supported
with great flexibility. You can specify the clustering either by:
\begin{itemize}
\tightlist
\item
a pre-defined distance method (e.g. \texttt{"eulidean"} or
\texttt{"pearson"}),
\item
a distance function,
\item
a object that already contains clustering (a \texttt{hclust} or
\texttt{dendrogram} object or object that can be coerced to
\texttt{hclust} or \texttt{dendrogram} class),
\item
a clustering function.
\end{itemize}
It is also possible to render the dendrograms with different colors and
styles for different branches for better revealing structures of your
data (e.g.~by \texttt{dendextend::color\_branches()}).
First, there are general settings for the clustering, e.g.~whether apply
clustering or show dendrograms, the side of the dendrograms and heights
of the dendrograms.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{cluster_rows =} \OtherTok{FALSE}\NormalTok{) }\CommentTok{# turn off row clustering}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_basic-1} \end{center}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{show_column_dend =} \OtherTok{FALSE}\NormalTok{) }\CommentTok{# hide column dendrogram}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_basic-2} \end{center}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{row_dend_side =} \StringTok{"right"}\NormalTok{, }\DataTypeTok{column_dend_side =} \StringTok{"bottom"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_basic-3} \end{center}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{column_dend_height =} \KeywordTok{unit}\NormalTok{(}\DecValTok{4}\NormalTok{, }\StringTok{"cm"}\NormalTok{), }
\DataTypeTok{row_dend_width =} \KeywordTok{unit}\NormalTok{(}\DecValTok{4}\NormalTok{, }\StringTok{"cm"}\NormalTok{))}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_basic-4} \end{center}
\subsection{Distance methods}\label{distance-methods}
Hierarchical clustering is performed in two steps: calculate the
distance matrix and apply clustering. There are three ways to specify
distance metric for clustering:
\begin{itemize}
\tightlist
\item
specify distance as a pre-defined option. The valid values are the
supported methods in \texttt{dist()} function and in
\texttt{"pearson"}, \texttt{"spearman"} and \texttt{"kendall"}. If
there is any \texttt{NA} values in the matrix,
\texttt{ComplexHeatmap::dist2()} is used instead which performs
pairwise distance calculation by removing \texttt{NA} values. The
correlation distance is defined as \texttt{1\ -\ cor(x,\ y,\ method)}.
\item
a self-defined function which calculates distance from a matrix. The
function should only contain one argument. Please note for clustering
on columns, the matrix will be transposed automatically.
\item
a self-defined function which calculates distance from two vectors.
The function should only contain two arguments.
\end{itemize}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{clustering_distance_rows =} \StringTok{"pearson"}\NormalTok{,}
\DataTypeTok{column_title =} \StringTok{"pre-defined distance method (1 - pearson)"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_distance-1} \end{center}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{clustering_distance_rows =} \ControlFlowTok{function}\NormalTok{(m) }\KeywordTok{dist}\NormalTok{(m),}
\DataTypeTok{column_title =} \StringTok{"a function that calculates distance matrix"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_distance-2} \end{center}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{clustering_distance_rows =} \ControlFlowTok{function}\NormalTok{(x, y) }\DecValTok{1} \OperatorTok{-}\StringTok{ }\KeywordTok{cor}\NormalTok{(x, y),}
\DataTypeTok{column_title =} \StringTok{"a function that calculates pairwise distance"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_distance-3} \end{center}
Based on these features, we can apply clustering which is robust to
outliers based on the pairwise distance. Note here we set the color
mapping function because we don't want outliers affect the colors.
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{mat_with_outliers =}\StringTok{ }\NormalTok{mat}
\ControlFlowTok{for}\NormalTok{(i }\ControlFlowTok{in} \DecValTok{1}\OperatorTok{:}\DecValTok{10}\NormalTok{) mat_with_outliers[i, i] =}\StringTok{ }\DecValTok{1000}
\NormalTok{robust_dist =}\StringTok{ }\ControlFlowTok{function}\NormalTok{(x, y) \{}
\NormalTok{ qx =}\StringTok{ }\KeywordTok{quantile}\NormalTok{(x, }\KeywordTok{c}\NormalTok{(}\FloatTok{0.1}\NormalTok{, }\FloatTok{0.9}\NormalTok{))}
\NormalTok{ qy =}\StringTok{ }\KeywordTok{quantile}\NormalTok{(y, }\KeywordTok{c}\NormalTok{(}\FloatTok{0.1}\NormalTok{, }\FloatTok{0.9}\NormalTok{))}
\NormalTok{ l =}\StringTok{ }\NormalTok{x }\OperatorTok{>}\StringTok{ }\NormalTok{qx[}\DecValTok{1}\NormalTok{] }\OperatorTok{&}\StringTok{ }\NormalTok{x }\OperatorTok{<}\StringTok{ }\NormalTok{qx[}\DecValTok{2}\NormalTok{] }\OperatorTok{&}\StringTok{ }\NormalTok{y }\OperatorTok{>}\StringTok{ }\NormalTok{qy[}\DecValTok{1}\NormalTok{] }\OperatorTok{&}\StringTok{ }\NormalTok{y }\OperatorTok{<}\StringTok{ }\NormalTok{qy[}\DecValTok{2}\NormalTok{]}
\NormalTok{ x =}\StringTok{ }\NormalTok{x[l]}
\NormalTok{ y =}\StringTok{ }\NormalTok{y[l]}
\KeywordTok{sqrt}\NormalTok{(}\KeywordTok{sum}\NormalTok{((x }\OperatorTok{-}\StringTok{ }\NormalTok{y)}\OperatorTok{^}\DecValTok{2}\NormalTok{))}
\NormalTok{\}}
\end{Highlighting}
\end{Shaded}
and we compare the two heatmaps with or without the robust distance
method:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat_with_outliers, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }
\DataTypeTok{col =} \KeywordTok{colorRamp2}\NormalTok{(}\KeywordTok{c}\NormalTok{(}\OperatorTok{-}\DecValTok{2}\NormalTok{, }\DecValTok{0}\NormalTok{, }\DecValTok{2}\NormalTok{), }\KeywordTok{c}\NormalTok{(}\StringTok{"green"}\NormalTok{, }\StringTok{"white"}\NormalTok{, }\StringTok{"red"}\NormalTok{)),}
\DataTypeTok{column_title =} \StringTok{"dist"}\NormalTok{)}
\KeywordTok{Heatmap}\NormalTok{(mat_with_outliers, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }
\DataTypeTok{col =} \KeywordTok{colorRamp2}\NormalTok{(}\KeywordTok{c}\NormalTok{(}\OperatorTok{-}\DecValTok{2}\NormalTok{, }\DecValTok{0}\NormalTok{, }\DecValTok{2}\NormalTok{), }\KeywordTok{c}\NormalTok{(}\StringTok{"green"}\NormalTok{, }\StringTok{"white"}\NormalTok{, }\StringTok{"red"}\NormalTok{)),}
\DataTypeTok{clustering_distance_rows =}\NormalTok{ robust_dist,}
\DataTypeTok{clustering_distance_columns =}\NormalTok{ robust_dist,}
\DataTypeTok{column_title =} \StringTok{"robust_dist"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/unnamed-chunk-14-1} \end{center}
If there are proper distance methods (like methods in
\href{https://cran.r-project.org/web/packages/stringdist/}{\textbf{stringdist}
package}, you can also cluster a character matrix. \texttt{cell\_fun}
argument will be introduced in Section \ref{customize-the-heatmap-body}.
\begin{Shaded}
\begin{Highlighting}[]
\NormalTok{mat_letters =}\StringTok{ }\KeywordTok{matrix}\NormalTok{(}\KeywordTok{sample}\NormalTok{(letters[}\DecValTok{1}\OperatorTok{:}\DecValTok{4}\NormalTok{], }\DecValTok{100}\NormalTok{, }\DataTypeTok{replace =} \OtherTok{TRUE}\NormalTok{), }\DecValTok{10}\NormalTok{)}
\CommentTok{# distance in the ASCII table}
\NormalTok{dist_letters =}\StringTok{ }\ControlFlowTok{function}\NormalTok{(x, y) \{}
\NormalTok{ x =}\StringTok{ }\KeywordTok{strtoi}\NormalTok{(}\KeywordTok{charToRaw}\NormalTok{(}\KeywordTok{paste}\NormalTok{(x, }\DataTypeTok{collapse =} \StringTok{""}\NormalTok{)), }\DataTypeTok{base =} \DecValTok{16}\NormalTok{)}
\NormalTok{ y =}\StringTok{ }\KeywordTok{strtoi}\NormalTok{(}\KeywordTok{charToRaw}\NormalTok{(}\KeywordTok{paste}\NormalTok{(y, }\DataTypeTok{collapse =} \StringTok{""}\NormalTok{)), }\DataTypeTok{base =} \DecValTok{16}\NormalTok{)}
\KeywordTok{sqrt}\NormalTok{(}\KeywordTok{sum}\NormalTok{((x }\OperatorTok{-}\StringTok{ }\NormalTok{y)}\OperatorTok{^}\DecValTok{2}\NormalTok{))}
\NormalTok{\}}
\KeywordTok{Heatmap}\NormalTok{(mat_letters, }\DataTypeTok{name =} \StringTok{"letters"}\NormalTok{, }\DataTypeTok{col =} \KeywordTok{structure}\NormalTok{(}\DecValTok{2}\OperatorTok{:}\DecValTok{5}\NormalTok{, }\DataTypeTok{names =}\NormalTok{ letters[}\DecValTok{1}\OperatorTok{:}\DecValTok{4}\NormalTok{]),}
\DataTypeTok{clustering_distance_rows =}\NormalTok{ dist_letters, }\DataTypeTok{clustering_distance_columns =}\NormalTok{ dist_letters,}
\DataTypeTok{cell_fun =} \ControlFlowTok{function}\NormalTok{(j, i, x, y, w, h, col) \{ }\CommentTok{# add text to each grid}
\KeywordTok{grid.text}\NormalTok{(mat_letters[i, j], x, y)}
\NormalTok{ \})}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_character_matrix-1} \end{center}
\subsection{Clustering methods}\label{clustering-methods}
Method to perform hierarchical clustering can be specified by
\texttt{clustering\_method\_rows} and
\texttt{clustering\_method\_columns}. Possible methods are those
supported in \texttt{hclust()} function.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{clustering_method_rows =} \StringTok{"single"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_method-1} \end{center}
If you already have clustering objects or a function which directly
returns a clustering object, you can ignore the distance settings and
set \texttt{cluster\_rows} or \texttt{cluster\_columns} to the
clustering objects or clustering functions. If it is a clustering
function, the only argument should be the matrix and it should return a
\texttt{hclust} or \texttt{dendrogram} object or a object that can be
coerced to the two classes.
In following example, we perform clustering with methods from
\textbf{cluster} package either by a pre-calculated clustering object or
a clustering function:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{library}\NormalTok{(cluster)}
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{cluster_rows =} \KeywordTok{as.dendrogram}\NormalTok{(}\KeywordTok{diana}\NormalTok{(mat)),}
\DataTypeTok{cluster_columns =} \KeywordTok{as.dendrogram}\NormalTok{(}\KeywordTok{agnes}\NormalTok{(}\KeywordTok{t}\NormalTok{(mat))), }\DataTypeTok{column_title =} \StringTok{"clustering objects"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_object-1} \end{center}
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{cluster_rows =}\NormalTok{ diana,}
\DataTypeTok{cluster_columns =}\NormalTok{ agnes, }\DataTypeTok{column_title =} \StringTok{"clustering functions"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_object-2} \end{center}
The last command is as same as :
\begin{Shaded}
\begin{Highlighting}[]
\CommentTok{# code only for demonstration}
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{cluster_rows =} \ControlFlowTok{function}\NormalTok{(m) }\KeywordTok{as.dendrogram}\NormalTok{(}\KeywordTok{diana}\NormalTok{(m)),}
\DataTypeTok{cluster_columns =} \ControlFlowTok{function}\NormalTok{(m) }\KeywordTok{as.dendrogram}\NormalTok{(}\KeywordTok{agnes}\NormalTok{(m)), }\DataTypeTok{column_title =} \StringTok{"clutering functions"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
Please note, when \texttt{cluster\_rows} is set as a function, the
argument \texttt{m} is the input \texttt{mat} itself, while for
\texttt{cluster\_columns}, \texttt{m} is the transpose of \texttt{mat}.
\texttt{fastcluster::hclust} implements a faster version of
\texttt{hclust()}. We can set it to \texttt{cluster\_rows} and
\texttt{cluster\_columns} to use the faster version of
\texttt{hclust()}.
\begin{Shaded}
\begin{Highlighting}[]
\CommentTok{# code only for demonstration}
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{cluster_rows =}\NormalTok{ fastcluster}\OperatorTok{::}\NormalTok{hclust, }
\DataTypeTok{cluster_columns =}\NormalTok{ fastcluster}\OperatorTok{::}\NormalTok{hclust)}
\end{Highlighting}
\end{Shaded}
To make it more convinient to use the faster version of
\texttt{hclust()} (assuming you have many heatmaps to construct), it can
be set as a global option. The usage of \texttt{ht\_opt} is introduced
in Section \ref{change-graphic-parameters-simultaneously}.
\begin{Shaded}
\begin{Highlighting}[]
\CommentTok{# code not run when building the vignette}
\NormalTok{ht_opt}\OperatorTok{$}\NormalTok{fast_hclust =}\StringTok{ }\OtherTok{TRUE}
\CommentTok{# now fastcluster::hclust is used in all heatmaps}
\end{Highlighting}
\end{Shaded}
\subsection{Render dendrograms}\label{render-dendrograms}
If you want to render the dendrogram, normally you need to generate a
\texttt{dendrogram} object and render it in the first place, then send
it to the \texttt{cluster\_rows} or \texttt{cluster\_columns} argument.
You can render your \texttt{dendrogram} object by the
\textbf{dendextend} package to make a more customized visualization of
the dendrogram. Note \textbf{ComplexHeatmap} only allows rendering on
the dendrogram edges.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{library}\NormalTok{(dendextend)}
\NormalTok{row_dend =}\StringTok{ }\KeywordTok{as.dendrogram}\NormalTok{(}\KeywordTok{hclust}\NormalTok{(}\KeywordTok{dist}\NormalTok{(mat)))}
\NormalTok{row_dend =}\StringTok{ }\KeywordTok{color_branches}\NormalTok{(row_dend, }\DataTypeTok{k =} \DecValTok{2}\NormalTok{) }\CommentTok{# `color_branches()` returns a dendrogram object}
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{cluster_rows =}\NormalTok{ row_dend)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_dendextend-1} \end{center}
\subsection{Reorder dendrograms}\label{reorder-dendrograms}
In the \texttt{Heatmap()} function, dendrograms are reordered to make
features with larger difference more separated from each others (please
refer to the documentation of \texttt{reorder.dendrogram()}). Here the
difference (or it is called the weight) is measured by the row means if
it is a row dendrogram or by the column means if it is a column
dendrogram. \texttt{row\_dend\_reorder} and
\texttt{column\_dend\_reorder} control whether to apply dendrogram
reordering If they are set to \texttt{TRUE} or \texttt{FALSE}, ot they
control the weight for the reordering if they are set to numeric vectors
(send to the \texttt{wts} argument of \texttt{reorder.dendrogram()}).
The reordering can be turned off by setting e.g.
\texttt{row\_dend\_reorder\ =\ FALSE}.
There are many other methods for reordering dendrograms, e.g.~the
\textbf{dendsort} package. Basically, all these methods still return a
dendrogram that has been reordered, thus, we can firstly generate the
row or column dendrogram based on the data matrix, reorder it by some
method, and assign it back to \texttt{cluster\_rows} or
\texttt{cluster\_columns}.
Compare following three heatmaps:
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{row_dend_reorder =} \OtherTok{FALSE}\NormalTok{, }\DataTypeTok{column_title =} \StringTok{"no reordering"}\NormalTok{)}
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{row_dend_reorder =} \OtherTok{TRUE}\NormalTok{, }\DataTypeTok{column_title =} \StringTok{"applied reordering"}\NormalTok{)}
\KeywordTok{library}\NormalTok{(dendsort)}
\NormalTok{dend =}\StringTok{ }\KeywordTok{dendsort}\NormalTok{(}\KeywordTok{as.dendrogram}\NormalTok{(}\KeywordTok{hclust}\NormalTok{(}\KeywordTok{dist}\NormalTok{(mat))))}
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{cluster_rows =}\NormalTok{ dend, }\DataTypeTok{row_dend_reorder =} \OtherTok{FALSE}\NormalTok{, }
\DataTypeTok{column_title =} \StringTok{"reordering by dendsort"}\NormalTok{)}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/cluster_dendsort-1} \end{center}
\section{Row and column orders}\label{row-and_column_orders}
Clustering is used to adjust row orders and column orders of the
heatmap, but you can still set the order manually by \texttt{row\_order}
and \texttt{column\_order}. If e.g. \texttt{row\_order} is set, row
clustering is turned off.
\begin{Shaded}
\begin{Highlighting}[]
\KeywordTok{Heatmap}\NormalTok{(mat, }\DataTypeTok{name =} \StringTok{"mat"}\NormalTok{, }\DataTypeTok{row_order =} \KeywordTok{order}\NormalTok{(}\KeywordTok{rownames}\NormalTok{(mat)), }
\DataTypeTok{column_order =} \KeywordTok{order}\NormalTok{(}\KeywordTok{colnames}\NormalTok{(mat)))}
\end{Highlighting}
\end{Shaded}
\begin{center}\includegraphics{02-single_heatmap_files/figure-latex/manual_order-1} \end{center}
Note \texttt{row\_dend\_reorder} and \texttt{row\_order} are two
different things. \texttt{row\_dend\_reorder} is applied on the
dendrogram. For any node in the dendrogram, rotating its two branches
actually gives an identical dendrogram, thus, reordering the dendrogram
by automatically rotating sub-dendrogram at every node can help to