kpPlotMarkers {karyoploteR} | R Documentation

## kpPlotMarkers

### Description

Plots markers on the genome as a line with a label on top.

### Usage

    kpPlotMarkers(karyoplot, data=NULL, chr=NULL, x=NULL, y=0.75, labels=NULL,
                         adjust.label.position=TRUE,  ignore.chromosome.ends=FALSE,
                         label.margin=0.001, max.iter=150, label.dist=0.001,
                         marker.parts = c(0.8,0.1, 0.1), text.orientation ="vertical",
                         ymin=NULL, ymax=NULL, data.panel=1, r0=NULL, r1=NULL,
                         line.color="black", label.color="black",
                         pos=NULL, srt=NULL, offset=NULL, clipping=TRUE, ...)

### Arguments

`karyoplot` | (a `KaryoPlot` object) This is the first argument to all data plotting functions of `karyoploteR`. A KaryoPlot object referring to the currently active plot.
`data` | (a `GRanges`) A GRanges object with the data. If `data` is present, `chr` will be set to `seqnames(data)` and `x` to the midpoints of the rages in data. If no parameter `y` is specified and `data` has a column named `y` or `value` this column will be used to define the `y` value of each data point. (defaults to NULL)
`chr` | (a charecter vector) A vector of chromosome names specifying the chromosomes of the data points. If `data` is not NULL, `chr` is ignored. (defaults to NULL)
`x` | (a numeric vector) A numeric vector with the positions (in base pairs) of the data points in the chromosomes. If `data` is not NULL, `x` is ignored. (defaults to NULL)
`y` | (a numeric vector) A numeric vector with the values of the data points. If `y` is not NULL, it is used instead of any data column in `data`. (defaults to 0.75)
`labels` | (a character vector) The labels to be plotted. (defaults to NULL)
`adjust.label.position` | (logical) whether to adjust the label positions to avoid label overlapping (defaults to TRUE)
`ignore.chromosome.ends` | (logical) If TRUE, when adjusting label position marker labels can move beyond the chromosome ends. (defaults to FALSE, do not move out of origin chromosome)
`label.margin` | (numeric) The vertical margin to leave between the ens of the marker line and the marker label. In plot coordinates. (defaults to 0.001)
`max.iter` | (numeric) The maximum number of iterations in the iterative algorithm to adjust the label positioning. (defaults to 150)
`label.dist` | (numeric) The minimum distance between labels to consider them as non-overlapping (defaults to 0.001)
`marker.parts` | (numeruc vector of three elements) The portion of the distance between 0 and y to be filled with a: vertical, diagonal of vertical part of the marker line. (defaults to c(0.8,0.1,0.1), long vertical stem, small diagonal and small vertical on top)
`text.orientation` | ("vertical" or "horizontal) How should the text be plotted. Forced values of srt and pos take precedence. (defaults to "vertical")
`ymin` | (numeric) The minimum value of `y` to be plotted. If NULL, it is set to the min value of the selected data panel. (defaults to NULL)
`ymax` | (numeric) The maximum value of `y` to be plotted. If NULL, it is set to the max value of the selected data panel. (defaults to NULL)
`data.panel` | (numeric) The identifier of the data panel where the data is to be plotted. The available data panels depend on the plot type selected in the call to `plotKaryotype`. (defaults to 1)
`r0` | (numeric) r0 and r1 define the vertical range of the data panel to be used to draw this plot. They can be used to split the data panel in different vertical ranges (similar to tracks in a genome browser) to plot differents data. If NULL, they are set to the min and max of the data panel, it is, to use all the available space. (defaults to NULL)
`r1` | (numeric) r0 and r1 define the vertical range of the data panel to be used to draw this plot. They can be used to split the data panel in different vertical ranges (similar to tracks in a genome browser) to plot differents data. If NULL, they are set to the min and max of the data panel, it is, to use all the available space. (defaults to NULL)
`line.color` | (color) The color of marker line. (defaults to "black")
`label.color` | (color) The color of the label (defaults to "black")
`pos` | (1,2,3,4) The standard pos graphical parameter. If NULL, it's automatically set depending on "text.orientation". (defaults to NULL)
`srt` | (numeric) The standard srt graphical parameter. If NULL, it's automatically set depending on "text.orientation". (defaults to NULL)
`offset` | (numeric) The standard offset graphical parameter. If NULL, it's automatically set depending on "text.orientation". (defaults to NULL)
`clipping` | (boolean) Only used if zooming is active. If TRUE, the data representation will be not drawn out of the drawing area (i.e. in margins, etc) even if the data overflows the drawing area. If FALSE, the data representation may overflow into the margins of the plot. (defaults to TRUE)
`...` | The ellipsis operator can be used to specify any additional graphical parameters. Any additional parameter will be passed to the internal calls to the R base plotting functions.

### Details

This function plots markers on the genome. It implements an interative algorithm to avoid ovelapping between the labels of different markers. Since labels might be plotted in a different position than the original points, a line with three parts (a vertical, a diagonal and another vertical) is plotted to link the label with the original position. It is possible to plot labels in horizontal or vertical text and to specify different colors for the marker line and label.

There's more information at the https://bernatgel.github.io/karyoploter_tutorial/karyoploteR tutorial.

### Value

Returns the original karyoplot object with the data computed (adjusted label positioning) stored at `karyoplot$latest.plot`

### Note

The iterative algorithm is not guaranteed to suceed and might end up with overlapping labels if labels are too dense or if too few iterations allowed. With many markers, the algorithm might be slow.

### See Also

`plotKaryotype`, `kpLines`, `kpText`

### Examples

    data <- toGRanges(data.frame(c("chr1", "chr1", "chr1"), c(20e6, 21e6, 22e6), c(20.01e6, 21.01e6, 22.01e6), labels=c("GeneA", "GeneB", "GeneC")))

    kp <- plotKaryotype("hg19", plot.type=1, chromosomes = "chr1", main="Default markers")
    kpPlotMarkers(kp, data)

    kp <- plotKaryotype("hg19", plot.type=2, chromosomes = "chr1", main="Markers Horizontal")
    kpPlotMarkers(kp, data, text.orientation = "horizontal")
    kpPlotMarkers(kp, data, text.orientation = "horizontal", label.dist = 0.02, data.panel=2)

    kp <- plotKaryotype("hg19", plot.type=2, chromosomes = "chr1", main="Different Marker parts")
    kpPlotMarkers(kp, data, text.orientation = "horizontal", marker.parts=c(0, 1, 0), line.color="red")
    kpPlotMarkers(kp, data, text.orientation = "horizontal", marker.parts=c(0.1, 0.2, 0.4), label.dist = 0.02, data.panel=2, label.color="blue")

[Package karyoploteR version 1.20.3 Index]