bubble_cloud

bubble_cloud copied to clipboard

h1. Bubble Cloud Example Implementation

UPDATE: check out new D3v4 version here: http://vallandingham.me/bubble_charts_with_d3v4.html

Demo of a word bubble cloud in D3.

For more info, check out the tutorial on "vallandingham.me":http://vallandingham.me/

h2. Usage

h3. First Clone the Repository

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

h3. 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@.

h3. View Demo

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

h4. 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":http://www.anthonydebarros.com/2011/10/15/setting-up-python-in-windows-7/

h4. 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":http://0.0.0.0:3000/

and you have a basic visualization

h3. Start Coding

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

h2. 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

h2. 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:

h4. 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.

h4. 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:

      
        Sherlock Holmes
        Aesop's Fables
        Alice in Wonderland
        Gulliver's Travels
      

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:

      
        The Great Gatsby
        Sherlock Holmes
        Aesop's Fables
        Alice in Wonderland
        Gulliver's Travels
      

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

h4. 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!

h2. 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

h2. License

Released under the MIT license:

"www.opensource.org/licenses/MIT":http://www.opensource.org/licenses/MIT