tagcloud (version 0.7.0)

plot.tagcloud: 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 tagcloud
plot(
  x,
  family = NULL,
  add = FALSE,
  with.box = FALSE,
  col = NULL,
  sel = NULL,
  ...
)
# S3 method for 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,
  weightiscex = FALSE,
  plot = TRUE,
  add = FALSE
)

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.

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.

...

Further arguments to be passed to downstream methods.

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.

weightiscex

If TRUE, weights are assumed to be directly cex factor for the labels. Combined with scale=1 this ensures that the size of the labels shown exactly corresponds to weights.

plot

If FALSE, no plot will be produced.

Author

January Weiner <[e-mail]>

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.

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" )

if (FALSE) {
# 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 )
}