revised documentations

DESCRIPTION

@@ -2,7 +2,7 @@ Package: circlize
 Type: Package
 Title: Circular Visualization
 Version: 0.4.0
-Date: 2017-3-10
+Date: 2017-4-14
 Author: Zuguang Gu
 Maintainer: Zuguang Gu <[email protected]>
 Depends: R (>= 2.10.0), graphics
@@ -19,8 +19,8 @@ Description: Circular layout is an efficient way for the visualization of huge
     connection between the powerful computational and visual environment in R, 
     circlize gives users more convenience and freedom to design figures for 
     better understanding complex patterns behind multi-dimensional data.
-URL: https://github.com/jokergoo/circlize
+URL: https://github.com/jokergoo/circlize, http://jokergoo.github.io/circlize_book/book/
 License: GPL (>= 2)
-Packaged: 2017-3-10 00:00:00 UTC; Administrator
+Packaged: 2017-4-14 00:00:00 UTC; Administrator
 Repository: CRAN
-Date/Publication: 2017-3-10 00:00:00
+Date/Publication: 2017-4-14 00:00:00

NAMESPACE

@@ -79,6 +79,7 @@ export(uh)
 export(ux)
 export(uy)
 
+S3method(print, CELL_META)
 import(graphics)
 importFrom("GlobalOptions", setGlobalOptions)
 importFrom("colorspace", HLS)

NEWS

@@ -14,6 +14,7 @@ Changes in version 0.4.0
 * `circos.segments()`: graphic parameters can be set as vectors
 * add `circos.genomicIdeogram()`, `circos.genomicHeatmap()`, `circos.genomicLabels()`
 * add `circos.nestes()`
+* vignette has been moved to http://jokergoo.github.io/circlize_book/book/index.html
 
 Changes in version 0.3.10
 ----------------------------------------------------------------------------

R/chordDiagram.R

@@ -47,6 +47,9 @@
 # This function is flexible and contains some settings that may be a little difficult to understand. 
 # Please refer to vignette for better explanation.
 #
+# == seealso
+# http://jokergoo.github.io/circlize_book/book/the-chorddiagram-function.html
+#
 # == value
 # A data frame which contains positions of links, columns are:
 #

R/circos.nested.R

@@ -2,24 +2,24 @@
 # Nested zooming with two circular plots
 #
 # == param
-# -f1 a self-defined function with no argument for making the first circular plot
-# -f2 a self-defined function with no argument for making the second circular plot
+# -f1 a self-defined function for making the first circular plot. The function should have no argument.
+# -f2 a self-defined function for making the second circular plot. The function should have no argument.
 # -correspondance a six-column data frame which contains correspondance between the
 #               coordinates in two circular plots
-# -connection_height the height of the connections, measured as the percent to the radius of the unit circle.
+# -connection_height the height of the connection track, measured as the percent to the radius of the unit circle.
 #         The value can be specified by `uh` or `convert_height` with absolute units.
-# -connection_col filled color for the connection polygons. The value can be a vector with same length as number of rows of ``correspondance``
-# -connection_border border color for the connection polygons
-# -connection_lty line style for the connection polygon borders
-# -connection_lwd connection polygon border width
-# -adjust_start_degree If ``start.degree`` is not set in ``f2()``, the start degree for the second
+# -connection_col filled color of the connection track. The value can be a vector with same length as number of rows of ``correspondance``
+# -connection_border border color of the connection track.
+# -connection_lty line style of the connection track borders
+# -connection_lwd line width of the connection track borders
+# -adjust_start_degree If ``circos.par(start.degree = ...)`` is not set in ``f2()``, the start degree for the second
 #       circular plot will be adjusted to make the distance of sectors between the two plots to the minimal.
 #
 # == details
 # The function visualizes zoomings by combining two circular plots into one page where
-# one is the normal circular plot and the other one only contains regions need to be zoomed.
+# one is the normal circular plot and the other one only contains regions that need to be zoomed.
 # This function automatically arranges the two plots to make it easy to correspond between
