A book review of Exploring Everyday Things with R and Ruby.
Review by: RubyLearning’s mentor Victor Goff.
Book author: Sau Sheong Chang.
Publisher: O’Reilly Media.

I got the opportunity to review Exploring Everyday Things with R and Ruby by Sau Sheong Chang and published by O’Reilly Media¹

This book, as expected, talks about R and Ruby. The first chapters cover Ruby at an introductory level.

In the first chapter, after showing how you can install Ruby and an introduction to the basics of Ruby, he also provides “a quick introduction to Shoes, a simple but powerful UI toolkit for Ruby”², with installation suggestions and sample code.

His introduction to Ruby covers the basics and is just a bit more than enough to understand the code in the rest of his book. I think he did a really good job of that. The second part of the first chapter, covering Shoes, explains Shoes in a nutshell rather well, I think. You will get to use Shoes in later chapters.

He then goes on to introduce R, which I had not used before. He covers in a way that was fairly straightforward to install and get running. Within a few moments, I had R installed and the ‘normal’ graphical tools up and running and was able to run some sample code, and even had graphs floating around my screen based on data that I created from the samples.

Shortly after that, I had R code being created in my favorite text editor, and executing code right from there.

His introduction to the language is fairly quick, but again, just a bit more than enough to get you going.

He also covers some statistical transformation examples to change the statistical data into plottable information. That is a good thing, because throughout the book, you will be needing to recognize this in the examples, and will have fun producing your own graphical representations of data you get.

And all that is enough to get you started creating models to solve real world problems.

For example, do you need to convince your boss that you need more restrooms available for the people in your office? You can provide some simulations and reports and graphs (the boss likes graphs, right?) to support your argument, or will it support his assertion that what you have is just the right amount?

This gets to the fun part. Have you ever wondered how to mine data from your own e-mail? To find trends of when you send mail, or who you communicate with most? Finding the most often used words and the trending themes in your communications? You are in luck. He will take you through the Enron Saga to lightly touch on analyzing that e-mail data³, but easily apply it to your own IMAP e-mail accounts.

How about biometrics, recording your own heartbeat through a home-made electronic stethoscope? Yes, you will be able to do this, and take measurements, and analyze them graphically. Combine that with pulse oximetry with your webcam and you might have just enough evidence to convince your boss that your cubicle is suffocating you.

That sounds fun enough, but it will involve analyzing sound files and video files to get the readings and measurements that you want to produce in a graphical chart. That makes it fun to the nth power, right?

Well, what can be more fun than Boid’s… and boid is the woid⁴ in this next chapter. Using Ruby Shoes you will explore the flocking of birds, you will write a simulation and are encouraged to continue playing on.

What follows is an extension of the Boids and introduces the mortality and procreation of the boids, which were prior to this immortals in a veritable utopia. Life simulated and analyzed.

Overall, I really enjoyed this book, it was easy to read, had some math in it, of course, but nothing that requires advanced math. And the topics were fun to work through. And there is plenty of room to experiment and explore after finishing the chapters.

Like this review?

“Book Review: Exploring Everyday Things with R and Ruby” – Click to Tweet

Do you know Ruby Doctest?

This guest post is by Victor Goff, who enjoys mentoring Ruby at RubyLearning.org since 2008. You can reach him on IRC Chat #rubylearning on freenode.net. He also blogs occasionally at http://vgoff.posterous.com.

Rubydoctest is a gem that we will be installing. The purpose of the gem is simply to provide a way to document our programs using IRB sessions, resulting in a way to provide usage examples as well as knowing when an expected use fails because of some update or changes to our program or environment.

Installing Ruby DocTest

Rubydoctest can be installed by doing the following from the command line:

$ gem install rubydoctest

If you are running Windows or using RVM the above should work (pending network/internet connectivity) but you may need to use sudo to install depending on your set up.

The parts of Ruby DocTest

Rubydoctest information can be contained within a comment or a comment block.

Let’s start by creating a file hello.rb:

def hello name
  "Hello " + name
end
=begin # This is the beginning of a comment block
doctest: hello " World" will return "Hello World"
>> hello "World"
=> "Hello World"
=end

We have our trusty method called hello, but we have added a comment block with doctest information inside. Other than the doctest: directive, it should remind you of an IRB session.

