tk.browse {Rgb} | R Documentation

## R Genome browser

### Description

The `browsePlot` function produces an usual R plot from a `drawable` inheriting object list, at specific coordinates in the genome.

The `tk.browse` function summons a TCL-TK interface to navigate through the whole genome, relying on `browsePlot` for the plotting.

The former may be called directly to automatically export views from the genome browser, the latter is more suited to an interactive browsing with frequent coordinate jumps.

### Usage

      tk.browse(drawables = drawable.list(), blocking = FALSE, updateLimit = 0.4,
        render = c("auto", "png", "tkrplot"), tkrplot.scale = 1, png.res = 100,
        png.file = tempfile(fileext=".png"), panelWidth = "5 cm", panel = NA)
      browsePlot(drawables, chrom = NA, start = NA, end = NA, customLayout = FALSE,
        xaxt = "s", xaxm = 1.5, panelWidth = "5 cm", panel = NA, ...)

### Arguments

`drawables` | A `drawable.list` object containing the tracks to plot, as returned by `drawable.list` or `tk.tracks`.
`blocking` | Single logical value, whether to wait for the interface window to be closed before unfreezing the R console. The `FALSE` default let you use R and the interface in parallel (see the 'Typing R commands while browsing' section below), the codeTRUE value is used essentially in the stand alone version.
`updateLimit` | Single numeric value, minimal time (in seconds) between two image updates when move or zoom key are continuously pressed. This is used to limit zoom and move speed on fast computers.

`render`

Single character value from the ones listed, defining the rendering engine for the plot. "png" is recommended and the default on any platform supporting it (needs Tcl-tk version 8.6 or higher, already available on Linux and MacOS and on Windows with R version 3.4.0 or above), and consists in displaying an export to a PNG file. "tkrplot" is more limited and kept only for backward compatibility, it relies on the external package `tkrplot` and the Windows "metafile" format. "auto" (the dzfault) will select the best engine considering to the capabilities of your installation.

`tkrplot.scale` | Single numeric value, defining a multiplying factor for plot size with the "tkrplot" engine. This argument is mainly provided to temper a bug with the "Font size multiplication factor" feature of last Windows operating system version, and get plots filling the whole Rgb window. As an example if you use a 150
`png.res` | Single integer value, the resolution of the plot in Pixels Per Inches. Passed to `png`, see the corresponding manual for further details. This has no effect with the "tkrplot" engine used on Windows prior to R version 3.4.0.

`png.file`

Single character value, the path to the PNG file that is displayed in the main window. The default behavior is to hide it in a temporary location, however you can define this argument to have an easier access to the images displayed in Rgb (the image will be replaced each time Rgb refresh its display). This has no effect with the "tkrplot" engine used on Windows prior to R version 3.4.0.

`panelWidth` | Single value, the width of the panel displays on the left of the tracks, if any is to be plotted. This is handled by the `width` argument of the `layout` function, and thus can be defined as a fixed size in centimeters or a relative size considering that the main display has a weight of 1.
`panel` | Single logical value, wheter to force a panel to be displayed or to not be displayed. Default value of `NA` let the function decide according to the current track settings.
`chrom` | Single character value, the chromosome to plot.
`start` | Single integer value, the left boundary of the window to plot. `NA` will use 0.
`end` | Single integer value, the right boundary of the window to plot. `NA` will use the maximal drawable$getChromEnd() value throughout `trackList`.
`customLayout` | Single logical value, whether to organize the various plot or not. If `FALSE`, `layout` will be called and you will not be able to add custom plots. If `TRUE`, it is up to the user to define its `layout` call to handle the track plots that will be issued by the function.
`xaxt` | X axis showing (see `par`). Only applied to the last track, other ones never show their X axis ("n").
`xaxm` | Minimal bottom margin for the last track (see `par`). It assures enough margin is reserved for X axis showing (see `xaxt`).
`...` | Further arguments are passed through to the `draw` method of each track in `trackList`.

### Value

`tk.browse` invisibly returns the `drawables` argument (See the 'Typing R commands while browsing' section above).

`browsePlot` invisibly returns the `par` function output for the last track plot, as it is used by `tk.browse`.

### Interactive browsing

#### Jump to specific location

The left upper panel can be used to jump to specific coordinates, defined by a chromosome name, a starting position and an ending position (as floating point numerics in millions of base pairs.

#### Move along a chromosome

The left and right arrow keys may be used to shift the window to the corresponding side. The page-up and page-down keys can be used to switch chromosome, without changing genomic numeric position.

#### Generic zoom

The up and down arrow keys, as well as the vertical mouse wheel, may be used to zoom in or out on the current location.

#### Localized zoom in

A zoom can also be achieved with a mouse drag on the region to investigate : maintain a left click on the position to use as the new left boundary, and release the click at the position of the new right boundary.

#### Resize plot area

The plot area size is defined by `hscale` and `vscale`. During interactive browsing, resize the browser window and use the "r" key to adjust the plot area to the window size.

### Typing R commands while browsing

`tk.browse` returns the `drawable.list` objects it uses to store currently browsed data. As it is a reference class object, the same memory location is shared by `tk.browse` and the returned object, so updates (like track addition or edition) made by `tk.browse` will impact the object in the R Command Line Interface (CLI), and updates made via R commands will impact the current `tk.browse` session.

Some sub-interfaces (like information pop-ups and track selection panels) may freeze the R command prompt while opened, make sure to have only the `tk.browse` main window opened when typing R commands.

Notice some operating systems (including Windows) restrain users to type R commands while a tcl-tk window is opened, or seems to be instable while doing so. Setting `blocking` to `TRUE` will enforce this behavior, keeping users from typing commands while `tk.browse` is running.

### Author(s)

Sylvain Mareschal

### See Also

`singlePlot`, `drawable.list`, `drawable`

[Package Rgb version 1.6.1 Index]