worldbank_as_dataframe 0.1.0

data/lib/worldbank_as_dataframe/country.rb

@@ -0,0 +1,326 @@
+require 'worldbank_as_dataframe/queriable'
+module WorldbankAsDataframe
+
+  class Country
+    extend WorldbankAsDataframe::Queriable
+    COUNTRY_ALIASES = [
+      ['AW', 'ABW', 'aruba'],
+      ['AF', 'AFG', 'afganistan'],
+      ['AO', 'AGO', 'angola'],
+      ['AI', 'AIA', 'anguilla'],
+      ['AX', 'ALA', 'aland_islands'],
+      ['AL', 'ALB', 'albania'],
+      ['AD', 'AND', 'andorra'],
+      ['AE', 'ARE', 'united_arab_emirates'],
+      ['AR', 'ARG', 'argentina'],
+      ['AM', 'ARM', 'armenia'],
+      ['AS', 'ASM', 'american_samoa'],
+      ['AQ', 'ATA', 'antarctica'],
+      ['TF', 'ATF', 'french_southern_territories'],
+      ['AG', 'ATG', 'antigua_and_barbuda'],
+      ['AU', 'AUS', 'australia'],
+      ['AT', 'AUT', 'austria'],
+      ['AZ', 'AZE', 'azerbaijan'],
+      ['BI', 'BDI', 'burundi'],
+      ['BE', 'BEL', 'belgium'],
+      ['BJ', 'BEN', 'benin'],
+      ['BQ', 'BES', 'bonaire_saint_eustatius_and_saba'],
+      ['BF', 'BFA', 'burkina_faso'],
+      ['BD', 'BGD', 'bangladesh'],
+      ['BG', 'BGR', 'bulgaria'],
+      ['BH', 'BHR', 'bahrain'],
+      ['BS', 'BHS', 'bahamas'],
+      ['BA', 'BIH', 'bosnia_and_herzegovina'],
+      ['BL', 'BLM', 'saint_barthelemy'],
+      ['BY', 'BLR', 'belarus'],
+      ['BZ', 'BLZ', 'belize'],
+      ['BM', 'BMU', 'bermuda'],
+      ['BO', 'BOL', 'plurinational_state_of_bolivia'],
+      ['BR', 'BRA', 'brazil'],
+      ['BB', 'BRB', 'barbados'],
+      ['BN', 'BRN', 'brunei_darussalam'],
+      ['BT', 'BTN', 'bhutan'],
+      ['BV', 'BVT', 'bouvet_island'],
+      ['BW', 'BWA', 'botswana'],
+      ['CF', 'CAF', 'central_african_republic'],
+      ['CA', 'CAN', 'canada'],
+      ['CC', 'CCK', 'cocos_keeling_islands'],
+      ['CH', 'CHE', 'switzerland'],
+      ['CL', 'CHL', 'chile'],
+      ['CN', 'CHN', 'china'],
+      ['CI', 'CIV', 'cote_divoire'],
+      ['CM', 'CMR', 'cameroon'],
+      ['CD', 'COD', 'democratic_republic_of_the_congo'],
+      ['CG', 'COG', 'congo'],
+      ['CK', 'COK', 'cook_islands'],
+      ['CO', 'COL', 'colombia'],
+      ['KM', 'COM', 'comoros'],
+      ['CV', 'CPV', 'cape_verde'],
+      ['CR', 'CRI', 'costa_rica'],
+      ['CU', 'CUB', 'cuba'],
+      ['CW', 'CUW', 'curacao'],
+      ['CX', 'CXR', 'christmas_island'],
+      ['KY', 'CYM', 'cayman_islands'],
+      ['CY', 'CYP', 'cyprus'],
+      ['CZ', 'CZE', 'czech_republic'],
+      ['DE', 'DEU', 'germany'],
+      ['DJ', 'DJI', 'djibouti'],
+      ['DM', 'DMA', 'dominca'],
+      ['DK', 'DNK', 'denmark'],
+      ['DO', 'DOM', 'dominican_republic'],
+      ['DZ', 'DZA', 'algeria'],
+      ['EC', 'ECU', 'ecuador'],
+      ['EG', 'EGY', 'egypt'],
+      ['ER', 'ERI', 'eritrea'],
+      ['EH', 'ESH', 'western_sahara'],
+      ['ES', 'ESP', 'spain'],
+      ['EE', 'EST', 'estonia'],
+      ['ET', 'ETH', 'ethiopia'],
+      ['FI', 'FIN', 'finland'],
+      ['FJ', 'FJI', 'fiji'],
+      ['FK', 'FLK', 'falkland_islands_malvinas'],
+      ['FR', 'FRA', 'france'],
+      ['FO', 'FRO', 'faroe_islands'],
+      ['FM', 'FSM', 'federated_states_of_micronesia'],
+      ['GA', 'GAB', 'gabon'],
+      ['GB', 'GBR', 'united_kingdom'],
+      ['GE', 'GEO', 'georgia'],
+      ['GG', 'GGY', 'guernsey'],
+      ['GH', 'GHA', 'ghana'],
+      ['GI', 'GIB', 'gibraltar'],
+      ['GN', 'GIN', 'guinea'],
+      ['GP', 'GLP', 'guadeloupe'],
+      ['GM', 'GMB', 'gambia'],
+      ['GW', 'GNB', 'guinea_bissau'],
+      ['GQ', 'GNQ', 'equatorial_guinea'],
+      ['GR', 'GRC', 'greece'],
+      ['GD', 'GRD', 'grenada'],
+      ['GL', 'GRL', 'greenland'],
+      ['GT', 'GTM', 'guatemala'],
+      ['GF', 'GUF', 'french_guiana'],
+      ['GU', 'GUM', 'guam'],
+      ['GY', 'GUY', 'guyana'],
+      ['HK', 'HKG', 'hong_kong'],
+      ['HM', 'HMD', 'heard_island_mcdonald_islands'],
+      ['HN', 'HND', 'honduras'],
+      ['HR', 'HRV', 'croatia'],
+      ['HT', 'HTI', 'haiti'],
+      ['HU', 'HUN', 'hungary'],
+      ['ID', 'IDN', 'indonesia'],
+      ['IM', 'IMN', 'isle_of_man'],
+      ['IN', 'IND', 'india'],
+      ['IO', 'IOT', 'british_indian_ocean_territory'],
+      ['IE', 'IRL', 'ireland'],
+      ['IR', 'IRN', 'islamic_republic_of_iran'],
+      ['IQ', 'IRQ', 'iraq'],
+      ['IS', 'ISL', 'iceland'],
+      ['IL', 'ISR', 'israel'],
+      ['IT', 'ITA', 'italy'],
+      ['JM', 'JAM', 'jamaica'],
+      ['JE', 'JEY', 'jersey'],
+      ['JO', 'JOR', 'jordan'],
+      ['JP', 'JPN', 'japan'],
+      ['KZ', 'KAZ', 'kazakhstan'],
+      ['KE', 'KEN', 'kenya'],
+      ['KG', 'KGZ', 'kyrgyzstan'],
+      ['KH', 'KHM', 'cambodia'],
+      ['KI', 'KIR', 'kiribati'],
+      ['KN', 'KNA', 'saint_kitts_and_nevis'],
+      ['KR', 'KOR', 'republic_of_korea'],
+      ['KW', 'KWT', 'kuwait'],
+      ['LA', 'LAO', 'lao_peoples_democratic_republic'],
+      ['LB', 'LBN', 'lebanon'],
+      ['LR', 'LBR', 'liberia'],
+      ['LY', 'LBY', 'libyan_arab_jamahiriya'],
+      ['LC', 'LCA', 'saint_lucia'],
+      ['LI', 'LIE', 'liechtenstein'],
+      ['LK', 'LKA', 'sri_lanka'],
+      ['LS', 'LSO', 'lesotho'],
+      ['LT', 'LTU', 'lithuania'],
+      ['LU', 'LUX', 'luxembourg'],
+      ['LV', 'LVA', 'latvia'],
+      ['MO', 'MAC', 'macao'],
+      ['MF', 'MAF', 'saint_martin'],
+      ['MA', 'MAR', 'morocco'],
+      ['MC', 'MCO', 'monaco'],
+      ['MD', 'MDA', 'republic_of_moldova'],
+      ['MG', 'MDG', 'madagascar'],
+      ['MV', 'MDV', 'maldives'],
+      ['MX', 'MEX', 'mexico'],
+      ['MH', 'MHL', 'marshall_islands'],
+      ['MK', 'MKD', 'the_former_yugoslav_republic_of_macedonia'],
+      ['ML', 'MLI', 'mali'],
+      ['MT', 'MLT', 'malta'],
+      ['MM', 'MMR', 'myanmar'],
+      ['ME', 'MNE', 'montenegro'],
+      ['MN', 'MNG', 'mongolia'],
+      ['MP', 'MNP', 'northern_mariana_islands'],
+      ['MZ', 'MOZ', 'mozambique'],
+      ['MR', 'MRT', 'mauritania'],
+      ['MS', 'MSR', 'montserrat'],
+      ['MQ', 'MTQ', 'martinique'],
+      ['MU', 'MUS', 'mauritius'],
+      ['MW', 'MWI', 'malawi'],
+      ['MY', 'MYS', 'malaysia'],
+      ['YT', 'MYT', 'mayotte'],
+      ['NA', 'NAM', 'namibia'],
+      ['NC', 'NCL', 'new_caledonia'],
+      ['NE', 'NER', 'niger'],
+      ['NF', 'NFK', 'norfolk_island'],
+      ['NG', 'NGA', 'nigeria'],
+      ['NI', 'NIC', 'nicaragua'],
+      ['NU', 'NIU', 'niue'],
+      ['NL', 'NLD', 'netherlands'],
+      ['NO', 'NOR', 'norway'],
+      ['NP', 'NPL', 'nepal'],
+      ['NR', 'NRU', 'nauru'],
+      ['NZ', 'NZL', 'new_zealand'],
+      ['OM', 'OMN', 'oman'],
+      ['PK', 'PAK', 'pakistan'],
+      ['PA', 'PAN', 'panama'],
+      ['PN', 'PCN', 'pitcairn'],
+      ['PE', 'PER', 'peru'],
+      ['PH', 'PHL', 'philippines'],
+      ['PW', 'PLW', 'palau'],
+      ['PG', 'PNG', 'papua_new_guinea'],
+      ['PL', 'POL', 'poland'],
+      ['PR', 'PRI', 'puerto_rico'],
+      ['KP', 'PRK', 'democratic_peoples_republic_of_korea'],
+      ['PT', 'PRT', 'portugal'],
+      ['PY', 'PRY', 'paraguay'],
+      ['PS', 'PSE', 'occupied_palestinian_territory'],
+      ['PF', 'PYF', 'french_polynesia'],
+      ['QA', 'QAT', 'qatar'],
+      ['RE', 'REU', 'reunion'],
+      ['RO', 'ROU', 'romania'],
+      ['RU', 'RUS', 'russian_federation'],
+      ['RW', 'RWA', 'rwanda'],
+      ['SA', 'SAU', 'saudi_arabia'],
+      ['SD', 'SDN', 'sudan'],
+      ['SN', 'SEN', 'senegal'],
+      ['SG', 'SGP', 'singapore'],
+      ['GS', 'SGS', 'south_georgia_and_the_south_sandwich_islands'],
+      ['SH', 'SHN', 'saint_helena_ascension_and_tristan_da_cunha'],
+      ['SJ', 'SJM', 'svalbard_and_jan_mayen'],
+      ['SB', 'SLB', 'soloman_islands'],
+      ['SL', 'SLE', 'sierra_leone'],
+      ['SV', 'SLV', 'el_salvador'],
+      ['SM', 'SMR', 'san_marino'],
+      ['SO', 'SOM', 'somalia'],
+      ['PM', 'SPM', 'saint_pierre_and_miquelon'],
+      ['RS', 'SRB', 'serbia'],
+      ['ST', 'STP', 'sao_tome_and_principe'],
+      ['SR', 'SUR', 'suriname'],
+      ['SK', 'SVK', 'slovakia'],
+      ['SI', 'SVN', 'slovenia'],
+      ['SE', 'SWE', 'sweden'],
+      ['SZ', 'SWZ', 'swaziland'],
+      ['SX', 'SXM', 'sint_maarten'],
+      ['SC', 'SYC', 'seychelles'],
+      ['SY', 'SYR', 'syrian_arab_republic'],
+      ['TC', 'TCA', 'turks_caicos_islands'],
+      ['TD', 'TCD', 'chad'],
+      ['TG', 'TGO', 'togo'],
+      ['TH', 'THA', 'thailand'],
+      ['TJ', 'TJK', 'tajikistan'],
+      ['TK', 'TKL', 'tokelau'],
+      ['TM', 'TKM', 'turkmenistan'],
+      ['TL', 'TLS', 'timor_leste'],
+      ['TO', 'TON', 'tonga'],
+      ['TT', 'TTO', 'trinidad_and_tobago'],
+      ['TN', 'TUN', 'tunisia'],
+      ['TR', 'TUR', 'turkey'],
+      ['TU', 'TUV', 'tuvalu'],
+      ['TW', 'TWN', 'taiwan_provice_of_china'],
+      ['TZ', 'TZA', 'united_republic_of_tanzania'],
+      ['UG', 'UGA', 'uganda'],
+      ['UA', 'UKR', 'ukraine'],
+      ['UM', 'UMI', 'united_states_minor_outlying_islands'],
+      ['UY', 'URY', 'uruguay'],
+      ['US', 'USA', 'united_states_of_america'],
+      ['UZ', 'UZB', 'uzbekistan'],
+      ['VC', 'VCT', 'saint_vincent_and_the_grenadines'],
+      ['VE', 'VEN', 'bolivarian_republic_of_venezuela'],
+      ['VG', 'VGB', 'british_virgin_islands'],
+      ['VI', 'VIR', 'us_virgin_islands'],
+      ['VN', 'VNM', 'viet_nam'],
+      ['VU', 'VUT', 'vanuatu'],
+      ['WF', 'WLF', 'wallis_and_futuna'],
+      ['WS', 'WSM', 'samoa'],
+      ['YE', 'YEM', 'yemen'],
+      ['ZA', 'ZAF', 'south_africa'],
+      ['ZM', 'ZMB', 'zambia'],
+      ['ZW', 'ZWE', 'zimbabwe']
+    ]
+
+    attr_reader :raw, :name, :iso2_code, :iso3_code, :region, :income_level, :lending_type, :capital, :type
+
+    def self.country_aliases
+      COUNTRY_ALIASES
+    end
+
+    def self.country
+      find('all').country(arg)
+    end
+
+    def self.indicators(arg)
+      find('all').indicator(arg)
+    end
+
+    def self.fetch(arg)
+      find(arg).fetch
+    end
+
+    def self.all
+      find('all')
+    end
+
+    def self.find(id)
+      id = normalize_id id
+      id = ensure_id id unless id =~ /all/
+      WorldbankAsDataframe::ParamQuery.new('country', id, self)
+    end
+
+    def initialize(values={})
+      @raw = values
+      @name = values['name']
+      @iso2_code = values['iso2Code']
+      @iso3_code = values['id']
+      @region = WorldbankAsDataframe::Region.new(values['region']) if values['region']
+      @income_level = WorldbankAsDataframe::IncomeLevel.new(values['incomeLevel']) if values['incomeLevel']
+      @lending_type = WorldbankAsDataframe::LendingType.new(values['lendingType']) if values['lendingType']
+      @capital = values['capitalCity']
+      @type = 'countries'
+    end
+
+private
+
+    def self.ensure_id(id)
+      @id = id
+      if @id.length > 3
+        @matching = COUNTRIES.select do |country|
+          country[2] =~ Regexp.new(@id)
+        end
+        if @matching.length > 1
+          raise ArgumentError,
+            "More than one country code matched '#{@id}'. Perhaps you meant one of #{@matching.join(', ')}?",
+            caller
+        elsif @matching.length == 0
+          raise ArgumentError,
+            "No countries matched '#{@id}', please try again.",
+            caller
+        else
+          @id = @matching[0][0]
+        end
+      end
+      @id
+    end
+
+    def self.normalize_id(id)
+      id.gsub!(/[ -]/, '_')
+      id.downcase!
+      id
+    end
+  end
+end
+

