wordcloud.py 17.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
15
16
17
18
import numpy as np
from operator import itemgetter

from PIL import Image
from PIL import ImageDraw
from PIL import ImageFont
19

20
from .query_integral_image import query_integral_image
21
22
23

item1 = itemgetter(1)

24
25
FONT_PATH = os.environ.get("FONT_PATH", os.path.join(os.path.dirname(__file__),
                                                     "DroidSansMono.ttf"))
26
27
28
29
STOPWORDS = set([x.strip() for x in open(os.path.join(os.path.dirname(__file__),
                                                      'stopwords')).read().split('\n')])


30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
class IntegralOccupancyMap(object):
    def __init__(self, height, width, mask):
        self.height = height
        self.width = width
        if mask is not None:
            # the order of the cumsum's is important for speed ?!
            self.integral = np.cumsum(np.cumsum(255 * mask, axis=1),
                                      axis=0).astype(np.uint32)
        else:
            self.integral = np.zeros((height, width), dtype=np.uint32)

    def sample_position(self, size_x, size_y, random_state):
        return query_integral_image(self.integral, size_x, size_y, random_state)

    def update(self, img_array, pos_x, pos_y):
        partial_integral = np.cumsum(np.cumsum(img_array[pos_x:, pos_y:], axis=1),
                                     axis=0)
        # paste recomputed part into old image
        # if x or y is zero it is a bit annoying
        if pos_x > 0:
            if pos_y > 0:
                partial_integral += (self.integral[pos_x - 1, pos_y:]
                                     - self.integral[pos_x - 1, pos_y - 1])
            else:
                partial_integral += self.integral[pos_x - 1, pos_y:]
        if pos_y > 0:
            partial_integral += self.integral[pos_x:, pos_y - 1][:, np.newaxis]

        self.integral[pos_x:, pos_y:] = partial_integral


Andreas Mueller's avatar
Andreas Mueller committed
61
62
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
63
64
65
66
67
68
69
70
71
72
73
74
75
    """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.

    """
76
    if random_state is None:
77
        random_state = Random()
78
79
80
81
82
83
84
85
86
87
    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
88
89
        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.
90
91
92
93
94
95
96

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

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

Andreas Mueller's avatar
Andreas Mueller committed
97
    prefer_horizontal : float (default=0.90)
98
99
100
        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
101
102
103
104
105
        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!]
106

107
108
109
110
111
    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.

112
113
114
115
116
117
118
119
    min_font_size : int (default=4)
        Smallest font size to use. Will stop when there is no more room in this
        size.

    font_step : int (default=1)
        Step size for the font. font_step > 1 might speed up computation but
        give a worse fit.

Andreas Mueller's avatar
Andreas Mueller committed
120
    max_words : number (default=200)
121
122
123
124
125
        The maximum number of words.

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

126
127
128
    background_color : color value (default="black")
        Background color for the word cloud image.

Andreas Mueller's avatar
Andreas Mueller committed
129
130
131
    max_font_size : int or None (default=None)
        Maximum font size for the largest word. If None, height of the image is
        used.
132

133
    mode : string (default="RGB")
134
135
        Transparent background will be generated when mode is "RGBA" and
        background_color is None.
Andreas Mueller's avatar
Andreas Mueller committed
136

137
138
139
140
141
142
143
    relative_scaling : float (default=0)
        Importance of relative word frequencies for font-size.
        With relative_scaling=0, only word-ranks are considered.
        With relative_scaling=1, a word that is twice as frequent will have twice the size.
        If you want to consider the word frequencies and not only their rank, relative_scaling
        around .5 often looks good.

144
145
    Attributes
    ----------
Andreas Mueller's avatar
Andreas Mueller committed
146
    ``words_``: list of tuples (string, float)
147
148
        Word tokens with associated frequency.

Andreas Mueller's avatar
Andreas Mueller committed
149
    ``layout_`` : list of tuples (string, int, (int, int), int, color))
150
151
        Encodes the fitted word cloud. Encodes for each word the string, font
        size, position, orientation and color.
152
153
154
155
156
157
158
159
160

    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.
