From f082c462a739b43e4ded432b487b5a940fc98612 Mon Sep 17 00:00:00 2001 From: Vincent Arel-Bundock Date: Wed, 15 Nov 2023 19:39:31 -0500 Subject: [PATCH] update docs --- .Rbuildignore | 1 + altdoc/docsify.html | 45 ++++++++ altdoc/docsify.md | 6 ++ docs/NEWS.md | 95 +++++++++++++++++ docs/README.md | 141 +++++++++++++++++++++++++ docs/_sidebar.md | 12 +++ docs/docsify.html | 45 ++++++++ docs/index.html | 44 ++++++++ docs/man/WDI-package.md | 29 +++++ docs/man/WDI.md | 181 ++++++++++++++++++++++++++++++++ docs/man/WDI_data.md | 103 ++++++++++++++++++ docs/man/WDIbulk.md | 38 +++++++ docs/man/WDIcache.md | 27 +++++ docs/man/WDIsearch.md | 69 ++++++++++++ docs/man/languages_supported.md | 27 +++++ docs/man/wdi.dl.md | 21 ++++ docs/man/wdi.query.md | 20 ++++ 17 files changed, 904 insertions(+) create mode 100644 altdoc/docsify.html create mode 100644 altdoc/docsify.md create mode 100644 docs/NEWS.md create mode 100644 docs/README.md create mode 100644 docs/_sidebar.md create mode 100644 docs/docsify.html create mode 100644 docs/index.html create mode 100644 docs/man/WDI-package.md create mode 100644 docs/man/WDI.md create mode 100644 docs/man/WDI_data.md create mode 100644 docs/man/WDIbulk.md create mode 100644 docs/man/WDIcache.md create mode 100644 docs/man/WDIsearch.md create mode 100644 docs/man/languages_supported.md create mode 100644 docs/man/wdi.dl.md create mode 100644 docs/man/wdi.query.md diff --git a/.Rbuildignore b/.Rbuildignore index 988216c..755a041 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -10,3 +10,4 @@ cran-comments.md ^docs$ ^pkgdown$ ^\.github$ +^altdoc$ diff --git a/altdoc/docsify.html b/altdoc/docsify.html new file mode 100644 index 0000000..1d99413 --- /dev/null +++ b/altdoc/docsify.html @@ -0,0 +1,45 @@ + + + + + + + + + + + +
+ + + + + + + diff --git a/altdoc/docsify.md b/altdoc/docsify.md new file mode 100644 index 0000000..354f070 --- /dev/null +++ b/altdoc/docsify.md @@ -0,0 +1,6 @@ +* [Home](/) +* [Changelog]($ALTDOC_NEWS) +$ALTDOC_VIGNETTE_BLOCK +$ALTDOC_MAN_BLOCK +* [Code of Conduct]($ALTDOC_CODE_OF_CONDUCT) +* [License]($ALTDOC_LICENSE) diff --git a/docs/NEWS.md b/docs/NEWS.md new file mode 100644 index 0000000..f7aa9d1 --- /dev/null +++ b/docs/NEWS.md @@ -0,0 +1,95 @@ +# WDI 2.7.8.9000 + +- Fix a bug where ISO3 codes were wrongly attributed to column `iso2c` ([#54](https://github.com/vincentarelbundock/WDI//issues/54)). + +## WDI 2.7.8 + +- Move to `jsonlite` +- `end` is NULL by default + +## WDI 2.7.7 + +- Update the cache + +## WDI 2.7.6 + +- `WDI(extra = TRUE)` includes a new `lastupdated` column. + +## WDI 2.7.5 + +- Add the observation status (whether an observation is a forecast) when `extra = TRUE` in `WDI()` ([#48](https://github.com/vincentarelbundock/WDI//issues/48)) +- Updated cache + +## WDI 2.7.4 + +- Bug fix for on-the-fly rename + +## WDI 2.7.3 + +- Better error message +- Bug fixes + +## WDI 2.7.2 + +- Add support for several languages with the "language" argument in `WDI()` ([#15](https://github.com/vincentarelbundock/WDI//issues/15)) +- Add "latest" argument in `WDI()`, to fetch the most recent non-NA values ([#29](https://github.com/vincentarelbundock/WDI//issues/29), [#43](https://github.com/vincentarelbundock/WDI//issues/43)) +- Speed improvement in WDIbulk (Thanks to [@etiennebacher](https://github.com/etiennebacher)) +- WDIbulk gets a `timeout` argument + +## WDI 2.7.1 + +- Bug: did not download all countries +- WDIcache did not retrieve regions + +## WDI 2.7.0 + +- API v2 +- Fix a breaking change after API v2 +- per\_page not large enough when dataset is big +- Monthly and quarterly data + +## WDI 2.6.0 + +- `start` and `end` are NULL as default and download all available years. +- `label` attribute to the return data.frame includes descriptive labels for each +- `WDIbulk` function to download all of WDI +- WDIcache and data trim whitespace from region names + +## WDI 2.5.1 + +- New # WDI numbering scheme +- Updated country and indicator data + +## WDI 2.5.0 + +- Namespace issues (thanks to Jan Dietrich) +- Updated the list of available indicators +- Allow iso3c or iso2c as input for country argument +- Rolled-back indicator input clean up because too aggressive (Thanks to Geoff Wright) +- Rename columns automatically when using a named vector + +## WDI 2.4.0 + +- Call RJSONIO::fromJSON explicitly to avoid conflict with JSON package (Thanks to Richard Cotton) + +## WDI 2.3.0 + +- Change default start/end date per user request + +## WDI 2.2.0 + +- Bug: country names were stripped of digits + +## WDI 2.1.0 + +- Fixed various issues (thanks to Matthieu Stigler for bug reports and patches) +- Faster downloads when requesting multiple countries (leveraging the US;BR;CA API syntax) + +## WDI 2.0.0 + +- Now uses JSON instead of XML (Faster, easier) +- WDIcache function now allows users to update the locally stored database of available WDI series +- Fixed doc examples +- Documentation now uses roxygen2 +- Moved development to github +- Series and country info now in a single data list. utf-8 encoding fixed diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..c1f006a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,141 @@ +# World Bank data in `R` + +The `WDI` package allows users to search and download data from over 40 datasets hosted by the World Bank, including the World Development Indicators ('WDI'), International Debt Statistics, Doing Business, Human Capital Index, and Sub-national Poverty indicators. + + + +![CRAN downloads](http://cranlogs.r-pkg.org/badges/grand-total/WDI) +[![AppVeyor build status](https://ci.appveyor.com/api/projects/status/github/vincentarelbundock/WDI?branch=master&svg=true)](https://ci.appveyor.com/project/vincentarelbundock/WDI) +[![R build status](https://github.com/vincentarelbundock/WDI/workflows/R-CMD-check/badge.svg)](https://github.com/vincentarelbundock/WDI/actions) + + + +## Installation + +`WDI` is published on CRAN and so can be installed by simply typing this in the `R` console: + +```r +install.packages('WDI') +``` + +To install the development version of the package, use `remotes`: + +```r +library(remotes) +install_github('vincentarelbundock/WDI') +``` + +## Searching for data + +You can search for data by using keywords in `WDIsearch`. For instance, if you are looking for data on Gross Domestic Product: + +```r +WDIsearch('gdp') +``` + +Which produces this: + +```r +> WDIsearch('gdp')[1:10,] + indicator name + [1,] "BG.GSR.NFSV.GD.ZS" "Trade in services (% of GDP)" + [2,] "BM.KLT.DINV.GD.ZS" "Foreign direct investment, net outflows (% of GDP)" + [3,] "BN.CAB.XOKA.GD.ZS" "Current account balance (% of GDP)" + [4,] "BN.CUR.GDPM.ZS" "Current account balance excluding net official capital grants (% of GDP)" + [5,] "BN.GSR.FCTY.CD.ZS" "Net income (% of GDP)" + [6,] "BN.KLT.DINV.CD.ZS" "Foreign direct investment (% of GDP)" + [7,] "BN.KLT.PRVT.GD.ZS" "Private capital flows, total (% of GDP)" + [8,] "BN.TRF.CURR.CD.ZS" "Net current transfers (% of GDP)" + [9,] "BNCABFUNDCD_" "Current Account Balance, %GDP" +[10,] "BX.KLT.DINV.WD.GD.ZS" "Foreign direct investment, net inflows (% of GDP)" +``` + +`WDIsearch` uses grep and ignores cases, so you can also use regular expressions. For instance, if you are looking for GDP per capita in constant dollars: + +```r +WDIsearch('gdp.*capita.*constant') + indicator name +[1,] "GDPPCKD" "GDP per Capita, constant US$, millions" +[2,] "NY.GDP.PCAP.KD" "GDP per capita (constant 2000 US$)" +[3,] "NY.GDP.PCAP.KN" "GDP per capita (constant LCU)" +[4,] "NY.GDP.PCAP.PP.KD" "GDP per capita, PPP (constant 2005 international $)" +``` + +## Download and use the data + +Download a series you like for the countries you like: + +```r +dat = WDI(indicator='NY.GDP.PCAP.KD', country=c('MX','CA','US'), start=1960, end=2012) +``` + +Look at the data: + +```r +head(dat) + iso2c country NY.GDP.PCAP.KD year +1 CA Canada 9374.883 1960 +2 CA Canada 9479.824 1961 +3 CA Canada 9967.366 1962 +4 CA Canada 10290.362 1963 +5 CA Canada 10774.653 1964 +6 CA Canada 11283.606 1965 +``` + +Plot the data: + +```r +library(ggplot2) +ggplot(dat, aes(year, NY.GDP.PCAP.KD, color=country)) + geom_line() + + xlab('Year') + ylab('GDP per capita') +``` + +![GDP per capita in North America](https://raw.githubusercontent.com/vincentarelbundock/WDI/main/web/gdp_per_capita.jpg) + +Note: You can use `country='all'` to download data for all available countries. You can also feed a vector of indicator strings if you want to download multiple indicators at once. + +## Monthly or quarterly data + +Some World Bank series are available at the monthly or quarterly frequency. You can download those simply using the `start` and `end` arguments: + +```r +WDI(indicator = 'DPANUSSPB', country = 'CHN', start = '2012M01', end = '2012M05') + + iso2c country DPANUSSPB year +1 CHN China 6.324130 2012M05 +2 CHN China 6.303810 2012M04 +3 CHN China 6.313545 2012M03 +4 CHN China 6.300286 2012M02 +5 CHN China 6.313091 2012M01 +``` + +## Automatic rename + +If the vector that you supply to `WDI` is named, the function will automatically rename columns where possible. + +```r +dat <- WDI(indicator = c("gdp_per_capita" = "NY.GDP.PCAP.KD", + "population" = "SP.POP.TOTL")) +head(dat) +iso2c country year gdp_per_capita population +1 1A Arab World 2005 5378.379 316264728 +2 1A Arab World 2006 5594.899 323773264 +3 1A Arab World 2007 5711.663 331653797 +4 1A Arab World 2008 5898.516 339825483 +5 1A Arab World 2009 5782.422 348145094 +6 1A Arab World 2010 5916.330 356508908 +``` + +## Updating series list + +To speed up search, `WDI` ships with a local list of all available WDI series. This list will be updated semi-regularly, but you may still want to update it manually to get access to the very latest data series. To do so, use the `cache` function: + +```r +new_cache = WDIcache() +WDIsearch('gdp', cache=new_cache) +``` + +## Bugs, suggestions, etc. + +Thanks for using `WDI`! Please send all bug reports and suggestions through the github issue tracker or by email to [vincent.arel-bundock@umontreal.ca](mailto:vincent.arel-bundock@umontreal.ca) + diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 0000000..115ca26 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,12 @@ +* [Home](/) +* [Changelog](NEWS.md) +* Reference + - [languages_supported](man/languages_supported) + - [WDI_data](man/WDI_data) + - [WDI-package](man/WDI-package) + - [wdi](man/wdi.dl) + - [WDI](man/WDI) + - [wdi](man/wdi.query) + - [WDIbulk](man/WDIbulk) + - [WDIcache](man/WDIcache) + - [WDIsearch](man/WDIsearch) diff --git a/docs/docsify.html b/docs/docsify.html new file mode 100644 index 0000000..1d99413 --- /dev/null +++ b/docs/docsify.html @@ -0,0 +1,45 @@ + + + + + + + + + + + +
+ + + + + + + diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..364b37e --- /dev/null +++ b/docs/index.html @@ -0,0 +1,44 @@ + + + + + + + + + + + +
+ + + + + + + diff --git a/docs/man/WDI-package.md b/docs/man/WDI-package.md new file mode 100644 index 0000000..b19282e --- /dev/null +++ b/docs/man/WDI-package.md @@ -0,0 +1,29 @@ + +# WDI-package + +Search, extract, and format data from the World Bank + +## Description + +Search, extract and format data from the World Bank’s World Development +Indicators + +## Details + +The WDI function provides convenient access to over 40 +databases hosted by the World Bank, including the World Development +Indicators (WDI), International Debt Statistics, Doing Business, Human +Capital Index, and Sub-national poverty indicators. For fast searching, +the WDI package ships with a local list of available data series. This +local list can be updated to the latest version using the +WDIcache function. + +## Author(s) + +Vincent Arel-Bundock +vincent.arel-bundock@umontreal.ca + +## References + +http://arelbundock.com +https://github.com/vincentarelbundock/WDI diff --git a/docs/man/WDI.md b/docs/man/WDI.md new file mode 100644 index 0000000..01ab658 --- /dev/null +++ b/docs/man/WDI.md @@ -0,0 +1,181 @@ + +# WDI + +WDI: World Development Indicators (World Bank) + +## Description + +Downloads the requested data by using the World Bank’s API, parses the +resulting XML file, and formats it in long country-year format. + +## Usage + +
WDI(
+  country = "all",
+  indicator = "NY.GDP.PCAP.KD",
+  start = 1960,
+  end = NULL,
+  extra = FALSE,
+  cache = NULL,
+  latest = NULL,
+  language = "en"
+)
+
+ +## Arguments + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+country + +Vector of countries (ISO-2 character codes, e.g. "BR", "US", "CA") for +which the data is needed. Using the string "all" instead of individual +iso codes pulls data for every available country. +
+indicator + +Character vector of indicators codes. See the WDIsearch() function. If +you supply a named vector, the indicators will be automatically renamed: +‘c(’women_private_sector’ = ‘BI.PWK.PRVS.FE.ZS’)’ +
+start + +Start date, usually a year in integer format. Must be 1960 or greater. +
+end + +End date, usually a year in integer format. Must be greater than the +‘start’ argument. If ‘NULL’, the end date is set to 5 years in the +future. +
+extra + +TRUE returns extra variables such as region, iso3c code, and +incomeLevel. See Details. +
+cache + +NULL (optional) a list created by WDIcache() to be used with the +extra=TRUE argument. +
+latest + +Integer indicating the number of most recent non-NA values to get. +Default is NULL. If specified, it overrides the start and end dates. +
+language + +ISO-2 code in lower case indicating in which language the characters +should be provided. List of languages available with +‘WDI::languages_supported()’. Default is English. +
+ +## Details + +It is possible to only specify the ‘indicator’ and the ‘country’ +arguments, in which case ‘WDI()’ will return data from 1960 to the last +year available on World Bank’s website. It is also possible to get only +the most recent non-NA values, with ‘latest’. + +If ‘extra = TRUE’, additional variables are provided: + + + +## Value + +Data frame with country-year observations. You can extract a data.frame +with indicator names and descriptive labels by inspecting the ‘label’ +attribute of the resulting data.frame: ‘attr(dat, ’label’)’ + +## Author(s) + +Vincent Arel-Bundock +vincent.arel-bundock@umontreal.ca + +## Examples + +``` r +library(WDI) + + + +WDI(country="all", indicator=c("AG.AGR.TRAC.NO","TM.TAX.TCOM.BC.ZS"), + start=1990, end=2000) +WDI(country=c("US","BR"), indicator="NY.GNS.ICTR.GN.ZS", start=1999, end=2000, + extra=TRUE, cache=NULL) + +# Rename indicators on the fly +WDI(country = 'CA', indicator = c('women_private_sector' = 'BI.PWK.PRVS.FE.ZS', + 'women_public_sector' = 'BI.PWK.PUBS.FE.ZS')) + +# Get the 5 latest non-NA values +WDI(country=c("US","BR"), indicator="NY.GNS.ICTR.GN.ZS", latest = 5) +``` diff --git a/docs/man/WDI_data.md b/docs/man/WDI_data.md new file mode 100644 index 0000000..834842b --- /dev/null +++ b/docs/man/WDI_data.md @@ -0,0 +1,103 @@ + +# WDI_data + +World Development Indicators series and country information + +## Description + +A list of two character matrices. + +## Usage + +
WDI_data
+
+ +## Format + +List of 2 data frames + +## Details + +The first character matrix includes a full list of WDI series. This list +is updated semi-regularly. Users can refresh the list manually using the +‘WDIcache()’ function and search in the updated list using the ‘cache’ +argument. + + + +The second character matrix includes extra country information (updated +2012-06-18): + + diff --git a/docs/man/WDIbulk.md b/docs/man/WDIbulk.md new file mode 100644 index 0000000..21ca2cf --- /dev/null +++ b/docs/man/WDIbulk.md @@ -0,0 +1,38 @@ + +# WDIbulk + +Download all the WDI indicators at once. + +## Description + +Download all the WDI indicators at once. + +## Usage + +
WDIbulk(timeout = 600)
+
+ +## Arguments + + + + + + +
+timeout + +integer maximum number of seconds to wait for download +
+ +## Value + +Data frame + +a list of 6 data frames: Data, Country, Series, Country-Series, +Series-Time, FootNote + +## Author(s) + +Vincent Arel-Bundock +vincent.arel-bundock@umontreal.ca diff --git a/docs/man/WDIcache.md b/docs/man/WDIcache.md new file mode 100644 index 0000000..7cf7509 --- /dev/null +++ b/docs/man/WDIcache.md @@ -0,0 +1,27 @@ + +# WDIcache + +Update the list of available WDI indicators + +## Description + +Download an updated list of available WDI indicators from the World Bank +website. Returns a list for use in the WDIsearch function. + +## Usage + +
WDIcache()
+
+ +## Value + +Series of indicators, sources and descriptions in two lists list + +## Note + +Downloading all series information from the World Bank website can take +time. The WDI package ships with a local data object with +information on all the series available on 2012-06-18. You can update +this database by retrieving a new list using WDIcache, and +then feeding the resulting object to WDIsearch via the +cache argument. diff --git a/docs/man/WDIsearch.md b/docs/man/WDIsearch.md new file mode 100644 index 0000000..c741153 --- /dev/null +++ b/docs/man/WDIsearch.md @@ -0,0 +1,69 @@ + +# WDIsearch + +Search names and descriptions of available WDI series + +## Description + +Data frame with series code, name, description, and source for the WDI +series which match the given criteria + +## Usage + +
WDIsearch(string = "gdp", field = "name", short = TRUE, cache = NULL)
+
+ +## Arguments + + + + + + + + + + + + + + + + + + +
+string + +Character string. Search for this string using grep with +ignore.case=TRUE. +
+field + +Character string. Search this field. Admissible fields: ‘indicator’, +‘name’, ‘description’, ‘sourceDatabase’, ‘sourceOrganization’ +
+short + +TRUE: Returns only the indicator’s code and name. FALSE: Returns the +indicator’s code, name, description, and source. +
+cache + +Data list generated by the WDIcache function. If omitted, +WDIsearch will search a local list of series. +
+ +## Value + +Data frame with code, name, source, and description of all series which +match the criteria. + +## Examples + +``` r +library(WDI) + +WDIsearch(string='gdp', field='name', cache=NULL) +WDIsearch(string='AG.AGR.TRAC.NO', field='indicator', cache=NULL) +``` diff --git a/docs/man/languages_supported.md b/docs/man/languages_supported.md new file mode 100644 index 0000000..3ea7f4e --- /dev/null +++ b/docs/man/languages_supported.md @@ -0,0 +1,27 @@ + +# languages_supported + +List of supported languages + +## Description + +This prints two lists of languages, the fully supported ones and the +locally supported ones: \* the languages in the category "fully" will +return translated names and other info for all countries. \* the +languages in the category "partially" will return translated names and +other info only for the country they represent. + +## Usage + +
languages_supported()
+
+ +## Details + +For example, choosing "vi" (for Vietnamese) will translate "Vietnam" in +the dataset but other country names won’t be translated and will be +empty. + +## Value + +A list of fully and partially supported languages. diff --git a/docs/man/wdi.dl.md b/docs/man/wdi.dl.md new file mode 100644 index 0000000..05b2f3f --- /dev/null +++ b/docs/man/wdi.dl.md @@ -0,0 +1,21 @@ + +# wdi.dl + +Internal function to download data + +## Description + +Internal function to download data + +## Usage + +
wdi.dl(
+  indicator,
+  country,
+  start,
+  end,
+  latest = NULL,
+  language = "en",
+  extra = FALSE
+)
+
diff --git a/docs/man/wdi.query.md b/docs/man/wdi.query.md new file mode 100644 index 0000000..d50d825 --- /dev/null +++ b/docs/man/wdi.query.md @@ -0,0 +1,20 @@ + +# wdi.query + +Internal function to build API call + +## Description + +Internal function to build API call + +## Usage + +
wdi.query(
+  indicator = "NY.GDP.PCAP.CD",
+  country = "all",
+  start = NULL,
+  end = NULL,
+  latest = NULL,
+  language = "en"
+)
+