wordcloud.py 15.7 KB
Newer Older
Andreas Mueller's avatar
Andreas Mueller committed
1
2
# Author: Andreas Christian Mueller <t3kcit@gmail.com>
#
3
4
5
6
7
# (c) 2012
# Modified by: Paul Nechifor <paul@nechifor.net>
#
# License: MIT

Andreas Mueller's avatar
Andreas Mueller committed
8
import warnings
9
from random import Random
10
11
import os
import re
12
import sys
13
14
import numpy as np
from operator import itemgetter
15
from platform import system
16
17
18
19

from PIL import Image
from PIL import ImageDraw
from PIL import ImageFont
20
from .query_integral_image import query_integral_image
21
22
23

item1 = itemgetter(1)

24
25
26
27
if system() == "Windows":
    FONT_PATH = r"C:\Windows\Fonts\consola.ttf"
else:
    FONT_PATH = os.environ.get("FONT_PATH", "/usr/share/fonts/truetype/droid/DroidSansMono.ttf")
28
29
30
31
STOPWORDS = set([x.strip() for x in open(os.path.join(os.path.dirname(__file__),
                                                      'stopwords')).read().split('\n')])


Andreas Mueller's avatar
Andreas Mueller committed
32
33
def random_color_func(word=None, font_size=None, position=None,
                      orientation=None, font_path=None, random_state=None):
Andreas Mueller's avatar
Andreas Mueller committed
34
35
36
37
38
39
40
41
42
43
44
45
46
    """Random hue color generation.

    Default coloring method. This just picks a random hue with value 80% and
    lumination 50%.

    Parameters
    ----------
    word, font_size, position, orientation  : ignored.

    random_state : random.Random object or None, (default=None)
        If a random object is given, this is used for generating random numbers.

    """
47
    if random_state is None:
48
        random_state = Random()
49
50
51
52
53
54
55
56
57
58
    return "hsl(%d, 80%%, 50%%)" % random_state.randint(0, 255)


class WordCloud(object):
    """Word cloud object for generating and drawing.

    Parameters
    ----------
    font_path : string
        Font path to the font that will be used (OTF or TTF).
Andreas Mueller's avatar
Andreas Mueller committed
59
60
        Defaults to DroidSansMono path on a Linux machine. If you are on
        another OS or don't have this font, you need to adjust this path.
61
62
63
64
65
66
67
68
69
70

    width : int (default=400)
        Width of the canvas.

    height : int (default=200)
        Height of the canvas.

    ranks_only : boolean (default=False)
        Only use the rank of the words, not the actual counts.

Andreas Mueller's avatar
Andreas Mueller committed
71
    prefer_horizontal : float (default=0.90)
72
73
74
        The ratio of times to try horizontal fitting as opposed to vertical.

    mask : nd-array or None (default=None)
Andreas Mueller's avatar
Andreas Mueller committed
75
76
77
78
79
        If not None, gives a binary mask on where to draw words. If mask is not
        None, width and height will be ignored and the shape of mask will be
        used instead. All white (#FF or #FFFFFF) entries will be considerd
        "masked out" while other entries will be free to draw on. [This
        changed in the most recent version!]
80

81
82
83
84
85
    scale : float (default=1)
        Scaling between computation and drawing. For large word-cloud images,
        using scale instead of larger canvas size is significantly faster, but
        might lead to a coarser fit for the words.

Andreas Mueller's avatar
Andreas Mueller committed
86
    max_words : number (default=200)
87
88
89
90
91
        The maximum number of words.

    stopwords : set of strings
        The words that will be eliminated.

92
93
94
    background_color : color value (default="black")
        Background color for the word cloud image.

Andreas Mueller's avatar
Andreas Mueller committed
95
96
97
    max_font_size : int or None (default=None)
        Maximum font size for the largest word. If None, height of the image is
        used.
98
99
100
    mode: string (default="RGB")
        Transparent background will be generated when mode is "RGBA" and
        background_color is None.
Andreas Mueller's avatar
Andreas Mueller committed
101

102
103
    Attributes
    ----------
Andreas Mueller's avatar
Andreas Mueller committed
104
    ``words_``: list of tuples (string, float)
105
106
        Word tokens with associated frequency.

Andreas Mueller's avatar
Andreas Mueller committed
107
    ``layout_`` : list of tuples (string, int, (int, int), int, color))
108
109
        Encodes the fitted word cloud. Encodes for each word the string, font
        size, position, orientation and color.
110
111
112
113
114
115
116
117
118

    Notes
    -----
    Larger canvases with make the code significantly slower. If you need a large
    word cloud, try a lower canvas size, and set the scale parameter.

    The algorithm might give more weight to the ranking of the words
    than their actual frequencies, depending on the ``max_font_size`` and the
    scaling heuristic.
119
120
121
    """

    def __init__(self, font_path=None, width=400, height=200, margin=5,
Andreas Mueller's avatar
Andreas Mueller committed
122
                 ranks_only=False, prefer_horizontal=0.9, mask=None, scale=1,
123
                 color_func=random_color_func, max_words=200, stopwords=None,
124
125
                 random_state=None, background_color='black', max_font_size=None,
                 mode="RGB"):