161
162
    """

163
    def __init__(self, font_path=None, width=400, height=200, margin=2,
164
                 ranks_only=None, prefer_horizontal=0.9, mask=None, scale=1,
165
166
                 color_func=random_color_func, max_words=200, min_font_size=4,
                 stopwords=None, random_state=None, background_color='black',
167
                 max_font_size=None, font_step=1, mode="RGB", relative_scaling=0):
168
169
170
171
172
173
174
175
176
177
178
179
        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
        self.prefer_horizontal = prefer_horizontal
        self.mask = mask
        self.scale = scale
        self.color_func = color_func
Andreas Mueller's avatar
Andreas Mueller committed
180
181
        self.max_words = max_words
        self.stopwords = stopwords
182
183
        self.min_font_size = min_font_size
        self.font_step = font_step
184
185
186
        if isinstance(random_state, int):
            random_state = Random(random_state)
        self.random_state = random_state
187
        self.background_color = background_color
Andreas Mueller's avatar
Andreas Mueller committed
188
189
190
        if max_font_size is None:
            max_font_size = height
        self.max_font_size = max_font_size
191
        self.mode = mode
192
193
194
195
196
197
198
        if relative_scaling < 0 or relative_scaling > 1:
            raise ValueError("relative_scaling needs to be between 0 and 1, got %f."
                             % relative_scaling)
        self.relative_scaling = relative_scaling
        if ranks_only is not None:
            warnings.warn("ranks_only is deprecated and will be removed as"
                          " it had no effect. Look into relative_scaling.", DeprecationWarning)
199

200
201
202
203
    def fit_words(self, frequencies):
        """Create a word_cloud from words and frequencies.

        Alias to generate_from_frequencies.
204
205
206

        Parameters
        ----------
207
        frequencies : array of tuples
208
209
210
211
            A tuple contains the word and its frequency.

        Returns
        -------
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
        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
227
228

        """
229
        # make sure frequencies are sorted and normalized
230
        frequencies = sorted(frequencies, key=item1, reverse=True)
231
232
        frequencies = frequencies[:self.max_words]
        # largest entry will be 1
233
        max_frequency = float(frequencies[0][1])
234

235
        frequencies = [ (word, freq / max_frequency) for word, freq in frequencies ]
236

237
238
        self.words_ = frequencies

239
240
241
242
        if self.random_state is not None:
            random_state = self.random_state
        else:
            random_state = Random()
243

244
        if len(frequencies) <= 0:
245
            print("We need at least 1 word to plot a word cloud, got %d."
246
                  % len(frequencies))
247
248

        if self.mask is not None:
249
            mask = self.mask
Andreas Mueller's avatar
Andreas Mueller committed
250
251
            width = mask.shape[1]
            height = mask.shape[0]
252
            if mask.dtype.kind == 'f':
Andreas Mueller's avatar
Andreas Mueller committed
253
                warnings.warn("mask image should be unsigned byte between 0 and"
Andreas Mueller's avatar
Andreas Mueller committed
254
                              " 255. Got a float array")
Andreas Mueller's avatar
Andreas Mueller committed
255
256
257
            if mask.ndim == 2:
                boolean_mask = mask == 255
            elif mask.ndim == 3:
Andreas Mueller's avatar
Andreas Mueller committed
258
259
                # if all channels are white, mask out
                boolean_mask = np.all(mask[:, :, :3] == 255, axis=-1)
Andreas Mueller's avatar
Andreas Mueller committed
260
            else:
261
                raise ValueError("Got mask of invalid shape: %s" % str(mask.shape))
262
        else:
263
            boolean_mask = None
Andreas Mueller's avatar
Andreas Mueller committed
264
            height, width = self.height, self.width
265
        occupancy = IntegralOccupancyMap(height, width, boolean_mask)
266
267
268
269
270
271
272

        # 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
273
        font_size = self.max_font_size
274
        last_freq = 1.
275
276

        # start drawing grey image
277
        for word, freq in frequencies:
278
279
280
281
            # select the font size
            rs = self.relative_scaling
            if rs != 0:
                font_size = int(round((rs * (freq / float(last_freq)) + (1 - rs)) * font_size))
282
283
284
285
            while True:
                # try to find a position
                font = ImageFont.truetype(self.font_path, font_size)
                # transpose font optionally
286
                if random_state.random() < self.prefer_horizontal:
287
288
289
290
291
292
                    orientation = None
                else:
                    orientation = Image.ROTATE_90
                transposed_font = ImageFont.TransposedFont(font,
                                                           orientation=orientation)
                # get size of resulting text
293
                box_size = draw.textsize(word, font=transposed_font)
294
                # find possible places using integral image:
295
296
297
                result = occupancy.sample_position(box_size[1] + self.margin,
                                                   box_size[0] + self.margin,
                                                   random_state)
298
299
300
                if result is not None or font_size == 0:
                    break
                # if we didn't find a place, make font smaller
301
                font_size -= self.font_step
302

303
            if font_size < self.min_font_size:
304
305
306
307
308
                # we were unable to draw any more
                break

            x, y = np.array(result) + self.margin // 2
            # actually draw the text
309
            draw.text((y, x), word, fill="white", font=transposed_font)
310
311
312
            positions.append((x, y))
            orientations.append(orientation)
            font_sizes.append(font_size)
Andreas Mueller's avatar
Andreas Mueller committed
313
314
315
316
317
            colors.append(self.color_func(word, font_size=font_size,
                                          position=(x, y),
                                          orientation=orientation,
                                          random_state=random_state,
                                          font_path=self.font_path))
318
            # recompute integral image
Andreas Mueller's avatar
Andreas Mueller committed
319
320
321
            if self.mask is None:
                img_array = np.asarray(img_grey)
            else:
Andreas Mueller's avatar
Andreas Mueller committed
322
                img_array = np.asarray(img_grey) + boolean_mask
323
324
            # recompute bottom right
            # the order of the cumsum's is important for speed ?!
325
            occupancy.update(img_array, x, y)
326
            last_freq = freq
327

328
329
        self.layout_ = list(zip(frequencies, font_sizes, positions, orientations, colors))
        return self
330

331
    def process_text(self, text):
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
        """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 = {}
