hc_points-HilbertCurve-method: Add points to the Hilbert curve
In HilbertCurve: Making 2D Hilbert Curve

Description Usage Arguments Details Value Author(s) Examples

Add points to the Hilbert curve

## S4 method for signature 'HilbertCurve'
hc_points(object, ir = NULL, x1 = NULL, x2 = x1,
    np = max(c(2, 10 - hc_level(object))), size = unit(1, "char"),
    pch = 1, gp = gpar(), mean_mode = c("w0", "absolute", "weighted"),
    shape = "circle")

`object`	A `HilbertCurve-class` object.
`ir`	an `IRanges` object which specifies the input intervals.
`x1`	if start positions are not integers, they can be set by `x1`.
`x2`	if end positions are not integers, they can be set by `x2`.
`np`	number of points (a circle or a square, ...) that are put in a segment. `np` controls the mode of how to add the points to the curve. See 'Details' section.
`size`	size of the points. It should be a `unit` object. Only works if `np <= 1`
`pch`	shape of points, used for points if `np <= 1`.
`gp`	graphic parameters for points. It should be specified by `gpar`.
`mean_mode`	when `np >= 2`, each segment on the curve is split into `np` windows and each window actually represents an small interval in the axis. When overlapping input intervals to the windows on the curve and when the window can not completely cover the input intervals, some averaging method should be applied to get a more accurate estimation for the value in the window. Here the HilbertCurve package provides three modes: "w0", "weighted" and "absolute" which calculate the mean value in the window with respect to different scenarios. See 'Details' section and the vignette for more informative explanation.
`shape`	shape of points, used for points if `np >= 2`. Possible values are "circle", "square", "triangle", "hexagon", "star".

If np is set to 1 or NULL, points will be added in the middle for each interval in ir (or x1, x2).

If np is set to a value larger or equal to 2, every segment on the curve is split by np points (e.g. circles). In this case, each point actually represent a window on the curve and when the window is not fully covered by the input intervals, there are three different metrics to average the values in the window.

Following illustrates different settings for mean_mode:

       100    80     60    values in ir
    ++++++   +++   +++++   ir
      ================     window (width = 16)
        4     3     3      overlap

    absolute: (100 + 80 + 60)/3
    weighted: (100*4 + 80*3 + 60*3)/(4 + 3 + 3)
    w0:       (100*4 + 80*3 + 60*3 + 0*6)/16

So which mode to use depends on specific scenario. If the background is not of interest, absolute and weighted modes may be proper and if the value also needs to be averaged with background, w0 is the proper choice. Section "Averaging models" in the vignette gives a more detailed explanation for this argument.

If np >= 2, the value of np also controls the size of points.

Graphic parameters is always represented as numeric values (e.g. colors can be converted into numeric RGB values) and they will be averaged according to above rules.

Internally, it will depatch to hc_normal_points,HilbertCurve-method or hc_segmented_points,HilbertCurve-method depending on the value of np.

A data frame which contains coordinates (in the 2D space) of points.

Zuguang Gu <z.gu@dkfz.de>

hc = HilbertCurve(1, 100, level = 4, reference = TRUE)

x = sort(sample(100, 20))
s = x[1:10*2 - 1]
e = x[1:10*2]
require(IRanges)
ir = IRanges(s, e)

hc_points(hc, ir)

hc = HilbertCurve(1, 100, level = 4, reference = TRUE)
hc_points(hc, x1 = c(1.5, 50.5), x2 = c(10.5, 60.5))

require(circlize)
value = runif(length(ir))
col_fun = colorRamp2(range(value), c("white", "red"))
hc = HilbertCurve(1, 100, level = 4, reference = TRUE)
hc_points(hc, ir, np = 3, shape = "star", gp = gpar(fill = col_fun(value)))

hc = HilbertCurve(1, 100, level = 4, reference = TRUE)
hc_points(hc, ir, np = 0)

hc = HilbertCurve(1, 100, level = 4, reference = TRUE)
hc_points(hc, np = 0, x1 = c(1.5, 50.5), x2 = c(10.5, 60.5))
hc_points(hc, np = 0, x1 = 70.5, gp = gpar(col = "red"))

Loading required package: grid
========================================
HilbertCurve version 1.20.0
Bioconductor page: http://bioconductor.org/packages/HilbertCurve/
Github page: https://github.com/jokergoo/HilbertCurve
Documentation: http://bioconductor.org/packages/HilbertCurve/

If you use it in published research, please cite:
Gu, Z. HilbertCurve: an R/Bioconductor package for high-resolution 
  visualization of genomic data. Bioinformatics 2016.
========================================

Loading required package: IRanges
Loading required package: BiocGenerics
Loading required package: parallel

Attaching package: ‘BiocGenerics’

The following objects are masked from ‘package:parallel’:

    clusterApply, clusterApplyLB, clusterCall, clusterEvalQ,
    clusterExport, clusterMap, parApply, parCapply, parLapply,
    parLapplyLB, parRapply, parSapply, parSapplyLB

The following objects are masked from ‘package:stats’:

    IQR, mad, sd, var, xtabs

The following objects are masked from ‘package:base’:

    anyDuplicated, append, as.data.frame, basename, cbind, colnames,
    dirname, do.call, duplicated, eval, evalq, Filter, Find, get, grep,
    grepl, intersect, is.unsorted, lapply, Map, mapply, match, mget,
    order, paste, pmax, pmax.int, pmin, pmin.int, Position, rank,
    rbind, Reduce, rownames, sapply, setdiff, sort, table, tapply,
    union, unique, unsplit, which.max, which.min

Loading required package: S4Vectors
Loading required package: stats4

Attaching package: ‘S4Vectors’

The following object is masked from ‘package:base’:

    expand.grid

Loading required package: circlize
========================================
circlize version 0.4.11
CRAN page: https://cran.r-project.org/package=circlize
Github page: https://github.com/jokergoo/circlize
Documentation: https://jokergoo.github.io/circlize_book/book/

If you use it in published research, please cite:
Gu, Z. circlize implements and enhances circular visualization
  in R. Bioinformatics 2014.

This message can be suppressed by:
  suppressPackageStartupMessages(library(circlize))
========================================