gmovizInitialise {gmoviz} | R Documentation

## Initialise the layout of the circular plot

### Description

Draws the ideogram (sectors around a circle representing sequences of interest, like chromosomes), labels and genomic axis in preparation for the addition of other tracks like `drawFeatureTrack` or `drawLinegraphTrack`.

### Usage

    gmovizInitialise(ideogram_data, start_degree = 90,
      space_between_sectors = 1, zoom_sectors = NULL, zoom_size = 0.055,
      remove_unzoomed = TRUE, zoom_prefix = "zoomed_",
      custom_sector_width = NULL, track_height = 0.1,
      sector_colours = nice_colours, sector_border_colours = nice_colours,
      coverage_rectangle = NULL, coverage_data = NULL,
      custom_ylim = NULL, sector_labels = TRUE, sector_label_size = 0.9,
      sector_label_colour = "black", xaxis = TRUE,
      xaxis_orientation = "top", xaxis_label_size = 0.75,
      xaxis_colour = "#747577", xaxis_spacing = 10,
      xaxis_spacing_unit = "deg", label_data = NULL,
      label_colour = "black", label_size = 0.85,
      space_between_labels = 0.4, label_orientation = "outside",
      sort_sectors = TRUE)

### Arguments

`ideogram_data` | Either a GRanges representing regions of interest or a data frame in bed format (containing the `chr`, `start` and `end` columns). If you want to read in data from file, please see the `getIdeogramData` function.
`start_degree` | Where on the circle the first sector will start being drawn from (90 = 12 o'clock).
`space_between_sectors` | Space between each sector.
`zoom_sectors` | A character vector of sectors that should be 'zoomed' (made bigger than usual, useful to show shorter sequences like plasmids alongside longer sequences like chromosomes).
`zoom_size` | The size of the zoomed chromosome, as a proportion of the entire circle (0 = invisible, 1 = entire circle filled). The default value of `0.055` is good for displaying something small (e.g. plasmid) alongside something large (e.g. chromosomes).
`remove_unzoomed` | If `TRUE`, the sectors in `zoom_sectors` will only appear in their zoomed form. If `FALSE`, both the zoomed and unzoomed versions will be plotted.
`zoom_prefix` | A character prefix that will be applied to zoomed sequences to distinguish them from non-zoomed ones.
`custom_sector_width` | Normally, the size of each sector is proportional to its relative length, but `custom_sector_width` can change this. It is a vector of sector sizes (as proportions of the entire circle), given in the same order in which sectors are plotted: firstly 'chr1', 'chr2' ... through to 'chrX' and 'chrY' followed by any differently named sectors e.g. 'gene 1', plasmid' in alphabetical order.
`track_height` | The height (vertical distance around the circle) that will be taken up by this track. Should be a number between 0 (none) and 1 (entire circle).
`sector_colours` | Either a single colour (which will be applied to all sectors) or a vector with the same length as the number of sectors/regions. This package includes 5 colour sets: `nice_colours`, `pastel_colours`, `bright_colours_transparent`, `bright_colours_opaque` and `rich_colours`. See `colourSets` for more information about these.
`sector_border_colours` | Same as `sector_colours`, only for the border of each sector.
`coverage_rectangle` | A vector containing the name(s) of any sector(s) that you would like to depict as 'coverage rectangles': filled in shapes that are a plot of the coverage data over that sector. See the example below or the vignette for an example of this.
`coverage_data` | A GRanges (or data frame) containing the coverage data to plot for those sectors in `coverage_rectangle`. To read this data in from a BAM file, please see the `getCoverage` function.
`custom_ylim` | A vector of length two containing the y (coverage) axis limits. No need to set if not using coverage rectangles or if you're happy with the default: c(0, maximum coverage).
`sector_labels` | If `TRUE`, labels ('chr1', 'chr2' etc.) will be drawn for each sector (recommended).
`sector_label_size` | Size of the sector labels.
`sector_label_colour` | Colour of the sector labels.
`xaxis` | If `TRUE`, an x (genomic position) xaxis will be plotted.
`xaxis_orientation` | Either `'top'` to put the x axis on the outside of the circle or `'bottom'` to put it on the inside.
`xaxis_label_size` | Size of the x axis labels.
`xaxis_colour` | Colour of the x axis labels.
`xaxis_spacing` | Space between the x axis labels, in degrees. Alternatively, the string 'start_end' will place a label at the start and end of each sector only.
`xaxis_spacing_unit` | Either `"deg"` to draw ticks every certain number of degrees around the circle or `"bp"` to draw ticks every certain bp around the circle (be warned that when the scales for each sector are very different, it's best to use `"deg"`)
`label_data` | Data frame or GRanges containing the labels. If a GRanges, `label` should be a metadata column containing the character strings of the labels. `type` and `colour` can also be used to store additional information about the type (e.g. 'gene' or 'promoter') and colour of the label. This information can be used to colour code the labels by supplying the colour column as the `label_colour` parameter. Data frames should additionally include the `chr`, `start`, `end` which dictate the position of the label.
`label_colour` | Colour of the labels, can be either a single value (applied to all labels) or a vector with the same length as the number of labels (for colour-coding).
`label_size` | Size of the labels.
`space_between_labels` | Space between the labels
`label_orientation` | `'outside'` to put the labels on the outside of the circle, `'inside'` to put them on the inside.
`sort_sectors` | If `TRUE`, the sectors will be plotted around the circle in alphabetical order. Otherwise, they will be in the order in which they appear in `ideogram_data`

### Value

Generates an image of the initial ideogram track which can then be added to with various other functions.

### See Also

The `drawScatterplotTrack`, `drawFeatureTrack` and `drawLinegraphTrack`, which can be used to add information to this plot. Also `getIdeogramData` which can be used to read in the needed ideogram data for this function.

### Examples

    ## normal/standard usage
    ideogram <- data.frame(chr=paste0('chr', c(1:19, 'X', 'Y')),
    start=rep(0, 21),
    end=c(195471971, 182113224, 160039680, 156508116, 151834684, 149736546,
    145441459, 129401213, 124595110, 130694993, 122082543, 120129022,
    120421639, 124902244, 104043685, 98207768, 94987271, 90702639, 61431566,
    171031299, 91744698))
    gmovizInitialise(ideogram)

    ## zooming a sector
    gmovizInitialise(ideogram, zoom_sectors='chr19', zoom_size=0.2)

    ## custom sector width
    small_ideogram <- data.frame(chr=c('region 1', 'region 2', 'region 3'),
    start=c(0, 0, 0), end=c(10000, 12000, 10000))
    gmovizInitialise(small_ideogram, custom_sector_width=c(0.3, 0.3, 0.3))

    ## coverage rectangle
    path <- system.file('extdata', 'ex1.bam', package='Rsamtools')
    ideo <- getIdeogramData(path, wanted_chr='seq1')
    coverage <- getCoverage(bam_file=path, regions_of_interest='seq1',
    window_size=30)
    gmovizInitialise(ideo, coverage_rectangle='seq1', coverage_data=coverage)

[Package gmoviz version 1.0.1 Index]