The doctest: directive is the human readable title of the test. If this isn’t supplied you would end up seeing ‘default’ as the title.

To use rubydoctest:

USAGE: rubydoctest [options] 

  rubydoctest parses Ruby files (.rb) or DocTest files (.doctest) for irb-style
  sessions in comments, and runs the commented sessions as tests.

  Options:
    Output Format:
      --html  - output in HTML format
      --plain - force output in plain text (no Ansi colors)

    Debug:
      --ignore-interactive - do not heed !!! special directives
      --trace     - turn backtrace on to debug Ruby DocTest
      --debugger  - include ruby-debug library / gem

Let’s go ahead and run the following command to see what happens here:

rubydoctest hello.rb
=== Testing 'hello.rb'...
 OK  | hello "World" will return "Hello World"
1 comparisons, 1 doctests, 0 failures, 0 errors

As you can see, we get passing tests. And if this were above the method definition it may even be collected during ri and rdoc generation (this process is outside the scope of this article.)

Refactoring with RubyDoctest

Once we have a simple test in place, and that test is passing, we can refactor it, with confidence that the method still passes.

I noticed that I used “String” + variable in this method, but realized that it may read a little better (and create only one object) if I use string interpolation:

def hello name
  "Hello #{name}"
end

Which I think should pass the test, but just for good measure, we want to actually test it:

rubydoctest hello.rb
=== Testing 'hello.rb'...
 OK  | hello "World" will return "Hello World"
1 comparisons, 1 doctests, 0 failures, 0 errors

And as we can see, it passes.

Next, we will fully develop our hello method so that it has some nice features.

Using RubyDoctest in a TDD manner

We will be starting our hello method over from scratch. Going through the full life cycle of a small method, and testing along the way. It will be conversational, and demonstrative, so that you can follow along as we go.

Starting with an idea

It all starts with an idea: I would like a hello method that will simply state “Hello World!” In order to make this happen, and have the documentation and the tests that I would eventually like to have, I place this in my hello.rb file:

=begin
doctest: hello returns “Hello World!”
>> hello
=> “Hello World!”
=end

And to make sure that it is written correctly, we do want to run the following command and get the information back from our test:

