WordCloud.jl Documentation

The WordCloud.jl package is a flexible, faithful and efficient word cloud generator in Julia.

using WordCloud
wc = wordcloud("It's easy to generate a beautiful word cloud.") |> generate!
paint(wc, "wordcloud.svg")

Please visit the repository at: https://github.com/guo-yong-zhi/WordCloud.jl

For editing SVGs of words. The 1st argument is wordcloud, the 2nd optional argument is index which can be string, number, list, or any other standard supported index. There are two kinds of keyword arguments, children and wrappers. The nodes in children will be linked under the root node of the SVG. The nodes in wrappers will be inserted between the SVG root node and all its child nodes. The children will be wraped by the wrapper node. A node is represented as a String Pair. e.g.

• child "title"=>"word" for <title>word</title>
• child "title"=>("word", :lang=>"en-us") for <title lang="en-us">word</title>
• child "animate" => ["attributeName"=>"opacity", "to"=>"0", "dur"=>"6s"] for <animate attributeName="opacity" to="0" dur="6s"/>
• wrapper "a"=>("href"=>"https://www.google.com") for <a href="https://www.google.com"> and </a>

Arguments children and wrappers can be a Pair, or a Tuple of Pairs to add multiple nodes to a SVG. Again, giving a list of Tuples of Pairs is ok to edit multiple SVGs corresponding to the index argument.

Positional Arguments

• wc: the word cloud object generated by the wordcloud function, which needs to be fitted.
• epochs: the number of training epochs

Keyword Arguments

• patience: the number of epochs before repositioning
• reposition: a boolean value that determines whether repositioning is enabled or disabled. Additionally, it can accept a float value p (0 ≤ p ≤ 1) to indicate the repositioning ratio, an integer value n to specify the minimum index for repositioning, a function index::Int -> repositionable::Bool to customize the repositioning behavior, or a whitelist for specific indexes.
• trainer: specify a training engine

Positional Arguments

• wc: the word cloud object generated by the wordcloud function, which needs to be fitted.
• epochs: the number of training epochs

Keyword Arguments

• retry: the number of attempts for shrinking and retraining, default is 3; set to 1 to disable shrinking
• patience: the number of epochs before repositioning
• reposition: a boolean value that determines whether repositioning is enabled or disabled. Additionally, it can accept a float value p (0 ≤ p ≤ 1) to indicate the repositioning ratio, an integer value n to specify the minimum index for repositioning, a function index::Int -> repositionable::Bool to customize the repositioning behavior, or a whitelist for specific indexes.
• trainer: specify a training engine

This function accepts two positional arguments: a wordcloud object and an index. The index can be a string, number, list, or any other supported type of index. The index argument is optional, and omitting it will retrieve all the values.

This function accepts two positional arguments: a wordcloud object and an index. The index can be a string, number, list, or any other supported type of index. The index argument is optional, and omitting it will retrieve all the values.

This function accepts two positional arguments: a wordcloud object and an index. The index can be a string, number, list, or any other supported type of index. The index argument is optional, and omitting it will retrieve all the values.

This function accepts two positional arguments: a wordcloud object and an index. The index can be a string, number, list, or any other supported type of index. The index argument is optional, and omitting it will retrieve all the values.

This function accepts two positional arguments: a wordcloud object and an index. The index can be a string, number, list, or any other supported type of index. The index argument is optional, and omitting it will retrieve all the values.

This function accepts two positional arguments: a wordcloud object and an index. The index can be a string, number, list, or any other supported type of index. The index argument is optional, and omitting it will retrieve all the values. The keyword argument mode can be either getshift or getcenter.

getscheme(wc::WC)

Returns the scheme of an existing word cloud, which can be used to create a new word cloud with the same styling. e.g., wc1 = wordcloud("a word cloud"); wc2 = wordcloud("a new word cloud"; getscheme(wc1)...)

This function accepts two positional arguments: a wordcloud object and an index. The index can be a string, number, list, or any other supported type of index. The index argument is optional, and omitting it will retrieve all the values.