data/lib/worldbank_as_dataframe/data.rb

@@ -0,0 +1,47 @@
+require 'worldbank_as_dataframe/queriable'
+module WorldbankAsDataframe
+
+  class Data
+    extend WorldbankAsDataframe::Queriable
+    attr_reader :raw, :name, :id, :value, :date, :others
+
+    def self.raw
+      find('all').raw
+    end
+
+    def self.country(arg)
+      find('all').country(arg)
+    end
+
+    def self.fetch(arg)
+      find(arg).fetch
+    end
+
+    def self.all
+      find('all')
+    end
+
+    def self.find(id)
+      WorldbankAsDataframe::DataQuery.new('indicator', id, self)
+    end
+
+    def initialize(values={})
+      @raw = values
+      @name = values['indicator'].delete('value')
+      @id = values['indicator'].delete('id')
+      @value = values.delete('value')
+      @date = values.delete('date')
+      values.delete('indicator')
+      @others = values
+    end
+
+    def to_h
+      hdr = @name
+      suffix = nil
+      suffix = " for #{@others['country']['value']}" rescue ''
+      hdr += suffix
+
+      {'Timestamps' => @date, hdr => @value }
+    end
+  end
+end

data/lib/worldbank_as_dataframe/data_query.rb

@@ -0,0 +1,82 @@
+module WorldbankAsDataframe
+
+  class DataQuery < Query
+
+    def initialize(name, id, model)
+      super
+      clear_params!
+    end
+    
+    def fetch_as_hsh
+      results = super
+      clear_params!
+      results
+    end
+    
+    def fetch
+      require 'polars-df'
+
+      results = super
+      clear_params!
+      Polars::DataFrame.new(results.map(&:to_h))
+    end
+    
+    def lending_type(lending_type)
+      ensure_unconflicting_qualifiers
+      parsed = indifferent_number lending_type
+      @param_dir = ['lendingTypes', parsed]
+      self
+    end
+
+    def income_level(income_level)
+      ensure_unconflicting_qualifiers
+      parsed = indifferent_number income_level
+      @param_dir = ['incomeLevels', parsed]
+      self
+    end
+
+    def region(regions)
+      ensure_unconflicting_qualifiers
+      parsed = indifferent_number regions
+      @param_dir = ['country', parsed]
+      self
+    end
+
+    def country(country)
+      ensure_unconflicting_qualifiers
+      parsed = indifferent_type country
+      parsed = ensure_country_id parsed
+      @param_dir = ['country', parsed]
+      self
+    end
+
+    def indicator(indicators)
+      parsed = indifferent_number indicators
+      @id = parsed
+      self
+    end
+    alias_method(:find, :indicator)
+
+    def source(sources)
+      ensure_unconflicting_qualifiers
+      parsed = indifferent_number sources
+      @param_dir = ['sources', parsed]
+      self
+    end
+
+    private
+
+    def ensure_unconflicting_qualifiers
+      if @params_filled
+        raise ArgumentError,
+          "Only one of 'income_level', 'lending_type', 'country', or 'source' can be called on the same query"
+      end
+      @params_filled = true
+    end
+    
+    def clear_params!
+      @param_dir = []
+      @params_filled = false      
+    end    
+  end
+end