rubydoctest hello.rb
=== Testing 'hello.rb'...
ERR  | hello returns "Hello World!"
       NameError: undefined local variable or method `hello' for main:Object
         from hello.rb:3
       hello
1 comparisons, 1 doctests, 0 failures, 1 errors

This information, if we pause and read it, tells us exactly what we need to get it past this error. It states “undefined local variable or method ‘hello’” and from which line it was called. We have already made the assumption that we want a method, and so we can do the least amount to cause this ERR to no longer exist. (You may see it as a shade of yellow in your console.)

So let’s write the least amount of code that we can think of to get it to not error (I placed the following on lines 6 and 7, just below the comment block):

def hello
end

Once I save this, and run the rubydoctest command, I get the following:

rubydoctest hello.rb
=== Testing 'hello.rb'...
FAIL | hello returns "Hello World!"
       Got: nil
       Expected: "Hello World!"
         from hello.rb:4
1 comparisons, 1 doctests, 1 failures, 0 errors

Depending on your settings, you should get a red “FAIL” message as well as the next three lines. Regardless you will get the summary information with 1 comparisons, 1 doctests, 1 failures and 0 errors.

The error count is 0, which means that we have progressed past the yellow ERR message. We will generally always want to work past ERR messages first, then FAIL messages, until we get to OK.

Let’s go forward in our journey and get past this FAIL message.

Paying attention to the feedback we get, it states that we are getting nil when we are expecting “Hello World!”. I think it is fairly obvious that we can simply have the method return the string “Hello World!” and get this to pass. Simplistic, and exactly what we want:

def hello
  "Hello World!"
end

Simplistic and rids us of the failure in our test:

rubydoctest hello.rb
=== Testing 'hello.rb'...
 OK  | hello returns "Hello World!"
1 comparisons, 1 doctests, 0 failures, 0 errors

Again, in your console, you may actually see a green OK. The important thing to note is the 0 failures and 0 errors.

It continues with expanding ideas

Let’s think about what we have. A hello method that greets the world. Not too bad. But let’s say that we want to be able to use it to greet the world, but also to greet someone in particular. Continuing our program documentation, we add the following:

doctest: hello "reader" returns "Hello reader!"
>> hello "student"
=> "Hello student!"

Those three lines should be added to comment block and our entire file looks like so:

=begin
doctest: hello returns "Hello World!"
>> hello
=> "Hello World!"
doctest: hello "reader" returns "Hello reader!"
>> hello "student"
=> "Hello student!"
=end
def hello
  "Hello World!"
end

When we run the doctest (which we should do any time we make a change in either the documentation or in the code itself), we should get:

rubydoctest hello.rb
=== Testing 'hello.rb'...
 OK  | hello returns "Hello World!"
ERR  | hello "reader" returns "Hello reader!"
       ArgumentError: wrong number of arguments (1 for 0)
         from hello.rb:6
       hello "student"
2 comparisons, 2 doctests, 0 failures, 1 errors

From this we can see that the current way we want to use it by giving one argument is in error on line 6, because our method wants 0. That is what the “(1 for 0)” means. We are giving it one argument “student” and it is really what we want.

You may think that if we fix the error, the first test with either error or fail, and you would be right. When going through this process, you want to be careful to make small changes, as well as concentrating on the feature you are working on. So we will work on test hello “reader” returns “Hello reader!” until it passes. Until that happens, we will ignore the first test.

How might we get out of our error condition? Perhaps like this?

def hello name
  "Hello World!"
end

Notice how we added the argument of name to our method. We could have used something instead of name, perhaps arg or argument, but that simply states what it is, not what we should pass. In this way, what we call the argument helps to document our method as well.

As we have made a change, it is time to run rubydoctest again and see if we got past the error:

rubydoctest hello.rb
=== Testing 'hello.rb'...
ERR  | hello returns "Hello World!"
       ArgumentError: wrong number of arguments (0 for 1)
         from hello.rb:3
       hello
FAIL | hello "reader" returns "Hello reader!"
       Got: "Hello World!"
       Expected: "Hello student!"
         from hello.rb:7
2 comparisons, 2 doctests, 1 failures, 1 errors

As you can see, we went from ERR to FAIL, which is where we want to be. Ignoring the first test, we go from FAIL to OK (pass) in the simplest change we can think of:

def hello name
  "Hello student!"
end

Simply replacing ‘World’ with ‘student’, I think, should get this test to pass:

rubydoctest hello.rb
=== Testing 'hello.rb'...
ERR  | hello returns "Hello World!"
       ArgumentError: wrong number of arguments (0 for 1)
         from hello.rb:3
       hello
 OK  | hello "reader" returns "Hello reader!"
2 comparisons, 2 doctests, 0 failures, 1 errors

There we go. Now we can look for any ERR messages as they are critical to allowing our program to run. It is complaining about wrong number of arguments, this time in reverse of what our second test was complaining about a few moments ago.

Do we want to change the test? It is something we could consider. I think I like having the ability to have default behavior of no argument to say greet the world. And so I would leave the test as it is.

Changing the method itself to accept 0 or more arguments is likely the right thing to do here. Let’s give that a shot:

def hello *name
  “Hello student!”
end

Adding the * to the argument will give us the ability to accept 0 or more arguments. Let’s test and see if we are still in an error condition:

rubydoctest hello.rb
=== Testing 'hello.rb'...
FAIL | hello returns "Hello World!"
       Got: "Hello student!"
       Expected: "Hello World!"
         from hello.rb:4
 OK  | hello "reader" returns "Hello reader!"
2 comparisons, 2 doctests, 1 failures, 0 errors

Seems to be OK, as we are no longer in an error condition. And a fail condition leads us where to go. We are getting “Hello student!” when we don’t give any argument. Looking above at our program, we want something a little more dynamic. Let’s use name variable to give us what we want in the string.

def hello *name
  "Hello " + name + "!"
end

It looks good to me, let’s see what our tests tell us?

rubydoctest hello.rb
=== Testing 'hello.rb'...
ERR  | hello returns "Hello World!"
       TypeError: can't convert Array into String
         from hello.rb:3
       hello
ERR  | hello "reader" returns "Hello reader!"
       TypeError: can't convert Array into String
         from hello.rb:6
       hello "student"
2 comparisons, 2 doctests, 0 failures, 2 errors

As I know that prior to this change, the additional feature passed, we will ignore any change to that, and continue to make our default behavior work.

What is Ruby telling us? That we can’t convert Array into String on line 3. It must be the +() method. Let’s use .to_s method to convert the name variable explicitly to a string:

def hello *name
  "Hello " + name.to_s + "!"
end

and see if that takes us away from the error:

rubydoctest hello.rb
=== Testing 'hello.rb'...
FAIL | hello returns "Hello World!"
       Got: "Hello []!"
       Expected: "Hello World!"
         from hello.rb:4
FAIL | hello "reader" returns "Hello reader!"
       Got: "Hello [\"student\"]!"
       Expected: "Hello student!"
         from hello.rb:7
2 comparisons, 2 doctests, 2 failures, 0 errors

Good, we are out of error mode again, and back to FAIL mode. We can deal with that, and we got some more information. We got what appears to be an empty Array as indicated by the [] in the string. I would guess it is because of the *name that we added. Let’s try a default value instead. Still not changing any tests… but paying attention to the feedback from the first test.

def hello name='World'
  "Hello " + name.to_s + "!"
end

That gets us out of fail and into OK (pass) for each test as indicated below:

rubydoctest hello.rb
=== Testing 'hello.rb'...
 OK  | hello returns "Hello World!"
 OK  | hello "reader" returns "Hello reader!"
2 comparisons, 2 doctests, 0 failures, 0 errors

Refactoring in the Green

You might think we are done. But we are in ‘green’ mode and so are free to refactor our code. And looking at our code I see some things that can be improved.

def hello name='World'
  "Hello + name + “!"
end

Let’s use remove the .to_s method as we know we are going to get a string. Of course, we test after refactoring to make sure we are still good.

rubydoctest hello.rb
=== Testing 'hello.rb'...
 OK  | hello returns "Hello World!"
 OK  | hello "reader" returns "Hello reader!"
2 comparisons, 2 doctests, 0 failures, 0 errors

And we see we are still golden.

And on second thought, we can use string interpolation which to me makes it more readable, but also creates only one String object.

def hello name='World'
  "Hello #{name}!"
end

And of course, we run rubydoctest again to make sure we didn’t break anything, and we see that we are good.

I hope you found this article valuable. Feel free to ask questions and give feedback in the comments section of this post. Thanks!

Cloning Internet Applications with Ruby by Chang Sau Sheong

Cloning Internet Applications with Ruby is a new Ruby book by Chang Sau Sheong and published by Packt Publishing. It’s now for sale at $34.12 at Amazon. In India, it’s available at a special price of Rs. 837.25.

This book is for those interested in and with some experience with web applications. The interesting thing is that the author describes four well-known applications and shows you not only how to implement each one, but describes different concerns about each type of application.

The author will walk you through the code, but will not teach you in-depth programming theory, instead he will show you the parts that may be used to put together clones of these four famous services. He will also go over a quick history of each service type.

For example, you will not even get to page sixty, and you will have a URL Shortening Clone built and deployed. He shows you the ‘parts’ that you will use with Ruby to get it up and running. He walks you through the installation of Sinatra, Haml, and DataMapper. And then shows you how to use Blueprint CSS, Google Chart API, and HostIP. Alternatively, he goes over quickly how to deploy using Heroku.

The next application you will look at is TwitterClone.

You will use the following: JSON, GoogleClientLogin, Gravatar, and TinyURL, RPX (authentication provisioning service), TinyURL, and of course, Heroku for non-local deployment.

Like the first clone, you will review why he chose Twitter (kind of obvious, right?), how it is popular and valued, and some of the issues faced. He will show you a data map of the features, and by page 120, you have done it again, went from Design to Implementation, to Deployment.

The next exercise is cloning Flickr, and the author brings you the history, and overview, and then goes through the steps with you once again, to bring you to the last two chapters in the book, which clones Facebook! And it really isn’t as complex as you may think.

Have fun with this book, it will give you some insights, and may help to simplify a few tasks that you wanted to do, but were maybe intimidated by. It turns out, it isn’t as complex as it may first appear!

Have you read this book? Why don’t you share your experiences with us? Let us know in the comments section of this post. Thanks!