This function accepts two positional arguments: a wordcloud object and an index. The index can be a string, number, list, or any other supported type of index. The index argument is optional, and omitting it will retrieve all the values.

This function accepts two positional arguments: a wordcloud object and an index. The index can be a string, number, list, or any other supported type of index. The index argument is optional, and omitting it will retrieve all the values.

Exclude specific words as if they do not exist, and then execute the function. It functions as the opposite of keep.

• ignore(fun, wc, ws::String) # ignore a word
• ignore(fun, wc, ws::Set{String}) # ignore all words in ws
• ignore(fun, wc, ws::Vector{String}) # ignore all words in ws
• ignore(fun, wc, inds::Union{Integer, Vector{Integer}})
• ignore(fun, wc::WC, mask::AbstractArray{Bool}) # ignore words. The mask must have the same length as wc

Initialize the images and other resources associated with words using the specified style.

Retain specific words and ignore the rest, and then execute the function. It functions as the opposite of ignore.

• keep(fun, wc, ws::String) # keep a word
• keep(fun, wc, ws::Set{String}) # keep all words in ws
• keep(fun, wc, ws::Vector{String}) # keep all words in ws
• keep(fun, wc, inds::Union{Integer, Vector{Integer}})
• keep(fun, wc::WC, mask::AbstractArray{Bool}) # keep words. The mask must have the same length as wc

The layout! function is employed to establish an initial layout for the word cloud.

• layout!(wc)
• layout!(wc, style=:uniform)
• layout!(wc, style=:gathering)
• layout!(wc, style=:gathering, level=5) # The level parameter controls the intensity of gathering, typically ranging from 4 to 6. The default value is 5.
• layout!(wc, style=:gathering, level=6, rt=0) # rt=0 for rectangle, rt=1 for ellipse, rt=2 for rhombus. The default value is 1.

There is also a keyword argument centralword available. For example, centralword=1, centralword="Alice" or centralword=false. When you have set style=:gathering, you should also disable repositioning in generate!, especially for big words. For example, generate!(wc, reposition=0.7). The keyword argument reorder is a function used to reorder the words, which affects the order of placement. For example, you can use reverse or WordCloud.shuffle.

Load an image as a mask, recolor it, or resize it, among other options.

Examples

• loadmask(open("res/heart.jpg"), 256, 256) # resize to 256*256
• loadmask("res/heart.jpg", ratio=0.3) # scaled by 0.3
• loadmask("res/heart.jpg", color="red", ratio=2) # set forecolor
• loadmask("res/heart.jpg", transparent=rgba->maximum(rgba[1:3])*(rgba[4]/255)>128) # set transparent using a Function
• loadmask("res/heart.jpg", color="red", transparent=(1,1,1)) # set forecolor and transparent
• loadmask("res/heart.svg") # only a subset of arguments is supported

padding: an Integer or a tuple of two Integers. For other keyword arguments like outline, linecolor, and smoothness, refer to the function outline.

Paint the wordcloud generated object into an image or an SVG file. See also: paintsvg

Examples

• paint(wc::WC)
• paint(wc::WC, background=false) # without background
• paint(wc::WC, background=outline(wc.mask)) # use a different background
• paint(wc::WC, ratio=0.5) # resize the output
• paint(wc::WC, "result.png", ratio=0.5) # save as png file
• paint(wc::WC, "result.svg") # save as svg file

Generate a word cloud image from text. This function acts as a convenient shortcut for paint(generate!(wordcloud(...))...). It accepts the same arguments as wordcloud and paint.

other arguments

• quiet: suppresses the output of the generation process. defaults to true.

See also: paintsvgcloud

Examples

• paintcloud("holly bible")
• paintcloud("holly bible", "result.svg", quiet=false)
• paintcloud(["holly", "bible"], [0.7, 0.3], "result.png", background=false)
• paintcloud("holly bible", angles=(0, 90), ratio=0.5)

Similar to paint, but exports SVG

Similar to paintcloud, but exports SVG

Fix specific words as if they were part of the background, and then execute the function.

