Browse code

documentation for UpSet() finished

Zuguang Gu authored on 27/12/2018 12:09:22
Showing6 changed files

... ...
@@ -159,6 +159,8 @@ export("decorate_row_title")
159 159
 export("decorate_title")
160 160
 export("default_axis_param")
161 161
 export("default_get_type")
162
+export("default_upset_right_annotation")
163
+export("default_upset_top_annotation")
162 164
 export("dend_heights")
163 165
 export("dend_xy")
164 166
 export("dendrogramGrob")
... ...
@@ -326,6 +326,11 @@ make_comb_mat = function(..., mode = c("distinct", "intersect", "union"),
326 326
 	make_comb_mat_from_list(lt, value_fun, mode = mode, top_n_sets = top_n_sets, min_set_size = min_set_size)
327 327
 }
328 328
 
329
+
330
+binaryToInt = function(x) {
331
+	sum(x * 2^(rev(seq_along(x)) - 1))
332
+}
333
+
329 334
 # == title
330 335
 # Set Names
331 336
 #
... ...
@@ -455,9 +460,20 @@ comb_degree = function(m) {
455 460
 # Extract Elements in a Combination set
456 461
 #
457 462
 # == param
458
-# -m
459
-# -comb_name
463
+# -m A combination matrix returned by `make_comb_mat`.
464
+# -comb_name The valid combination set name should be from `comb_name`.
465
+#
466
+# == details
467
+# It returns the combination set.
460 468
 #
469
+# == example
470
+# set.seed(123)
471
+# lt = list(a = sample(letters, 10),
472
+# 	      b = sample(letters, 15),
473
+# 	      c = sample(letters, 20))
474
+#
475
+# m = make_comb_mat(lt)
476
+# extract_comb(m, "110")
461 477
 extract_comb = function(m, comb_name) {
462 478
 	all_comb_names = comb_name(m)
463 479
 	if(!comb_name %in% all_comb_names) {
... ...
@@ -652,10 +668,75 @@ print.comb_mat = function(x, ...) {
652 668
 #    the position of sets and combination sets.
653 669
 # -set_order The order of sets.
654 670
 # -comb_order The order of combination sets.
671
+# -top_annotation A `HeatmapAnnotation` object on top of the combination matrix.
672
+# -right_annotation A `HeatmapAnnotation` object on the right of the combination matrix.
655 673
 # -... Other arguments passed to `Heatmap`.
656 674
 #
675
+# == details
676
+# BY default, the sets are on rows and combination sets are on columns. The positions of the
677
+# two types of sets can be switched by transposing the matrix.
678
+#
679
+# When sets are on rows, the default top annotation is the barplot showing the size of each
680
+# combination sets and the default right annotation is the barplot showing the size of the sets.
681
+# The annotations are simply constructed by `HeatmapAnnotation` and `anno_barplot` with some
682
+# parameters pre-set. Users can check the source code of `default_upset_top_annotation` and
683
+# `default_upset_right_annotation` to find out how the annotations are defined.
684
+#
685
+# To change or to add annotations, users just need to define a new `HeatmapAnnotation` object.
686
+# E.g. if we want to change the side of the axis and name on top annotation:
687
+#
688
+#     Upset(..., top_annotation = 
689
+#         HeatmapAnnotation(
690
+#            "Intersection size" = anno_barplot(
691
+#                comb_size(m), 
692
+#                border = FALSE, 
693
+#                gp = gpar(fill = "black"), 
694
+#                height = unit(2, "cm"),
695
+#                axis_param = list(side = "right")
696
+#            ), 
697
+#            annotation_name_side = "right", 
698
+#            annotation_name_rot = 0)
699
+#     )
700
+#
701
+# To add more annotations on top, users just add it in `HeatmapAnnotation`:
702
+#
703
+#     Upset(..., top_annotation = 
704
+#         HeatmapAnnotation(
705
+#            "Intersection size" = anno_barplot(
706
+#                comb_size(m), 
707
+#                border = FALSE, 
708
+#                gp = gpar(fill = "black"), 
709
+#                height = unit(2, "cm"),
710
+#                axis_param = list(side = "right")
711
+#            ), 
712
+#            "anno1" = anno_points(...),
713
+#            "anno2" = some_vector, 
714
+#            annotation_name_side = "right", 
715
+#            annotation_name_rot = 0)
716
+#     )
717
+#
718
+# And so is for the right annotations.
719
+#
720
+# `UpSet` returns a `Heatmap-class` object, which means, you can add it with other heatmaps and annotations
721
+# by ``+`` or `\%v\%`.
722
+#
723
+# == example
724
+# set.seed(123)
725
+# lt = list(a = sample(letters, 10),
726
+# 	      b = sample(letters, 15),
727
+# 	      c = sample(letters, 20))
728
+# m = make_comb_mat(lt)
729
+# UpSet(m)
730
+# UpSet(t(m))
731
+# 
732
+# m = make_comb_mat(lt, mode = "union")
733
+# UpSet(m)
734
+#
657 735
 UpSet = function(m, set_order = order(set_size(m), decreasing = TRUE), 
658
-	comb_order = order(comb_size(m), decreasing = TRUE), ...) {
736
+	comb_order = order(comb_size(m), decreasing = TRUE), 
737
+	top_annotation = default_upset_top_annotation(m),
738
+	right_annotation = default_upset_right_annotation(m),
739
+	...) {
659 740
 
660 741
 	set_on_rows = attr(m, "set_on_rows")
661 742
 	mode = attr(m, "mode")
... ...
@@ -685,11 +766,8 @@ UpSet = function(m, set_order = order(set_size(m), decreasing = TRUE),
685 766
 		}
686 767
 		ht = Heatmap(m2, cluster_rows = FALSE, cluster_columns = FALSE, rect_gp = gpar(type = "none"),
687 768
 			layer_fun = layer_fun, show_heatmap_legend = FALSE,
688
-			top_annotation = HeatmapAnnotation("Combination size" = anno_barplot(comb_size(m), 
689
-					border = FALSE, gp = gpar(fill = "black"), height = unit(2, "cm")), 
690
-				annotation_name_side = "left", annotation_name_rot = 0),
691
-			right_annotation = rowAnnotation("Set size" = anno_barplot(set_size(m), border = FALSE, 
692
-					gp = gpar(fill = "black"), width = unit(3, "cm"))),
769
+			top_annotation = top_annotation,
770
+			right_annotation = right_annotation,
693 771
 			row_names_side = "left",
694 772
 			row_order = set_order, column_order = comb_order, ...)
695 773
 	} else {
... ...
@@ -713,17 +791,75 @@ UpSet = function(m, set_order = order(set_size(m), decreasing = TRUE),
713 791
 		}
714 792
 		ht = Heatmap(m2, cluster_rows = FALSE, cluster_columns = FALSE, rect_gp = gpar(type = "none"),
715 793
 			layer_fun = layer_fun, show_heatmap_legend = FALSE,
716
-			right_annotation = rowAnnotation("Combination size" = anno_barplot(comb_size(m), 
717
-				border = FALSE, gp = gpar(fill = "black"), width = unit(2, "cm"))),
718
-			top_annotation = HeatmapAnnotation("Set size" = anno_barplot(set_size(m), border = FALSE, gp = gpar(fill = "black"),
719
-				height = unit(3, "cm")),
720
-				annotation_name_side = "left", annotation_name_rot = 0),
794
+			top_annotation = top_annotation,
795
+			right_annotation = right_annotation,
721 796
 			row_order = comb_order, column_order = set_order, ...)
722 797
 	}
723 798
 	ht
724 799
 }
725 800
 
801
+# == title
802
+# Default UpSet Top Annotation
803
+#
804
+# == param
805
+# -m A combination matrix which is as same as the one for `UpSet`.
806
+#
807
+# == details
808
+# The default top annotation is actually barplot implemented by `anno_barplot`. For
809
+# how to set the top annotation or bottom annotation in `UpSet`, please refer to `UpSet`.
810
+#
811
+default_upset_top_annotation = function(m) {
812
+	set_on_rows = attr(m, "set_on_rows")
813
+	
814
+	if(set_on_rows) {
815
+		ha = HeatmapAnnotation("Intersection size" = anno_barplot(comb_size(m), 
816
+				border = FALSE, gp = gpar(fill = "black"), height = unit(2, "cm")), 
817
+			annotation_name_side = "left", annotation_name_rot = 0)
818
+	} else {
819
+		ha = HeatmapAnnotation("Set size" = anno_barplot(set_size(m), border = FALSE, 
820
+				gp = gpar(fill = "black"), height = unit(3, "cm")),
821
+			annotation_name_side = "left", annotation_name_rot = 0)
822
+	}
726 823
 
727
-binaryToInt = function(x) {
728
-	sum(x * 2^(rev(seq_along(x)) - 1))
824
+	mode = attr(m, "mode")
825
+	if(set_on_rows) {
826
+		if(mode %in% c("distinct", "intersect")) {
827
+			names(ha) = "Intersection size"
828
+		} else {
829
+			names(ha) = "Union size"
830
+		}
831
+	}
832
+	return(ha)
833
+}
834
+
835
+# == title
836
+# Default UpSet Right Annotation
837
+#
838
+# == param
839
+# -m A combination matrix which is as same as the one for `UpSet`.
840
+#
841
+# == details
842
+# The default right annotation is actually barplot implemented by `anno_barplot`. For
843
+# how to set the right annotation or left annotation in `UpSet`, please refer to `UpSet`.
844
+#
845
+default_upset_right_annotation = function(m) {
846
+	set_on_rows = attr(m, "set_on_rows")
847
+
848
+	if(set_on_rows) {
849
+		ha = rowAnnotation("Set size" = anno_barplot(set_size(m), border = FALSE, 
850
+					gp = gpar(fill = "black"), width = unit(3, "cm")))
851
+	} else {
852
+		ha = rowAnnotation("Intersection size" = anno_barplot(comb_size(m), 
853
+				border = FALSE, gp = gpar(fill = "black"), width = unit(2, "cm")))
854
+	}
855
+
856
+	mode = attr(m, "mode")
857
+	if(!set_on_rows) {
858
+		if(mode %in% c("distinct", "intersect")) {
859
+			names(ha) = "Intersection size"
860
+		} else {
861
+			names(ha) = "Union size"
862
+		}
863
+	}
864
+	return(ha)
729 865
 }
... ...
@@ -8,18 +8,80 @@ Make the UpSet plot
8 8
 }
9 9
 \usage{
10 10
 UpSet(m, set_order = order(set_size(m), decreasing = TRUE),
11
-    comb_order = order(comb_size(m), decreasing = TRUE), ...)
11
+    comb_order = order(comb_size(m), decreasing = TRUE),
12
+    top_annotation = default_upset_top_annotation(m),
13
+    right_annotation = default_upset_right_annotation(m),
14
+    ...)
12 15
 }
13 16
 \arguments{
14 17
 
15 18
   \item{m}{A combination matrix returned by \code{\link{make_comb_mat}}. The matrix can be transposed to switch the position of sets and combination sets.}
16 19
   \item{set_order}{The order of sets.}
17 20
   \item{comb_order}{The order of combination sets.}
21
+  \item{top_annotation}{A \code{\link{HeatmapAnnotation}} object on top of the combination matrix.}
22
+  \item{right_annotation}{A \code{\link{HeatmapAnnotation}} object on the right of the combination matrix.}
18 23
   \item{...}{Other arguments passed to \code{\link{Heatmap}}.}
19 24
 
25
+}
26
+\details{
27
+BY default, the sets are on rows and combination sets are on columns. The positions of the
28
+two types of sets can be switched by transposing the matrix.
29
+
30
+When sets are on rows, the default top annotation is the barplot showing the size of each
31
+combination sets and the default right annotation is the barplot showing the size of the sets.
32
+The annotations are simply constructed by \code{\link{HeatmapAnnotation}} and \code{\link{anno_barplot}} with some
33
+parameters pre-set. Users can check the source code of \code{\link{default_upset_top_annotation}} and
34
+\code{\link{default_upset_right_annotation}} to find out how the annotations are defined.
35
+
36
+To change or to add annotations, users just need to define a new \code{\link{HeatmapAnnotation}} object.
37
+E.g. if we want to change the side of the axis and name on top annotation:
38
+
39
+  \preformatted{
40
+    Upset(..., top_annotation = 
41
+        HeatmapAnnotation(
42
+           "Intersection size" = anno_barplot(
43
+               comb_size(m), 
44
+               border = FALSE, 
45
+               gp = gpar(fill = "black"), 
46
+               height = unit(2, "cm"),
47
+               axis_param = list(side = "right")
48
+           ), 
49
+           annotation_name_side = "right", 
50
+           annotation_name_rot = 0)
51
+    )  }
52
+
53
+To add more annotations on top, users just add it in \code{\link{HeatmapAnnotation}}:
54
+
55
+  \preformatted{
56
+    Upset(..., top_annotation = 
57
+        HeatmapAnnotation(
58
+           "Intersection size" = anno_barplot(
59
+               comb_size(m), 
60
+               border = FALSE, 
61
+               gp = gpar(fill = "black"), 
62
+               height = unit(2, "cm"),
63
+               axis_param = list(side = "right")
64
+           ), 
65
+           "anno1" = anno_points(...),
66
+           "anno2" = some_vector, 
67
+           annotation_name_side = "right", 
68
+           annotation_name_rot = 0)
69
+    )  }
70
+
71
+And so is for the right annotations.
72
+
73
+\code{\link{UpSet}} returns a \code{\link{Heatmap-class}} object, which means, you can add it with other heatmaps and annotations
74
+by \code{+} or \code{\link[=pct_v_pct]{\%v\%}}.
20 75
 }
21 76
 \examples{
22
-# There is no example
23
-NULL
77
+set.seed(123)
78
+lt = list(a = sample(letters, 10),
79
+	      b = sample(letters, 15),
80
+	      c = sample(letters, 20))
81
+m = make_comb_mat(lt)
82
+UpSet(m)
83
+UpSet(t(m))
24 84
 
85
+m = make_comb_mat(lt, mode = "union")
86
+UpSet(m)
25 87
 }
26 88
new file mode 100644
... ...
@@ -0,0 +1,25 @@
1
+\name{default_upset_right_annotation}
2
+\alias{default_upset_right_annotation}
3
+\title{
4
+Default UpSet Right Annotation
5
+}
6
+\description{
7
+Default UpSet Right Annotation
8
+}
9
+\usage{
10
+default_upset_right_annotation(m)
11
+}
12
+\arguments{
13
+
14
+  \item{m}{A combination matrix which is as same as the one for \code{\link{UpSet}}.}
15
+
16
+}
17
+\details{
18
+The default right annotation is actually barplot implemented by \code{\link{anno_barplot}}. For
19
+how to set the right annotation or left annotation in \code{\link{UpSet}}, please refer to \code{\link{UpSet}}.
20
+}
21
+\examples{
22
+# There is no example
23
+NULL
24
+
25
+}
0 26
new file mode 100644
... ...
@@ -0,0 +1,25 @@
1
+\name{default_upset_top_annotation}
2
+\alias{default_upset_top_annotation}
3
+\title{
4
+Default UpSet Top Annotation
5
+}
6
+\description{
7
+Default UpSet Top Annotation
8
+}
9
+\usage{
10
+default_upset_top_annotation(m)
11
+}
12
+\arguments{
13
+
14
+  \item{m}{A combination matrix which is as same as the one for \code{\link{UpSet}}.}
15
+
16
+}
17
+\details{
18
+The default top annotation is actually barplot implemented by \code{\link{anno_barplot}}. For
19
+how to set the top annotation or bottom annotation in \code{\link{UpSet}}, please refer to \code{\link{UpSet}}.
20
+}
21
+\examples{
22
+# There is no example
23
+NULL
24
+
25
+}
... ...
@@ -11,12 +11,19 @@ extract_comb(m, comb_name)
11 11
 }
12 12
 \arguments{
13 13
 
14
-  \item{m}{-m}
15
-  \item{comb_name}{-comb_name}
14
+  \item{m}{A combination matrix returned by \code{\link{make_comb_mat}}.}
15
+  \item{comb_name}{The valid combination set name should be from \code{\link{comb_name}}.}
16 16
 
17
+}
18
+\details{
19
+It returns the combination set.
17 20
 }
18 21
 \examples{
19
-# There is no example
20
-NULL
22
+set.seed(123)
23
+lt = list(a = sample(letters, 10),
24
+	      b = sample(letters, 15),
25
+	      c = sample(letters, 20))
21 26
 
27
+m = make_comb_mat(lt)
28
+extract_comb(m, "110")
22 29
 }