hc_points-HilbertCurve-method {HilbertCurve} | R Documentation

## Add points to the Hilbert curve

### Description

Add points to the Hilbert curve

### Usage

    ## 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", "max_freq"),
        shape = "circle")

### Arguments

`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 four modes: "w0", "weighted", "absolute" and "max_freq" 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".

### Details

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.

There is one more value for `mean_mode` which is `max_freq`. `max_freq` is mainly for discrete signals and in a segment, value with the highest frequency (or with the highest length) is selected for this segment

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`.

### Value

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

### Author(s)

Zuguang Gu <z.gu@dkfz.de>

### Examples

    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"))

[Package HilbertCurve version 1.24.0 Index]