351
352
        flags = (re.UNICODE if sys.version < '3' and type(text) is unicode
                 else 0)
353
354
355
356
357
358
359
360
361
        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.
362
            try:
363
                d2 = d[word_lower]
364
            except KeyError:
365
366
367
368
369
370
                d2 = {}
                d[word_lower] = d2

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

371
372
373
374
375
376
377
378
379
380
381
382
        # merge plurals into the singular count (simple cases only)
        for key in list(d.keys()):
            if key.endswith('s'):
                key_singular = key[:-1]
                if key_singular in d:
                    dict_plural = d[key]
                    dict_singular = d[key_singular]
                    for word, count in dict_plural.items():
                        singular = word[:-1]
                        dict_singular[singular] = dict_singular.get(singular, 0) + count
                    del d[key]

383
384
385
        d3 = {}
        for d2 in d.values():
            # Get the most popular case.
defacto133's avatar
defacto133 committed
386
            first = max(d2.items(), key=item1)[0]
387
388
            d3[first] = sum(d2.values())

389
        return d3.items()
390

391
    def generate_from_text(self, text):
392
393
        """Generate wordcloud from text.

394
        Calls process_text and generate_from_frequencies.
395
396
397
398
399

        Returns
        -------
        self
        """
400
401
        words = self.process_text(text)
        self.generate_from_frequencies(words)
402
403
        return self

404
405
406
407
408
    def generate(self, text):
        """Generate wordcloud from text.

        Alias to generate_from_text.

409
        Calls process_text and generate_from_frequencies.
410
411
412
413
414
415
416

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

417
    def _check_generated(self):
Andreas Mueller's avatar
Andreas Mueller committed
418
        """Check if ``layout_`` was computed, otherwise raise error."""
419
420
        if not hasattr(self, "layout_"):
            raise ValueError("WordCloud has not been calculated, call generate first.")
421
422
423
424
425
426
427
428
429

    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

430
431
        img = Image.new(self.mode, (width * self.scale, height * self.scale),
                        self.background_color)
432
433
434
435
436
437
        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)
            pos = (position[1] * self.scale, position[0] * self.scale)
438
            draw.text(pos, word, fill=color, font=transposed_font)
439
440
441
442
443
444
445
446
447
        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
        ----------
448
449
450
        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.
451
452
453
454
455
456
457
458
459

        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
        """
460
461
        if isinstance(random_state, int):
            random_state = Random(random_state)
462
        self._check_generated()
463
464
465

        if color_func is None:
            color_func = self.color_func
466
467
        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
468
469
                                    position=position, orientation=orientation,
                                    random_state=random_state, font_path=self.font_path))
470
                        for word_freq, font_size, position, orientation, _ in self.layout_]
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
        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
498
        return np.array(self.to_image())
499

Andreas Mueller's avatar
Andreas Mueller committed
500
    def __array__(self):
501
502
503
504
505
506
507
        """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
508
        return self.to_array()
509
510
511

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