• pin(fun, wc, ws::String) # pin an single word
• pin(fun, wc, ws::Set{String}) # pin all words in ws
• pin(fun, wc, ws::Vector{String}) # pin all words in ws
• pin(fun, wc, inds::Union{Integer, Vector{Integer}})
• pin(fun, wc::WC, mask::AbstractArray{Bool}) # pin words. # pin words. The mask must have the same length as wc.

Recolor the words according to the pixel color in the background image. The styles supported are :average, :main, :clipping, :blending, and :reset (to undo all effects of the other styles).

Examples

• recolor!(wc, style=:average)
• recolor!(wc, style=:main)
• recolor!(wc, style=:clipping, background=blur(getmask(wc))) # The background parameter is optional
• recolor!(wc, style=:blending, alpha=0.3) # The alpha parameter is optional
• recolor!(wc, style=:reset)

The effects of :average, :main, and :clipping are determined solely by the background. However, the effect of :blending is also influenced by the previous color of the word. Therefore, :blending can also be used in combination with other styles. The results of clipping and blending cannot be exported as SVG files; PNG should be used instead.

rescale!(wc::WC, ratio::Real)

Resize all words proportionally. Use a ratio < 1 to shrink the size, and a ratio > 1 to expand the size.

Available values: [:alice, :animation1, :animation2, :benchmark, :compare, :compare2, :custom, :fromweb, :gathering, :highdensity, :hyperlink, :japanese, :juliadoc, :languages, :lettermask, :logo, :nomask, :outline, :pattern, :qianziwen, :random, :recolor, :semantic, :series, :svgconfig, :中文]

This function accepts three positional arguments: a wordcloud object, an index, and a value. The index can be a string, number, list, or any other supported type of index.

This function accepts three positional arguments: a wordcloud object, an index, and a value. The index can be a string, number, list, or any other supported type of index.

setfontcandidates!(lang::AbstractString, str_list)

Customize font candidates for language lang

This function accepts three positional arguments: a wordcloud object, an index, and a value. The index can be a string, number, list, or any other supported type of index.

This function accepts three positional arguments: a wordcloud object, an index, and a value. The index can be a string, number, list, or any other supported type of index.

This function accepts three positional arguments: a wordcloud object, an index, and a value. The index can be a string, number, list, or any other supported type of index.

This function accepts three positional arguments: a wordcloud object, an index, and a value. The index can be a string, number, list, or any other supported type of index. The keyword argument mode can be either setshift! or setcenter!.

This function accepts three positional arguments: a wordcloud object, an index, and a value. The index can be a string, number, list, or any other supported type of index.

This function accepts three positional arguments: a wordcloud object, an index, and a value. The index can be a string, number, list, or any other supported type of index.

This function accepts three positional arguments: a wordcloud object, an index, and a value. The index can be a string, number, list, or any other supported type of index.

Available values: [:alice, :animation1, :animation2, :benchmark, :compare, :compare2, :custom, :fromweb, :gathering, :highdensity, :hyperlink, :japanese, :juliadoc, :languages, :lettermask, :logo, :nomask, :outline, :pattern, :qianziwen, :random, :recolor, :semantic, :series, :svgconfig, :中文]

Positional Arguments

The positional arguments are used to specify words and weights in various forms, such as Tuple or Dict.

• words::AbstractVector{<:AbstractString}, weights::AbstractVector{<:Real}
• words_weights::Tuple
• counter::AbstractDict
• counter::AbstractVector{<:Pair}

Optional Keyword Arguments

text-related keyword arguments

For more sophisticated text processing, please utilize the function processtext.

• language: language of the text, default is :auto.
• stopwords: a set of words, default is :auto which means decided by language.
• stopwords_extra: an additional set of stopwords. By setting this while keeping the stopwords argument as :auto, the built-in stopword list will be preserved.
• maxnum: maximum number of words, default is 500

style-related keyword arguments

