tagcloud: Tag and Word Clouds

In january3/tagcloud: Tag 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 <[e-mail]>

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)

january3/tagcloud documentation built on March 7, 2020, 12:47 a.m.