imclab / bubble_cloud

Bubble Cloud Example Implementation

Demo of a word bubble cloud in D3.

For more info, check out the tutorial on vallandingham.me

Usage

First Clone the Repository

git clone [email protected]:vlandham/bubble_cloud.git
cd vis

Remove Google Analytics Code

To make things easy on myself, This is the same code that is used to
power the live demo. As a consequence, my GA code is in there.

If you could be a nice person and remove or change that in your version,
I’d appreciate it.

Should be a script block around line 70.

View Demo

Because of how D3 handles importing data, this tutorial should be viewed using a local webserver to serve the pages.

Python webserver

You can start up a local webserver by using python’s built-in simple server:

For Python 2.xx

python -m SimpleHTTPServer -p 3000

For Python 3.xx

python -m http.server

This assumes you have Python availible from the command line.

On Windows, you will need to install Python. Here is one tutorial for that

Ruby webserver

The thin webserver, a ruby gem, can also be used:

thin start
# might have to run 'bundle install' first

Now go to http://0.0.0.0:3000

and you have a basic visualization

Start Coding

Open up coffee/vis.coffee and start modifying the built in visualization to fit your needs.

Folder Organization

• /
  • main vis area
• /index.html
  • main page for your visualization. Loads coffeescript and javascript files.
• /coffee/
  • coffeescript files. vis.coffee.
• /data/
  • data dump for .csv and .json files and other data files your vis uses.
• /js/
  • javascript goes here. JS Libraries in libs directory
• /css/
  • put your stylesheets in here

Add your own data

The format of the input data for each word set is a .csv file that looks something like:

name,count
alice,147
little,44
# ...

If you have your own word list in a similar csv file, you can add it to the drop down list and view it in the demo by following these instructions:

Add your .csv file to the /data/ directory

Ensure your csv has a simple name, optimally [title].csv where [title] is a single word with no spaces or punctuation.

Then put your csv in the /data directory along side the other csv files.

Add your word list to index.html

First we will add an entry for your new word csv file to the index.html page. The drop-down box is created in index.html around line 28. It looks like this:

      <select id="text-select">
        <option value="sherlock">Sherlock Holmes</option>
        <option value="aesop">Aesop's Fables</option>
        <option value="alice">Alice in Wonderland</option>
        <option value="gulliver">Gulliver's Travels</option>
      </select>

You will want to add your title and a key associated with that title to this list. Let’s say you have a csv file called gatsby.csv that has word counts for the book ‘The Great Gatsby’, then your select might look like this:

      <select id="text-select">
        <option value="gatsby">The Great Gatsby</option>
        <option value="sherlock">Sherlock Holmes</option>
        <option value="aesop">Aesop's Fables</option>
        <option value="alice">Alice in Wonderland</option>
        <option value="gulliver">Gulliver's Travels</option>
      </select>

The value associated with the option is just a key that we will use in vis.coffee to load the right file.

Add entry in vis.coffee texts

Finally, we will add an entry to the texts Object in vis.coffee to associate our key with the file to load.

texts starts at line 407 in vis.coffee. We need to add a new line that uses the key we put in our option value and the actual file name. In our example, we used the key gatsby and our file’s name is gatsby.csv, so the text object would look like:

texts = [
  {key:"gatsby",file:"gatsby.csv",name:"The Great Gatsby"}
  {key:"sherlock",file:"top_sherlock.csv",name:"The Adventures of Sherlock Holmes"}
  {key:"aesop",file:"top_aesop.csv",name:"Aesop's Fables"}
  {key:"alice",file:"alice.csv",name:"Alice's Adventures in Wonderland"}
  {key:"gulliver",file:"top_gulliver.csv",name:"Gulliver's Travels"}
]

To make things easier, ensure the order of the entries in texts matches the order of the option values in index.html.

Reloading the page, you should see your new bubble cloud appear!

Requirements

To startup the server, you either need python, or a bunch of ruby gems (should be simplified in the future).

Run bundle install to get the gems needed. Gems listed in the Gemfile

License

Released under the MIT license:

www.opensource.org/licenses/MIT