data/lib/worldbank_as_dataframe/income_level.rb

@@ -0,0 +1,23 @@
+module WorldbankAsDataframe
+
+  class IncomeLevel
+
+    attr_reader :raw, :id, :name, :type
+
+    def self.all
+      find('all')
+    end
+
+    def self.find(id)
+      WorldbankAsDataframe::ParamQuery.new('incomeLevels', id, self)
+    end
+
+    def initialize(values={})
+      @raw = values
+      @id = values['id']
+      @name = values['value']
+      @type = 'incomeLevels'
+    end
+  end
+
+end

data/lib/worldbank_as_dataframe/indicator.rb

@@ -0,0 +1,42 @@
+require 'worldbank_as_dataframe/queriable'
+module WorldbankAsDataframe
+
+  class Indicator
+    extend WorldbankAsDataframe::Queriable
+    attr_reader :raw, :id, :name, :source, :note, :organization, :topics, :type
+
+    def self.country
+      find('all').country(arg)
+    end
+
+    def self.fetch(arg)
+      find(arg).fetch
+    end
+
+    def self.featured
+      find('all').featured_indicators
+    end
+
+    def self.all
+      find('all')
+    end
+
+    def self.find(id)
+      WorldbankAsDataframe::ParamQuery.new('indicator', id, self)
+    end
+
+    def initialize(values={})
+      @raw = values
+      @id = values['id']
+      @name = values['name']
+      @source = WorldbankAsDataframe::Source.new(values['source'])
+      @note = values['sourceNote']
+      @organization = values['sourceOrganization']
+      @topics = []
+      values['topics'].each do |topic| 
+        @topics << WorldbankAsDataframe::Topic.new(topic)
+      end
+      @type = 'indicator'
+    end
+  end
+end

