minimaxir/stylecloud


Generate stylistic wordclouds, including gradients and icon shapes!

stylecloud is a Python package that leverages the popularword_cloudpackage, adding useful features to create truly unique word clouds!

  • Icon shapes (of any size!) for wordclouds (viaFont Awesome5.11.2)
  • Support for advanced color palettes (viapalettable)
  • Directional gradients w/ the aforementioned palettes.
  • Supports reading a file of text, or reading a pre-generated CSV with words and counts.
  • Command Line Interface!

This package is a more formal implementation of mystylistic word cloud projectfrom 2016.

Installation

You can installstylecloudvia pip:

Usage

You can use stylecloud in a Python script or as a standalone CLI app. For example, let’s say you have a text of the U.S. Constitutionconstitution.txt.

Python script:

importstylecloud

stylecloud.gen_stylecloud(file_path='constitution.txt')

But you can do so much more! You can use thefree Font Awesome iconsto change the shape, change the color palette to one frompalettablefor a custom style, change the background color, and, most importantly, add a gradient so the colors flow in a specified direction!

importstylecloud

stylecloud.gen_stylecloud(file_path='constitution.txt',
                         icon_name='fas fa-dog',
                         palette='colorbrewer.diverging.Spectral_11',
                         background_color='black',
                         gradient='horizontal')

You can also use the CLI for even faster stylecloud generation! For the simple flag stylecloud above:

stylecloud --file_path constitution.txt

For the more complex dog-gradient stylecloud:

stylecloud --file_path constitution.txt --icon_name'fas fa-dog'--palette colorbrewer.diverging.Spectral_11 --background_color black --gradient horizontal

You can find more examples of styleclouds, including how to make styleclouds from Twitter and Reddit data, in thestylecloud-examplesrepo.

In order to deal with different languages or simply add list of custom stopwords it is possible to pass a list contained in a string as parameter like so :

stylecloud --file_path constitution.txt --custom_words"[thereof, may, state, united states]"

For more control it would of course be most ideal to define the list in code since if one is defining stopwords for another language these lists can get long. In that case simply pass in the list as argument to the function

importstylecloud
my_long_list=["thereof","may","state","united states"]

stylecloud.gen_stylecloud(file_path=constitution.txt,custom_words=my_long_list)

Good ressources for stopwords in other languages are thestop-words python packagewhich gives you python lists directly. Or as JSON arrays this list ofiso stopword collections.

Helpful Parameters

These parameters are valid for both the Python function and the CLI (you can usestylecloud -hto get this information as well).

  • text: Input text. Best used if calling the function directly.
  • file_path: File path of the input text/CSV. Best used on the CLI.
  • gradient: Direction of gradient. (if not None, the stylecloud will use a directional gradient) [default:None]
  • size: Size (length and width in pixels) of the stylecloud. [default:512]
  • icon_name: Icon Name for the stylecloud shape. (e.g. ‘fas fa-grin’) [default:fas fa-flag]
  • palette: Color palette (via palettable) [default:cartocolors.qualitative.Bold_6]
  • background_color: Background color (name or hex) [default:white]
  • max_font_size: Maximum font size in the stylecloud. [default:200]
  • max_words: Maximum number of words to include in the stylecloud. [default:2000]
  • stopwords: Boolean to filter out common stopwords. [default:True]
  • custom_stopwords: list of custom stopwords. e.g: For other languages than english [default:STOPWORDS]
  • output_name: Output file name of the stylecloud. [default:stylecloud.png]
  • font_path: Path to .ttf file for font to use in stylecloud. [default: uses included Staatliches font]
  • random_state: Controls random state of words and colors.

Helpful Notes

  • The primary goal of this package is to create data visualizations of text that provide a unique aesthetic. Word clouds have tradeoffs in terms of a statistically robust data visualization, but this is explicitly prioritizing coolness!
  • This package is released as a separate package fromword_clouddue to the increase in scope and Python dependencies.
  • The ideal fonts for generating a good stylecloud are a) bold/high weight in order to increase readability, and b) condensed/low kerning to fit more text. Both of these traits are whyStaatlichesis the default font for stylecloud (overriding Droid Sans in the baseword_cloud).
  • You may want to consider doing post-processing after generating a stylecloud: for example, adding color masks, adding perception skew, feed it to a style transfer AI model, etc.
  • The defaultmax_font_sizeof200is calibrated for the defaultsizeof512. If you increase thesize, you may want to consider increasingmax_font_sizeas well.
  • Due to the size of the included Font Awesome font files, they will not be updated on every new minor FA release.
  • It’s recommended to use FA icons which are large with heavy weight; thin icons might constrain the text too much.
  • If using the default random-color-sampling method, it’s recommended to use a qualitative palette. Inversely, if using a gradient, it’s recommended to use anonqualitative palette (e.g. a sequential palette).
  • Support custom font files (e.g. Font Awesome Pro)
  • Create an app running stylecloud

Maintainer/Creator

Max Woolf (@minimaxir)

Max’s open-source projects are supported by hisPatreonand GitHub Sponsors. If you found this project helpful, any monetary contributions to the Patreon are appreciated and will be put to good creative use.

License

MIT

Font Awesome icon font files included per the terms in itsSIL OFL 1.1 License.

Staatliches font included per the terms in itsSIL OFL 1.1 License.

Read More

LEAVE A REPLY

Please enter your comment!
Please enter your name here