facebook_wordcloud 1.1
A Python tool for generating a word cloud for a Facebook chat conversation.
License: MIT
Keywords: facebook chat word cloud generate

facebook-chat-word-cloud
========================
.. image:: https://travis-ci.org/mjmeli/facebook-chat-word-cloud.svg?branch=master
    :target: https://travis-ci.org/mjmeli/facebook-chat-word-cloud

A Python tool for generating a word cloud for a Facebook chat conversation.

Requirements
------------
This uses `lxml` to parse the messages file provided by Facebook. This requires `libxml2` and `libxslt` to be installed.

For Debian/Ubuntu:

    sudo apt-get install libxml2-dev libxslt-dev python-dev python-tk

This also uses `Pillow` to handle image manipulation. This requires `libjpeg`, `zlib`, and `libfreetype`:

    sudo apt-get install libjpeg-dev zlib1g-dev libfreetype6-dev

Installation
------------
    pip install facebook_wordcloud

Development
-----------

    git clone https://github.com/mjmeli/facebook-chat-word-cloud.git
    pip install -e .

Testing
-------
    python setup.py test

Major Facebook Change
---------------------
Recently, Facebook switched identifying everyone in messenger chats from their actual name to a `@facebook.com` address. What this means is that you will have to figure out your friend's `@facebook.com` address for this library to work as otherwise it will not be able to identify the message threads. You can do this relatively simply by looking in the `messages.htm` file and finding your messages and looking at the thread header (or possibly the sending user), but please keep this in mind.

Unfortunately, Facebook did not backfill this change. So all names prior to the change are real names, and all names after the change are addresses. It would be difficult to support both with the current design so the unfortunate solution in the name of future compatibility over past compatibility is that all messages with your real names will be ignored. This sucks, I agree. Feel free to contribute if you want to try and fix it.

I'm really sorry for the inconvenience.

Quick Example Usage
-------------------
Request your Facebook data archive and get the messages.htm file.

**\* Please see note in section "Major Facebook Change" section**

Generate default word cloud:

    facebook_wordcloud examples/messages_sample.htm "Foo Bar"

Use a configuration file for customization:

    facebook_wordcloud examples/messages_sample.htm "Foo Bar" -c config.json

Use the sample conversation file for quick testing:

    facebook_wordcloud examples/messages_sample.htm "Foo Bar" -sample

Output the word cloud to an image

    facebook_wordcloud examples/messages_sample.htm "Foo Bar" -o output.png

Detailed Usage
--------------
This is essentially a command line wrapper around the `Andreas Muller's <https://github.com/amueller>`_ (amueller) `word_cloud Python library <https://github.com/amueller/word_cloud>`_ . This simply parses Facebook messages and passes data to that library.

First step is to get your Facebook messages archive:

1. Go to Facebook Settings: https://www.facebook.com/settings
2. Click the link at the bottom ("Download a copy of your Facebook data")
3. Click "Start My Archive" and wait for the download to be ready
4. Download and extract
5. Pull out or remember the location of the **messages.htm** file

The script is easy to use:

    facebook_wordcloud [messages_file] [users] {optional arguments}

Where,

- [message_file] is the relative path of your **messages.html** file
- [users] is a comma separated list of the users* involved in the conversation (i.e., if you want the conversation with your friend John Smith, [users] should be "John Smith"). You can specify multiple people for group conversations (i.e. "John Smith, Bob Bobby")

**\* Please see note in section "Finding Your Friends Name" section**

There are a few important optional arguments:

- the "-c" or "--config-file" arguments allow you to specify a json configuration file. There is an example of one in the root of this directory (**config.json**), and some more examples in the examples/ folder. **I highly recommend using such a file if you want non-default settings**!
- the "-o" or "--out" option allows you to specify where you want the image to output to
- the "-sample" or "--sample" option allows you to use an internal sample conversation (same as in examples/messages_sample.htm). **Your messages file will likely be large and will take a long time to parse, so when you are customizing, you may find this option helpful.**
- the "-h" or "--help" option shows help

There are many more arguments that mainly allow you to change the configuration of the word cloud. However, *all of these arguments can be specified in the json configuration file*. It will be much easier to use a config file! If you are stubborn, use the "-h" or "--help" option to see all the arguments.

**IMPORTANT: Command line arguments override config files!**

Helpful Hints
-------------
The messages file downloaded from Facebook will probably be quite large (mine was 60 MB). It may take a while to parse, which can get annoying when you are making small changes to get a nice looking word cloud. I highly recommend using the sample conversation I provide as this will parse in seconds and has very high word density. You can either directly reference this file (examples/messages_sample.htm with user "Foo Bar") or just use the "-sample" option with the command

Examples
--------
See the **examples** directory for some great examples of what you can do and some more description on the topic of customization.

.. image:: http://i.imgur.com/cKP4nJB.png

.. image:: http://i.imgur.com/7Q4bjdY.png

.. image:: http://i.imgur.com/2E9HRF5.png

.. image:: http://i.imgur.com/JDYoVxm.png

.. image:: http://i.imgur.com/UXIGvLW.png

Parser Choice
-------------
I originally used BeautifulSoup and then switched to the lxml parser. This is slightly annoying because it requires system libraries, but the performance is significantly better. See the benchmarks below from attempting to analyze a 60 MB file:

+---------------+-------------------------+-------------------+
| Parser        | Build Tree Runtime (ms) | Max Memory Usage  |
+===============+=========================+===================+
| BeautifulSoup | 90750                   | 3450 MB (3.45 GB) |
+---------------+-------------------------+-------------------+
| lxml          | 1945                    | 910 MB (0.91 GB)  |
+---------------+-------------------------+-------------------+

Issues
------
**ImportError: The _imagingft C module is not installed**
This means you don't have `libfreetype` installed. See the Requirements section. If installing it does not work, you may have to uninstall and reinstall `Pillow` via `pip`.

**IOError: Couldn't locate mask file...did you make sure to specify the URL relative to where you are running the script?**
This error is self-explanatory. In `masked/config.json`, the mask file is specified with a relative URL. This URL is *relative to where you are running the script*. I wrote the config file assuming that you were running the `facebook_wordcloud` in the `/examples` directory. If this is not the case, then either `cd` into that directory, or adjust the path in `masked/config.json`.

**The mask doesn't seem to be working?**
I ran into this issue a few times. Make sure the mask is either in RGB or grayscale. Note that only parts that are pure white (#FFFFFF) will be removed.