R: Tag and Word Clouds

plot.tagcloud {tagcloud} | R Documentation

## Tag and Word Clouds

### Description

Functions to create and display plots called tag clouds, word clouds or weighted lists, in which a usually large number of words is displayed in size correlated with a numerical value (for example, frequency in a text or enrichment of a GO term). This makes it easier to visualize the prominence of certain tags or words. Also, it looks nice.

### Usage

    ## S3 method for class 'tagcloud'
    plot(x, family = NULL, add = FALSE, with.box = FALSE,
      col = NULL, sel = NULL, ...)

    ## S3 method for class 'tagcloud'
    summary(object, ...)

    tagcloud(tags, weights = 1, algorithm = "oval", scale = "auto",
      scale.multiplier = 1, order = "size", sel = NULL, wmin = NULL,
      wmax = NULL, floor = 1, ceiling = 3, family = NULL, col = NULL,
      fvert = 0, plot = TRUE, add = FALSE)

### Arguments

`x,object` | An object of the type produced by tagcloud.
`family` | Font family to use, a vector containing font families to use for each tag. For the `tagcloud` function, the special keyword "random" can be used to assign random families (requires the extrafont package).
`add` | If TRUE, the tags will be added to the current plot instead of creating a new plot.
`with.box` | If TRUE, a rectangle will be plotted around each tag.
`col` | Color or a vector containing colors to use for drawing the tags.
`sel` | An integer or boolean vector indicating which terms from the provided list will be used to plot. The vectors `col` and `weights` will be filtered accordingly.
`tags` | A character vector containing words or tags to be shown on the plot.
`weights` | A numeric vector giving the relative proportions of text size corresponding to the given tag.
`algorithm` | Name of the algorithm to use. Can be "oval", "fill", "random", "snake", "list" or "clist". See Details.
`scale` | If "auto", text expansion will be calculated automatically to fit the available space. Otherwise, a numeric value used to modify the calculated text sizes; tune scale to achieve a better fit.
`scale.multiplier` | Multiplier for the final calculated text expansion parameter. Increase if there is too much empty space around the tag cloud; decrease if the tags go over the plot boundaries.
`order` | Determines in which order the tags will be drawn. Can be "size", "keep", "random", "height" or "width". See Details.
`wmin` | All items in the `weights` vector smaller than `wmin` will be changed to `wmin`
`wmax` | All items in the `weights` vector larger than `wmax` will be changed to `wmax`
`floor` | Minimal text size. See Details.
`ceiling` | Maximal text size. See Details.
`fvert` | Fraction of tags which will be rotated by 90 degrees counterclockwise.
`plot` | If FALSE, no plot will be produced.
`...` | Further arguments to be passed to downstream methods.

### Details

The package `tagcloud` creates and plots tag clouds (word clouds). The algorithms in the package have been designed specifically with long tags (such as GO Term descriptions) in mind.

#### Term ordering

The available arguments are as follows:

- size – tags are ordered by size, that is, their effective width multiplied by their effective height. Default.

- keep – keep the order from the list of words provided

- random – randomize the tag list

- width – order by effective screen width

- height – order by effective screen height

By default, prior to plotting terms are ordered by size.

#### Algorithms

There are four algorithms for placing tags on the plot implemented in tagcloud.

- oval – creates an oval cloud.

- fill – an attempt will be made to fill the available space

- random – randomly distribute tags over the available space. This algorithm is slow and not very effective

- snake – tags are placed clockwise around the first tag to plot

- list – create a list, one tag directly beneath another, justified left

- clist – create a list, one tag directly beneath another, centered

Algorithms `oval`, `fill` and `random` attempt to fill the available space by adjusting the scaling factor for the font sizes.

#### Calculation of tag sizes

Placing tags such that the empty space between the tags is minimized poses a non-trivial problem, because the effective bounding box of a displayed text is not linearly dependent on the `cex` parameter.

In tagcloud, first a `cex` parameter is calculated for each tag separately, based on the parameters `floor`, `ceiling` and the vector of weights. Note that all weights smaller than `wmin` are replaced by `wmin` and all weights larger than `wmax` are replaced by `wmax`. Then, effective heights and widths of the tags to be displayed are calculated using the `strwidth` and `strheight` functions.

Unless the argument `scale` is different from "auto", a scaling parameter for `cex` is automatically calculated based on the current area of the tags and the available plotting area. This usually results in a reasonable plot, but is neither guaranteed to occupy all of the available space without margins, nor that no tag will cross the view port.

### Value

`tagcloud` returns an object of the `tagcloud-class`, which really is a data frame with the following columns:

- `tags` – the tags, words or phrases shown on the plot

- `weights` – a numeric vector that is used to calculate the size of the plotted tags

- `family` – name of the font family to be used in plotting

- `vertical` – whether the tag should be rotated by 90 degrees counter-clockwise

- `x`,`y` – coordinates of the left lower corner of the tags bounding box

- `w`,`h` – width and height of the bounding box

- `cex` – text expansion factor, see `par`

- `s` – surface of the tag (width x height)

The object of the `tagcloud` class can be manipulated using `editor.tagcloud` and displayed using `plot`, `print` and `summary` functions.

### Note

Care should be taken when using extra fonts loaded by the extrafont package; not all fonts can be easily copied to a PDF file.

Some ideas in this package are based on the 'wordcloud' package by Ian Fellows.

### Author(s)

January Weiner <january.weiner@gmail.com>

### See Also

`editor.tagcloud` – interactive editing of tagcloud objects.

`strmultline` – splitting multi-word sentences into lines for a better cloud display.

`smoothPalette` – mapping values onto a color gradient.

### Examples

    # a rather boring tag cloud
    data( gambia )
    terms <- gambia$Term
    tagcloud( terms )

    # tag cloud with weights relative to P value
    # colors relative to odds ratio, from light
    # grey to black
    weights <- -log( gambia$Pvalue )
    colors  <- smoothPalette( gambia$OddsRatio, max=4 )
    tagcloud( terms, weights, col= colors, algorithm= "oval" )

    # tag cloud filling the whole plot
    tagcloud( terms, weights, col= colors, algorithm= "fill" )

    # just a list of only the first ten terms
    tagcloud( terms, weights, sel= 1:10,
              col= colors, algorithm= "list", order= "width" )

    # oval, with line breaks in terms
    terms <- strmultline( gambia$Term )
    tagcloud( terms, weights, col= colors, algorithm= "oval" )

    ## Not run:
    # shows available font families, scaled according to
    # the total disk space occupied by the fonts
    require( extrafont )
    ft <- fonttable()
    fi <- file.info( fonttable()$fontfile )
    families <- unique( ft$FamilyName )
    sizes    <- sapply( families,function( x ) sum( fi[ ft$FamilyName == x, "size" ] ) )
    tagcloud( families, sizes, family= families )

    ## End(Not run)

[Package tagcloud version 0.6 Index]