126
127
128
129
130
131
132
133
        if stopwords is None:
            stopwords = STOPWORDS
        if font_path is None:
            font_path = FONT_PATH
        self.font_path = font_path
        self.width = width
        self.height = height
        self.margin = margin
Andreas Mueller's avatar
Andreas Mueller committed
134
        self.ranks_only = ranks_only
135
136
137
138
        self.prefer_horizontal = prefer_horizontal
        self.mask = mask
        self.scale = scale
        self.color_func = color_func
Andreas Mueller's avatar
Andreas Mueller committed
139
140
        self.max_words = max_words
        self.stopwords = stopwords
141
142
143
        if isinstance(random_state, int):
            random_state = Random(random_state)
        self.random_state = random_state
144
        self.background_color = background_color
Andreas Mueller's avatar
Andreas Mueller committed
145
146
147
        if max_font_size is None:
            max_font_size = height
        self.max_font_size = max_font_size
148
        self.mode = mode
149

150
151
152
153
    def fit_words(self, frequencies):
        """Create a word_cloud from words and frequencies.

        Alias to generate_from_frequencies.
154
155
156

        Parameters
        ----------
157
        frequencies : array of tuples
158
159
160
161
            A tuple contains the word and its frequency.

        Returns
        -------
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
        self
        """
        return self.generate_from_frequencies(frequencies)

    def generate_from_frequencies(self, frequencies):
        """Create a word_cloud from words and frequencies.

        Parameters
        ----------
        frequencies : array of tuples
            A tuple contains the word and its frequency.

        Returns
        -------
        self
177
178

        """
179
180
181
182
        if self.random_state is not None:
            random_state = self.random_state
        else:
            random_state = Random()
183

184
        if len(frequencies) <= 0:
185
            print("We need at least 1 word to plot a word cloud, got %d."
186
                  % len(frequencies))
187
188

        if self.mask is not None:
189
            mask = self.mask
Andreas Mueller's avatar
Andreas Mueller committed
190
191
            width = mask.shape[1]
            height = mask.shape[0]
192
            if mask.dtype.kind == 'f':
Andreas Mueller's avatar
Andreas Mueller committed
193
                warnings.warn("mask image should be unsigned byte between 0 and"
Andreas Mueller's avatar
Andreas Mueller committed
194
                              " 255. Got a float array")
Andreas Mueller's avatar
Andreas Mueller committed
195
196
197
            if mask.ndim == 2:
                boolean_mask = mask == 255
            elif mask.ndim == 3:
Andreas Mueller's avatar
Andreas Mueller committed
198
199
                # if all channels are white, mask out
                boolean_mask = np.all(mask[:, :, :3] == 255, axis=-1)
Andreas Mueller's avatar
Andreas Mueller committed
200
            else:
201
                raise ValueError("Got mask of invalid shape: %s" % str(mask.shape))
202
            # the order of the cumsum's is important for speed ?!
Andreas Mueller's avatar
Andreas Mueller committed
203
            integral = np.cumsum(np.cumsum(boolean_mask * 255, axis=1), axis=0).astype(np.uint32)
204
        else:
Andreas Mueller's avatar
Andreas Mueller committed
205
            height, width = self.height, self.width
