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

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.

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.

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

Similar to paint, 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, :juliadoc, :languages, :lettermask, :logo, :nomask, :outline, :pattern, :qianziwen, :random, :recolor, :semantic, :series, :中文]

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.

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, :juliadoc, :languages, :lettermask, :logo, :nomask, :outline, :pattern, :qianziwen, :random, :recolor, :semantic, :series, :中文]

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

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
• density = 0.55 # default is 0.5
• spacing = 1 # minimum spacing between words, default is 2

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
  • 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

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

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

Optional Keyword Arguments

• stopwords: a set of words
• 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
• process: a function to process word counter, default is rescaleweights(identity, 0) ∘ casemerge! ∘ lemmatize!

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.

a, b, c, d are all inclusive

a, b, c, d are all inclusive

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