• colors = "black" # same color for all words
• colors = ("black", (0.5,0.5,0.7), "yellow", "#ff0000", 0.2) # entries are randomly chosen
• colors = ["black", (0.5,0.5,0.7), "yellow", "red", (0.5,0.5,0.7), 0.2, ......] # elements are used in a cyclic manner
• colors = :seaborn_dark # Using a preset scheme. See WordCloud.colorschemes for all supported Symbols. WordCloud.displayschemes() may be helpful.
• angles = 0 # same angle for all words
• angles = (0, 90, 45) # randomly select entries
• angles = 0:180 # randomly select entries
• angles = [0, 22, 4, 1, 100, 10, ......] # use elements in a cyclic manner
• fonts = "Serif Bold" # same font for all words
• fonts = ("Arial", "Times New Roman", "Tahoma") # randomly select entries
• fonts = ["Arial", "Times New Roman", "Tahoma", ......] # use elements in a cyclic manner
• minfontsize: The minimum font size in pixel.
• maxfontsize: The maximum font size in pixel.
• avgfontsize: The average font size in pixel, default is 12. It is used to control the size of the generated picture when masksize is not specified.
• density = 0.55 # default is 0.5
• spacing = 1 # minimum spacing between words, default is :auto

mask-related keyword arguments

• mask = loadmask("res/heart.jpg", 256, 256) # refer to the documentation of loadmask
• mask = loadmask("res/heart.jpg", color="red", ratio=2) # refer to the documentation of loadmask
• mask = "res/heart.jpg" # shortcut for loadmask("res/heart.jpg")
• mask = shape(ellipse, 800, 600, color="white", backgroundcolor=(0,0,0,0)) # refer to the documentation of shape.
• mask = box # mask can also be one of box, ellipse, squircle, ngon, star, bezingon or bezistar. Refer to the documentation of shape.
• masksize: It can be a tuple (width, height), a single number indicating the side length, or one of the symbols :original, :default, or :auto.
• backgroundsize: Refer to shape. It is used with masksize to specify the padding size.
• maskcolor: It can take various values that represent colors, such as "black", "#f000f0", (0.5, 0.5, 0.7), or 0.2. Alternatively, it can be set to one of the following options: :default, :original (to maintain its original color), or :auto (to automatically recolor the mask).
• backgroundcolor: It can take various values that represent colors. Alternatively, it can be set to one of the following options: :default, :original, :maskcolor, or :auto (which randomly selects between :original and :maskcolor).
• outline, linecolor, smoothness: Refer to the shape and outline functions.
• transparent = (1,0,0) # interpret the color (1,0,0) as transparent
• transparent = nothing # no transparent color
• transparent = c->(c[1]+c[2]+c[3])/3*(c[4]/255)>128) # set transparency using a function. c is an (r,g,b,a) Tuple.

• Notes
  • getscheme is useful when you want to create a new word cloud with the same style as an existing word cloud.
  • Some arguments depend on whether the mask is provided or on the type of the provided mask.

other keyword arguments

• style, centralword, reorder, rt, level: Configure the layout style of word cloud. Refer to the documentation of layout!.
• The keyword argument state is a function. It will be called after the wordcloud object is constructed, which sets the object to a specific state.
  • state = initialize! # only initializes resources, such as word images
  • state = layout! # It is the default setting that initializes the position of words
  • state = generate! # get the result directly
  • state = identity # do nothing

• Notes
  • After obtaining the wordcloud object, the following steps are required to obtain the resulting picture: initialize! -> layout! -> generate! -> paint
  • You can skip initialize! and/or layout!, and these operations will be automatically performed with default parameters
  • You can use paintcloud and paintsvgcloud to obtain the final picture directly.

countwords(text_or_counter; counter=Dict{String,Int}(), language=:auto, regexp=r"(?:\S[\s\S]*)?[^0-9_\W](?:[\s\S]*\S)?")

Count words in text. And save results into counter. text_or_counter can be a String, a Vector of Strings, an opend file (IO) or a Dict. regexp is a regular expression to partially match and filter words. For example, regexp=r"\S(?:[\s\S]*\S)?" will trim whitespaces then eliminate empty words.

only handles the simple cases of plural nouns and third person singular verbs

Process the text, filter the words, and adjust the weights. Return a vector of words and a vector of weights.

Positional Arguments

• textorcounter: a string, a vector of words, an opened file (IO), a Dict{<:String, <:Real}, a Vector{Pair}, a Vector{Tuple}, or two Vectors.