206
207
208
209
210
211
212
213
            integral = np.zeros((height, width), dtype=np.uint32)

        # create image
        img_grey = Image.new("L", (width, height))
        draw = ImageDraw.Draw(img_grey)
        img_array = np.asarray(img_grey)
        font_sizes, positions, orientations, colors = [], [], [], []

Andreas Mueller's avatar
Andreas Mueller committed
214
        font_size = self.max_font_size
215
216

        # start drawing grey image
217
        for word, count in frequencies:
218
219
220
221
222
223
224
            # alternative way to set the font size
            if not self.ranks_only:
                font_size = min(font_size, int(100 * np.log(count + 100)))
            while True:
                # try to find a position
                font = ImageFont.truetype(self.font_path, font_size)
                # transpose font optionally
225
                if random_state.random() < self.prefer_horizontal:
226
227
228
229
230
231
232
233
234
235
                    orientation = None
                else:
                    orientation = Image.ROTATE_90
                transposed_font = ImageFont.TransposedFont(font,
                                                           orientation=orientation)
                draw.setfont(transposed_font)
                # get size of resulting text
                box_size = draw.textsize(word)
                # find possible places using integral image:
                result = query_integral_image(integral, box_size[1] + self.margin,
236
                                              box_size[0] + self.margin, random_state)
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
                if result is not None or font_size == 0:
                    break
                # if we didn't find a place, make font smaller
                font_size -= 1

            if font_size == 0:
                # we were unable to draw any more
                break

            x, y = np.array(result) + self.margin // 2
            # actually draw the text
            draw.text((y, x), word, fill="white")
            positions.append((x, y))
            orientations.append(orientation)
            font_sizes.append(font_size)
Andreas Mueller's avatar
Andreas Mueller committed
252
253
254
255
256
            colors.append(self.color_func(word, font_size=font_size,
                                          position=(x, y),
                                          orientation=orientation,
                                          random_state=random_state,
                                          font_path=self.font_path))
257
            # recompute integral image
Andreas Mueller's avatar
Andreas Mueller committed
258
259
260
            if self.mask is None:
                img_array = np.asarray(img_grey)
            else:
Andreas Mueller's avatar
Andreas Mueller committed
261
                img_array = np.asarray(img_grey) + boolean_mask
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
            # recompute bottom right
            # the order of the cumsum's is important for speed ?!
            partial_integral = np.cumsum(np.cumsum(img_array[x:, y:], axis=1),
                                         axis=0)
            # paste recomputed part into old image
            # if x or y is zero it is a bit annoying
            if x > 0:
                if y > 0:
                    partial_integral += (integral[x - 1, y:]
                                         - integral[x - 1, y - 1])
                else:
                    partial_integral += integral[x - 1, y:]
            if y > 0:
                partial_integral += integral[x:, y - 1][:, np.newaxis]

            integral[x:, y:] = partial_integral

279
280
        self.layout_ = list(zip(frequencies, font_sizes, positions, orientations, colors))
        return self
281

282
    def process_text(self, text):
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
        """Splits a long text into words, eliminates the stopwords.

        Parameters
        ----------
        text : string
            The text to be processed.

        Returns
        -------
        words : list of tuples (string, float)
            Word tokens with associated frequency.

        Notes
        -----
        There are better ways to do word tokenization, but I don't want to
        include all those things.
        """

        d = {}
302
303
        flags = (re.UNICODE if sys.version < '3' and type(text) is unicode
                 else 0)
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
        for word in re.findall(r"\w[\w']*", text, flags=flags):
            if word.isdigit():
                continue

            word_lower = word.lower()
            if word_lower in self.stopwords:
                continue

            # Look in lowercase dict.
            if word_lower in d:
                d2 = d[word_lower]
            else:
                d2 = {}
                d[word_lower] = d2

            # Look in any case dict.
            d2[word] = d2.get(word, 0) + 1

        d3 = {}
        for d2 in d.values():
            # Get the most popular case.
defacto133's avatar
defacto133 committed
325
            first = max(d2.items(), key=item1)[0]
326
327
328
            d3[first] = sum(d2.values())

        # merge plurals into the singular count (simple cases only)
defacto133's avatar
defacto133 committed
329
        for key in list(d3.keys()):
