#### 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  }