-# the original and the zoomed plots.
+# the original and the zoomed sectors.
 #
 # Since the function needs to know the information of the two circular plots, please do not call
 # `circos.clear` in either ``f1()`` or ``f2()``. It will be called internally in `circos.nested`.
@@ -28,6 +28,9 @@
 # Also ``canvas.xlim`` and ``canvas.ylim`` are reset in ``f2()``, they should not be set in ``f2()``
 # either.
 #
+# == seealso
+# http://jokergoo.github.io/circlize_book/book/nested-zooming.html
+#
 # == author
 # Zuguang Gu <[email protected]>
 #

R/genomic.R

@@ -1695,6 +1695,7 @@ posTransform.text = function(region, y, labels, cex = 1, font = par("font"),
 # == param
 # -bed a data frame in bed format, the matrix is stored from the fourth column.
 # -col colors for the heatmaps. The value can be a matrix or a color mapping function generated by `colorRamp2`.
+# -numeric.column column index for the numeric columns. The values can be integer index or character index
 # -border border of the heatmap grids.
 # -border_lwd line width for borders of heatmap grids
 # -border_lty line style for borders of heatmap grids
@@ -1717,27 +1718,41 @@ posTransform.text = function(region, y, labels, cex = 1, font = par("font"),
 # Zuguang Gu <[email protected]>
 #
 # == example
+# \dontrun{
 # circos.initializeWithIdeogram(plotType = c("labels", "axis"))
 # bed = generateRandomBed(nr = 100, nc = 4)
 # col_fun = colorRamp2(c(-1, 0, 1), c("green", "black", "red"))
 # circos.genomicHeatmap(bed, col_fun, side = "inside", border = "white")
 # circos.genomicHeatmap(bed, col_fun, side = "outside", 
 #     line_col = as.numeric(factor(bed[[1]])))
-circos.genomicHeatmap = function(bed, col, border = NA, border_lwd = par("lwd"), 
+# }
+circos.genomicHeatmap = function(bed, col, numeric.column = NULL,
+	border = NA, border_lwd = par("lwd"), 
 	border_lty = par("lty"), connection_height = convert_height(5, "mm"),
 	line_col = par("col"), line_lwd = par("lwd"), line_lty = par("lty"),
 	heatmap_height = 0.15, side = c("inside", "outside"), 
 	track.margin = circos.par("track.margin")) {
 
 	mat = bed[, -(1:3)]
-	mat = mat[, apply(mat, 2, "is.numeric"), drop = FALSE]
-	if(ncol(mat) == 0) {
-		stop("You don't have numeric columns in `bed`.")
+	if(is.null(numeric.column)) {
+		numeric.column = which(apply(mat, 2, "is.numeric"))
+		if(length(numeric.column) == 0) {
+			stop("You don't have numeric columns in `bed`.")
+		}
+	} else {
+		if(is.numeric(numeric.column)) {
+			numeric.column = numeric.column - 3
+		}
 	}
+	mat = mat[, numeric.column, drop = FALSE]
+
 	mat = as.matrix(mat)
 	bed = cbind(bed[, 1:3], mat)
 
 	side = match.arg(side)
+	if(missing(col)) {
+		col = colorRamp2(seq(min(na.rm = TRUE), max(mat, na.rm = TRUE), length = 3), c("blue", "#EEEEEE", "red"))
+	}
 	if(is.function(col)) {
 		col = col(mat)
 	}
@@ -1810,18 +1825,21 @@ circos.genomicHeatmap = function(bed, col, border = NA, border_lwd = par("lwd"),
 # Zuguang Gu <[email protected]>
 # 
 # == example
+# \dontrun{
 # circos.initializeWithIdeogram(plotType = c("labels", "axis"))
 # bed = generateRandomBed(nr = 100, fun = function(k) sample(letters, k, replace = TRUE))
 # bed[1, 4] = "aaaaaaaa"
 # circos.genomicLabels(bed, labels.column = 4, side = "inside",
 #     col = as.numeric(factor(bed[[1]])))
 # circos.genomicLabels(bed, labels.column = 4, side = "outside",
 #     line_col = as.numeric(factor(bed[[1]])))
+# }
 circos.genomicLabels = function(bed, labels = NULL, labels.column = NULL,
 	col = par("col"), cex = 0.8, font = par("font"), padding = 0.4,
 	connection_height = convert_height(5, "mm"), 
 	line_col = par("col"), line_lwd = par("lwd"), line_lty = par("lty"),
-	labels_height = min(c(convert_height(1.5, "cm"), max(strwidth(labels, cex = cex, font = font)))),
+	labels_height = min(c(convert_height(1.5, "cm"), 
+		max(strwidth(labels, cex = cex, font = font)))),
 	side = c("inside", "outside"), track.margin = circos.par("track.margin")) {
 
 	if(is.null(labels)){

R/genomic_utils.R

@@ -16,19 +16,17 @@
 #
 # You can find the data structure of the cytoband data from http://hgdownload.cse.ucsc.edu/goldenpath/hg19/database/cytoBand.txt.gz
 #
-# If ``sort.chr`` is not set and ``chromosome.index`` is not specified, there would be several circumstances when 
-# determining the order of chromosomes. Assuming ``chromosome`` is the first column in the cytoband data frame,
-# then, if ``cytoband`` is defined as a file path, or ``species`` is set, the order of chromosomes is ``unique(chromosome)`` 
-# which is read from the file; If ``cytoband``
-# is set as a data frame and the first column is a factor, the order of chromosomes is ``levels(chromosome)``; If ``cytoband`` is a data frame
-# and the first column is just a character vector, the order of chromosomes is ``unique(chromosome)``. Please not this concept is really
-# important since the order of chromosomes will be used to control the order of sectors when initializing the circos plot.
-#
 # == values
 # -``df``         Data frame for cytoband data (rows are sorted if ``sort.chr`` is set to ``TRUE``)
 # -``chromosome`` Sorted chromosome names
 # -``chr.len``    Length of chromosomes. Orders are same as ``chromosome``
 #
+# == example
+# data = read.cytoband(species = "hg19")
+# data = read.cytoband(cytoband = system.file(package = "circlize", "extdata", "cytoBand.txt"))
+# cytoband = read.table(system.file(package = "circlize", "extdata", "cytoBand.txt"), 
+#     colClasses = c("character", "numeric", "numeric", "character", "character"), sep = "\t")
+# data = read.cytoband(cytoband = cytoband)
 read.cytoband = function(cytoband = system.file(package = "circlize",
     "extdata", "cytoBand.txt"), species = NULL, chromosome.index = NULL, sort.chr = TRUE) {
 
@@ -119,21 +117,19 @@ read.cytoband = function(cytoband = system.file(package = "circlize",
 # The function read the chromInfo data, sort the chromosome names and calculate the length of each chromosome. 
 # By default, it is human hg19 chromInfo data.
 #
-# You can find the data structure for the cytoband data from http://hgdownload.cse.ucsc.edu/goldenpath/hg19/database/chromInfo.txt.gz
-#
-# If ``sort.chr`` is not set and ``chromosome.index`` is not specified, there would be several circumstances when determining the order of chromosomes. 
-# Assuming ``chromosome`` is the first column in the chromInfo data frame,
-# then, if ``chromInfo`` is defined as a file path, or ``species`` is set, the order of chromosomes is ``unique(chromosome)`` 
-# which is read from the file; If ``chromInfo``
-# is set as a data frame and the first column is a factor, the order of chromosomes is ``levels(chromosome)``; If ``chromInfo`` is a data frame
-# and the first column is just a character vector, the order of chromosomes is ``unique(chromosome)``. Please not this concept is really
-# important since the order of chromosomes will be used to control the order of sectors when initializing the circos plot.
+# You can find the data structure for the chromInfo data from http://hgdownload.cse.ucsc.edu/goldenpath/hg19/database/chromInfo.txt.gz
 #
 # == values
 # -``df``         Data frame for chromInfo data (rows are sorted if ``sort.chr`` is set to ``TRUE``)
 # -``chromosome`` Sorted chromosome names
 # -``chr.len``    Length of chromosomes. Order are same as ``chromosome``
 #
+# == example
+# data = read.chromInfo(species = "hg19")
+# data = read.chromInfo(chromInfo = system.file(package = "circlize", "extdata", "chromInfo.txt"))
+# chromInfo = read.table(system.file(package = "circlize", "extdata", "chromInfo.txt"), 
+#     colClasses = c("character", "numeric"), sep = "\t")
+# data = read.chromInfo(chromInfo = chromInfo)
 read.chromInfo = function(chromInfo = system.file(package = "circlize",
     "extdata", "chromInfo.txt"), species = NULL, chromosome.index = NULL, sort.chr = TRUE) {
 

R/global.R

@@ -18,8 +18,8 @@ resetGlobalVariable()
 # == param
 # -... Arguments for the parameters, see "details" section
 # -RESET reset to default values
-# -READ.ONLY whether only return read-only options
-# -LOCAL switch local mode
+# -READ.ONLY please ignore
+# -LOCAL please ignore
 # 
 # == details
 # Global parameters for the circular layout. Currently supported parameters are:
@@ -180,15 +180,14 @@ is.circos.initialized = function() {
 # Initialize the circular layout
 #
 # == param
-# -factors Factors which represent data categories
+# -factors A `factor` variable or a character vector which represent data categories
 # -x       Data on x-axes, a vector
 # -xlim    Ranges for values on x-axes, see "details" section for explanation of the format
 # -sector.width Width for each sector. The length of the vector should be either 1 which means
 #          all sectors have same width or as same as the number of sectors. Values for
-#          the vector are relative, and they will be scaled by dividing their summation. It is
-#          encouraged to manually set ``sector.width``.
+#          the vector are relative, and they will be scaled by dividing their summation. 
 #          By default, it is ``NULL`` which means the width of sectors correspond to the data
-#          range in sectors which is calculated internally.
+#          range in sectors.
 #
 # == details
 # The function allocates the sectors according to the values on x-axis.
@@ -209,10 +208,13 @@ is.circos.initialized = function() {
 #
 # Normally, width of sectors will be calculated internally according to the data range in sectors. But you can
 # still set the width manually. However, it is not always a good idea to change the default sector width since
-# the width can reflect the range of data in sectors. Anyway, in some cases, it is useful to manually set
-# the width such as you want to zoom in some part of the sectors.
+# the width can reflect the range of data in sectors. However, in some cases, it is useful to manually set
+# the width such as you want to zoom some part of the sectors.
 #
-# The function finally calls `graphics::plot` with enforing aspect ratio being 1 and be ready for adding graphics.
+# The function finally calls `graphics::plot` with enforing aspect ratio to be 1 and be ready for adding graphics.
+#
+# == seealso
+# http://jokergoo.github.io/circlize_book/book/circular-layout.html
 circos.initialize = function(factors, x = NULL, xlim = NULL, sector.width = NULL) {
 
     resetGlobalVariable()
@@ -395,12 +397,12 @@ circos.initialize = function(factors, x = NULL, xlim = NULL, sector.width = NULL
 }
 
 # == title
-# Reset the circos layout parameters
+# Reset the circular layout parameters
 #
 # == details
 # Because there are several
 # parameters for the circular plot which can only be set before `circos.initialize`. So before you draw the next
-# circular plot, you need to reset these parameters.
+# circular plot, you need to reset all these parameters.
 #
 # If you meet some errors when re-drawing the circular plot, try running this function and it will solve most of the problems.
 circos.clear = function() {
@@ -528,7 +530,7 @@ has.cell = function(sector.index, track.index) {
 # all sectors and all tracks. If ``sector.index`` and/or ``track.index`` are set,
 # the function would print ``xlim``, ``ylim``, ``cell.xlim``, ``cell.ylim``,
 # ``xplot``, ``yplot``, ``track.margin`` and ``cell.padding`` for every cell in specified sectors and tracks.
-# Also, the function will print index for your current sector and current track.
+# Also, the function will print index of your current sector and current track.
 #
 # If ``plot`` is set to ``TRUE``, the function will plot the index of the sector and the track 
 # for each cell on the figure.
@@ -643,8 +645,20 @@ show.index = function() {
 # -``track.margin``         Margin for the cell
 # -``cell.padding``         Padding for the cell
 #
-# The function is useful when using ``panel.fun`` in `circos.trackPlotRegion` to
+# The function is useful when using ``panel.fun`` in `circos.track` to
 # get detailed information of the current cell.
+#
+# == seealso
+# `CELL_META` is a short version of `get.cell.meta.data`.
+#
+# == example
+# factors = letters[1:4]
+# circos.initialize(factors, xlim = c(0, 1))
+# circos.trackPlotRegion(ylim = c(0, 1), panel.fun = function(x, y) {
+#     print(get.cell.meta.data("xlim"))
+# })
+# print(get.cell.meta.data("xlim", sector.index = "a", track.index = 1))
+# circos.clear()
 get.cell.meta.data = function(name, sector.index = get.current.sector.index(), 
                               track.index = get.current.track.index()) {
 	if(length(sector.index) == 0) {
@@ -750,6 +764,15 @@ get.cell.meta.data = function(name, sector.index = get.current.sector.index(),
 #
 # == seealso
 # `get.cell.meta.data`
+#
+# == example
+# pdf(NULL)
+# circos.initialize("a", xlim = c(0, 1))
+# circos.track(ylim = c(0, 1), panel.fun = function(x, y) {
+# 	print(CELL_META$sector.index)
+# 	print(CELL_META$xlim)
+# })
+# dev.off()
 CELL_META = "don't use me directly"
 class(CELL_META) = "CELL_META"
 

R/link.R

@@ -3,16 +3,16 @@
 # Draw links between points or/and intervals
 #
 # == param
-# -sector.index1 Index for the first sector where one root locates
+# -sector.index1 Index for the first sector where one link end locates
 # -point1        A single value or a numeric vector of length 2. If it is a 2-elements vector, then
 #                the link would be a belt/ribbon.
-# -sector.index2 Index for the other sector where the other root locates
+# -sector.index2 Index for the other sector where the other link end locates
 # -point2        A single value or a numeric vector of length 2. If it is a 2-elements vector, then
 #                the link would be a belt/ribbon.
-# -rou           The position of the 'root' of the link (if ``rou1`` and ``rou2`` are not set). It is the percentage of the radius of the unit circle.
+# -rou           The position of the the link ends (if ``rou1`` and ``rou2`` are not set). It is the percentage of the radius of the unit circle.
 #                By default its value is the position of bottom margin of the most inner track.
-# -rou1          The position of root 1 of the link. 
-# -rou2          The position of root 2 of the link.
+# -rou1          The position of end 1 of the link. 
+# -rou2          The position of end 2 of the link.
 # -h             Height of the link, measured as percent to the radius to the unit circle. By default it is automatically infered.
 # -w             Since the link is a Bezier curve, it controls the shape of Bezier curve.
 # -h2            Height of the bottom edge of the link if it is a ribbon.
@@ -21,7 +21,7 @@
 # -lwd           Line (or border) width
 # -lty           Line (or border) style
 # -border        If the link is a ribbon, then it is the color for the ribbon border.
-# -directional   0 for no direction, 1 for direction from point1 to point2, -1 for direction from point2 to point1.
+# -directional   0 for no direction, 1 for direction from ``point1`` to ``point2``, -1 for direction from ``point2`` to ``point1``.
 #                2 for two directional. The direction is important when arrow heads are added.
 # -arr.width     Width of the arrows, pass to `shape::Arrowhead`.
 # -arr.type      Type of the arrows, pass to `shape::Arrowhead`. Default value is ``triangle``. There is an additional option
@@ -40,7 +40,11 @@
 # By default you only need to set ``sector.index1``, ``point1``, ``sector.index2`` and ``point2``. The
 # links would look nice. 
 #
-# See vignette for detailed explanation.
+# Please refer to the vignette for detailed explanation.
+#
+# == seealso
+# http://jokergoo.github.io/circlize_book/book/graphics.html#links
+#
 circos.link = function(sector.index1, point1, sector.index2, point2,
     rou = get_most_inside_radius(),
     rou1 = rou, rou2 = rou, h = NULL, w = 1, h2 = h, w2 = w,