Package: wordcloud-fa
WordCloudFaThis module is an easy-to-use wrapper forword_cloud module.The original module doesn't support Farsi Texts. But by usingWordCloudFayou can generate word clouds from
texts those are including Persian and English words.This module is not only a wrapper, but it adds some features to the original module.How to InstallHow to UseGenerating Word Cloud from TextGenerating Word Cloud from FrequenciesWorking with StopwordsMask ImageReshaping wordsAvoiding Dangerous non-ASCII charactersExamplesFontPersian TutorialContributionCommon ProblemsFarsi Letters are separatedI See Repeated Farsi WordsI Have Problem in Running Example ScriptsThere is any problem?CitationsHow to InstallFor installing this module on other operating systems, you can simply runpip install wordcloud-fa.This module tested onpython 3WordCloudFadepends onnumpyandpillow.Also you should haveHazmmodule. Normally, all of them will install automatically when you install this module usingpipas described at the beginning of this section.To save the wordcloud into a file,matplotlibcan also be installed.AttentionYou need to havepython-devfor python3 on your system. If you don't have it, you can install it on operating systems
those usingaptas the package manager (Like Ubuntu) by this command:sudo apt-get install python3-devAnd you can install it on operating systems those usingyumas the package manager (like RedHat, Fedora and ...) you can
use the following command:sudo yum install python3-develHow to UseFor creating a word cloud from a text, first you should import the class into your code:from wordcloud_fa import WordCloudFayou can create an instance of this class like:wordcloud = WordCloudFa()You can pass different parameters to the constructor. For see full documents of them, you can seeWordCloud DocumentationsThere are three parameters that are not in the original class.First one ispersian_normalize. If you pass this parameter withTruevalue, your data will normalize by usingHazm normalizer. It's recommended to always pass this parameter. That will replace
arabic letters with persian ones and do some other stuff.
The default value of this parameter isFalse.wordcloud = WordCloudFa(persian_normalize=True)the second parameter isinclude_numbersthat is not in the published original module. If you set this parameter toFalse,
all Persian, Arabic and English numbers will remove from your data.The default value of this parameter isTruewordcloud = WordCloudFa(include_numbers=False)Common problem Hint:The last and very important parameter is:no_reshape. The default value of the parameter isFalse. But if you see
that the letters of the words in Farsi texts are separated in your local system, you should passTruevalue to this parameter.wordcloud=WordCloudFa(no_reshape=True)Generating Word Cloud from Textfor generating word cloud from a string, you can simply callgeneratemethod of you instance:wordcloud=WordCloudFa(persian_normalize=True)wc=wordcloud.generate(text)image=wc.to_image()image.show()image.save('wordcloud.png')Generating Word Cloud from FrequenciesYou can generate a word cloud from frequencies. You can use the output ofprocess_textmethod as frequencies.
Also you can use any dictionary like this.wordcloud=WordCloudFa()frequencies=wordcloud.process_text(text)wc=wordcloud.generate_from_frequencies(frequencies)generate_from_frequenciesmethod in this module will exclude stopwords. But the original module will not exclude them
when you are using this method. Also you can use Persian words as keys in frequencies dict without any problem.Working with StopwordsStopwords are the words that we don't want to consider. If you dan't pass any stopword, the default words in thestopwordsfile will consider as
stopwords.You don't want to use them at all and you want to choose your stopwords? you can simply setstopwordsparameter when
you are creating an instance fromWordCloudFaand pass asetof words into it.stop_words=set(['کلمه‌ی اول','کلمه‌ی دوم'])wc=WordCloudFa(stopwords=stop_words)If you want to add additional words to the default stopwords, you can simply calladd_stop_wordsmethod on your
instance ofWordCloudFaand pass an iterable type (list,set, ...) into it.wc=WordCloudFa()wc.add_stop_words(['کلمه‌ی اول','کلمه‌ی دوم'])Also you can add stopwords from a file. That file should include stopwords and each word should be in a separate line.For that, you should useadd_stop_words_from_filemethod. The only parameter of thismethod is relative or absolute path to the stop words file.wc=WordCloudFa()wc.add_stop_words_from_file("stopwords.txt")Mask ImageYou can mask the final word cloud by an image. For example, the first image of this document is a wordcloud masked by an image
of the map of Iran country. For setting a mask, you should pass themaskparameter.But before, you first should be sure you have a black and white image. Because other images will not create a good result.Then, you should convert that image to a numpy array. For that, you should do something like this:importnumpyasnpfromPILimportImagemask_array=np.array(Image.open("mask.png"))You just should add those two imports, but you don't need to be worried about installing them, because those have been
installed as dependencies of this module.Then, you can pass that array to the constructor of theWordCloudFaclass for masking the result.wordcloud=WordCloudFa(mask=mask_array)Now you can use your worldcloud instance as before.Reshaping wordsWhen you pass your texts into an instance of this class, all words will reshape for turning to a proper way for showing
And avoiding the invalid shape of Persian or Arabic words (splitted and inverse letters).If you want to do the same thing outside of this module, you can callreshape_wordsstatic method.reshaped_words=WordCloudFa.reshape_words(['کلمه‌ی اول','کلمه‌ی دوم'])this method gets anIterableas input and returns a list of reshaped words.DONT FORGET THAT YOU SHOULD NOT PASS RESHAPED WORDS TO THE METHODS OF THIS CLASS AND THIS STATIC METHOD IS ONLY FOR USAGES OUT OF THIS MODULEAvoiding Dangerous non-ASCII charactersSome non-ASCII characters like emojies causing errors. By Default, those characters will remove from the input text (not when you are using thegenerate_from_frequenciesmethod).For disabling this feature, you can set the value of theremove_unhandled_utf_charactersparameter toFalsewhen you are creating a new instance of theWordCloudFa.Also you can access the compiled regex patten of those characters using theunhandled_characters_regexclass attribute.ExamplesYou can seeExample codes in the Examples directory.FontThe default font is an unknown! font that supports both Persian and English letters. So you don't need to pass a font for
getting results. But if you want to change the font you can passfont_pathparameter.Persian TutorialIf you want to read a brief tutorial about how to use this package in Farsi (Persian), you canclick on this link.ContributionWe want to keep this library fresh and useful for all Iranian developers. So we need your help for adding new features, fixing bugs and adding more documents.You are wondering how you can contribute to this project? Here is a list of what you can do:Documents are not enough? You can help us by adding more documents.The current code could be better? You can make this cleaner or faster.Do you think one useful feature missed? You can open an issue and tell us about it.Did you find a good open and free font that supports Farsi and English? You can notify us by a pull request or if opening an issueCommon ProblemsFarsi Letters are separatedIf you see separated Farsi letters in your output, you should passno_reshape=Trueparameter to yourWordCoudFaconstructor:wordcloud=WordCloudFa(no_reshape=True)I See Repeated Farsi WordsIn some cases you may see repeated Farsi words in the output. For solving that problem, you should passcollocations=FalseParameter to yourWordCloudFaconstructor:wordcloud=WordCloudFa(collocations=False)I Have Problem in Running Example ScriptsIn some operating systems like Windows, you should specify the encoding of the example text files. If you can not open example files, addencoding="utf-8"to your open statements:withopen('persian-example.txt','r',encoding="utf-8")asfile:There is any problem?If you have questions, find some bugs or need some features, you can open an issue and tell us. For some strange reasons this is not possible? so contact me by this email:salam@alihoseiny.ir.CitationsTexts in theExampledirectory are fromthisandthisWikipedia pages.