330
331
332
333
334
335
336
337
            if key.endswith('s'):
                key_singular = key[:-1]
                if key_singular in d3:
                    val_plural = d3[key]
                    val_singular = d3[key_singular]
                    d3[key_singular] = val_singular + val_plural
                    del d3[key]

defacto133's avatar
defacto133 committed
338
        words = sorted(d3.items(), key=item1, reverse=True)
Andreas Mueller's avatar
Andreas Mueller committed
339
        words = words[:self.max_words]
340
341
342
343
344
345
346
347
        maximum = float(max(d3.values()))
        for i, (word, count) in enumerate(words):
            words[i] = word, count / maximum

        self.words_ = words

        return words

348
    def generate_from_text(self, text):
349
350
        """Generate wordcloud from text.

351
        Calls process_text and fit_words.
352
353
354
355
356

        Returns
        -------
        self
        """
357
358
        self.process_text(text)
        self.fit_words(self.words_)
359
360
        return self

361
362
363
364
365
366
367
368
369
370
371
372
373
    def generate(self, text):
        """Generate wordcloud from text.

        Alias to generate_from_text.

        Calls process_text and fit_words.

        Returns
        -------
        self
        """
        return self.generate_from_text(text)

374
    def _check_generated(self):
Andreas Mueller's avatar
Andreas Mueller committed
375
        """Check if ``layout_`` was computed, otherwise raise error."""
376
377
        if not hasattr(self, "layout_"):
            raise ValueError("WordCloud has not been calculated, call generate first.")
378
379
380
381
382
383
384
385
386

    def to_image(self):
        self._check_generated()
        if self.mask is not None:
            width = self.mask.shape[1]
            height = self.mask.shape[0]
        else:
            height, width = self.height, self.width

387
388
        img = Image.new(self.mode, (width * self.scale, height * self.scale),
                        self.background_color)
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
        draw = ImageDraw.Draw(img)
        for (word, count), font_size, position, orientation, color in self.layout_:
            font = ImageFont.truetype(self.font_path, font_size * self.scale)
            transposed_font = ImageFont.TransposedFont(font,
                                                       orientation=orientation)
            draw.setfont(transposed_font)
            pos = (position[1] * self.scale, position[0] * self.scale)
            draw.text(pos, word, fill=color)
        return img

    def recolor(self, random_state=None, color_func=None):
        """Recolor existing layout.

        Applying a new coloring is much faster than generating the whole wordcloud.

        Parameters
        ----------
406
407
408
        random_state : RandomState, int, or None, default=None
            If not None, a fixed random state is used. If an int is given, this
            is used as seed for a random.Random state.
409
410
411
412
413
414
415
416
417

        color_func : function or None, default=None
            Function to generate new color from word count, font size, position
            and orientation.  If None, self.color_func is used.

        Returns
        -------
        self
        """
418
419
        if isinstance(random_state, int):
            random_state = Random(random_state)
420
        self._check_generated()
421
422
423

        if color_func is None:
            color_func = self.color_func
424
425
        self.layout_ = [(word_freq, font_size, position, orientation,
                         color_func(word=word_freq[0], font_size=font_size,
Andreas Mueller's avatar
Andreas Mueller committed
426
427
                                    position=position, orientation=orientation,
                                    random_state=random_state, font_path=self.font_path))
428
                        for word_freq, font_size, position, orientation, _ in self.layout_]
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
        return self

    def to_file(self, filename):
        """Export to image file.

        Parameters
        ----------
        filename : string
            Location to write to.

        Returns
        -------
        self
        """

        img = self.to_image()
        img.save(filename)
        return self

    def to_array(self):
        """Convert to numpy array.

        Returns
        -------
        image : nd-array size (width, height, 3)
            Word cloud image as numpy matrix.
        """
Andreas Mueller's avatar
Andreas Mueller committed
456
        return np.array(self.to_image())
457

Andreas Mueller's avatar
Andreas Mueller committed
458
    def __array__(self):
459
460
461
462
463
464
465
        """Convert to numpy array.

        Returns
        -------
        image : nd-array size (width, height, 3)
            Word cloud image as numpy matrix.
        """
Andreas Mueller's avatar
Andreas Mueller committed
466
        return self.to_array()
467
468
469

    def to_html(self):
        raise NotImplementedError("FIXME!!!")