From 2d3fe0a8b35dcd02b3417f264ef3ec1d4a8a10ae Mon Sep 17 00:00:00 2001 From: Christoph Scheuch <19249734+christophscheuch@users.noreply.github.com> Date: Tue, 19 Nov 2024 14:40:56 +0100 Subject: [PATCH 1/4] Update DESCRIPTION --- DESCRIPTION | 36 ++++++++++++++++-------------------- 1 file changed, 16 insertions(+), 20 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 3be892b..4d3a4ae 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -3,16 +3,19 @@ Package: wbwdi Title: Work seamlessly with World Bank World Development Indicators (WDI) Version: 0.1.0 Authors@R: c( - person("Christoph", "Scheuch", , "christophh@tidy-intelligence.com", role = c("aut", "cre", "cph"), - comment = c(ORCID = "0009-0004-0423-6819")) - ) -Description: A modern, flexible interface for accessing the World Bank’s World Development Indicators - (WDI) API . - 'wbwdi' allows users to download, process, and analyze WDI indicators for multiple geographies and specific time periods. - The package is designed to work seamlessly with International Debt Statistics (IDS) provided through the 'wbids' package. + person("Christoph", "Scheuch", , "christophh@tidy-intelligence.com", + role = c("aut", "cre", "cph"), + comment = c(ORCID = "0009-0004-0423-6819")) + ) +Description: Access and analyze the World Bank’s World Development Indicators + (WDI) using the corresponding API . + WDI provides more than 24,000 country or region-level indicators for various + contexts. 'wbwdi' enables users to download, process and work with WDI + series across multiple geographies and time periods. License: MIT + file LICENSE -URL: https://github.com/tidy-intelligence/r-wbwdi -BugReports: https://github.com/tidy-intelligence/r-wbwdi/issues +Encoding: UTF-8 +Roxygen: list(markdown = TRUE) +RoxygenNote: 7.3.2 Depends: R (>= 4.1) Imports: @@ -27,15 +30,8 @@ Suggests: curl, knitr, rmarkdown, - testthat (>= 3.2.0) + testthat (>= 3.0.0) Config/testthat/edition: 3 -Encoding: UTF-8 -LazyData: true -Roxygen: list(markdown = TRUE) -RoxygenNote: 7.3.2 -VignetteBuilder: - knitr -Remotes: - r-lib/devtools, - r-lib/lintr, - REditorSupport/languageserver +URL: https://github.com/tidy-intelligence/r-wbwdi +BugReports: https://github.com/tidy-intelligence/r-wbwdi/issues +VignetteBuilder: knitr From 91772d09c51c8f51f9be0938a70cecbb7e322e59 Mon Sep 17 00:00:00 2001 From: Christoph Scheuch <19249734+christophscheuch@users.noreply.github.com> Date: Tue, 19 Nov 2024 14:41:03 +0100 Subject: [PATCH 2/4] Update README --- README.Rmd | 14 ++++++++------ README.md | 43 ++++++++++++++++++++++++------------------- 2 files changed, 32 insertions(+), 25 deletions(-) diff --git a/README.Rmd b/README.Rmd index 29fc9a2..572ef90 100644 --- a/README.Rmd +++ b/README.Rmd @@ -20,13 +20,15 @@ knitr::opts_chunk$set( ) ``` -The goal of 'wbwdi' is to provide a modern, flexible interface for accessing the World Bank’s [World Development Indicators (WDI) API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation) through R. 'wbwdi' allows users to download, process, and analyze WDI indicators for multiple geographies and specific time periods. The package is designed to work seamlessly with International Debt Statistics (IDS) provided through the 'wbids' package and the Python library ['wbwdi'](https://github.com/tidy-intelligence/py-wbwdi). +`wbwdi` is an R package to access and analyze the World Bank’s World Development Indicators (WDI) using the corresponding [API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation). WDI provides more than 24,000 country or region-level indicators for various contexts. `wbwdi` enables users to download, process and work with WDI series across multiple geographies and time periods. + +The package is designed to work seamlessly with International Debt Statistics (IDS) provided through the [`wbids`](https://github.com/Teal-Insights/r-wbids) package and shares its syntax with the Python library ['py-wbwdi'](https://github.com/tidy-intelligence/py-wbwdi). This package is a product of Christoph Scheuch and not sponsored by or affiliated with the World Bank in any way, except for the use of the World Bank WDI API. ## Installation -You can install the development version of 'wbwdi' like this: +You can install the development version of `wbwdi` like this: ``` r pak::pak("tidy-intelligence/r-wbwdi") @@ -100,10 +102,10 @@ wdi_search( ## Relation to existing packages -The most important difference to existing packages is that 'wbwdi' is designed to (i) have a narrow focus on World Bank Development Indicators, (ii) have a consistent interface with other R packages (e.g., 'wbids'), and (iii) have a shared interface with Python libraries (e.g. ['py-wbwdi'](https://github.com/tidy-intelligence/py-wbwdi)). 'wbwdi' also refrains from using cached data because this approach frequently leads to problems for users to to outdated caches and uses 'httr2' to manage API requests. +The most important difference to existing packages is that `wbwdi` is designed to (i) have a narrow focus on World Bank Development Indicators, (ii) have a consistent interface with other R packages (e.g., `wbids`), and (iii) have a shared interface with Python libraries (e.g. ['py-wbwdi'](https://github.com/tidy-intelligence/py-wbwdi)). `wbwdi` also refrains from using cached data because this approach frequently leads to problems for users to to outdated caches and uses `httr2` to manage API requests. The relation to the most popular existing R packages are: -- [WDI](https://cran.r-project.org/web/packages/WDI/index.html): uses cached data by default, does not allow downloading meta data from the WDI API (e.g., languages, sources, topics), does neither use 'httr' nor 'httr2'. -- [worldbank](https://cran.r-project.org/web/packages/worldbank/index.html): does not have a narrow focus because it includes the Poverty and Inequality Platform and Finances One API. -- [wbstats](https://cran.r-project.org/web/packages/wbstats/index.html): uses cached data by default, does not use 'httr2'. +- [`WDI`](https://cran.r-project.org/web/packages/WDI/index.html): uses cached data by default, does not allow downloading meta data from the WDI API (e.g., languages, sources, topics), does neither use 'httr' nor `httr2`. +- [`worldbank`](https://cran.r-project.org/web/packages/worldbank/index.html): only allows the download of a single indicator with each function call and does not have a narrow focus because it includes the Poverty and Inequality Platform and Finances One API. +- [`wbstats`](https://cran.r-project.org/web/packages/wbstats/index.html): uses cached data by default, does not use `httr2`. diff --git a/README.md b/README.md index 5c6d2e8..85eae55 100644 --- a/README.md +++ b/README.md @@ -12,14 +12,18 @@ coverage](https://codecov.io/gh/tidy-intelligence/r-wbwdi/graph/badge.svg)](http -The goal of ‘wbwdi’ is to provide a modern, flexible interface for -accessing the World Bank’s [World Development Indicators (WDI) -API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation) -through R. ‘wbwdi’ allows users to download, process, and analyze WDI -indicators for multiple geographies and specific time periods. The -package is designed to work seamlessly with International Debt -Statistics (IDS) provided through the ‘wbids’ package and the Python -library [‘wbwdi’](https://github.com/tidy-intelligence/py-wbwdi). +`wbwdi` is an R package to access and analyze the World Bank’s World +Development Indicators (WDI) using the corresponding +[API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation). +WDI provides more than 24,000 country or region-level indicators for +various contexts. `wbwdi` enables users to download, process and work +with WDI series across multiple geographies and time periods. + +The package is designed to work seamlessly with International Debt +Statistics (IDS) provided through the +[`wbids`](https://github.com/Teal-Insights/r-wbids) package and shares +its syntax with the Python library +[‘py-wbwdi’](https://github.com/tidy-intelligence/py-wbwdi). This package is a product of Christoph Scheuch and not sponsored by or affiliated with the World Bank in any way, except for the use of the @@ -27,7 +31,7 @@ World Bank WDI API. ## Installation -You can install the development version of ‘wbwdi’ like this: +You can install the development version of `wbwdi` like this: ``` r pak::pak("tidy-intelligence/r-wbwdi") @@ -108,23 +112,24 @@ wdi_search( ## Relation to existing packages -The most important difference to existing packages is that ‘wbwdi’ is +The most important difference to existing packages is that `wbwdi` is designed to (i) have a narrow focus on World Bank Development Indicators, (ii) have a consistent interface with other R packages -(e.g., ‘wbids’), and (iii) have a shared interface with Python libraries +(e.g., `wbids`), and (iii) have a shared interface with Python libraries (e.g. [‘py-wbwdi’](https://github.com/tidy-intelligence/py-wbwdi)). -‘wbwdi’ also refrains from using cached data because this approach +`wbwdi` also refrains from using cached data because this approach frequently leads to problems for users to to outdated caches and uses -‘httr2’ to manage API requests. +`httr2` to manage API requests. The relation to the most popular existing R packages are: -- [WDI](https://cran.r-project.org/web/packages/WDI/index.html): uses +- [`WDI`](https://cran.r-project.org/web/packages/WDI/index.html): uses cached data by default, does not allow downloading meta data from the WDI API (e.g., languages, sources, topics), does neither use ‘httr’ - nor ‘httr2’. -- [worldbank](https://cran.r-project.org/web/packages/worldbank/index.html): - does not have a narrow focus because it includes the Poverty and + nor `httr2`. +- [`worldbank`](https://cran.r-project.org/web/packages/worldbank/index.html): + only allows the download of a single indicator with each function call + and does not have a narrow focus because it includes the Poverty and Inequality Platform and Finances One API. -- [wbstats](https://cran.r-project.org/web/packages/wbstats/index.html): - uses cached data by default, does not use ‘httr2’. +- [`wbstats`](https://cran.r-project.org/web/packages/wbstats/index.html): + uses cached data by default, does not use `httr2`. From 675c158589be5420833ca8b3a4c325910473b6db Mon Sep 17 00:00:00 2001 From: Christoph Scheuch <19249734+christophscheuch@users.noreply.github.com> Date: Tue, 19 Nov 2024 14:41:17 +0100 Subject: [PATCH 3/4] Update vignettes/using-wbwdi --- vignettes/using-wbwdi.Rmd | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/vignettes/using-wbwdi.Rmd b/vignettes/using-wbwdi.Rmd index 6cafd6f..e070b1e 100644 --- a/vignettes/using-wbwdi.Rmd +++ b/vignettes/using-wbwdi.Rmd @@ -20,15 +20,7 @@ library(wbwdi) The `wbwdi` package provides a modern and flexible interface for accessing the World Bank’s [World Development Indicators (WDI)](https://datatopics.worldbank.org/world-development-indicators/). With `wbwdi`, you can download data for multiple indicators and geographies in a single function call, benefit from progress bars, and receive the output in a tidy data format, making it ideal for further analysis with other data sources. -## Installation - -To install the development version of `wbwdi`, use: - -```{r eval=FALSE} -pak::pak("tidy-intelligence/r-wbwdi") -``` - -## Listing supported indicators +## Listing Supported Indicators The `wbwdi` package allows you to retrieve a full list of all supported indicators from the World Bank [Indicators API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation). Each indicator is accompanied by metadata such as its unit of measurement, source, and associated topics. @@ -48,11 +40,11 @@ To get the list of languages supported by the API, call: wdi_get_languages() ``` -Note that not all indicators might be translated into all languages. +Note that not all indicators and their columns might be translated into all languages. -## Listing supported geographies +## Listing Supported Geographies -You can retrieve a list of all geographies supported by the World Bank API along with metadata such as region, administrative region, income level, and lending type. +You can retrieve a list of all geographies supported by the World Bank API along with metadata such as region, administrative region, income level, and lending type. Note that a geography might be a country or a region, hence the more general table name. ```{r} wdi_get_geographies() @@ -64,7 +56,7 @@ This information can also be requested in other languages. For example, to view wdi_get_geographies(language = "zh") ``` -### Downloading indicator data +### Downloading Indicator Data With `wbwdi`, you can download indicator data for multiple geographies and indicators in a single function call. The function returns a tidy data frame with country, indicator, date, and value columns. @@ -86,7 +78,17 @@ wdi_get( ) ``` -## Other helper functions +If you want to retrieve the indicators in a wide format, you can use the corresponding parameter. + +```{r} +wdi_get( + geographies = "US", + indicators = c("NY.GDP.PCAP.KD", "SP.POP.TOTL"), + format = "wide" +) +``` + +## Other Helper Functions You can fetch a list of all supported regions, sources, topics and lending types, respectively, using the corresponding helper function: @@ -97,7 +99,7 @@ wdi_get_topics() wdi_get_lending_types() ``` -If you want to search for specific keywords among indicators or other data sources, you can use the RStudio or Positron data explorer. Alternatively, this package comes with a helper function: +If you want to search for specific keywords among indicators or other data sources, you can use the built-in RStudio data frame viewing functionality or the [Positron Data Explorer](https://positron.posit.co/data-explorer.html). Alternatively, this package comes with a helper function: ```{r} indicators <- wdi_get_indicators() From 3b932cfbf248ad63620ced4a44c8273903385225 Mon Sep 17 00:00:00 2001 From: Christoph Scheuch <19249734+christophscheuch@users.noreply.github.com> Date: Tue, 19 Nov 2024 14:59:38 +0100 Subject: [PATCH 4/4] Add pkgdown workflow --- .Rbuildignore | 3 +++ .github/workflows/pkgdown.yaml | 49 ++++++++++++++++++++++++++++++++++ .gitignore | 1 + DESCRIPTION | 2 +- README.Rmd | 4 +-- _pkgdown.yml | 4 +++ renv.lock | 4 +-- vignettes/data-model.Rmd | 2 +- 8 files changed, 63 insertions(+), 6 deletions(-) create mode 100644 .github/workflows/pkgdown.yaml create mode 100644 _pkgdown.yml diff --git a/.Rbuildignore b/.Rbuildignore index 32e998b..9c115f7 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -12,3 +12,6 @@ ^\.github$ ^.lintr$ ^vignettes/*_files$ +^_pkgdown\.yml$ +^docs$ +^pkgdown$ diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml new file mode 100644 index 0000000..bfc9f4d --- /dev/null +++ b/.github/workflows/pkgdown.yaml @@ -0,0 +1,49 @@ +# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples +# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help +on: + push: + branches: [main, master] + pull_request: + release: + types: [published] + workflow_dispatch: + +name: pkgdown.yaml + +permissions: read-all + +jobs: + pkgdown: + runs-on: ubuntu-latest + # Only restrict concurrency for non-PR jobs + concurrency: + group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + permissions: + contents: write + steps: + - uses: actions/checkout@v4 + + - uses: r-lib/actions/setup-pandoc@v2 + + - uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + + - uses: r-lib/actions/setup-r-dependencies@v2 + with: + extra-packages: any::pkgdown, local::. + needs: website + + - name: Build site + run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) + shell: Rscript {0} + + - name: Deploy to GitHub pages 🚀 + if: github.event_name != 'pull_request' + uses: JamesIves/github-pages-deploy-action@v4.5.0 + with: + clean: false + branch: gh-pages + folder: docs diff --git a/.gitignore b/.gitignore index 7a7155e..0691ddd 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ inst/doc /doc/ /Meta/ +docs diff --git a/DESCRIPTION b/DESCRIPTION index 4d3a4ae..987e371 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -32,6 +32,6 @@ Suggests: rmarkdown, testthat (>= 3.0.0) Config/testthat/edition: 3 -URL: https://github.com/tidy-intelligence/r-wbwdi +URL: https://github.com/tidy-intelligence/r-wbwdi, https://tidy-intelligence.github.io/r-wbwdi/ BugReports: https://github.com/tidy-intelligence/r-wbwdi/issues VignetteBuilder: knitr diff --git a/README.Rmd b/README.Rmd index 572ef90..c493a6a 100644 --- a/README.Rmd +++ b/README.Rmd @@ -22,7 +22,7 @@ knitr::opts_chunk$set( `wbwdi` is an R package to access and analyze the World Bank’s World Development Indicators (WDI) using the corresponding [API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation). WDI provides more than 24,000 country or region-level indicators for various contexts. `wbwdi` enables users to download, process and work with WDI series across multiple geographies and time periods. -The package is designed to work seamlessly with International Debt Statistics (IDS) provided through the [`wbids`](https://github.com/Teal-Insights/r-wbids) package and shares its syntax with the Python library ['py-wbwdi'](https://github.com/tidy-intelligence/py-wbwdi). +The package is designed to work seamlessly with International Debt Statistics (IDS) provided through the [`wbids`](https://github.com/Teal-Insights/r-wbids) package and shares its syntax with its sibling Python library [`wbwdi`](https://github.com/tidy-intelligence/py-wbwdi). This package is a product of Christoph Scheuch and not sponsored by or affiliated with the World Bank in any way, except for the use of the World Bank WDI API. @@ -102,7 +102,7 @@ wdi_search( ## Relation to existing packages -The most important difference to existing packages is that `wbwdi` is designed to (i) have a narrow focus on World Bank Development Indicators, (ii) have a consistent interface with other R packages (e.g., `wbids`), and (iii) have a shared interface with Python libraries (e.g. ['py-wbwdi'](https://github.com/tidy-intelligence/py-wbwdi)). `wbwdi` also refrains from using cached data because this approach frequently leads to problems for users to to outdated caches and uses `httr2` to manage API requests. +The most important difference to existing packages is that `wbwdi` is designed to (i) have a narrow focus on World Bank Development Indicators, (ii) have a consistent interface with other R packages (e.g., `wbids`), and (iii) have a shared interface with Python libraries (e.g., [`wbwdi`](https://github.com/tidy-intelligence/py-wbwdi)). `wbwdi` also refrains from using cached data because this approach frequently leads to problems for users to to outdated caches and uses `httr2` to manage API requests. The relation to the most popular existing R packages are: diff --git a/_pkgdown.yml b/_pkgdown.yml new file mode 100644 index 0000000..aed54f2 --- /dev/null +++ b/_pkgdown.yml @@ -0,0 +1,4 @@ +url: https://tidy-intelligence.github.io/r-wbwdi/ +template: + bootstrap: 5 + diff --git a/renv.lock b/renv.lock index 909106e..a351775 100644 --- a/renv.lock +++ b/renv.lock @@ -52,13 +52,13 @@ }, "curl": { "Package": "curl", - "Version": "6.0.0", + "Version": "6.0.1", "Source": "Repository", "Repository": "CRAN", "Requirements": [ "R" ], - "Hash": "ff51697d9205fe715f29e7171e874c6e" + "Hash": "e8ba62486230951fcd2b881c5be23f96" }, "dplyr": { "Package": "dplyr", diff --git a/vignettes/data-model.Rmd b/vignettes/data-model.Rmd index f5f8101..487f002 100644 --- a/vignettes/data-model.Rmd +++ b/vignettes/data-model.Rmd @@ -11,7 +11,7 @@ vignette: > The diagram below shows the data model of the `wbwdi` package. In our design, we primarily have R users in mind, particularly those who rely heavily on the popular data manipulation packages `dplyr` and `data.table`. For these users, having consistent and descriptive primary key column names across different tables (e.g., `geography_id`, `series_id`) simplifies writing joins across tables, reduces the risk of column name conflicts, and avoids ambiguity. -```{r, out.width = "100%", echo=FALSE} +```{r, out.width = "100%", echo=FALSE, fig.alt = "A visual representation of the data model behind the 'wbwdi' R package."} knitr::include_graphics("images/data-model.png") ```