bankofcanada_as_dataframe 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0abb0da0ebbf1a62900356917942cebea1e450109498aefc274a1c6b7c46fb1b
-  data.tar.gz: 61bdb7b0ef3271c0c78ea93df3c5a3525a6abb537e1a61633fc210b5c626f591
+  metadata.gz: 1cf8710362c6ea712f6e986f8d7816967a1dc46d76a40bdd95fc0290e5b6c8de
+  data.tar.gz: 2f856b4cdf9972ee394c93c35d8b5069ece19ad945c56ba05c805e93df120211
 SHA512:
-  metadata.gz: bc7d6d816fd7372f6166fb7c36e0e02af23dde904d23cab801df7563205596a67f2415f948e9a258016f9d61256348ab23d771fd0a78fd02efbbf25943682973
-  data.tar.gz: 032b3be1de9e5fda8201df378cd691ee23797048b4bfc625ee0919eb1616327f703d3c77694d92e9165aa1628acd516ee2cc59ee1711674c35165a7ad70edea8
+  metadata.gz: 93d34cf40be6cbbf6b4bd6960657f9083c0ca3d17e7f5b2436d63c19e65380707d63127672cbb8eef2559a476962b5d5d62dfa2d1be3ce2eae1d466a2500bfc5
+  data.tar.gz: a42d1caea25055d5691214b3c05b57d7c76f0de0b8e54b8f7455c61c7ff7b5e83e2d611cb5f48ce11c0349ceba54711c5be6cfdf5cddf28eb19c817d55fef591

data/.ruby-version

@@ -0,0 +1 @@
+3.3.6

data/Gemfile

@@ -1,7 +1,10 @@
 source "https://rubygems.org"
 
+ruby '3.3.6'
+
 # Specify your gem's dependencies in bankofcanada_as_dataframe.gemspec
 gemspec
 
 gem "rake", "~> 12.0"
-gem "none", "~> "
+gem "rspec", "~> 3.0"
+gem "webmock", "~> 3.0"

data/Gemfile.lock

