rupee 0.1.3 → 0.1.5

data/README.rdoc

@@ -0,0 +1,103 @@
+= Rupee - financial tools for Ruby
+
+Homepage::  http://www.brymck.com
+Author::    Bryan McKelvey
+Copyright:: (c) 2011 Bryan McKelvey
+License::   MIT
+
+        /|\
+       / | \
+      /  |  \
+     /_ / \ _\    RU       PE      E
+    |  |   |  |   _ _      _
+    |  |   |  |  | | |    | |__o  ____
+    |  |   |  |  | | | _  |  __| |____|
+    | _|   |_ |  | | |/ / | |___
+     \  \ /  /  /_/|___/   \____|
+      \  |  /
+       \ | /
+        \|/
+
+== Installing
+
+Note that you must have Ruby 1.8.7+ installed and the ability to compile native
+extensions (standard on most platforms and available on Windows via
+{DevKit}[http://rubyinstaller.org/downloads/]).
+
+  gem install rupee
+
+You can also do things the hard way if you want to keep track of the repo:
+
+  git clone git://github.com/brymck/rupee.git
+  cd rupee
+  bundle update
+  rake install
+
+After all that hard work, you can take a test drive by running something like
+this in the Ruby console (i.e. <tt>irb</tt> in a command prompt):
+
+  require "rupee"
+  Rupee::Option.black_scholes "c", 60, 65, 0.25, 0.08, 0, 0.3
+  Rupee::Call.new(
+    :underlying => 60,
+    :strike     => 65,
+    :time       =>  0.25,
+    :rate       =>  0.08,
+    :div_yield  =>  0.00,
+    :volatility =>  0.3
+  ).black_scholes
+
+both of which should return <tt>2.1334</tt>.
+
+You should also be able to get the latest stock info for, for example, Wells
+Fargo using the following (note that you only need to <tt>require</tt> the
+<tt>quote</tt> module):
+
+  require "rupee/quote"
+  wfc = Rupee::Quote.new("WFC")
+
+  wfc.get :price, :change, :pct_change
+  #=> {:price=>24.96, :change=>0.17, :pct_change =>0.686}
+
+  wfc.price
+  #=> 24.96
+
+  wfc.change
+  #=> 0.17
+
+<tt>wfc.get</tt> will return a hash of the requested information for the security.
+Each valid parameter will also have its own utility method. The results will
+update every <tt>wfc.frequency</tt> seconds (defaults to 15).
+
+Got it? Good. This will surely help you collect some rupees in real life.
+
+== Performance
+
+This is just a simple benchmark I ran on my own laptop, where I value a simple
+call option with Black-Scholes 100,000 times. You can test the same on yours
+with rake, but in any case it makes the point that for the mathematical side
+of finance a native extension has substantial benefits:
+
+  rake benchmark:black_scholes
+
+Results:
+
+                            user     system      total        real
+  Rupee (class):        0.190000   0.000000   0.190000 (  0.194001)
+  Rupee (one object):   0.180000   0.000000   0.180000 (  0.183091)
+  Rupee (new object):   2.210000   0.000000   2.210000 (  2.213351)
+  Pure Ruby:            2.320000   0.000000   2.320000 (  2.324259)
+
+In words, for math-intensive operations, using a C implementation is clearly
+faster than the same thing in Ruby.
+
+Also, if you're doing a valuation on a one-off set of examples (e.g. in a Monte
+Carlo simulation), you probably don't want to create an object every time.
+Something like <tt>Rupee::Option.black_scholes ...</tt> should work just fine.
+Creating a <tt>Rupee::Option</tt> object takes roughly the same amount of time as
+running <tt>Rupee::Option.black_scholes</tt> a dozen times.
+
+However, if you're creating and reusing an object, I strongly recommend
+preserving the object orientation of Ruby: the penalty for using a new instance
+rather than calling the class method directly is almost entirely in the object
+initialization itself.

data/ext/rupee/bond.c

@@ -295,7 +295,7 @@ init_bond()
   rb_define_singleton_method(klass, "duration", duration_discrete, 3);
   rb_define_alias(singleton, "dur", "duration");
   rb_define_singleton_method(klass, "macaulay", macaulay_discrete, 3);
-  rb_define_alias(singleton, "macaulary_duration", "macaulay");
+  rb_define_alias(singleton, "macaulay_duration", "macaulay");
   rb_define_singleton_method(klass, "price", price_discrete, 3);
   rb_define_alias(singleton, "value", "price");
   rb_define_singleton_method(klass, "yield_to_maturity", yield_to_maturity_discrete, 3);

data/ext/rupee/distribution.c

@@ -53,7 +53,7 @@ init_distribution()
   VALUE klass, singleton;
 
 #if 0
-  value module = rb_define_module("rupee");
+  VALUE module = rb_define_module("Rupee");
 #endif
 
   klass = rb_define_class_under(module, "Distribution", rb_cObject);

data/lib/rupee/benchmark.rb

@@ -3,7 +3,9 @@ module Rupee
   class Benchmark
     class << self
       # Black-Scholes option price valuation
+      #
       # by Michael Neumann (with some revisions)
+      #
       # http://www.espenhaug.com/black_scholes.html
       def black_scholes(callPutFlag, s, x, t, r, v)
         d1 = (Math.log(s / x) + (r + v * v / 2.0) * t) / (v * Math.sqrt(t))
@@ -17,14 +19,16 @@ module Rupee
 
       private
 
-      A1 =  0.31938153
-      A2 = -0.356563782
-      A3 =  1.781477937
-      A4 = -1.821255978
-      A5 =  1.330274429
+      A1 =  0.31938153   # :nodoc:
+      A2 = -0.356563782  # :nodoc:
+      A3 =  1.781477937  # :nodoc:
+      A4 = -1.821255978  # :nodoc:
+      A5 =  1.330274429  # :nodoc:
 
       # Cumulative normal distribution
+      #
       # by Michael Neumann (with some revisions)
+      #
       # http://www.espenhaug.com/black_scholes.html
       def cnd(x)
         l = x.abs

data/lib/rupee/option.rb

@@ -2,28 +2,45 @@ require "rupee/security"
 
 module Rupee
   class Option < Security
-    attr_accessor :type, :underlying, :strike, :time, :rate, :div_yield, :volatility, :price
-    alias :rfr :rate
-    alias :rfr= :rate=
-    alias :risk_free_rate :rate
-    alias :risk_free_rate= :rate=
-    alias :value :price
-    alias :value= :price=
+    # The type of the option. Accepts <tt>"call"</tt> and <tt>"put"</tt>.
+    attr_accessor :type
+    # The price of the underlying security
+    attr_accessor :underlying
+    # The strike price of the underlying security
+    attr_accessor :strike
+    # The remaining time to maturity
+    attr_accessor :time
+    # The risk-free rate
+    attr_accessor :rate
+    # The dividend yield
+    attr_accessor :div_yield
+    # The annualized price volatility
+    attr_accessor :volatility
+    # The price of the option
+    attr_accessor :price
+
+    attr_alias :rfr, :rate
+    attr_alias :risk_free_rate, :rate
+    attr_alias :value, :price
 
     def black_scholes
       @value = self.class.black_scholes @type.to_s, @underlying, @strike, @time, @rate, @div_yield, @volatility
     end
   end
 
+  # The same thing as Rupee::Option, but with the <tt>:type</tt> flag set to
+  # <tt>"call"</tt>
   class Call < Option
-    def initialize(opts = {})
+    def initialize(opts = {}) # :nodoc:
       @type = "call"
       super
     end
   end
 
+  # The same thing as Rupee::Option, but with the <tt>:type</tt> flag set to
+  # <tt>"put"</tt>
   class Put < Option
-    def initialize(opts = {})
+    def initialize(opts = {}) # :nodoc:
       @type = :put
       super
     end

data/lib/rupee/quote.rb

@@ -3,7 +3,23 @@ autoload :Net, "net/http"
 autoload :URI, "uri"
 
 module Rupee
-  # The quote and data import functionality in Rupee
+  # An object representing a security quote from an online source. With a
+  # Rupee::Quote object, you can retrieve the most recent information on a
+  # particular security using either the <tt>get</tt> method or the helper
+  # methods for each parameter (e.g. <tt>price</tt>, <tt>change</tt>):
+  #
+  #   require "rupee/quote"
+  #
+  #   wfc = Rupee::Quote.new("WFC")
+  #
+  #   wfc.get :price, :change, :pct_change
+  #   #=> {:price=>24.96, :change=>0.17, :pct_change =>0.686}
+  #
+  #   wfc.price
+  #   #=> 24.96
+  #
+  #   wfc.change
+  #   #=> 0.17
   class Quote
     # A ticker symbol
     attr_accessor :ticker
@@ -11,19 +27,29 @@ module Rupee
     # The name of the quote source
     attr_accessor :source
 
-    # The cached HTML
-    attr :html
-
     # The frequency in seconds that a quote's information should be updated
     attr_accessor :frequency
 
     # The time at which the next pull from the online quote source will occur
     attr :next_pull
 
+    # Creates a new Rupee::Quote object.
+    #
+    #   wfc = Rupee::Quote.new("WFC")
+    #
+    # is equivalent to
+    # 
+    #   wfc = Rupee::Quote.new("WFC", :source => :bloomberg, :frequency => 15)
+    # 
+    # Configuration options
+    #
+    # * <tt>:source</tt> - The name of the source (default is +:bloomberg+).
+    # * <tt>:frequency</tt> - How often the quote will seek new values from the
+    #   quote source, in seconds (default is +15+).
     def initialize(ticker, opts = {})
       opts = { :source => :bloomberg, :frequency => 15 }.merge opts
       @ticker = ticker
-      @source = Quote.sources[opts[:source]]
+      @source = shorten_source(Quote.sources[opts[:source]])
       @frequency = opts[:frequency]
       @next_pull = Time.now
     end
@@ -58,6 +84,9 @@ module Rupee
       end
     end
 
+    # call-seq: Rupee#price
+    #
+    # Blah
     [:price, :change, :pct_change, :date, :time, :bid, :ask, :open, :high,
       :low, :volume, :mkt_cap, :p_e].each do |method_name|
       define_method method_name do
@@ -65,7 +94,7 @@ module Rupee
       end
     end
 
-    def frequency=(x)
+    def frequency=(x) # :nodoc:
       @next_pull += (x - @frequency)
       @frequency = x
     end
@@ -87,6 +116,10 @@ module Rupee
       end
     end
 
+    # Parses an object that might be a number
+    #
+    #   parse "15"  #=> 15
+    #   parse "abc" #=> "abc"
     def parse(result)
       begin
         Float(result)

data/lib/rupee/security.rb

@@ -4,26 +4,26 @@ module Rupee
     # Automatically sets all arguments passed to <tt>initialize</tt> to
     # instance variables if they exist (think Rails mass assignment).
     #
-    #     require "rupee"
+    #   require "rupee"
     #
-    #     call = Rupee::Call.new(
-    #       :underlying => 60,
-    #       :strike     => 65,
-    #       :time       =>  0.25,
-    #       :rate       =>  0.08,
-    #       :div_yield  =>  0.00,
-    #       :volatility =>  0.3
-    #     )
-    #     puts call.black_scholes
-    #     #=> 2.1333718619275794
+    #   call = Rupee::Call.new(
+    #     :underlying => 60,
+    #     :strike     => 65,
+    #     :time       =>  0.25,
+    #     :rate       =>  0.08,
+    #     :div_yield  =>  0.00,
+    #     :volatility =>  0.3
+    #   )
+    #   puts call.black_scholes
+    #   #=> 2.1333718619275794
     #
     # You still have the option of avoiding the creation of an object (and the
     # overhead it entails) by using the class methods directly:
     #
-    #     require "rupee"
+    #   require "rupee"
     #
-    #     puts Rupee::Option.black_scholes "c", 60, 65, 0.25, 0.08, 0, 0.3
-    #     #=> 2.1333718619275794
+    #   puts Rupee::Option.black_scholes "c", 60, 65, 0.25, 0.08, 0, 0.3
+    #   #=> 2.1333718619275794
     def initialize(opts = {})
       opts.each do |key, value|
         writer = key.to_s.+("=").to_sym
@@ -32,5 +32,22 @@ module Rupee
         end
       end
     end
+
+    class << self
+      # Aliases an attribute, taking into account both its getter and setter
+      # methods. For example,
+      #
+      #   attr_accessor :price
+      #   attr_alias :value, :price
+      # 
+      # would add both a <tt>value</tt> and a <tt>value=</tt> that are equivalent
+      # to their <tt>price</tt> counterparts.
+      def attr_alias(new_read, old_read)
+        alias_method(new_read, old_read) if method_defined?(old_read)
+        new_write = "#{new_read}="
+        old_write = "#{old_read}="
+        alias_method(new_write, old_write) if method_defined?(old_write)
+      end
+    end
   end
 end

data/lib/rupee/version.rb

@@ -1,4 +1,4 @@
 module Rupee
   # The current version
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/spec/c/bond_spec.rb

@@ -7,10 +7,9 @@ require File.dirname(__FILE__) + "/../spec_helper"
 # bond yield to maturity = 0.09
 # new bond price = 104.282
 
-TOLERANCE = 0.001
-
 describe Rupee::Bond do
   before :each do
+    @tolerance = 0.001
     @times = [1, 2, 3]
     @cflows = [10, 10, 110]
     @r = 0.09
@@ -18,39 +17,39 @@ describe Rupee::Bond do
 
   describe "with discrete discounting" do
     it "should produce an accurate price" do
-      Rupee::Bond.price(@times, @cflows, @r).should be_within(TOLERANCE).of 102.531
+      Rupee::Bond.price(@times, @cflows, @r).should be_within(@tolerance).of 102.531
     end
 
     it "should produce an accurate duration" do
-      Rupee::Bond.duration(@times, @cflows, @r).should be_within(TOLERANCE).of 2.73895
+      Rupee::Bond.duration(@times, @cflows, @r).should be_within(@tolerance).of 2.73895
     end
 
     it "should produce an accurate convexity" do
-      Rupee::Bond.convexity(@times, @cflows, @r).should be_within(TOLERANCE).of 8.93248
+      Rupee::Bond.convexity(@times, @cflows, @r).should be_within(@tolerance).of 8.93248
     end
 
     it "should produce an accurate yield to maturity" do
       @price = Rupee::Bond.price(@times, @cflows, @r)
-      Rupee::Bond.yield_to_maturity(@times, @cflows, @price).should be_within(TOLERANCE).of @r
+      Rupee::Bond.yield_to_maturity(@times, @cflows, @price).should be_within(@tolerance).of @r
     end
   end
 
   describe "with continuous discounting" do
     it "should produce an accurate price" do
-      Rupee::Bond.continuous_price(@times, @cflows, @r).should be_within(TOLERANCE).of 101.464
+      Rupee::Bond.continuous_price(@times, @cflows, @r).should be_within(@tolerance).of 101.464
     end
 
     it "should produce an accurate duration" do
-      Rupee::Bond.continuous_duration(@times, @cflows, @r).should be_within(TOLERANCE).of 2.73753
+      Rupee::Bond.continuous_duration(@times, @cflows, @r).should be_within(@tolerance).of 2.73753
     end
 
     it "should produce an accurate convexity" do
-      Rupee::Bond.continuous_convexity(@times, @cflows, @r).should be_within(TOLERANCE).of 7.86779
+      Rupee::Bond.continuous_convexity(@times, @cflows, @r).should be_within(@tolerance).of 7.86779
     end
 
     it "should produce an accurate yield to maturity" do
       @price = Rupee::Bond.continuous_price(@times, @cflows, @r)
-      Rupee::Bond.continuous_yield_to_maturity(@times, @cflows, @price).should be_within(TOLERANCE).of @r
+      Rupee::Bond.continuous_yield_to_maturity(@times, @cflows, @price).should be_within(@tolerance).of @r
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rupee
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2011-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &79757030 !ruby/object:Gem::Requirement
+  requirement: &84129210 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '1.0'
   type: :development
   prerelease: false
-  version_requirements: *79757030
+  version_requirements: *84129210
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &79755150 !ruby/object:Gem::Requirement
+  requirement: &84128900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '2.0'
   type: :development
   prerelease: false
-  version_requirements: *79755150
+  version_requirements: *84128900
 - !ruby/object:Gem::Dependency
   name: autotest
-  requirement: &79754560 !ruby/object:Gem::Requirement
+  requirement: &84127610 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,7 +43,7 @@ dependencies:
         version: '4.0'
   type: :development
   prerelease: false
-  version_requirements: *79754560
+  version_requirements: *84127610
 description: rupee aims to provide user-friendly tools for use in financial gems and
   applications.
 email:
@@ -58,7 +58,7 @@ files:
 - .rspec
 - COPYING
 - Gemfile
-- README.md
+- README.rdoc
 - Rakefile
 - ext/rupee/bond.c
 - ext/rupee/distribution.c

data/README.md

@@ -1,122 +0,0 @@
-Rupee - financial tools for Ruby
-================================
-
-<table>
-  <tr>
-    <td>Homepage</td>
-    <td><a href="http://www.brymck.com">www.brymck.com</a></td>
-  </tr>
-  <tr>
-    <td>Author</td>
-    <td>Bryan McKelvey</td>
-  </tr>
-  <tr>
-    <td>Copyright</td>
-    <td>(c) 2011 Bryan McKelvey</td>
-  </tr>
-  <tr>
-    <td>License</td>
-    <td>MIT</td>
-  </tr>
-</table>
-
-[![Flattr this git repo](http://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=brymck&url=https://github.com/brymck/rupee&title=rupee&language=en_GB&tags=github&category=software)
-
-        /|\
-       / | \
-      /  |  \
-     /_ / \ _\    RU       PE      E
-    |  |   |  |   _ _      _
-    |  |   |  |  | | |    | |__o  ____
-    |  |   |  |  | | | _  |  __| |____|
-    | _|   |_ |  | | |/ / | |___
-     \  \ /  /  /_/|___/   \____|
-      \  |  /
-       \ | /
-        \|/ brymck
-
-Installing
-----------
-
-Note that you must have Ruby 1.8.7+ installed and the ability to compile native
-extensions (standard on most platforms and available on Windows via
-[DevKit](http://rubyinstaller.org/downloads/)).
-
-    gem install rupee
-
-You can also do things the hard way if you want to keep track of the repo:
-
-    git clone git://github.com/brymck/rupee.git
-    cd rupee
-    bundle update
-    rake install
-
-After all that hard work, you can take a test drive by running something like
-this in the Ruby console (i.e. `irb` in a command prompt):
-
-    require "rupee"
-    Rupee::Option.black_scholes "c", 60, 65, 0.25, 0.08, 0, 0.3
-    Rupee::Call.new(
-      :underlying => 60,
-      :strike     => 65,
-      :time       =>  0.25,
-      :rate       =>  0.08,
-      :div_yield  =>  0.00,
-      :volatility =>  0.3
-    ).black_scholes
-
-both of which should return `2.1334`.
-
-You should also be able to get the latest stock info for, for example, Wells
-Fargo using the following (note that you only need to `require` the `quote`
-module):
-
-    require "rupee/quote"
-    wfc = Rupee::Quote.new("WFC")
-
-    wfc.get :price, :change, :pct_change
-    #=> {:price=>24.96, :change=>0.17, :pct_change =>0.686}
-
-    wfc.price
-    #=> 24.96
-
-    wfc.change
-    #=> 0.17
-
-`wfc.get` will return a hash of the requested information for the security.
-Each valid parameter will also have its own utility method. The results will
-update every `wfc.frequency` seconds (defaults to 15).
-
-Got it? Good. This will surely help you collect some rupees in real life.
-
-Performance
------------
-
-This is just a simple benchmark I ran on my own laptop, where I value a simple
-call option with Black-Scholes 100,000 times. You can test the same on yours
-with rake, but in any case it makes the point that for the mathematical side
-of finance a native extension has substantial benefits:
-
-    rake benchmark:black_scholes
-
-Results:
-
-                              user     system      total        real
-    Rupee (class):        0.190000   0.000000   0.190000 (  0.194001)
-    Rupee (one object):   0.180000   0.000000   0.180000 (  0.183091)
-    Rupee (new object):   2.210000   0.000000   2.210000 (  2.213351)
-    Pure Ruby:            2.320000   0.000000   2.320000 (  2.324259)
-
-In words, for math-intensive operations, using a C implementation is clearly
-faster than the same thing in Ruby.
-
-Also, if you're doing a valuation on a one-off set of examples (e.g. in a Monte
-Carlo simulation), you probably don't want to create an object every time.
-Something like `Rupee::Option.black_scholes ...` should work just fine.
-Creating a `Rupee::Option` object takes roughly the same amount of time as
-running `Rupee::Option.black_scholes` a dozen times.
-
-However, if you're creating and reusing an object, I strongly recommend
-preserving the object orientation of Ruby: the penalty for using a new instance
-rather than calling the class method directly is almost entirely in the object
-initialization itself.