data/lib/worldbank_as_dataframe/lending_type.rb

@@ -0,0 +1,23 @@
+module WorldbankAsDataframe
+
+  class LendingType
+
+    attr_reader :raw, :id, :name, :type
+
+    def self.all
+      find('all')
+    end
+
+    def self.find(id)
+      WorldbankAsDataframe::ParamQuery.new('lendingTypes', id, self)
+    end
+
+    def initialize(values={})
+      @raw = values
+      @id = values['id']
+      @name = values['value']
+      @type = 'lendingTypes'
+    end
+  end
+end
+

data/lib/worldbank_as_dataframe/param_query.rb

@@ -0,0 +1,51 @@
+module WorldbankAsDataframe
+
+  class ParamQuery < Query
+  
+    def initialize(name, id, model)
+      super
+    end
+    
+    def lending_type(lending_type)
+      parsed = indifferent_number lending_type
+      @query[:params].merge!({:lendingTypes => parsed})
+      self
+    end
+
+    def income_level(income_levels)
+      parsed = indifferent_number income_levels
+      @query[:params].merge!({:incomeLevels => parsed})
+      self
+    end
+
+    def region(regions)
+      parsed = indifferent_number regions
+      @query[:params].merge!({:country => parsed})
+      self
+    end
+
+    def country(country)
+      parsed = indifferent_type country
+      parsed = ensure_country_id parsed
+      @query[:params].merge!({:country => parsed})
+      self
+    end
+
+    def indicator(indicators)
+      parsed = indifferent_number indicators
+      @query[:params].merge!({:indicator => parsed})
+      self
+    end
+
+    def featured_indicators
+      @query[:params].merge!({:featured => 1})
+      self
+    end
+
+    def source(sources)
+      parsed = indifferent_number sources
+      @query[:params].merge!({:sources => parsed})
+      self
+    end
+  end
+end

data/lib/worldbank_as_dataframe/queriable.rb

@@ -0,0 +1,39 @@
+module WorldbankAsDataframe
+  module Queriable    
+    def id(arg)
+      find('all').id(arg)
+    end
+
+    def most_recent_values(arg)
+      find('all').most_recent_values(arg)
+    end
+
+    def page(arg)
+      find('all').page(arg)
+    end
+
+    def self.per_page(arg)
+      find('all').per_page(arg)
+    end
+
+    def language(arg)
+      find('all').language(arg)
+    end
+
+    def format(arg)
+      find('all').format(arg)
+    end
+
+    def income_level(arg)
+      find('all').income_level(arg)
+    end
+
+    def lending_type(arg)
+      find('all').lending_type(arg)
+    end
+
+    def region(arg)
+      find('all').region(arg)
+    end
+  end  
+end