@@ -0,0 +1,85 @@
+PATH
+  remote: .
+  specs:
+    bankofcanada_as_dataframe (0.1.0)
+      httparty
+      polars-df (= 0.27.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    bigdecimal (4.1.2)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    csv (3.3.6)
+    diff-lcs (1.6.2)
+    hashdiff (1.2.1)
+    httparty (0.24.2)
+      csv
+      mini_mime (>= 1.0.0)
+      multi_xml (>= 0.5.2)
+    mini_mime (1.1.5)
+    multi_xml (0.9.1)
+      bigdecimal (>= 3.1, < 5)
+    polars-df (0.27.1-x86_64-linux)
+    public_suffix (7.0.5)
+    rake (12.3.3)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    webmock (3.26.3)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  bankofcanada_as_dataframe!
+  rake (~> 12.0)
+  rspec (~> 3.0)
+  webmock (~> 3.0)
+
+CHECKSUMS
+  addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
+  bankofcanada_as_dataframe (0.1.0)
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  bundler (4.0.19) sha256=b48056e4c77fb3853cc47775b5447ede44aaa4f53c32f168014ab4fe86587d47
+  crack (1.0.1) sha256=ff4a10390cd31d66440b7524eb1841874db86201d5b70032028553130b6d4c7e
+  csv (3.3.6) sha256=aba61e7e507a66f03d45cb1f3c4b6359861c3504038b422962875dce099e4456
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  hashdiff (1.2.1) sha256=9c079dbc513dfc8833ab59c0c2d8f230fa28499cc5efb4b8dd276cf931457cd1
+  httparty (0.24.2) sha256=8fca6a54aa0c4aa4303a0fd33e5e2156175d6a5334f714263b458abd7fda9c38
+  mini_mime (1.1.5) sha256=8681b7e2e4215f2a159f9400b5816d85e9d8c6c6b491e96a12797e798f8bccef
+  multi_xml (0.9.1) sha256=7ce766b59c17241ed62976caeae1fae9b2431b263398c35396239a68c4a64e57
+  polars-df (0.27.1-x86_64-linux) sha256=3cb35fe50bfd783845976e6bc567a560d547dbded8a96887a2d5a658d01396e2
+  public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
+  rake (12.3.3) sha256=f7694adb4fe638da35452300cee6c545e9c377a0e3190018ac04d590b3c26ab3
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  webmock (3.26.3) sha256=77c612816bdcb2fc43db0e42fd98b19be7d4770fd708816fdde65a006664ddec
+
+RUBY VERSION
+  ruby 3.3.6
+
+BUNDLED WITH
+  4.0.19

data/README.md

@@ -1,8 +1,15 @@
-# EconDataReader
+# BankofcanadaAsDataframe
 
 Up to date remote economic data access for ruby, using Polars dataframes. 
 
-This package will fetch economic and financial information from the Bank of Canada's API, and return the results as a Polars dataframe.
+This package will fetch economic and financial information from the Bank of Canada's API, and return the results as a Polars dataframe.  For details regarding the data available from the Bank of Canada, see https://www.bankofcanada.ca/valet/docs .
+
+
+## Requirements
+
+- **Ruby**: >= 3.3
+- **polars-df**: 0.27.1
+
 
 ## Installation
 
@@ -23,13 +30,110 @@ Or install it yourself as:
 
 ## Usage
 
+### Fetching Series Data
+
+Fetch data for a specific series by creating a client with the series code and calling `fetch`:
+
 ``` ruby
-BankofcanadaAsDataframe::Client.new('IEXE0102').fetch
+3.3.0 :001 > BankofcanadaAsDataframe::Client.new('IEXE0102').fetch
+ => 
+shape: (2_504, 2)                                                                  
+┌────────────┬────────┐                                                            
+│ Timestamps ┆ Values │                                                            
+│ ---        ┆ ---    │                                                            
+│ date       ┆ f64    │                                                            
+╞════════════╪════════╡                                                            
+│ 2007-05-01 ┆ 1.1105 │                                                            
+│ 2007-05-02 ┆ 1.1087 │                                                            
+│ 2007-05-03 ┆ 1.1066 │                                                            
+│ 2007-05-04 ┆ 1.1075 │                                                            
+│ 2007-05-07 ┆ 1.1018 │                                                            
+│ …          ┆ …      │                                                            
+│ 2017-04-24 ┆ 1.3511 │
+│ 2017-04-25 ┆ 1.3565 │
+│ 2017-04-26 ┆ 1.3612 │
+│ 2017-04-27 ┆ 1.3624 │
+│ 2017-04-28 ┆ 1.365  │
+└────────────┴────────┘ 
+```
+
+You can filter by date range using the `start` and `fin` parameters:
+
+``` ruby
+3.3.0 :002 > BankofcanadaAsDataframe::Client.new('IEXE0102').fetch(start: '2010-01-01', fin: '2016-01-01')
+ => 
+shape: (1_502, 2)                                                                              
+┌────────────┬────────┐                                                                        
+│ Timestamps ┆ Values │                                                                        
+│ ---        ┆ ---    │                                                                        
+│ date       ┆ f64    │                                                                        
+╞════════════╪════════╡                                                                        
+│ 2010-01-04 ┆ 1.0414 │                                                                        
+│ 2010-01-05 ┆ 1.039  │                                                                       
+│ 2010-01-06 ┆ 1.0325 │                                                                       
+│ 2010-01-07 ┆ 1.035  │                                                                       
+│ 2010-01-08 ┆ 1.0309 │                                                                       
+│ …          ┆ …      │                                                                       
+│ 2015-12-23 ┆ 1.3857 │                                                                       
+│ 2015-12-24 ┆ 1.3845 │                                                                       
+│ 2015-12-29 ┆ 1.3823 │
+│ 2015-12-30 ┆ 1.3885 │
+│ 2015-12-31 ┆ 1.384  │
+└────────────┴────────┘ 
+```
+
+### Listing Available Series
+
+To discover available series codes and their descriptions, use the `list_series` class method:
+
+``` ruby
+3.3.0 :003 > BankofcanadaAsDataframe::Client.list_series
+ => 
+shape: (1_234, 2)
+┌──────────────┬─────────────────────────────────────┐
+│ Series       ┆ Description                         │
+│ ---          ┆ ---                                 │
+│ str          ┆ str                                 │
+╞══════════════╪═════════════════════════════════════╡
+│ IEXE0102     ┆ US dollar, noon spot rate; United…  │
+│ FXCADUSD     ┆ Canadian dollar (noon); Canadian…   │
+│ …            ┆ …                                   │
+└──────────────┴─────────────────────────────────────┘
 ```
 
 ## Documentation
 
-TBD
+### Public API
+
+#### `Client.new(series_code, options = {})`
+
+Creates a new client for fetching data for the specified series code.
+
+**Parameters:**
+- `series_code` (String): The Bank of Canada series code (e.g., 'IEXE0102')
+- `options` (Hash): Optional configuration options
+
+**Returns:** A new `BankofcanadaAsDataframe::Client` instance
+
+#### `#fetch(start: nil, fin: nil)`
+
+Fetches observations for the series and returns them as a Polars DataFrame.
+
+**Parameters:**
+- `start` (String or Date, optional): Filter observations on or after this date
+- `fin` (String or Date, optional): Filter observations on or before this date
+
+**Returns:** A `Polars::DataFrame` with columns:
+- `Timestamps`: Date column containing observation dates
+- `Values`: Float64 column containing observation values
+
+#### `Client.list_series`
+
+Class method that returns a list of all available series from the Bank of Canada.
+
+**Returns:** A `Polars::DataFrame` with columns:
+- `Series`: String column containing series codes
+- `Description`: String column containing series label and description (separated by semicolon)
 
 ## Contributing
 
@@ -42,7 +146,21 @@ The following conventions are intended for this project.
  * When fetched, the dataset may be filtered based on optional (hash) arguments.
  * Output should be provided in a consistent DataFrame format (currently Polars::DataFrame).
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/bmck/econ_data_reader.
+Bug reports and pull requests are welcome on GitHub at https://github.com/bmck/bankofcanada_as_dataframe.
+
+
+## Testing
+
+This gem uses RSpec for testing. All tests use webmock to stub HTTP requests, so no live network connections are made during testing.
+
+To run the test suite:
+
+    $ bundle install
+    $ bundle exec rake spec
+
+Or run tests directly with RSpec:
+
+    $ bundle exec rspec
 
 
 ## License

data/Rakefile

@@ -1,2 +1,6 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
 task :default => :spec

data/bankofcanada_as_dataframe.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
   spec.description   = "Economic and financial data from the Bank of Canada"
   spec.homepage      = "https://github.com/bmck/bankofcanada_as_dataframe"
   spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.3.0")
 
   # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
 
@@ -29,6 +29,6 @@ Gem::Specification.new do |spec|
 
   # Uncomment to register a new dependency of your gem
   # spec.add_dependency "typhoeus-gem", "~> 0.6.9"
-  spec.add_dependency 'polars-df'
+  spec.add_dependency 'polars-df', '0.27.1'
   spec.add_dependency 'httparty'
 end

data/lib/bankofcanada_as_dataframe/client.rb

@@ -0,0 +1,58 @@
+require 'polars-df'
+require 'httparty'
+require 'date'
+
+module BankofcanadaAsDataframe
+  class Client
+    # Get data for the given name from the Bank of Canada.
+
+    include ::HTTParty
+    base_uri "https://www.bankofcanada.ca/valet"
+    format :json
+
+    attr_reader :tag
+
+    def initialize(series, options={})
+      @tag = series
+    end
+
+    def fetch(start: nil, fin: nil)
+      dta = observations({}).parsed_response['observations']
+      dta = dta.select{|d| start.nil? ? true : Date.parse(d['d']) >= _parse_date(start) } unless start.nil?
+      dta = dta.select{|d| fin.nil? ? true : Date.parse(d['d']) <= _parse_date(fin) } unless fin.nil?
+
+      dates = dta.map{|d| Date.parse(d['d']) }
+      vals = dta.map{|d| d[tag]['v'].to_f }
+
+      Polars::DataFrame.new({Timestamps: dates, Values: vals})
+    end
+
+    def self.list_series
+      dta = (get('/lists/series/json').parsed_response)['series']
+
+      series = dta.keys
+      desc = series.map{|s| [dta[s]['label'], dta[s]['description']].join('; ') }
+
+      Polars::Config.set_tbl_rows(-1)
+      Polars::DataFrame.new({Series: series, Description: desc})
+    end
+
+    protected
+
+    def default_options
+      { }
+    end
+
+    private
+
+    def observations(options={})
+      self.class.get("/observations/#{tag}/json", :query => options.merge(self.default_options))
+    end
+
+    def _parse_date(date_input)
+      return date_input if date_input.is_a?(Date)
+      Date.parse(date_input.to_s)
+    end
+
+  end
+end

data/lib/bankofcanada_as_dataframe/version.rb

@@ -1,3 +1,3 @@
 module BankofcanadaAsDataframe
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: bankofcanada_as_dataframe
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Bill McKinnon
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-05 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: polars-df
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.27.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.27.1
 - !ruby/object:Gem::Dependency
   name: httparty
   requirement: !ruby/object:Gem::Requirement
@@ -46,8 +46,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".ruby-version"
 - ".travis.yml"
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -55,6 +57,7 @@ files:
 - bin/console
 - bin/setup
 - lib/bankofcanada_as_dataframe.rb
+- lib/bankofcanada_as_dataframe/client.rb
 - lib/bankofcanada_as_dataframe/version.rb
 homepage: https://github.com/bmck/bankofcanada_as_dataframe
 licenses:
@@ -71,14 +74,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Economic and financial data from the Bank of Canada