featureDiagram {gmoviz} | R Documentation

## Display 'features' of interest in a diagram

### Description

Generates a diagram which displays 'features' (e.g. genes, indels, primer sequences etc) using coloured shapes. See `insertionDiagram` for a similar function which specialises in plotting insertions or `drawFeatureTrack` to add a feature track to an existing graph.

### Usage

    featureDiagram(ideogram_data, feature_data, start_degree = 180,
      coverage_rectangle = NULL, coverage_data = NULL,
      custom_sector_width = NULL, space_between_sectors = 4,
      flipped_sector = NULL, sector_colours = nice_colours,
      sector_border_colours = nice_colours, sector_labels = TRUE,
      sector_label_size = 1.3, sector_label_colour = "black",
      label_data = NULL, label_size = 1.1, label_colour = "black",
      xaxis = TRUE, xaxis_label_size = 0.9, xaxis_colour = "#747577",
      xaxis_spacing = 10, feature_label_cutoff = 50,
      xaxis_spacing_unit = "deg", track_height = 0.1,
      feature_label_size = 0.9, link_data = NULL,
      link_colour = "#84c6d6", link_ends = "default", custom_ylim = NULL,
      label_track_height = 0.1 * feature_label_size,
      feature_outline = 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.
`feature_data` | A data frame or GRanges containing the 'features' to plot. GRanges input should contain `label`, `colour`, `shape` and `track` as metadata columns. Data frame should contain `label`, `colour`, `shape` and `track`, as well as the additional columns `chr`, `start` and `end` Please see below for a detailed description of these columns, and `getFeatures` for a function which can read this information in from a .gff file.
`start_degree` | Where on the circle the first sector will start being drawn from (90 = 12 o'clock).
`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_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.
`space_between_sectors` | Space between each sector.
`flipped_sector` | A vector of sectors that will have their genomic position (x values) reversed (ascending in anti-clockwise direction, as opposed to the usual ascending in a clock-wise direction).
`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.
`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.
`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_size` | Size of the labels.
`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).
`xaxis` | If `TRUE`, an x (genomic position) xaxis will be plotted.
`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.
`feature_label_cutoff` | To enhance readability when the shapes are small, those labels belonging to features smaller than `feature_label_cutoff` will instead be plotted on a new track closer to the centre of the circle, rather than inside the shapes themselves.
`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"`)
`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).
`feature_label_size` | Size of the feature labels.
`link_data` | If you would like to draw a link between two sectors of the circle, `link_data` should be a data frame with two rows: one for each end of the link. There should be 3 columns: `chr`, `start` & `end` which describe the position of each end of the link.
`link_colour` | The colour of the link: this should be a 6 digit hex code, the transparency is automatically added.
`link_ends` | How far the link extends in either direction. This is set automatically but if you want to edit it, provide a vector of length 2 with each element being between 0 (centre of circle) and 1 (right at the edge of the circle).
`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).
`label_track_height` | Size of the track on which to plot the labels.
`feature_outline` | Should a black outline be drawn around the feature shape? (It is recommended to set this to `FALSE` when dealing with very small features)

### Value

Generates an image of the feature data supplied.

### Warning

If you choose to use a data frame to supply the feature data, please be careful to add the `stringsAsFactors = FALSE` argument. Otherwise, the colours may not be correct.

### See Also

`insertionDiagram` for a more specialised function which shows the copy number of insertions. Also `drawFeatureTrack` to add the exact same feature information to an existing plot and `getFeatures` for a function that can read in the feature information from a .gff file.

### Examples

    ## plasmid map
    plasmid_ideogram <- data.frame(chr='plasmid', start=0, end=2500)

    plasmid_features <- GRanges(seqnames=rep('plasmid', 4),
    ranges=IRanges(start=c(0, 451, 901, 1700), end=c(450, 900, 1400, 2200)),
    colour=c('#d44a9f', '#4a91d4', '#7ad44a', '#d49d4a'),
    label=c('promoter', 'gene', 'GFP', 'ampR'),
    shape=c('rectangle', 'forward_arrow', 'forward_arrow', 'reverse_arrow'),
    track=rep(1, 4))

    featureDiagram(plasmid_ideogram, plasmid_features)

[Package gmoviz version 1.0.1 Index]