Optional Keyword Arguments

• language: language of the text, default is :auto.
• stopwords: a set of words, default is :auto which means decided by language.
• stopwords_extra: an additional set of stopwords. By setting this while keeping the stopwords argument as :auto, the built-in stopword list will be preserved.
• minlength, maxlength: minimum and maximum length of a word to be included
• minfrequency: minimum frequency of a word to be included
• maxnum: maximum number of words, default is 500
• minweight, maxweight: within 0 ~ 1, set to adjust extreme weight
• regexp: a regular expression to partially match and filter words. For example, regexp=r"\S(?:[\s\S]*\S)?" will trim whitespaces then eliminate empty words. This argument is not available when text_or_counter is a counter.
• process: a function to process word count dict, default is rescaleweights(identity, 0) ∘ casemerge!

rescaleweights(func=identity, p=0)

This function takes word length into account. Therefore, the rescaled weights can be used as font size coefficients. The function func(w::Real)->Real is used to remap the weight, expressed as weight = func(weight); p represents the exponent of the power mean. We set weight = powermean(1*fontsize, wordlength*fontsize) = ((fontsize^p + (wordlength*fontsize)^p)/2) ^ (1/p). That is, weight = fontsize * powermean(1, wordlength). Overall, this gives us fontsize = func(weight) / powermean(1, wordlength). When p is -Inf, the power mean is the minimum value, resulting in fontsize=weight. When p is Inf, the power mean is the maximum value, resulting in fontsize=weight/wordlength. When p is -1, the power mean is the harmonic mean. When p is 0, the power mean is the geometric mean, preserving the word area. When p is 1, the power mean is the arithmetic mean. When p is 2, the power mean is the root mean square, preserving the diagonal length.

setlemmatizer!(lang::AbstractString, str_to_str_func)

Customize lemmatizer for language lang

setstopwords!(lang::AbstractString, str_set)

Customize stopwords for language lang

settokenizer!(lang::AbstractString, str_to_list_func)

Customize tokenizer for language lang

Return the intersecting region views of img1 and img2, where img2 is positioned in img1 with its top left corner located at coordinates (x, y).

Positional Arguments

• img: a bitmap image

Keyword Arguments

• linewidth: 0 <= linewidth
• color: line color
• transparent: the color of the transparent area, default is :auto
• smoothness: 0 <= smoothness <= 1, smoothness of the line, default is 0.5

Place img2 onto img1 at coordinates (x, y).

Generate an SVG image of a box, ellipse, squircle, ngon, star, bezingon, or bezistar.

Positional Arguments

• shape: one of box, ellipse, squircle, ngon, star, bezingon, or bezistar
• width: width of the shape
• height: height of the shape

Keyword Arguments

• outline: an integer indicating the width of the outline
• padding: an integer or a tuple of two integers indicating the padding size
• backgroundsize: a tuple of two integers indicating the size of the background
• color, linecolor, backgroundcolor: any value that can be parsed as a color.
• npoints, starratio, orientation, cornerradius, rt: see the Examples section below

Examples

• shape(box, 80, 50) # box with dimensions 80*50
• shape(box, 80, 50, cornerradius=4) # box with corner radius 4
• shape(squircle, 80, 50, rt=0.7) # squircle or superellipse. rt=0 for rectangle, rt=1 for ellipse, rt=2 for rhombus.
• shape(ngon, 120, 100, npoints=12, orientation=π/6) # regular dodecagon (12 corners) oriented by π/6
• shape(star, 120, 100, npoints=5) # pentagram (5 tips)
• shape(star, 120, 100, npoints=5, starratio=0.7, orientation=π/2) # 0.7 specifies the ratio of the smaller and larger radii; oriented by π/2
• shape(ellipse, 80, 50, color="red") # red ellipse with dimensions 80*50
• shape(box, 80, 50, backgroundcolor=(0,1,0), backgroundsize=(100, 100)) # 8050 box on a 100100 green background
• shape(squircle, 80, 50, outline=3, linecolor="red", backgroundcolor="gray") # add a red outline to the squircle