diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..511a1a6 --- /dev/null +++ b/.env.example @@ -0,0 +1 @@ +NASA_API_KEY = diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..eab0fd0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,43 @@ +--- +name: Bug Report +about: Use to report a bug +title: '' +labels: bug +assignees: '' +--- + +## Bug Report + +### Description + +Provide a brief overview of the bug encountered. Describe the behavior observed when the bug occurs and explain the behavior expected when the bug is not present. + +### Reproducibility + +- [ ] The bug is reproducible. +- [ ] The bug is intermittent. +- [ ] The bug occurs only under specific conditions. + +#### Steps to Reproduce + +1. List the steps to reproduce the bug. +2. Be as detailed as possible to help with replication. + +#### Screenshots / Error Messages (if applicable) + +Insert any relevant screenshots or error messages related to the bug. + +#### Environment + +- **Operating System**: [e.g., Windows 10, macOS, Linux] +- **Browser (if applicable)**: [e.g., Google Chrome, Firefox, Safari] +- **Application Version/Commit**: [e.g., v1.2.3, Git commit hash] +- **Additional Environment Details**: [e.g., hardware specifications, network conditions] + +### Additional Context + +Provide any additional context or information about the bug. + +### Possible Fix + +If you have suggestions for a fix, please describe them here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..bbcbbe7 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,20 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: '' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/peer_review.md b/.github/ISSUE_TEMPLATE/peer_review.md new file mode 100644 index 0000000..251d8a1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/peer_review.md @@ -0,0 +1,42 @@ +--- +name: Peer Review +about: Use to submit a peer review +title: '' +labels: review +assignees: '' +--- + +## Peer Review for Reproducibility Checks + +### Review Checklist + +Please review the following aspects related to reproducibility checks: + +- [ ] **Environment Setup**: + - [ ] Were detailed instructions provided for setting up the development environment? + - [ ] Are all necessary dependencies and libraries clearly documented? +- [ ] **Data Preparation**: + - [ ] Are source data files and preprocessing steps clearly documented? + - [ ] Are scripts or commands for data transformation included and well-documented? +- [ ] **Code Execution**: + - [ ] Were clear instructions provided for running the code? + - [ ] Does the code execute without errors and produce expected outputs? +- [ ] **Configuration Management**: + - [ ] Is version control information (e.g., Git commit hash) included for reproducibility? + - [ ] Are any configuration files or parameters used properly documented? +- [ ] **Results Verification**: + - [ ] Are output results (e.g., metrics, visualizations) included and matched with expected outcomes? + - [ ] Have any discrepancies between expected and actual results been identified and explained? +- [ ] **Documentation**: + - [ ] Is there a detailed README or documentation explaining the experiment setup and execution process? + - [ ] Are code comments and documentation clear and informative? +- [ ] **External Dependencies**: + - [ ] Are any external data sources or APIs used accessible and well-documented? + - [ ] Are external libraries or packages properly cited and versioned for reproducibility? +- [ ] **Validation**: + - [ ] Can an independent reviewer replicate the experiment using the provided instructions? + - [ ] Are the results consistent across different environments or platforms? + +### Additional Comments + +Include any additional comments, concerns, or suggestions related to reproducibility. diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..6a7695c --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,6 @@ +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..72132d3 --- /dev/null +++ b/.github/workflows/gh-pages.yml @@ -0,0 +1,31 @@ +name: Publish to GitHub Pages + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.10" + cache: "pip" + - name: Dependencies + run: | + if [ -f docs/requirements.txt ]; then pip install -r docs/requirements.txt; fi + if [ -f pyproject.toml ]; then pip install ".[docs]"; fi + - name: Build Jupyter Book + run: | + jupyter-book build . --config docs/_config.yml --toc docs/_toc.yml + - name: Deploy + uses: peaceiris/actions-gh-pages@v3 + if: github.ref == 'refs/heads/main' && job.status == 'success' + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./_build/html + enable_jekyll: false diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..e2bd51e --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,93 @@ +name: Publish Python ๐Ÿ distribution ๐Ÿ“ฆ to PyPI and TestPyPI + +on: push + +jobs: + build: + name: Build distribution ๐Ÿ“ฆ + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: "3.x" + - name: Install pypa/build + run: >- + python3 -m + pip install + build + --user + - name: Build a binary wheel and a source tarball + run: python3 -m build + - name: Store the distribution packages + uses: actions/upload-artifact@v3 + with: + name: python-package-distributions + path: dist/ + + publish-to-pypi: + name: >- + Publish Python ๐Ÿ distribution ๐Ÿ“ฆ to PyPI + if: startsWith(github.ref, 'refs/tags/') # only publish to PyPI on tag pushes + needs: + - build + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/p/data-lab-template # Replace with your PyPI project name + permissions: + id-token: write # IMPORTANT: mandatory for trusted publishing + + steps: + - name: Download all the dists + uses: actions/download-artifact@v3 + with: + name: python-package-distributions + path: dist/ + - name: Publish distribution ๐Ÿ“ฆ to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + + github-release: + name: >- + Sign the Python ๐Ÿ distribution ๐Ÿ“ฆ with Sigstore + and upload them to GitHub Release + needs: + - publish-to-pypi + runs-on: ubuntu-latest + + permissions: + contents: write # IMPORTANT: mandatory for making GitHub Releases + id-token: write # IMPORTANT: mandatory for sigstore + + steps: + - name: Download all the dists + uses: actions/download-artifact@v3 + with: + name: python-package-distributions + path: dist/ + - name: Sign the dists with Sigstore + uses: sigstore/gh-action-sigstore-python@v1.2.3 + with: + inputs: >- + ./dist/*.tar.gz + ./dist/*.whl + - name: Create GitHub Release + env: + GITHUB_TOKEN: ${{ github.token }} + run: >- + gh release create + '${{ github.ref_name }}' + --repo '${{ github.repository }}' + --notes "" + - name: Upload artifact signatures to GitHub Release + env: + GITHUB_TOKEN: ${{ github.token }} + # Upload to GitHub Release using the `gh` CLI. + # `dist/` contains the built packages, and the + # sigstore-produced signatures and certificates. + run: >- + gh release upload + '${{ github.ref_name }}' dist/** + --repo '${{ github.repository }}' diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..dd6d4f7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,95 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] + +# C extensions +*.so + +# Distribution / packaging +.Python +env/ +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover + +# Translations +*.mo +*.pot + +# Django stuff: +*.log + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# DotEnv configuration +.env + +# Database +*.db +*.rdb + +# Pycharm +.idea + +# VS Code +.vscode/ + +# Spyder +.spyproject/ + +# Jupyter NB Checkpoints +.ipynb_checkpoints/ + +# Mac OS-specific storage files +.DS_Store + +# vim +*.swp +*.swo + +# Mypy cache +.mypy_cache/ + +# Jupyter Book +_build/ + +# python-dotenv +.env + +# setuptools-scm/ +src/*/_version.py diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..3474f25 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,39 @@ +# See https://pre-commit.com for more information +# See https://pre-commit.com/hooks.html for more hooks +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + - id: check-ast + - id: check-json + - id: detect-aws-credentials + args: [--allow-missing-credentials] + - id: detect-private-key + - repo: https://github.com/igorshubovych/markdownlint-cli + rev: v0.39.0 + hooks: + - id: markdownlint + name: Markdownlint + files: \.(md|mdown|markdown)$ + args: [ + "--disable=MD013", # line-length + "--disable=MD033", # no-inline-html + ] + - repo: https://github.com/codespell-project/codespell + rev: v2.2.6 + hooks: + - id: codespell + name: codespell + description: Checks for common misspellings in text files + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.3.3 + hooks: + - id: ruff + types_or: [python, pyi, jupyter] + args: [--fix] + - id: ruff-format + types_or: [python, pyi, jupyter] diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..54fdd6c --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,11 @@ +cff-version: 1.2.0 +message: "Country borders or names do not necessarily reflect the World Bank Groupโ€™s official position. All maps are for illustrative purposes and do not imply the expression of any opinion on the part of the World Bank, concerning the legal status of any country or territory or concerning the delimitation of frontiers or boundaries." +title: "World Bank Data Lab Project Template" +authors: + - affiliation: World Bank + family-names: Stefanini Vicente + given-names: Gabriel + orcid: https://orcid.org/0000-0001-6530-3780 +keywords: + - Open Science +repository-code: https://github.com/worldbank/template/tree/main diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..ef17e49 --- /dev/null +++ b/LICENSE @@ -0,0 +1,385 @@ +Mozilla Public License Version 2.0 +================================== + +1. Definitions + +-------------- + +1.1. "Contributor" + means each individual or legal entity that creates, contributes to + the creation of, or owns Covered Software. + +1.2. "Contributor Version" + means the combination of the Contributions of others (if any) used + by a Contributor and that particular Contributor's Contribution. + +1.3. "Contribution" + means Covered Software of a particular Contributor. + +1.4. "Covered Software" + means Source Code Form to which the initial Contributor has attached + the notice in Exhibit A, the Executable Form of such Source Code + Form, and Modifications of such Source Code Form, in each case + including portions thereof. + +1.5. "Incompatible With Secondary Licenses" + means + + (a) that the initial Contributor has attached the notice described + in Exhibit B to the Covered Software; or + + (b) that the Covered Software was made available under the terms of + version 1.1 or earlier of the License, but not also under the + terms of a Secondary License. + +1.6. "Executable Form" + means any form of the work other than Source Code Form. + +1.7. "Larger Work" + means a work that combines Covered Software with other material, in + a separate file or files, that is not Covered Software. + +1.8. "License" + means this document. + +1.9. "Licensable" + means having the right to grant, to the maximum extent possible, + whether at the time of the initial grant or subsequently, any and + all of the rights conveyed by this License. + +1.10. "Modifications" + means any of the following: + + (a) any file in Source Code Form that results from an addition to, + deletion from, or modification of the contents of Covered + Software; or + + (b) any new file in Source Code Form that contains any Covered + Software. + +1.11. "Patent Claims" of a Contributor + means any patent claim(s), including without limitation, method, + process, and apparatus claims, in any patent Licensable by such + Contributor that would be infringed, but for the grant of the + License, by the making, using, selling, offering for sale, having + made, import, or transfer of either its Contributions or its + Contributor Version. + +1.12. "Secondary License" + means either the GNU General Public License, Version 2.0, the GNU + Lesser General Public License, Version 2.1, the GNU Affero General + Public License, Version 3.0, or any later versions of those + licenses. + +1.13. "Source Code Form" + means the form of the work preferred for making modifications. + +1.14. "You" (or "Your") + means an individual or a legal entity exercising rights under this + License. For legal entities, "You" includes any entity that + controls, is controlled by, or is under common control with You. For + purposes of this definition, "control" means (a) the power, direct + or indirect, to cause the direction or management of such entity, + whether by contract or otherwise, or (b) ownership of more than + fifty percent (50%) of the outstanding shares or beneficial + ownership of such entity. + +2. License Grants and Conditions + +-------------------------------- + +2.1. Grants + +Each Contributor hereby grants You a world-wide, royalty-free, +non-exclusive license: + +(a) under intellectual property rights (other than patent or trademark) + Licensable by such Contributor to use, reproduce, make available, + modify, display, perform, distribute, and otherwise exploit its + Contributions, either on an unmodified basis, with Modifications, or + as part of a Larger Work; and + +(b) under Patent Claims of such Contributor to make, use, sell, offer + for sale, have made, import, and otherwise transfer either its + Contributions or its Contributor Version. + +2.2. Effective Date + +The licenses granted in Section 2.1 with respect to any Contribution +become effective for each Contribution on the date the Contributor first +distributes such Contribution. + +2.3. Limitations on Grant Scope + +The licenses granted in this Section 2 are the only rights granted under +this License. No additional rights or licenses will be implied from the +distribution or licensing of Covered Software under this License. +Notwithstanding Section 2.1(b) above, no patent license is granted by a +Contributor: + +(a) for any code that a Contributor has removed from Covered Software; + or + +(b) for infringements caused by: (i) Your and any other third party's + modifications of Covered Software, or (ii) the combination of its + Contributions with other software (except as part of its Contributor + Version); or + +(c) under Patent Claims infringed by Covered Software in the absence of + its Contributions. + +This License does not grant any rights in the trademarks, service marks, +or logos of any Contributor (except as may be necessary to comply with +the notice requirements in Section 3.4). + +2.4. Subsequent Licenses + +No Contributor makes additional grants as a result of Your choice to +distribute the Covered Software under a subsequent version of this +License (see Section 10.2) or under the terms of a Secondary License (if +permitted under the terms of Section 3.3). + +2.5. Representation + +Each Contributor represents that the Contributor believes its +Contributions are its original creation(s) or it has sufficient rights +to grant the rights to its Contributions conveyed by this License. + +2.6. Fair Use + +This License is not intended to limit any rights You have under +applicable copyright doctrines of fair use, fair dealing, or other +equivalents. + +2.7. Conditions + +Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted +in Section 2.1. + +3. Responsibilities + +------------------- + +3.1. Distribution of Source Form + +All distribution of Covered Software in Source Code Form, including any +Modifications that You create or to which You contribute, must be under +the terms of this License. You must inform recipients that the Source +Code Form of the Covered Software is governed by the terms of this +License, and how they can obtain a copy of this License. You may not +attempt to alter or restrict the recipients' rights in the Source Code +Form. + +3.2. Distribution of Executable Form + +If You distribute Covered Software in Executable Form then: + +(a) such Covered Software must also be made available in Source Code + Form, as described in Section 3.1, and You must inform recipients of + the Executable Form how they can obtain a copy of such Source Code + Form by reasonable means in a timely manner, at a charge no more + than the cost of distribution to the recipient; and + +(b) You may distribute such Executable Form under the terms of this + License, or sublicense it under different terms, provided that the + license for the Executable Form does not attempt to limit or alter + the recipients' rights in the Source Code Form under this License. + +3.3. Distribution of a Larger Work + +You may create and distribute a Larger Work under terms of Your choice, +provided that You also comply with the requirements of this License for +the Covered Software. If the Larger Work is a combination of Covered +Software with a work governed by one or more Secondary Licenses, and the +Covered Software is not Incompatible With Secondary Licenses, this +License permits You to additionally distribute such Covered Software +under the terms of such Secondary License(s), so that the recipient of +the Larger Work may, at their option, further distribute the Covered +Software under the terms of either this License or such Secondary +License(s). + +3.4. Notices + +You may not remove or alter the substance of any license notices +(including copyright notices, patent notices, disclaimers of warranty, +or limitations of liability) contained within the Source Code Form of +the Covered Software, except that You may alter any license notices to +the extent required to remedy known factual inaccuracies. + +3.5. Application of Additional Terms + +You may choose to offer, and to charge a fee for, warranty, support, +indemnity or liability obligations to one or more recipients of Covered +Software. However, You may do so only on Your own behalf, and not on +behalf of any Contributor. You must make it absolutely clear that any +such warranty, support, indemnity, or liability obligation is offered by +You alone, and You hereby agree to indemnify every Contributor for any +liability incurred by such Contributor as a result of warranty, support, +indemnity or liability terms You offer. You may include additional +disclaimers of warranty and limitations of liability specific to any +jurisdiction. + +4. Inability to Comply Due to Statute or Regulation + +--------------------------------------------------- + +If it is impossible for You to comply with any of the terms of this +License with respect to some or all of the Covered Software due to +statute, judicial order, or regulation then You must: (a) comply with +the terms of this License to the maximum extent possible; and (b) +describe the limitations and the code they affect. Such description must +be placed in a text file included with all distributions of the Covered +Software under this License. Except to the extent prohibited by statute +or regulation, such description must be sufficiently detailed for a +recipient of ordinary skill to be able to understand it. + +5. Termination + +-------------- + +5.1. The rights granted under this License will terminate automatically +if You fail to comply with any of its terms. However, if You become +compliant, then the rights granted under this License from a particular +Contributor are reinstated (a) provisionally, unless and until such +Contributor explicitly and finally terminates Your grants, and (b) on an +ongoing basis, if such Contributor fails to notify You of the +non-compliance by some reasonable means prior to 60 days after You have +come back into compliance. Moreover, Your grants from a particular +Contributor are reinstated on an ongoing basis if such Contributor +notifies You of the non-compliance by some reasonable means, this is the +first time You have received notice of non-compliance with this License +from such Contributor, and You become compliant prior to 30 days after +Your receipt of the notice. + +5.2. If You initiate litigation against any entity by asserting a patent +infringement claim (excluding declaratory judgment actions, +counter-claims, and cross-claims) alleging that a Contributor Version +directly or indirectly infringes any patent, then the rights granted to +You by any and all Contributors for the Covered Software under Section +2.1 of this License shall terminate. + +5.3. In the event of termination under Sections 5.1 or 5.2 above, all +end user license agreements (excluding distributors and resellers) which +have been validly granted by You or Your distributors under this License +prior to termination shall survive termination. + +************************************************************************ + +* * +* 6. Disclaimer of Warranty * +* ------------------------- * +* * +* Covered Software is provided under this License on an "as is" * +* basis, without warranty of any kind, either expressed, implied, or * +* statutory, including, without limitation, warranties that the * +* Covered Software is free of defects, merchantable, fit for a * +* particular purpose or non-infringing. The entire risk as to the * +* quality and performance of the Covered Software is with You. * +* Should any Covered Software prove defective in any respect, You * +* (not any Contributor) assume the cost of any necessary servicing, * +* repair, or correction. This disclaimer of warranty constitutes an * +* essential part of this License. No use of any Covered Software is * +* authorized under this License except under this disclaimer. * +* * + +************************************************************************ + +************************************************************************ + +* * +* 7. Limitation of Liability * +* -------------------------- * +* * +* Under no circumstances and under no legal theory, whether tort * +* (including negligence), contract, or otherwise, shall any * +* Contributor, or anyone who distributes Covered Software as * +* permitted above, be liable to You for any direct, indirect, * +* special, incidental, or consequential damages of any character * +* including, without limitation, damages for lost profits, loss of * +* goodwill, work stoppage, computer failure or malfunction, or any * +* and all other commercial damages or losses, even if such party * +* shall have been informed of the possibility of such damages. This * +* limitation of liability shall not apply to liability for death or * +* personal injury resulting from such party's negligence to the * +* extent applicable law prohibits such limitation. Some * +* jurisdictions do not allow the exclusion or limitation of * +* incidental or consequential damages, so this exclusion and * +* limitation may not apply to You. * +* * + +************************************************************************ + +8. Litigation + +------------- + +Any litigation relating to this License may be brought only in the +courts of a jurisdiction where the defendant maintains its principal +place of business and such litigation shall be governed by laws of that +jurisdiction, without reference to its conflict-of-law provisions. +Nothing in this Section shall prevent a party's ability to bring +cross-claims or counter-claims. + +9. Miscellaneous + +---------------- + +This License represents the complete agreement concerning the subject +matter hereof. If any provision of this License is held to be +unenforceable, such provision shall be reformed only to the extent +necessary to make it enforceable. Any law or regulation which provides +that the language of a contract shall be construed against the drafter +shall not be used to construe this License against a Contributor. + +10. Versions of the License + +--------------------------- + +10.1. New Versions + +Mozilla Foundation is the license steward. Except as provided in Section +10.3, no one other than the license steward has the right to modify or +publish new versions of this License. Each version will be given a +distinguishing version number. + +10.2. Effect of New Versions + +You may distribute the Covered Software under the terms of the version +of the License under which You originally received the Covered Software, +or under the terms of any subsequent version published by the license +steward. + +10.3. Modified Versions + +If you create software not governed by this License, and you want to +create a new license for such software, you may create and use a +modified version of this License if you rename the license and remove +any references to the name of the license steward (except to note that +such modified license differs from this License). + +10.4. Distributing Source Code Form that is Incompatible With Secondary +Licenses + +If You choose to distribute Source Code Form that is Incompatible With +Secondary Licenses under the terms of this version of the License, the +notice described in Exhibit B of this License must be attached. + +Exhibit A - Source Code Form License Notice +------------------------------------------- + + This Source Code Form is subject to the terms of the Mozilla Public + License, v. 2.0. If a copy of the MPL was not distributed with this + file, You can obtain one at . + +If it is not possible or desirable to put the notice in a particular +file, then You may include the notice in a location (such as a LICENSE +file in a relevant directory) where a recipient would be likely to look +for such a notice. + +You may add additional accurate notices of copyright ownership. + +Exhibit B - "Incompatible With Secondary Licenses" Notice +--------------------------------------------------------- + + This Source Code Form is "Incompatible With Secondary Licenses", as + defined by the Mozilla Public License, v. 2.0. diff --git a/README.md b/README.md new file mode 100644 index 0000000..c445064 --- /dev/null +++ b/README.md @@ -0,0 +1,268 @@ +# Project Template + +[![CalVer](https://img.shields.io/badge/calver-YY.0M.MICRO-22bfda.svg)](https://calver.org) +[![GitHub Release](https://img.shields.io/github/v/release/worldbank/template)](https://github.com/worldbank/template/releases) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/worldbank/template/main.svg)](https://results.pre-commit.ci/latest/github/worldbank/template/main) + +The template is a standardized, but flexible *project* and *documentation* structure of folders and files for sharing your data science work. + +Inspired by [literate programming](http://literateprogramming.com), maintained by the [Development Data Group](https://www.worldbank.org/en/about/unit/unit-dec/dev) and built as [GitHub template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template), the template contains: + +- [**README**](README), [**CODE_OF_CONDUCT**](docs/CODE_OF_CONDUCT.md), [**CONTRIBUTING**](docs/CONTRIBUTING.md) templates + > README files are important and often neglected. The files should inform anyone about the first steps to use, learn and contribute to your project. + +- [**CITATION.cff**](CITATION.cff) + > Embracing [CFF](https://citation-file-format.github.io) aligns with best practices for reproducible research and software development. By adhering to established standards for documenting project dependencies and citations, we demonstrate our commitment to quality, transparency, and integrity in our work. + +- [**LICENSE**](LICENSE) + > The LICENSE is a document that determines what others can and cannot do with contents of the repository. If no license is present, no one has permission to use and/or modify your code. The template is licensed under the [**Mozilla Public License**](https://www.mozilla.org/en-US/MPL/). And so will projects generated from it. + +- **docs/** + + > Documentation is often never prioritized until last minute. The template aims to revert the malpractice by setting up the documentation as an integral part, inspired by [literate programming](http://literateprogramming.com). With the power of [Jupyter Book](https://jupyterbook.org), data practitioners have a way to share [Jupyter notebooks](https://jupyter.org) on [GitHub Pages](https://pages.github.com) in a standardized and effortless way. + +- [**docs/bibliography.bib**](/docs/bibliography.bib) + > A `bibliography` using the [BibTeX](https://www.bibtex.org/Format/) format. Use this file to include and cite your project's bibliography. See also [Citations and bibliographies](https://jupyterbook.org/en/stable/content/citations.html). + +- **data/** + > Placeholder folder for data. Data is immutable. By default, the data folder is present but ignored from version control, in order to prevent files of being mistakenly versioned in the code repository. + +- **src/** + > Placeholder folder for source code. If Python, it is recommended the package is made pip-installable. + +- **notebooks/** + > Placeholder folder for [Jupyter notebooks](https://jupyter.org). Markdown files and Jupyter notebooks can be added to `docs/_toc.yml` (Table of Contents) to compose the *documentation*. + +- **.pre-commit-config.yml** + > Using [pre-commit](https://pre-commit.com) offers a significant advantage in streamlining the development process by enforcing code standards and reducing errors before code reaches the review stage or is committed to the repository. It automates the execution of various checks, such as syntax errors, code formatting, and ensuring compliance with coding standards, which saves time and improves code quality. + +- [GitHub Actions](https://github.com/features/actions) and [Dependabot](https://docs.github.com/en/code-security/dependabot) + > [GitHub Actions](https://github.com/features/actions) and [Dependabot](https://docs.github.com/en/code-security/dependabot) are two powerful features provided by [GitHub](https://github.com) to automate and secure software development workflows, making it easier for developers to maintain high-quality and safe codebases. + +- [GitHub Issues and Pull Requests GitHub](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) + > GitHub allows to customize how issues and pull requests are presented to the public. Custom templates encourage collaboration and maintainability. + +```{important} +*With flexibility comes great responsibility*. The template makes a few opiniated choices for the structure and code/documentation management of a project for what we envision to be most cases. However, even the best of the templates would never be perfect for the universe of cases out there. All in all, the template aims to encourage teams to start thinking and assimilate **collaborative coding**, **documentation**โ€‹, **enginerring**, **reproducibilityโ€‹** and **best practices** as an integral part of the project. *In a standardized way*. + +In this spirit, if the template is not for you or in case you have feedback, please consider [opening an issue](https://github.com/worldbank/template/issues) or [submitting a pull request](https://github.com/worldbank/template/pulls) to share your ideas and suggestions. Your contributions would be appreciated immensely. +``` + +## Benefits + +Project templates on GitHub are essential for streamlining the data science and collaboration processes, and they offer several key benefits: + +- ๐Ÿ› ๏ธ **Consistency and Best Practices:** Project templates encourage consistency in project structure, coding standards, and best practices. They provide a standardized starting point, ensuring that all team members follow the same guidelines and reduce the risk of introducing errors. + +- โณ **Time and Effort Savings:** Templates save time by eliminating the need to set up a project from scratch. Developers can quickly start working on their projects without the overhead of configuring the initial project structure, dependencies, or workflows. + +- ๐Ÿš€ **Faster Onboarding:** New team members or contributors can easily get up to speed by using project templates. It simplifies the onboarding process, allowing them to understand the project structure and development practices more quickly. + +- ๐ŸŽจ **Customization and Adaptability:** GitHub project templates can be customized to suit the specific needs of different types of projects or organizations. They serve as a foundation that can be adapted to meet unique requirements. + +- ๐Ÿค **Community Engagement:** Open-source projects can attract more contributors when they provide accessible project templates. These templates facilitate contributions by reducing the barriers to entry for potential collaborators. + +- ๐Ÿ”„ **Version Control Integration:** GitHub project templates are tightly integrated with Git version control. This makes it easier to manage changes, collaborate, and track the history of project configurations. + +- ๐Ÿ“– **Documentation and Guidance:** Templates often include documentation and guidance to help developers understand the project's structure and how to get started. This can include README files, code comments, and links to relevant resources. + +- ๐Ÿ” **Discoverability:** Templates are discoverable on GitHub, making it easy for developers to find and use project templates for their preferred programming languages, frameworks, and tools. This helps build a supportive ecosystem. + +- โœ๏ธ **Continual Improvement:** Project templates can evolve and improve over time as best practices, technology, and requirements change. This ensures that projects remain up to date and maintainable. + +In summary, GitHub project templates are valuable resources that enhance project management, development practices, and collaboration. They promote consistency, efficiency, and quality in software development, whether for individual projects, open-source contributions, or within organizational contexts. + +## Usage + +### Getting Started + +```{margin} โœจ Can't see the template ? +Please ensure you are logged in on [GitHub](https://github.com) and have permissions to create a repository. +``` + +1. **Create new repository from template** + + The template is a [GitHub template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template); in other words, you can generate a new GitHub repository with the same files and folders to use as the starting point for your project. + + > ๐ŸŒŸ [Create new repository from **template**](https://github.com/worldbank/template/generate) + + ```{figure} docs/images/github-template.png + --- + --- + ``` + + Now, give your repository a name, choose the **visibility** (Public or Private) and click **Create repository from template**. + + ```{figure} docs/images/github-template-create.png + --- + --- + ``` + + *Voilร !* The repository has been created with the same files and folders of the template. + + ```{seealso} + For additional information, see the [GitHub documentation](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) + ``` + +2. **Enable [GitHub Actions](https://github.com/features/actions) and [GitHub Pages](https://pages.github.com)** + + After creating the repository from the template, you will have to enable [GitHub Actions](https://github.com/features/actions) and [GitHub Pages](https://pages.github.com) to allow the [Jupyter Book](https://jupyterbook.org) to be built and published. + + To activate the workflow, please enable [GitHub Actions](https://github.com/features/actions) by going to the repository's settings (`Settings > Actions > General`), and selecting **read and write permissions** as shown below. + + ```{figure} docs/images/github-template-action-enable.png + --- + --- + ``` + + To publish, please enable [GitHub Pages](https://pages.github.com) by going to the repository's settings (`Settings > Pages`), and selecting to deploy from the `gh-pages` branch. + + ```{figure} docs/images/github-template-pages.png + --- + --- + ``` + + On the next push to `main`, the [Jupyter Book](https://jupyterbook.org) will be automatically built and published. You can check the progress on the `Actions` tab. + + ```{figure} docs/images/github-template-action.png + --- + --- + ``` + + ```{caution} + The *documentation* can be published from either *public* and *private* repositories. If publishing private content, please remember to carefully select the content to be made public and to abide by your organization's Data Privacy Policy. + ``` + +3. **Update configurations** + + The template comes with a default `docs/_config.yml` Jupyter Book configuration file. Remember to update it to reflect your project's name and details. + + ```yaml + repository: + url: https://github.com/worldbank/template + branch: main + ``` + + ```{seealso} + [Jupyter Book Configuration Reference](https://jupyterbook.org/en/stable/customize/config.html) + ``` + +4. **Review and update README files** + + The template comes with README files - including [this **README**](README) - that should provide anyone with the information about the first steps to use, learn and contribute to your project. Please **replace** and/or **repurpose** the files with instructions and detailed information about your project. + + > - **CODE_OF_CONDUCT** + > - **CONTRIBUTING** + > - **README** + > - Issues and Pull Requests GitHub templates + + ```{seealso} + [Awesome README](https://github.com/matiassingers/awesome-readme) + ``` + +5. **Choose a license** + + The template is licensed under the [**Mozilla Public License**](https://www.mozilla.org/en-US/MPL). A LICENSE is the document that guarantees the repository can be shared, modified and receive contributions. Otherwise, if no license is present, all rights are reserved. + +
+ +**Congratulations!** You just created a beautiful home for your project. To access your project page, use (and share) the link as shown below. + +> ๐ŸŒŸ `https://.github.io/` + +For example, see this template as a live demo. + +> ๐ŸŒŸ [worldbank.github.io/template](http://worldbank.github.io/template) (Live Demo) + +### Adding Content + +The template is created as a [Jupyter Book](https://jupyterbook.org/intro.html) - an open-source project to build beautiful, publication-quality books and documents from computational content. Let's see below how to add, execute and publish new content for your project. + +#### Table of Contents + +When ready to publish the *documentation* on [GitHub Pages](https://pages.github.com/), all you need to do is edit the [table of contents](#table-of-contents) and add and/or update content you would like to display. [Jupyter Book](https://jupyterbook.org) supports content written as [Markdown](https://daringfireball.net/projects/markdown/), [Jupyter](https://jupyter.org) notebooks and [reStructuredText](https://docutils.sourceforge.io/rst.html) files and the `docs/_toc.yml` file controls the [table of contents](#table-of-contents) of your book. + +The template comes with the [table of contents](#table-of-contents) below as an example. + +```yaml + +format: jb-book +root: README + +parts: + +- caption: Documentation + numbered: True + chapters: + - file: notebooks/world-bank-api.ipynb +- caption: Additional Resources + chapters: + - url: + title: Development Data Partnership + - url: + title: World Bank DEC + - url: + title: World Bank DIME + +``` + +```{seealso} +[Jupyter Book Structure and organize content](https://jupyterbook.org/en/stable/basics/organize.html) +``` + +#### Dependencies + +The next step is ensure your code is maintainable, reliable and reproducible by including +any dependencies and requirements, such as packages, configurations, secrets (template) and additional instructions. + +The template suggests to use [conda](https://docs.conda.io/) (or [mamba](https://mamba.readthedocs.io/en/latest/)) as environment manager and, as [conventional](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html), the environment is controlled by the `environment.yml` file. + +The `environment.yml` file is where you specify any packages available on the [Anaconda repository](https://anaconda.org) as well as from the Anaconda Cloud (including [conda-forge](https://conda-forge.org)) to install for your project. Ensure to include the pinned version of packages required by your project (including by Jupyter notebooks). + +```yaml +channels: + - conda-forge + - defaults +dependencies: + - python=3.9 + - bokeh=2.4.3 + - pandas=1.4.3 + - pip: + - requests==2.28.1 +``` + +To (re)create the environment on your installation of [conda](https://conda.io) via [anaconda](https://docs.anaconda.com/anaconda/install/), [miniconda](https://docs.conda.io/projects/continuumio-conda/en/latest/user-guide/install/) or preferably [miniforge](https://github.com/conda-forge/miniforge), you only need to pass the `environment.yml` file, which will install requirements and guarantee that whoever uses your code has the necessary packages (and correct versions). By default, the template uses [Python 3.9](https://www.python.org). + +```shell +conda env create -n -f environment.yml +``` + +In case your project uses Python, it is *strongly* recommended to distribute it as a [package](https://packaging.python.org/). + +```{important} +The template contains an example - the [datalab](https://github.com/worldbank/template/tree/main/src/datalab) Python package - and will automatically find and install any `src` packages as long as `pyproject.yml` is kept up-to-date. +``` + +```{seealso} +[Conda Managing Environments](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) +``` + +#### Jupyter Notebooks + +[Jupyter Notebooks](https://jupyter.org) can be beautifully rendered and downloaded from your book. By default, the template will render any files listed on the [table of contents](#table-of-contents) that have a notebook structure. The template comes with a Jupyter notebook example, `notebooks/world-bank-api.ipynb`, to illustrate. + +```{important} +Optionally, [Jupyter Book](https://jupyterbook.org) can execute notebooks during the build (on GitHub) and display **code outputs** and **interactive visualizations** as part of the *documentation* on the fly. In this case, Jupyter notebooks will be executed by [GitHub Actions](https://github.com/features/actions) during build on each commit to the `main` branch. Thus, it is important to include all [requirements and dependencies](#dependencies) in the repository. In case you would like to ignore a notebook, you can [exclude files from execution](https://jupyterbook.org/en/stable/content/execute.html#exclude-files-from-execution). +``` + +```{seealso} +[Jupyter Book Write executable content](https://jupyterbook.org/en/stable/content/executable/index.html) +``` + +## Code of Conduct + +The template maintains a [Code of Conduct](docs/CODE_OF_CONDUCT.md) to ensure an inclusive and respectful environment for everyone. Please adhere to it in all interactions within our community. + +## License + +The template is licensed under the [**Mozilla Public License**](https://www.mozilla.org/en-US/MPL). Remember to replace the [license](LICENSE) if necessary. If open source, [choose an open source license](https://choosealicense.com). diff --git a/_static/custom.css b/_static/custom.css new file mode 100644 index 0000000..4d2d7f3 --- /dev/null +++ b/_static/custom.css @@ -0,0 +1,48 @@ +root { + --sd-color-primary: #3eacad; + --sd-color-primary-highlight: #df6b00; + --sd-color-secondary: #56c3c4; + --sd-color-secondary-highlight: #f7951d; +} + +iframe { + display: block; + border-style: none; + margin: 0 auto; +} + +a:hover { + color: #56c3c4; +} + +a:visited { + color: #310459; +} + +a.headerlink { + color: #3eacad; +} + +a.reference.external:hover { + color: #f7951d; +} + +a.reference.internal:hover { + color: #3eacad; +} + +a.current.reference.internal { + color: #56c3c4; +} + +.prev-next-area a p.prev-next-title:hover { + color: #3eacad; +} + +.prev-next-area a:visited p.prev-next-title:hover { + color: #56c3c4; +} + +#pst-back-to-top { + background-color: #3eacad; +} diff --git a/data/.gitkeep b/data/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..9d623a1 --- /dev/null +++ b/docs/CODE_OF_CONDUCT.md @@ -0,0 +1,119 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[github@worldbank.org](mailto:github@worldbank.org) +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series +of actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within +the community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.0. Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..88ff556 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,93 @@ +# CONTRIBUTING + +Thank you for considering contributing to this project! Your involvement helps improve the overall quality and functionality of the project and its codebase. Please take a moment to review the following guidelines to ensure a collaborative contribution process. + +## Code of Conduct + +Please note that we have a [Code of Conduct](CODE_OF_CONDUCT.md) in place. We expect all contributors to adhere to it, both in interactions within this project and in interactions with other project members to promote a welcoming and inclusive environment for everyone. + +## How Can I Contribute? + +There are several ways you can contribute to this project: + +- **๐Ÿž Bug Reports:** If you encounter a bug or unexpected behavior, please open an issue on GitHub. Be sure to include as much detail as possible to help us identify and fix the problem. + +- **โœจ Feature Requests**: If you have an idea for a new feature or enhancement, please open an issue on GitHub. Describe the feature and its use case in detail. + +- **๐Ÿ“ฃ Community Engagement:** Ask questions, help other contributors and engage with the community on our [Discussions](https://github.com/orgs/worldbank/discussions). + +- **๐Ÿ“– Documentation Feedback:** If you find any errors or have suggestions for improving our documentation, you can report the issue on GitHub. + +- **๐Ÿ—๏ธ Pull Requests (PR):** If you'd like to contribute code or documentation changes, we encourage you to submit a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). + +## Contributing to the Code and Documentation + +Whether you are novice and expert, your contribution is valuable. If you're contributing code, we recommend getting started with [GitHub Guides](https://github.com/git-guides), [GitHub Skills](https://skills.github.com/), [GitHub Desktop](https://desktop.github.com) and/or [GitHub Docs](https://docs.github.com/en/get-started). In special, see also [collaborating with pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests). When ready, you may follow these guidelines: + +1. **[Fork the Repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo)**: Click the "Fork" button on the top-right corner of this repository on GitHub. This will create a copy of the project in your GitHub account. Then, clone or download this repository to your local machine. Then, navigate to the root directory of the repository. + +2. **[Create a Branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository):** Create a new branch for your feature or bug fix. Use a clear and descriptive name for your branch, like `feature/new-feature`. + +3. **Code Review and Changes:** Make your code changes and ensure they adhere to our coding standards. + +4. **Test:** Ensure that your changes do not break existing functionality. + +5. **[Commit and Push](https://github.com/git-guides/git-commit):** Commit your changes with a clear and concise commit message. Reference any related issues or pull requests in your commit message. Push your branch to your forked repository on GitHub. + +6. **[Create a Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request):** Open a pull request against the main branch of this repository. Provide a clear description of your changes and reference any relevant issues. Your PR will be reviewed by maintainers. + +7. **[Review and Iterate](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review):** Expect feedback and be prepared to make additional changes if necessary. We may request changes, and once everything looks good, your PR will be merged. + +### Cloning the Repository Locally + +[Cloning](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository), in the context of version control systems like [Git](https://git-scm.com), refers to the process of creating a copy of a repository from a remote location (such as a [GitHub](https://github.com) repository) onto your local machine. When you clone a repository, you replicate all of its files, folders, commit history, and branches onto your local system. This allows you to work on the project's codebase locally, make changes, create new branches, and contribute to the project without affecting the original repository. + +To clone a repository, you'll need the repository's URL and a Git client installed on your computer. First, open your [Git](https://git-scm.com) client of choice, such as [GitHub Desktop](https://desktop.github.com) or [GitKraken](https://www.gitkraken.com). Then, locate the option to clone a repository. In most [Git](https://git-scm.com) clients, this option is typically found under the "File" or "Repository" menu. Next, paste the URL of the repository you want to clone into the designated field. This URL can usually be found on the repository's [GitHub](https://github.com) page by clicking the green "Code" button and copying the URL provided. Once you've pasted the URL, choose the local directory where you want to save the cloned repository on your computer. Finally, initiate the cloning process by clicking the "Clone" button. The [Git](https://git-scm.com) client will then download a copy of the repository to your local machine, allowing you to work on the files locally and collaborate with others on the project. + +Alternatively, with you're using [Git CLI](https://git-scm.com/downloads), please follow the step below: + + ```shell + git clone https://github.com/PATH-TO/REPOSITORY + ``` + +### Running Notebooks Locally + +This repository provides a Conda/Mamba environment configuration to ensure consistent dependencies across different environments. [Conda](https://docs.conda.io)/[Mamba](https://mamba.readthedocs.io) are prevalent (interoperable) package managers. If haven't installed either, you may follow the installation instructions on the respective documentation. + +To run the notebooks locally, after (1) and (2) above, please follow these steps: + +- Create (or update) the environment: + + ```shell + mamba env create -f notebooks/environment.yml + ``` + + This command will create a new environment based on the specifications provided in the `environment.yml` file. + +- [Activate the environment](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment), run [JupyterLab](https://jupyterlab.readthedocs.io) and execute `notebooks`: + + ```shell + jupyterlab + ``` + +### Building Documentation Locally + +To build the documentation locally, after (1) and (2) above, please follow these steps: + +- Install the documentation dependencies: + + ```shell + pip install -r docs/requirements.txt + ``` + +- Build the documentation: + + ```shell + jupyter-book build . --config docs/_config.yml --toc docs/_toc.yml + ``` + +The generated documentation will be available in the `_build/html` directory. Open the `index.html` file in a web browser to view it. + +## Licensing + +By contributing to this project, you agree that your contributions will be licensed under the project's [LICENSE](LICENSE). diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..fde96ff --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,44 @@ +# Book settings +title: +author: Development Data Group +logo: docs/images/logo.png +only_build_toc_files: false + +repository: + url: https://github.com/worldbank/template + branch: main + +####################################################################################### +# HTML-specific settings +html: + home_page_in_navbar: false + extra_navbar: "" + use_edit_page_button: true + use_repository_button: true + use_issues_button: true + baseurl: https://worldbank.github.io/template + extra_footer: | +
+ Country borders or names do not necessarily reflect the World Bank Groupโ€™s official position. All maps are for illustrative purposes and do not imply the expression of any opinion on the part of the World Bank, concerning the legal status of any country or territory or concerning the delimitation of frontiers or boundaries +
+
+ All content (unless otherwise specified) is subject to the Mozilla Public License. +
+ favicon: docs/images/favicon.ico + +####################################################################################### +# Execution settings +execute: + execute_notebooks: off + +####################################################################################### +# Bibliography settings +bibtex_bibfiles: + - docs/bibliography.bib + +####################################################################################### +# Sphinx settings +sphinx: + config: + html_show_copyright: false + html_last_updated_fmt: "%b %d, %Y" diff --git a/docs/_toc.yml b/docs/_toc.yml new file mode 100644 index 0000000..130c2a0 --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,24 @@ +format: jb-book +root: README + +parts: + - caption: Examples + numbered: True + chapters: + - file: notebooks/world-bank-api.ipynb + - file: notebooks/world-bank-package.ipynb + - file: notebooks/nasa-apod.ipynb + - file: notebooks/bibliography.ipynb + - caption: Gallery + chapters: + - file: docs/gallery + - caption: Additional Resources + chapters: + - url: https://datapartnership.org + title: Development Data Partnership + - url: https://wbdatalab.org + title: World Bank Data Lab + - url: https://www.worldbank.org/en/about/unit/unit-dec + title: World Bank DEC + - url: https://www.worldbank.org/en/research/dime + title: World Bank DIME diff --git a/docs/bibliography.bib b/docs/bibliography.bib new file mode 100644 index 0000000..07103db --- /dev/null +++ b/docs/bibliography.bib @@ -0,0 +1,39 @@ +@book{WorldBank2021WorldDevelopmentReport, + author = {{World Bank}}, + publisher = {World Bank}, + url = {http://hdl.handle.net/10986/35218}, + date = {2021}, + note = {License: CC BY 3.0 IGO}, + title = {{W}orld {D}evelopment {R}eport 2021 : {D}ata for {B}etter {L}ives}, + type = {World Development Report}, + year = {2021}, +} +@book{WorldBank2022WorldDevelopmentReport, + author = {{World Bank}}, + publisher = {World Bank}, + url = {http://hdl.handle.net/10986/36883}, + date = {2022}, + note = {License: CC BY 3.0 IGO}, + title = {{W}orld {D}evelopment {R}eport 2022 : {F}inance for an {E}quitable {R}ecovery}, + type = {World Development Report}, + year = {2022}, +}, +@book{WorldBank2023WorldDevelopmentReport, + author = {{World Bank}}, + publisher = {World Bank}, + url = {https://openknowledge.worldbank.org/handle/10986/39696}, + date = {2023}, + note = {License: CC BY 3.0 IGO}, + title = {{W}orld {D}evelopment {R}eport 2021 : {M}igrants, {R}efugees, and {S}ocieties}, + type = {World Development Report}, + year = {2023}, +} +@misc{sdgatlas2020, + author = {Pirlea, A. F. and U. Serajuddin and D. Wadhwa and M. Welch and A. Whitby}, + publisher = {World Bank}, + url = {https://datatopics.worldbank.org/sdgatlas.}, + date = {2020}, + note = {License: CC BY 3.0 IGO}, + title = {{A}tlas of the {S}ustainable {D}evelopment {G}oals 2020: {F}rom {W}orld {D}evelopment {I}ndicators}, + year = {2020}, +} diff --git a/docs/gallery.md b/docs/gallery.md new file mode 100644 index 0000000..3b3eb74 --- /dev/null +++ b/docs/gallery.md @@ -0,0 +1,114 @@ +# Projects using the template + +> A curated list of projects/repositories using the template. + +::::{grid} +:gutter: 2 + +:::{grid-item-card} [Syria Economic Monitor](https://datapartnership.github.io/syria-economic-monitor) +Using Alternative Data to Understand Changing Trends in Trade and Economic Activity in Syria +::: + +:::{grid-item-card} [Tรผrkiye Earthquake Impact](https://datapartnership.github.io/turkiye-earthquake-impact) +Using Alternative Data to Understand Economic Impacts of the 2023 Turkeyโ€“Syria Earthquake +::: +:::: + +::::{grid} +:gutter: 2 + +:::{grid-item-card} [Lebanon Economic Monitor](https://datapartnership.github.io/lebanon-economic-monitor) +Understanding Lebanonโ€™s Economy through Alternative Data +::: + +:::{grid-item-card} [Mocorro Earthquake Impact](https://datapartnership.github.io/morocco-earthquake-impact) +Using Alternative Data to Understand Economic Impacts of the 2023 Morocco earthquake. +::: +:::: + +::::{grid} +:gutter: 2 + +:::{grid-item-card} [Myanmar Economic Monitor](https://datapartnership.github.io/myanmar-economic-monitor) +Understanding Myanmar's Economy through Alternative Data +::: + +:::{grid-item-card} [Pacific Observatory](https://worldbank.github.io/pacific-observatory) +The Pacific Observatory is the World Bank analytical program to explore and develop new information sources to mitigate the impact of data gaps in official statistics for Papua New Guinea (PNG) and the Pacific Island Countries (PICs). + +::: +:::: + +::::{grid} +:gutter: 2 + +:::{grid-item-card} [REaLTabFormer](https://worldbank.github.io/REaLTabFormer) +A suite of auto-regressive and Seq2Seq (sequence-to-sequence) transformer models for tabular and relational synthetic data generation. +::: +:::{grid-item-card} [iQual](https://worldbank.github.io/iQmual) +iQual is a package that leverages natural language processing to scale up interpretative qualitative analysis. It also provides methods to assess the bias, interpretability and efficiency of the machine-enhanced codes. iQual has been applied to analyse interviews on parents' aspirations for their children in Cox's Bazaar, Bangladesh. +:::: + +::::{grid} +:gutter: 2 + +:::{grid-item-card} [GEE Zonal](https://worldbank.github.io/GEE_Zonal/) +This python package provides a wrapper function to request temporal and zonal statistics from Google Earth Engine (GEE) datasets. +::: + +:::{grid-item-card} [Geospatial Operations Support Team (GOST)](https://worldbank.github.io/GOST) +We document important resources, methods, and sources in real time via this live wiki. This repository is the evolving, growing workspace where GOST stores libraries and scripts for operationalizing the many initiatives currently going on in the geospatial realm within the World Bank Group. +::: +:::: + +::::{grid} +:gutter: 2 + +:::{grid-item-card} [DECAT_Space2Stats](https://worldbank.github.io/DECAT_Space2Stats) +Consistent, comparable, authoritative data describing sub-national variation is a constant point of complication for World Bank teams, our development partners, and client countries when assessing and investigating economic issues and national policy. This project will focus on creating and disseminating such data through aggregation of geospatial information at standard administrative divisions, and through the attribution of household survey data with foundational geospatial variables. +::: + +:::{grid-item-card} [ZAF_Econ_Diversification](https://worldbank.github.io/ZAF_Econ_Diversification) +Mapping and quantifying opportunities for economic diversification in Mpumalanga in South Africa +::: +:::: + +::::{grid} +:gutter: 2 + +:::{grid-item-card} [GFF Health Equity](https://worldbank.github.io/health-equity-diagnostics) +This repository contains scripts developed by GOST to map health facilities and understand differences in population access in support of the GFF Country Equity Diagnostic and other projects. +::: + +:::{grid-item-card} [Heatwaves Data Collaborative](https://datapartnership.org/heatwaves/PH) +The Heatwaves Data Collaborative enables teams across sectors and +organizations to simultaneously focus on their areas of expertise, while +collaborating through use of common frameworks and datasets, standards for +production and review of reusable methods, and through regular check-ins to +ensure the different work streams are aligned and build upon each other. +::: +:::: + +::::{grid} +:gutter: 2 + +:::{grid-item-card} [Geospatial Analysis - MENA Poverty and Equity Group](https://worldbank.github.io/mena-pov) +The Geospatial Analysis repository aims to centrally maintain cleaning and analysis of data that leverage geospatial data conducted by the Poverty and Equity Group in the MENA region. +::: + +:::{grid-item-card} [Health Planning in the Philippines](https://datapartnership.org/health-planning-in-philippines) +The team conducted geospatial analysis to advise on key questions that could inform a more integrated health care system, starting with three LGUs (Bohol, Baguio City, and Maguindanao). +::: +:::: + +::::{grid} +:gutter: 2 + +:::{grid-item-card} [Understanding societal responses to policies undertaken during emergencies: Lessons from COVID-19โ€™s Second Wave in Maharashtra](https://datapartnership.github.io/covid-19-maharashtra) +Understanding societal responses to policies undertaken during emergencies: Lessons from COVID-19's Second Wave in Maharashtra +::: + +:::{grid-item-card} [Understanding the vulnerability of New Delhi to Heatwaves](https://datapartnership.org/vulnerability-to-heatwaves-in-india) +Part of Understanding the vulnerability of New Delhi to Heatwaves, this repository holds a collection of (experimental) Jupyter notebooks exploring data available through the Development Data Partnership. +::: +:::: diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 0000000..6fa0889 Binary files /dev/null and b/docs/images/favicon.ico differ diff --git a/docs/images/github-template-action-enable.png b/docs/images/github-template-action-enable.png new file mode 100644 index 0000000..8951744 Binary files /dev/null and b/docs/images/github-template-action-enable.png differ diff --git a/docs/images/github-template-action.png b/docs/images/github-template-action.png new file mode 100644 index 0000000..2738d51 Binary files /dev/null and b/docs/images/github-template-action.png differ diff --git a/docs/images/github-template-create.png b/docs/images/github-template-create.png new file mode 100644 index 0000000..a2782ed Binary files /dev/null and b/docs/images/github-template-create.png differ diff --git a/docs/images/github-template-pages.png b/docs/images/github-template-pages.png new file mode 100644 index 0000000..619f8ab Binary files /dev/null and b/docs/images/github-template-pages.png differ diff --git a/docs/images/github-template.png b/docs/images/github-template.png new file mode 100644 index 0000000..9503f66 Binary files /dev/null and b/docs/images/github-template.png differ diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 0000000..9c46884 Binary files /dev/null and b/docs/images/logo.png differ diff --git a/notebooks/.gitkeep b/notebooks/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/notebooks/bibliography.ipynb b/notebooks/bibliography.ipynb new file mode 100644 index 0000000..17ab1a6 --- /dev/null +++ b/notebooks/bibliography.ipynb @@ -0,0 +1,173 @@ +{ + "cells": [ + { + "attachments": {}, + "cell_type": "markdown", + "id": "90700fdc-fcc7-4e54-8c9e-449879d8c66d", + "metadata": { + "tags": [] + }, + "source": [ + "(bibliography)=\n", + "\n", + "# Including Bibliography" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "14e89727", + "metadata": {}, + "source": [ + "Including a bibliography is of utmost importance in any academic or research work. A bibliography serves as a comprehensive list of all the sources consulted and referenced during the creation of a paper, essay, or any scholarly project. It not only adds credibility to the work but also demonstrates the depth of research conducted by the author. By providing a bibliography, the author acknowledges the contributions of other scholars and researchers, thereby showing respect for intellectual property and avoiding plagiarism. \n", + "\n", + "Furthermore, a bibliography allows readers to delve deeper into the subject matter, explore related sources, and verify the accuracy and reliability of the information presented. In essence, the inclusion of a well-constructed bibliography is an essential aspect of scholarly writing that promotes transparency, authenticity, and the advancement of knowledge." + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "b4c0f3e8-7756-41bb-aa21-cc2eee5ff67f", + "metadata": {}, + "source": [ + "## Usage\n", + "\n", + "```{seealso}\n", + "[Jupyter Book: Citations and bibliographies](https://jupyterbook.org/en/stable/content/citations.html)\n", + "```\n", + "\n", + "The template includes [`docs/bibliography.bib`](docs/bibliography.bib) as example, containing an entry to the World Bank flagship publication [World Development Report 2021](https://www.worldbank.org/en/publication/wdr2021) in [BibTeX Format](http://www.bibtex.org/Format). \n", + "\n", + "To include a **citation**, we use the syntax as shown below.\n", + " \n", + "````md\n", + "{cite}`WorldBank2021WorldDevelopmentReport`\n", + "````\n", + "\n", + "Additionally, we can use different citation styles.\n", + "\n", + "- **{cite:t}**: {cite:t}`WorldBank2021WorldDevelopmentReport`\n", + "\n", + "- **{cite:p}**: {cite:p}`WorldBank2021WorldDevelopmentReport`\n", + "\n", + "\n", + "```{seealso}\n", + "For a more complete list of in-line citation styles, check out the [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#roles-and-directives).\n", + "```\n", + "\n", + "To include the **bibliography**, we use the syntax as shown below. Note that this will include all citations throughout the book. \n", + "\n", + "````md\n", + "```{bibliography}\n", + "```\n", + "````\n", + "\n", + "```{bibliography}\n", + "```\n", + "\n", + "To include only the **local bibliography**, we use the syntax as shown below. \n", + "\n", + "````md\n", + "```{bibliography}\n", + ":filter: docname in docnames\n", + "```\n", + "````\n", + "\n", + "```{bibliography}\n", + ":filter: docname in docnames\n", + "```\n" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "d0066241", + "metadata": {}, + "source": [ + "## Bibliography Styles\n", + "\n", + "\n", + "### `alpha`\n", + "\n", + "````md\n", + "```{bibliography}\n", + ":style: alpha\n", + "```\n", + "````\n", + "\n", + "```{bibliography}\n", + ":style: alpha\n", + "```\n", + "\n", + "### `plain`\n", + "\n", + "````md\n", + "```{bibliography}\n", + ":style: plain\n", + "```\n", + "````\n", + "\n", + "```{bibliography}\n", + ":style: plain\n", + "```\n", + "\n", + "### `unsrt`\n", + "\n", + "````md\n", + "```{bibliography}\n", + ":style: unsrt\n", + "```\n", + "````\n", + "\n", + "```{bibliography}\n", + ":style: unsrt\n", + "```\n", + "\n", + "### `unsrtalpha`\n", + "\n", + "````md\n", + "```{bibliography}\n", + ":style: unsrtalpha\n", + "```\n", + "````\n", + "\n", + "```{bibliography}\n", + ":style: unsrtalpha\n", + "```\n" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "b0e84fdb", + "metadata": {}, + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.9.12" + }, + "vscode": { + "interpreter": { + "hash": "b6702b69e93007336b96338c5a331192f07cedff01d36d4dcfa0f842adb718ad" + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/environment.yml b/notebooks/environment.yml new file mode 100644 index 0000000..500c72c --- /dev/null +++ b/notebooks/environment.yml @@ -0,0 +1,10 @@ +channels: + - conda-forge + - defaults +dependencies: + - python=3.10 + - bokeh + - pandas + - pip + - pip: + - requests==2.28.1 diff --git a/notebooks/nasa-apod.ipynb b/notebooks/nasa-apod.ipynb new file mode 100644 index 0000000..18553cb --- /dev/null +++ b/notebooks/nasa-apod.ipynb @@ -0,0 +1,282 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "90700fdc-fcc7-4e54-8c9e-449879d8c66d", + "metadata": { + "tags": [] + }, + "source": [ + "# Securely Using API Keys\n", + "\n", + "> The following are (opinionated) best practices to store and use API keys in your source code. If you disagree, please consider [contributing](https://github.com/worldbank/template/issues/new/choose). " + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "ac0ed1c0", + "metadata": {}, + "source": [ + "## Environment Variables\n", + "\n", + "An [environment variable](https://en.wikipedia.org/wiki/Environment_variable) is a dynamic-named value that can be used to store information on a computer. For instance, an environment variable can be used to store settings and/or privileged information (e.g. API keys) on your local computer or server.\n", + "\n", + "To set a environment variable to a new value, in **Unix-like** systems, you must pass a `name` and a `value` pair as shown below in the terminal.\n", + "\n", + "```shell\n", + "export SECRET_API_KEY = \n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "080bd097-f128-4759-946d-793368230804", + "metadata": { + "tags": [] + }, + "source": [ + "The `value` is accessible by the `name` without being exposed throughout the system. In particular, in [Python](https://python.org), the value can be retrieve as follows." + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "8d023b4e-496b-440c-91a7-199bceb44d7d", + "metadata": { + "tags": [] + }, + "source": [ + "```python\n", + "secret_api_key = os.getenv(\"SECRET_API_KEY\")\n", + "```" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "54a99582-d509-4ab8-be42-ddb4921c0f45", + "metadata": { + "tags": [] + }, + "source": [ + "Alternatively, it is customary to use a `.env` file to organize and load environments variables as needed. Packages such as [dotenv](https://www.npmjs.com/package/dotenv) and [python-dotenv](https://pypi.org/project/python-dotenv/) will automatically load environments variables for you from the `.env` file.\n", + "\n", + "```shell\n", + "source .env\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "3c0cc26a-2a99-49b0-a406-d57f31fff8ee", + "metadata": {}, + "source": [ + "With [Python](https://python.org)," + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "960398ce-eadb-45e3-b160-53e6c9250dd0", + "metadata": { + "tags": [ + "remove_output" + ] + }, + "outputs": [], + "source": [ + "from dotenv import load_dotenv\n", + "\n", + "load_dotenv()" + ] + }, + { + "cell_type": "markdown", + "id": "bda573d0-c877-42e6-8ee5-3000b780b4b7", + "metadata": { + "tags": [] + }, + "source": [ + "With [Jupyter](https://jupyter.org)," + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "2e700464-b50d-4b06-b0aa-afaafa17e68e", + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "%load_ext dotenv\n", + "%dotenv" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "660db869", + "metadata": {}, + "source": [ + "The template includes `.env.example` as an example; to use, simply rename it to `.env` and add your settings and secrets to it. Please note that `.env` **must** never be committed/versioned (for example, to GitHub) and **should** be ignored on `.gitignore`. " + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "74484f7e", + "metadata": {}, + "source": [ + "```{tip}\n", + "While environments variables are a convenient way to minimize the security risk, it is important to emphasize secrets are still stored in plaintext in your computer. It is strongly recommended to use instead a secret manager, such as [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) or [1Password](https://developer.1password.com/docs/cli/secret-references).\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "14e89727", + "metadata": {}, + "source": [ + "## Astronomy Picture of the Day" + ] + }, + { + "cell_type": "markdown", + "id": "b4c0f3e8-7756-41bb-aa21-cc2eee5ff67f", + "metadata": {}, + "source": [ + "One of the most popular APIs is NASA's [Astronomy Picture of the Day](https://apod.nasa.gov/apod/astropix.html). Let's see in the following example how to use the NASA API with a secret API key." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "d797ef77-6ca4-4f9d-a1f8-abbfd9884b07", + "metadata": { + "tags": [ + "hide-cell" + ] + }, + "outputs": [], + "source": [ + "import os\n", + "\n", + "import httpx\n", + "from IPython.display import Image" + ] + }, + { + "cell_type": "markdown", + "id": "ece37244", + "metadata": {}, + "source": [ + "First, you will have to [generate your API key](https://api.nasa.gov) and set up the environment variable `NASA_API_KEY` with its value. Now you are ready to use it in your code. For instance, in this example, we assign it to `api_key`. Please note that the value is never exposed and the notebook can be securely shared with anyone. " + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "id": "7b914e66-7ae8-4d8b-9621-d6dc5ec49631", + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "api_key = os.getenv(\"NASA_API_KEY\")" + ] + }, + { + "cell_type": "markdown", + "id": "10b5b12a", + "metadata": {}, + "source": [ + "Now, we are ready to make the request to the NASA API. According to the [documentation](https://github.com/nasa/apod-api#docs), the `api_key` is passed a parameter to the GET request. " + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "1990c3b9-f145-4c1f-bbb5-82f50801a011", + "metadata": { + "tags": [] + }, + "outputs": [], + "source": [ + "async with httpx.AsyncClient() as client:\n", + " r = await client.get(\n", + " \"https://api.nasa.gov/planetary/apod\", params={\"api_key\": api_key}\n", + " )" + ] + }, + { + "cell_type": "markdown", + "id": "e952e343", + "metadata": {}, + "source": [ + "Voilร !" + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "bd1cb597-0144-43e8-bed8-12145a831a0c", + "metadata": { + "tags": [] + }, + "outputs": [ + { + "data": { + "text/html": [ + "" + ], + "text/plain": [ + "" + ] + }, + "execution_count": 14, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "Image(url=r.json()[\"hdurl\"])" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8c7cb67e-c7ba-4ed3-bee0-36d303c1517d", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.12" + }, + "vscode": { + "interpreter": { + "hash": "ce6d896885f4e28373aa2ff7c44f136ed5a497e2abd203a79a632f5859ed7bb5" + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/world-bank-api.ipynb b/notebooks/world-bank-api.ipynb new file mode 100644 index 0000000..7e4bbf0 --- /dev/null +++ b/notebooks/world-bank-api.ipynb @@ -0,0 +1,721 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "90700fdc-fcc7-4e54-8c9e-449879d8c66d", + "metadata": { + "tags": [] + }, + "source": [ + "# World Bank Indicators API Example\n", + "\n", + "> The following is an example of a [Jupyter notebook](https://jupyter.org) - a tutorial of how to retrieve data from the [World Bank Indicators API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation) - that illustrates how to use computational content with the [template](https://worldbank.github.io/template). " + ] + }, + { + "cell_type": "markdown", + "id": "e0d992a6-f656-45ce-a025-f824901e8797", + "metadata": {}, + "source": [ + "## Requirements" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "1811080b-c4c6-43cb-9e46-5cfa65d54abf", + "metadata": {}, + "outputs": [], + "source": [ + "import itertools\n", + "\n", + "import pandas\n", + "import requests\n", + "from bokeh.palettes import Spectral6\n", + "from bokeh.plotting import figure, output_notebook, show" + ] + }, + { + "attachments": {}, + "cell_type": "markdown", + "id": "fb8d2738-535e-4957-b82a-987891955a7f", + "metadata": {}, + "source": [ + "## Data Retrieval\n", + "\n", + "In this example, we retrieve **Population, total** (`SP.POP.TOTL`) from the [World Bank Indicators](https://data.worldbank.org/indicator) for [BRICS](https://infobrics.org)." + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "c955864a-1889-4f7f-a29e-108b0534846b", + "metadata": {}, + "outputs": [], + "source": [ + "url = \"https://api.worldbank.org/v2/country/chn;bra;ind;rus;zaf/indicator/SP.POP.TOTL?format=json&per_page=10000\"" + ] + }, + { + "cell_type": "markdown", + "id": "6b5aac7c-bf80-4daa-a4a4-eebe8edc97bb", + "metadata": {}, + "source": [ + "Let's use [requests](https://requests.readthedocs.io) to send a GET request," + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "8d699f28-853a-40a1-8ea9-8dd566962454", + "metadata": {}, + "outputs": [], + "source": [ + "r = requests.get(url)" + ] + }, + { + "cell_type": "markdown", + "id": "a21cf193-ec13-45b8-9726-bb960ac8586a", + "metadata": {}, + "source": [ + "Now, let's normalize and create `pandas.DataFrame` from the response," + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "3dc152b2-95ba-473a-a416-2c4d5bac7622", + "metadata": {}, + "outputs": [], + "source": [ + "# normalize\n", + "data = pandas.json_normalize(r.json()[-1])\n", + "\n", + "# create dataframe\n", + "df = pandas.DataFrame.from_dict(data)" + ] + }, + { + "cell_type": "markdown", + "id": "241904c0-35b9-4e43-a3f9-f97738ea9fd1", + "metadata": {}, + "source": [ + "```{tip}\n", + "Alternatively, the World Bank API supports downloading the data as an [archive](http://api.worldbank.org/v2/country/all/indicator/SP.POP.TOTL?date=2000&source=2&downloadformat=csv). \n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "bae3462b-f49c-4b8a-badb-8f580b4fc268", + "metadata": {}, + "source": [ + "Let's take a look at the dataframe, " + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "c0bbef2d-495c-4140-b8ac-45ee47772142", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "\n", + "\n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
countryiso3codeBRACHNINDRUSZAF
date
196073.092515667.070445.954579119.89700016.520441
196175.330008660.330456.351876121.23600016.989464
196277.599218665.770467.024193122.59100017.503133
196379.915555682.335477.933619123.96000018.042215
196482.262794698.355489.059309125.34500018.603097
..................
2018210.1665921402.7601369.003306144.47785957.339635
2019211.7828781407.7451383.112050144.40626158.087055
2020213.1963041411.1001396.387127144.07313958.801927
2021214.3262231412.3601407.563842144.13048259.392255
2022215.3134981412.1751417.173173144.23693359.893885
\n", + "

63 rows ร— 5 columns

\n", + "
" + ], + "text/plain": [ + "countryiso3code BRA CHN IND RUS ZAF\n", + "date \n", + "1960 73.092515 667.070 445.954579 119.897000 16.520441\n", + "1961 75.330008 660.330 456.351876 121.236000 16.989464\n", + "1962 77.599218 665.770 467.024193 122.591000 17.503133\n", + "1963 79.915555 682.335 477.933619 123.960000 18.042215\n", + "1964 82.262794 698.355 489.059309 125.345000 18.603097\n", + "... ... ... ... ... ...\n", + "2018 210.166592 1402.760 1369.003306 144.477859 57.339635\n", + "2019 211.782878 1407.745 1383.112050 144.406261 58.087055\n", + "2020 213.196304 1411.100 1396.387127 144.073139 58.801927\n", + "2021 214.326223 1412.360 1407.563842 144.130482 59.392255\n", + "2022 215.313498 1412.175 1417.173173 144.236933 59.893885\n", + "\n", + "[63 rows x 5 columns]" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "df = df.pivot_table(values=\"value\", index=\"date\", columns=\"countryiso3code\")\n", + "df = df / 1e6 # scaling\n", + "df" + ] + }, + { + "cell_type": "markdown", + "id": "27f26a03-6d7a-4c86-8a02-1ea341d7ac5b", + "metadata": {}, + "source": [ + "## Visualization" + ] + }, + { + "cell_type": "markdown", + "id": "38e8582b-2a51-4908-8356-76cb6158fdc3", + "metadata": {}, + "source": [ + "Let's now plot the data as a time series using [Bokeh](https://docs.bokeh.org)." + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "78041d94-56a6-43ff-a307-8e8a3b377858", + "metadata": { + "tags": [] + }, + "outputs": [ + { + "data": { + "text/html": [ + " \n", + "
\n", + " \n", + " Loading BokehJS ...\n", + "
\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "application/javascript": [ + "(function(root) {\n", + " function now() {\n", + " return new Date();\n", + " }\n", + "\n", + " const force = true;\n", + "\n", + " if (typeof root._bokeh_onload_callbacks === \"undefined\" || force === true) {\n", + " root._bokeh_onload_callbacks = [];\n", + " root._bokeh_is_loading = undefined;\n", + " }\n", + "\n", + "const JS_MIME_TYPE = 'application/javascript';\n", + " const HTML_MIME_TYPE = 'text/html';\n", + " const EXEC_MIME_TYPE = 'application/vnd.bokehjs_exec.v0+json';\n", + " const CLASS_NAME = 'output_bokeh rendered_html';\n", + "\n", + " /**\n", + " * Render data to the DOM node\n", + " */\n", + " function render(props, node) {\n", + " const script = document.createElement(\"script\");\n", + " node.appendChild(script);\n", + " }\n", + "\n", + " /**\n", + " * Handle when an output is cleared or removed\n", + " */\n", + " function handleClearOutput(event, handle) {\n", + " function drop(id) {\n", + " const view = Bokeh.index.get_by_id(id)\n", + " if (view != null) {\n", + " view.model.document.clear()\n", + " Bokeh.index.delete(view)\n", + " }\n", + " }\n", + "\n", + " const cell = handle.cell;\n", + "\n", + " const id = cell.output_area._bokeh_element_id;\n", + " const server_id = cell.output_area._bokeh_server_id;\n", + "\n", + " // Clean up Bokeh references\n", + " if (id != null) {\n", + " drop(id)\n", + " }\n", + "\n", + " if (server_id !== undefined) {\n", + " // Clean up Bokeh references\n", + " const cmd_clean = \"from bokeh.io.state import curstate; print(curstate().uuid_to_server['\" + server_id + \"'].get_sessions()[0].document.roots[0]._id)\";\n", + " cell.notebook.kernel.execute(cmd_clean, {\n", + " iopub: {\n", + " output: function(msg) {\n", + " const id = msg.content.text.trim()\n", + " drop(id)\n", + " }\n", + " }\n", + " });\n", + " // Destroy server and session\n", + " const cmd_destroy = \"import bokeh.io.notebook as ion; ion.destroy_server('\" + server_id + \"')\";\n", + " cell.notebook.kernel.execute(cmd_destroy);\n", + " }\n", + " }\n", + "\n", + " /**\n", + " * Handle when a new output is added\n", + " */\n", + " function handleAddOutput(event, handle) {\n", + " const output_area = handle.output_area;\n", + " const output = handle.output;\n", + "\n", + " // limit handleAddOutput to display_data with EXEC_MIME_TYPE content only\n", + " if ((output.output_type != \"display_data\") || (!Object.prototype.hasOwnProperty.call(output.data, EXEC_MIME_TYPE))) {\n", + " return\n", + " }\n", + "\n", + " const toinsert = output_area.element.find(\".\" + CLASS_NAME.split(' ')[0]);\n", + "\n", + " if (output.metadata[EXEC_MIME_TYPE][\"id\"] !== undefined) {\n", + " toinsert[toinsert.length - 1].firstChild.textContent = output.data[JS_MIME_TYPE];\n", + " // store reference to embed id on output_area\n", + " output_area._bokeh_element_id = output.metadata[EXEC_MIME_TYPE][\"id\"];\n", + " }\n", + " if (output.metadata[EXEC_MIME_TYPE][\"server_id\"] !== undefined) {\n", + " const bk_div = document.createElement(\"div\");\n", + " bk_div.innerHTML = output.data[HTML_MIME_TYPE];\n", + " const script_attrs = bk_div.children[0].attributes;\n", + " for (let i = 0; i < script_attrs.length; i++) {\n", + " toinsert[toinsert.length - 1].firstChild.setAttribute(script_attrs[i].name, script_attrs[i].value);\n", + " toinsert[toinsert.length - 1].firstChild.textContent = bk_div.children[0].textContent\n", + " }\n", + " // store reference to server id on output_area\n", + " output_area._bokeh_server_id = output.metadata[EXEC_MIME_TYPE][\"server_id\"];\n", + " }\n", + " }\n", + "\n", + " function register_renderer(events, OutputArea) {\n", + "\n", + " function append_mime(data, metadata, element) {\n", + " // create a DOM node to render to\n", + " const toinsert = this.create_output_subarea(\n", + " metadata,\n", + " CLASS_NAME,\n", + " EXEC_MIME_TYPE\n", + " );\n", + " this.keyboard_manager.register_events(toinsert);\n", + " // Render to node\n", + " const props = {data: data, metadata: metadata[EXEC_MIME_TYPE]};\n", + " render(props, toinsert[toinsert.length - 1]);\n", + " element.append(toinsert);\n", + " return toinsert\n", + " }\n", + "\n", + " /* Handle when an output is cleared or removed */\n", + " events.on('clear_output.CodeCell', handleClearOutput);\n", + " events.on('delete.Cell', handleClearOutput);\n", + "\n", + " /* Handle when a new output is added */\n", + " events.on('output_added.OutputArea', handleAddOutput);\n", + "\n", + " /**\n", + " * Register the mime type and append_mime function with output_area\n", + " */\n", + " OutputArea.prototype.register_mime_type(EXEC_MIME_TYPE, append_mime, {\n", + " /* Is output safe? */\n", + " safe: true,\n", + " /* Index of renderer in `output_area.display_order` */\n", + " index: 0\n", + " });\n", + " }\n", + "\n", + " // register the mime type if in Jupyter Notebook environment and previously unregistered\n", + " if (root.Jupyter !== undefined) {\n", + " const events = require('base/js/events');\n", + " const OutputArea = require('notebook/js/outputarea').OutputArea;\n", + "\n", + " if (OutputArea.prototype.mime_types().indexOf(EXEC_MIME_TYPE) == -1) {\n", + " register_renderer(events, OutputArea);\n", + " }\n", + " }\n", + " if (typeof (root._bokeh_timeout) === \"undefined\" || force === true) {\n", + " root._bokeh_timeout = Date.now() + 5000;\n", + " root._bokeh_failed_load = false;\n", + " }\n", + "\n", + " const NB_LOAD_WARNING = {'data': {'text/html':\n", + " \"
\\n\"+\n", + " \"

\\n\"+\n", + " \"BokehJS does not appear to have successfully loaded. If loading BokehJS from CDN, this \\n\"+\n", + " \"may be due to a slow or bad network connection. Possible fixes:\\n\"+\n", + " \"

\\n\"+\n", + " \"
    \\n\"+\n", + " \"
  • re-rerun `output_notebook()` to attempt to load from CDN again, or
    • \\n\"+\n", + " \"
  • use INLINE resources instead, as so:
    • \\n\"+\n", + " \"
\\n\"+\n", + " \"\\n\"+\n", + " \"from bokeh.resources import INLINE\\n\"+\n", + " \"output_notebook(resources=INLINE)\\n\"+\n", + " \"\\n\"+\n", + " \"
\"}};\n", + "\n", + " function display_loaded() {\n", + " const el = document.getElementById(\"b627ae3b-1db0-4fe3-8762-32a285a44007\");\n", + " if (el != null) {\n", + " el.textContent = \"BokehJS is loading...\";\n", + " }\n", + " if (root.Bokeh !== undefined) {\n", + " if (el != null) {\n", + " el.textContent = \"BokehJS \" + root.Bokeh.version + \" successfully loaded.\";\n", + " }\n", + " } else if (Date.now() < root._bokeh_timeout) {\n", + " setTimeout(display_loaded, 100)\n", + " }\n", + " }\n", + "\n", + " function run_callbacks() {\n", + " try {\n", + " root._bokeh_onload_callbacks.forEach(function(callback) {\n", + " if (callback != null)\n", + " callback();\n", + " });\n", + " } finally {\n", + " delete root._bokeh_onload_callbacks\n", + " }\n", + " console.debug(\"Bokeh: all callbacks have finished\");\n", + " }\n", + "\n", + " function load_libs(css_urls, js_urls, callback) {\n", + " if (css_urls == null) css_urls = [];\n", + " if (js_urls == null) js_urls = [];\n", + "\n", + " root._bokeh_onload_callbacks.push(callback);\n", + " if (root._bokeh_is_loading > 0) {\n", + " console.debug(\"Bokeh: BokehJS is being loaded, scheduling callback at\", now());\n", + " return null;\n", + " }\n", + " if (js_urls == null || js_urls.length === 0) {\n", + " run_callbacks();\n", + " return null;\n", + " }\n", + " console.debug(\"Bokeh: BokehJS not loaded, scheduling load and callback at\", now());\n", + " root._bokeh_is_loading = css_urls.length + js_urls.length;\n", + "\n", + " function on_load() {\n", + " root._bokeh_is_loading--;\n", + " if (root._bokeh_is_loading === 0) {\n", + " console.debug(\"Bokeh: all BokehJS libraries/stylesheets loaded\");\n", + " run_callbacks()\n", + " }\n", + " }\n", + "\n", + " function on_error(url) {\n", + " console.error(\"failed to load \" + url);\n", + " }\n", + "\n", + " for (let i = 0; i < css_urls.length; i++) {\n", + " const url = css_urls[i];\n", + " const element = document.createElement(\"link\");\n", + " element.onload = on_load;\n", + " element.onerror = on_error.bind(null, url);\n", + " element.rel = \"stylesheet\";\n", + " element.type = \"text/css\";\n", + " element.href = url;\n", + " console.debug(\"Bokeh: injecting link tag for BokehJS stylesheet: \", url);\n", + " document.body.appendChild(element);\n", + " }\n", + "\n", + " for (let i = 0; i < js_urls.length; i++) {\n", + " const url = js_urls[i];\n", + " const element = document.createElement('script');\n", + " element.onload = on_load;\n", + " element.onerror = on_error.bind(null, url);\n", + " element.async = false;\n", + " element.src = url;\n", + " console.debug(\"Bokeh: injecting script tag for BokehJS library: \", url);\n", + " document.head.appendChild(element);\n", + " }\n", + " };\n", + "\n", + " function inject_raw_css(css) {\n", + " const element = document.createElement(\"style\");\n", + " element.appendChild(document.createTextNode(css));\n", + " document.body.appendChild(element);\n", + " }\n", + "\n", + " const js_urls = [\"https://cdn.bokeh.org/bokeh/release/bokeh-3.3.4.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-gl-3.3.4.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-widgets-3.3.4.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-tables-3.3.4.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-mathjax-3.3.4.min.js\"];\n", + " const css_urls = [];\n", + "\n", + " const inline_js = [ function(Bokeh) {\n", + " Bokeh.set_log_level(\"info\");\n", + " },\n", + "function(Bokeh) {\n", + " }\n", + " ];\n", + "\n", + " function run_inline_js() {\n", + " if (root.Bokeh !== undefined || force === true) {\n", + " for (let i = 0; i < inline_js.length; i++) {\n", + " inline_js[i].call(root, root.Bokeh);\n", + " }\n", + "if (force === true) {\n", + " display_loaded();\n", + " }} else if (Date.now() < root._bokeh_timeout) {\n", + " setTimeout(run_inline_js, 100);\n", + " } else if (!root._bokeh_failed_load) {\n", + " console.log(\"Bokeh: BokehJS failed to load within specified timeout.\");\n", + " root._bokeh_failed_load = true;\n", + " } else if (force !== true) {\n", + " const cell = $(document.getElementById(\"b627ae3b-1db0-4fe3-8762-32a285a44007\")).parents('.cell').data().cell;\n", + " cell.output_area.append_execute_result(NB_LOAD_WARNING)\n", + " }\n", + " }\n", + "\n", + " if (root._bokeh_is_loading === 0) {\n", + " console.debug(\"Bokeh: BokehJS loaded, going straight to plotting\");\n", + " run_inline_js();\n", + " } else {\n", + " load_libs(css_urls, js_urls, function() {\n", + " console.debug(\"Bokeh: BokehJS plotting callback run at\", now());\n", + " run_inline_js();\n", + " });\n", + " }\n", + "}(window));" + ], + "application/vnd.bokehjs_load.v0+json": "(function(root) {\n function now() {\n return new Date();\n }\n\n const force = true;\n\n if (typeof root._bokeh_onload_callbacks === \"undefined\" || force === true) {\n root._bokeh_onload_callbacks = [];\n root._bokeh_is_loading = undefined;\n }\n\n\n if (typeof (root._bokeh_timeout) === \"undefined\" || force === true) {\n root._bokeh_timeout = Date.now() + 5000;\n root._bokeh_failed_load = false;\n }\n\n const NB_LOAD_WARNING = {'data': {'text/html':\n \"
\\n\"+\n \"

\\n\"+\n \"BokehJS does not appear to have successfully loaded. If loading BokehJS from CDN, this \\n\"+\n \"may be due to a slow or bad network connection. Possible fixes:\\n\"+\n \"

\\n\"+\n \"
    \\n\"+\n \"
  • re-rerun `output_notebook()` to attempt to load from CDN again, or
    • \\n\"+\n \"
  • use INLINE resources instead, as so:
    • \\n\"+\n \"
\\n\"+\n \"\\n\"+\n \"from bokeh.resources import INLINE\\n\"+\n \"output_notebook(resources=INLINE)\\n\"+\n \"\\n\"+\n \"
\"}};\n\n function display_loaded() {\n const el = document.getElementById(\"b627ae3b-1db0-4fe3-8762-32a285a44007\");\n if (el != null) {\n el.textContent = \"BokehJS is loading...\";\n }\n if (root.Bokeh !== undefined) {\n if (el != null) {\n el.textContent = \"BokehJS \" + root.Bokeh.version + \" successfully loaded.\";\n }\n } else if (Date.now() < root._bokeh_timeout) {\n setTimeout(display_loaded, 100)\n }\n }\n\n function run_callbacks() {\n try {\n root._bokeh_onload_callbacks.forEach(function(callback) {\n if (callback != null)\n callback();\n });\n } finally {\n delete root._bokeh_onload_callbacks\n }\n console.debug(\"Bokeh: all callbacks have finished\");\n }\n\n function load_libs(css_urls, js_urls, callback) {\n if (css_urls == null) css_urls = [];\n if (js_urls == null) js_urls = [];\n\n root._bokeh_onload_callbacks.push(callback);\n if (root._bokeh_is_loading > 0) {\n console.debug(\"Bokeh: BokehJS is being loaded, scheduling callback at\", now());\n return null;\n }\n if (js_urls == null || js_urls.length === 0) {\n run_callbacks();\n return null;\n }\n console.debug(\"Bokeh: BokehJS not loaded, scheduling load and callback at\", now());\n root._bokeh_is_loading = css_urls.length + js_urls.length;\n\n function on_load() {\n root._bokeh_is_loading--;\n if (root._bokeh_is_loading === 0) {\n console.debug(\"Bokeh: all BokehJS libraries/stylesheets loaded\");\n run_callbacks()\n }\n }\n\n function on_error(url) {\n console.error(\"failed to load \" + url);\n }\n\n for (let i = 0; i < css_urls.length; i++) {\n const url = css_urls[i];\n const element = document.createElement(\"link\");\n element.onload = on_load;\n element.onerror = on_error.bind(null, url);\n element.rel = \"stylesheet\";\n element.type = \"text/css\";\n element.href = url;\n console.debug(\"Bokeh: injecting link tag for BokehJS stylesheet: \", url);\n document.body.appendChild(element);\n }\n\n for (let i = 0; i < js_urls.length; i++) {\n const url = js_urls[i];\n const element = document.createElement('script');\n element.onload = on_load;\n element.onerror = on_error.bind(null, url);\n element.async = false;\n element.src = url;\n console.debug(\"Bokeh: injecting script tag for BokehJS library: \", url);\n document.head.appendChild(element);\n }\n };\n\n function inject_raw_css(css) {\n const element = document.createElement(\"style\");\n element.appendChild(document.createTextNode(css));\n document.body.appendChild(element);\n }\n\n const js_urls = [\"https://cdn.bokeh.org/bokeh/release/bokeh-3.3.4.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-gl-3.3.4.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-widgets-3.3.4.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-tables-3.3.4.min.js\", \"https://cdn.bokeh.org/bokeh/release/bokeh-mathjax-3.3.4.min.js\"];\n const css_urls = [];\n\n const inline_js = [ function(Bokeh) {\n Bokeh.set_log_level(\"info\");\n },\nfunction(Bokeh) {\n }\n ];\n\n function run_inline_js() {\n if (root.Bokeh !== undefined || force === true) {\n for (let i = 0; i < inline_js.length; i++) {\n inline_js[i].call(root, root.Bokeh);\n }\nif (force === true) {\n display_loaded();\n }} else if (Date.now() < root._bokeh_timeout) {\n setTimeout(run_inline_js, 100);\n } else if (!root._bokeh_failed_load) {\n console.log(\"Bokeh: BokehJS failed to load within specified timeout.\");\n root._bokeh_failed_load = true;\n } else if (force !== true) {\n const cell = $(document.getElementById(\"b627ae3b-1db0-4fe3-8762-32a285a44007\")).parents('.cell').data().cell;\n cell.output_area.append_execute_result(NB_LOAD_WARNING)\n }\n }\n\n if (root._bokeh_is_loading === 0) {\n console.debug(\"Bokeh: BokehJS loaded, going straight to plotting\");\n run_inline_js();\n } else {\n load_libs(css_urls, js_urls, function() {\n console.debug(\"Bokeh: BokehJS plotting callback run at\", now());\n run_inline_js();\n });\n }\n}(window));" + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/html": [ + "\n", + "
\n" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "application/javascript": [ + "(function(root) {\n", + " function embed_document(root) {\n", + " const docs_json = {\"6c86f57c-0f70-4648-a27e-ed2b73c3308b\":{\"version\":\"3.3.4\",\"title\":\"Bokeh Application\",\"roots\":[{\"type\":\"object\",\"name\":\"Figure\",\"id\":\"p1001\",\"attributes\":{\"width\":700,\"x_range\":{\"type\":\"object\",\"name\":\"DataRange1d\",\"id\":\"p1002\"},\"y_range\":{\"type\":\"object\",\"name\":\"DataRange1d\",\"id\":\"p1003\"},\"x_scale\":{\"type\":\"object\",\"name\":\"LinearScale\",\"id\":\"p1011\"},\"y_scale\":{\"type\":\"object\",\"name\":\"LinearScale\",\"id\":\"p1012\"},\"title\":{\"type\":\"object\",\"name\":\"Title\",\"id\":\"p1004\",\"attributes\":{\"text\":\"Population, total (World Bank)\",\"text_font_size\":\"12pt\"}},\"renderers\":[{\"type\":\"object\",\"name\":\"GlyphRenderer\",\"id\":\"p1040\",\"attributes\":{\"data_source\":{\"type\":\"object\",\"name\":\"ColumnDataSource\",\"id\":\"p1034\",\"attributes\":{\"selected\":{\"type\":\"object\",\"name\":\"Selection\",\"id\":\"p1035\",\"attributes\":{\"indices\":[],\"line_indices\":[]}},\"selection_policy\":{\"type\":\"object\",\"name\":\"UnionRenderers\",\"id\":\"p1036\"},\"data\":{\"type\":\"map\",\"entries\":[[\"x\",{\"type\":\"ndarray\",\"array\":[\"1960\",\"1961\",\"1962\",\"1963\",\"1964\",\"1965\",\"1966\",\"1967\",\"1968\",\"1969\",\"1970\",\"1971\",\"1972\",\"1973\",\"1974\",\"1975\",\"1976\",\"1977\",\"1978\",\"1979\",\"1980\",\"1981\",\"1982\",\"1983\",\"1984\",\"1985\",\"1986\",\"1987\",\"1988\",\"1989\",\"1990\",\"1991\",\"1992\",\"1993\",\"1994\",\"1995\",\"1996\",\"1997\",\"1998\",\"1999\",\"2000\",\"2001\",\"2002\",\"2003\",\"2004\",\"2005\",\"2006\",\"2007\",\"2008\",\"2009\",\"2010\",\"2011\",\"2012\",\"2013\",\"2014\",\"2015\",\"2016\",\"2017\",\"2018\",\"2019\",\"2020\",\"2021\",\"2022\"],\"shape\":[63],\"dtype\":\"object\",\"order\":\"little\"}],[\"y\",{\"type\":\"ndarray\",\"array\":{\"type\":\"bytes\",\"data\":\"7dgIxOtFUkDH2t/ZHtVSQCtLdJZZZlNAHaz/c5j6U0Bx5eyd0ZBUQJl+iXjrJ1VA16Gakqy+VUAdzCbAsFRWQDSBIhYx6lZAjKIHPgaAV0DpJjEIrBdYQE7U0twKsVhAeSKI83BMWUCVZB2OrupZQAiRDDm2ilpA4NbdPNUsW0AVi98UVtJbQPj9mxcnfFxARYMUPIUqXUDGGcOcoNxdQDtu+N10kl5AAvG6fsFKX0BDBBxCFQJgQO5Cc51GX2BAFNBE2HC8YEAz3IDPDxlhQPuWOV2WdGFAq+l6ouvOYUAlIvyLIChiQEuuYvEbgGJAe0ykNJvWYkDj/E0oxCpjQAvSjEXTfGNA+FPjpRvOY0CZ1NAGYB9kQNJWJZF9cGRAyv55GjDBZEDRr62ffhFlQADICRNGYWVAUfUrnY+vZUCOO6WD9ftlQJq0qbrHRmZAza/mAEGPZkD0wp0LI9RmQMnp6/kaF2dApb+XwoNZZ0BPzeUGQ5pnQJz4akfx2GdAb/HwnoMVaEB7ouvCj1BoQLlsdM5Pi2hARbx1/u3FaEBAwjBgSf9oQKCKG7cYN2lAaLPqc7VuaUAz/n3GBaZpQI7LuKmB22lAObnfoSgQakDP+L64VEVqQEHYKVYNeWpAXoJTH0imakB/hjdrcMpqQJEr9SwI6mpA\"},\"shape\":[63],\"dtype\":\"float64\",\"order\":\"little\"}]]}}},\"view\":{\"type\":\"object\",\"name\":\"CDSView\",\"id\":\"p1041\",\"attributes\":{\"filter\":{\"type\":\"object\",\"name\":\"AllIndices\",\"id\":\"p1042\"}}},\"glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1037\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#3288bd\",\"line_width\":2}},\"nonselection_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1038\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#3288bd\",\"line_alpha\":0.1,\"line_width\":2}},\"muted_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1039\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#3288bd\",\"line_alpha\":0.2,\"line_width\":2}}}},{\"type\":\"object\",\"name\":\"GlyphRenderer\",\"id\":\"p1051\",\"attributes\":{\"data_source\":{\"type\":\"object\",\"name\":\"ColumnDataSource\",\"id\":\"p1045\",\"attributes\":{\"selected\":{\"type\":\"object\",\"name\":\"Selection\",\"id\":\"p1046\",\"attributes\":{\"indices\":[],\"line_indices\":[]}},\"selection_policy\":{\"type\":\"object\",\"name\":\"UnionRenderers\",\"id\":\"p1047\"},\"data\":{\"type\":\"map\",\"entries\":[[\"x\",{\"type\":\"ndarray\",\"array\":[\"1960\",\"1961\",\"1962\",\"1963\",\"1964\",\"1965\",\"1966\",\"1967\",\"1968\",\"1969\",\"1970\",\"1971\",\"1972\",\"1973\",\"1974\",\"1975\",\"1976\",\"1977\",\"1978\",\"1979\",\"1980\",\"1981\",\"1982\",\"1983\",\"1984\",\"1985\",\"1986\",\"1987\",\"1988\",\"1989\",\"1990\",\"1991\",\"1992\",\"1993\",\"1994\",\"1995\",\"1996\",\"1997\",\"1998\",\"1999\",\"2000\",\"2001\",\"2002\",\"2003\",\"2004\",\"2005\",\"2006\",\"2007\",\"2008\",\"2009\",\"2010\",\"2011\",\"2012\",\"2013\",\"2014\",\"2015\",\"2016\",\"2017\",\"2018\",\"2019\",\"2020\",\"2021\",\"2022\"],\"shape\":[63],\"dtype\":\"object\",\"order\":\"little\"}],[\"y\",{\"type\":\"ndarray\",\"array\":{\"type\":\"bytes\",\"data\":\"w/UoXI/YhEBxPQrXo6KEQFyPwvUozoRASOF6FK5ShUCkcD0K19KFQBSuR+F6WYZAMzMzMzP7hkBmZmZmZpSHQK5H4XoUNIhAMzMzMzPgiEDsUbgehZKJQKRwPQrXSIpACtejcD3wikDsUbgehY+LQM3MzMzMIoxAXI/C9SijjEAUrkfhehWNQHE9Cteje41AuB6F61HhjUDXo3A9CkiOQHsUrkfhqY5ArkfhehQPj0DXo3A9CoWPQBSuR+F6+o9AzczMzEwzkEBcj8L1KGyQQFyPwvUoq5BAcT0K1yPwkEDsUbgehTaRQJqZmZmZepFACtejcL28kUCF61G4HvuRQHsUrkfhM5JA9ihcj8JpkkCkcD0KV5+SQFK4HoVr05JAMzMzMzMGk0DNzMzMTDiTQArXo3C9Z5NAPQrXo/CSk0CuR+F6lLqTQGZmZmZm35NAmpmZmZkBlECamZmZmSGUQM3MzMxMQJRAexSuR+FelECuR+F6FHyUQNejcD2Kl5RAhetRuJ6ylEDXo3A9Cs2UQLgehevR5pRAcT0K1yMElUD2KFyPwiiVQClcj8L1TJVAPQrXo3BvlUA9CtejcI+VQFyPwvUor5VAj8L1KNzQlUDXo3A9CuuVQBSuR+H6/pVAZmZmZmYMlkA9CtejcBGWQDMzMzOzEJZA\"},\"shape\":[63],\"dtype\":\"float64\",\"order\":\"little\"}]]}}},\"view\":{\"type\":\"object\",\"name\":\"CDSView\",\"id\":\"p1052\",\"attributes\":{\"filter\":{\"type\":\"object\",\"name\":\"AllIndices\",\"id\":\"p1053\"}}},\"glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1048\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#99d594\",\"line_width\":2}},\"nonselection_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1049\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#99d594\",\"line_alpha\":0.1,\"line_width\":2}},\"muted_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1050\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#99d594\",\"line_alpha\":0.2,\"line_width\":2}}}},{\"type\":\"object\",\"name\":\"GlyphRenderer\",\"id\":\"p1061\",\"attributes\":{\"data_source\":{\"type\":\"object\",\"name\":\"ColumnDataSource\",\"id\":\"p1055\",\"attributes\":{\"selected\":{\"type\":\"object\",\"name\":\"Selection\",\"id\":\"p1056\",\"attributes\":{\"indices\":[],\"line_indices\":[]}},\"selection_policy\":{\"type\":\"object\",\"name\":\"UnionRenderers\",\"id\":\"p1057\"},\"data\":{\"type\":\"map\",\"entries\":[[\"x\",{\"type\":\"ndarray\",\"array\":[\"1960\",\"1961\",\"1962\",\"1963\",\"1964\",\"1965\",\"1966\",\"1967\",\"1968\",\"1969\",\"1970\",\"1971\",\"1972\",\"1973\",\"1974\",\"1975\",\"1976\",\"1977\",\"1978\",\"1979\",\"1980\",\"1981\",\"1982\",\"1983\",\"1984\",\"1985\",\"1986\",\"1987\",\"1988\",\"1989\",\"1990\",\"1991\",\"1992\",\"1993\",\"1994\",\"1995\",\"1996\",\"1997\",\"1998\",\"1999\",\"2000\",\"2001\",\"2002\",\"2003\",\"2004\",\"2005\",\"2006\",\"2007\",\"2008\",\"2009\",\"2010\",\"2011\",\"2012\",\"2013\",\"2014\",\"2015\",\"2016\",\"2017\",\"2018\",\"2019\",\"2020\",\"2021\",\"2022\"],\"shape\":[63],\"dtype\":\"object\",\"order\":\"little\"}],[\"y\",{\"type\":\"ndarray\",\"array\":{\"type\":\"bytes\",\"data\":\"LSeh9EXfe0D1g7pIoYV8QK38MhhjMH1Ayv55GvDefUC8df7t8pB+QNumeFzUQX9AQgddwuHvf0Aqj26E5U+AQMmutIx0q4BAQni0cYQKgUCeQxmqAmyBQBAHCVH+z4FAcy8wK7Q2gkACDwwg3KCCQITyPo7GDYNAiSe7mTF8g0DC3sSQnOuDQMZpiCp8XYRAatlaXyTShEAP7zmw/EmFQPqbUIigxoVA04OCUvRGhkBGfv0QW8mGQB41JsScTodAjIaMRynXh0AUd7zJ72GIQE5jey0I74hAyXa+n7p9iUAa/P1i1g2KQFZETfQZoIpAK/uuCJ4zi0B/pl63iMeLQGmKAKeXXIxAdzHNdM/yjEBol299GIqNQOwy/Kc7Io5AXwg57z+6jkAb9RCNrlKPQANd+wJ6649A8OAnDgBCkEAsZRniiI6QQNTRcTXi25BAfa1LjUApkUBF8wAWqXWRQE+Q2O4OwZFAH9rHCo4KkkCNDkjCflGSQFAYlGnElpJAnuv7cPDakkDUYBqGjx6TQLAgzVh0YpNAR1Z+GXymk0B8LH3o8umTQAzohTuHLJRArvTabPxslEBIMxZNd6uUQIyEtpyL6pRA7YFWYMgolUCG56ViA2SVQBE2PL1ynJVAmDEFa4zRlUByGMxfQf6VQDNOQ1SxJJZA\"},\"shape\":[63],\"dtype\":\"float64\",\"order\":\"little\"}]]}}},\"view\":{\"type\":\"object\",\"name\":\"CDSView\",\"id\":\"p1062\",\"attributes\":{\"filter\":{\"type\":\"object\",\"name\":\"AllIndices\",\"id\":\"p1063\"}}},\"glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1058\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#e6f598\",\"line_width\":2}},\"nonselection_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1059\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#e6f598\",\"line_alpha\":0.1,\"line_width\":2}},\"muted_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1060\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#e6f598\",\"line_alpha\":0.2,\"line_width\":2}}}},{\"type\":\"object\",\"name\":\"GlyphRenderer\",\"id\":\"p1071\",\"attributes\":{\"data_source\":{\"type\":\"object\",\"name\":\"ColumnDataSource\",\"id\":\"p1065\",\"attributes\":{\"selected\":{\"type\":\"object\",\"name\":\"Selection\",\"id\":\"p1066\",\"attributes\":{\"indices\":[],\"line_indices\":[]}},\"selection_policy\":{\"type\":\"object\",\"name\":\"UnionRenderers\",\"id\":\"p1067\"},\"data\":{\"type\":\"map\",\"entries\":[[\"x\",{\"type\":\"ndarray\",\"array\":[\"1960\",\"1961\",\"1962\",\"1963\",\"1964\",\"1965\",\"1966\",\"1967\",\"1968\",\"1969\",\"1970\",\"1971\",\"1972\",\"1973\",\"1974\",\"1975\",\"1976\",\"1977\",\"1978\",\"1979\",\"1980\",\"1981\",\"1982\",\"1983\",\"1984\",\"1985\",\"1986\",\"1987\",\"1988\",\"1989\",\"1990\",\"1991\",\"1992\",\"1993\",\"1994\",\"1995\",\"1996\",\"1997\",\"1998\",\"1999\",\"2000\",\"2001\",\"2002\",\"2003\",\"2004\",\"2005\",\"2006\",\"2007\",\"2008\",\"2009\",\"2010\",\"2011\",\"2012\",\"2013\",\"2014\",\"2015\",\"2016\",\"2017\",\"2018\",\"2019\",\"2020\",\"2021\",\"2022\"],\"shape\":[63],\"dtype\":\"object\",\"order\":\"little\"}],[\"y\",{\"type\":\"ndarray\",\"array\":{\"type\":\"bytes\",\"data\":\"xSCwcmj5XUDJdr6fGk9eQOf7qfHSpV5APQrXo3D9XkCuR+F6FFZfQEjhehSur19Ay6FFtvPdX0CDwMqhRQZgQARWDi2yHWBAaJHtfD81YECwcmiR7UxgQClcj8L1ZGBADAIrhxZ9YEDFILByaJVgQOf7qfHSrWBAZmZmZmbGYEBiEFg5tORgQDMzMzMzA2FAUrgeheshYUC+nxov3UBhQLgehetRYGFAJzEIrBx+YUB1kxgEVpphQEw3iUFgtWFApHA9CtfXYUD6fmq8dPthQPhT46WbHGJAkxgEVg49YkCBlUOLbFtiQFCNl24Sd2JAbjDUYQV/YkDrcd9qnYxiQMU56ug4kWJABmUaTa6OYkCsdHedDY1iQGJodXIGjGJAhUTaxh+FYkAV4SajSn1iQMPVARB3dWJA5/7qcd9mYkDhXwSNGVNiQD/kLVc/P2JAT+rL0s4pYkAaM4l6wRRiQOxP4nMnAmJAn1bRH5rwYUB9dVWgluFhQKhxb37D2WFAMnVXdsHXYUBI3jmUIdlhQPTfg9cu22FA304iwr/eYUBTPZl/dOZhQIkHlE058GFAidNJtjr6YUDVPh2PGQNiQPSnjer0CmJAuvQvSeUPYkAtI/WeSg9iQH2UERcADWJA/aGZJ1cCYkDvVpboLARiQPvKg/SUB2JA\"},\"shape\":[63],\"dtype\":\"float64\",\"order\":\"little\"}]]}}},\"view\":{\"type\":\"object\",\"name\":\"CDSView\",\"id\":\"p1072\",\"attributes\":{\"filter\":{\"type\":\"object\",\"name\":\"AllIndices\",\"id\":\"p1073\"}}},\"glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1068\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#fee08b\",\"line_width\":2}},\"nonselection_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1069\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#fee08b\",\"line_alpha\":0.1,\"line_width\":2}},\"muted_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1070\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#fee08b\",\"line_alpha\":0.2,\"line_width\":2}}}},{\"type\":\"object\",\"name\":\"GlyphRenderer\",\"id\":\"p1081\",\"attributes\":{\"data_source\":{\"type\":\"object\",\"name\":\"ColumnDataSource\",\"id\":\"p1075\",\"attributes\":{\"selected\":{\"type\":\"object\",\"name\":\"Selection\",\"id\":\"p1076\",\"attributes\":{\"indices\":[],\"line_indices\":[]}},\"selection_policy\":{\"type\":\"object\",\"name\":\"UnionRenderers\",\"id\":\"p1077\"},\"data\":{\"type\":\"map\",\"entries\":[[\"x\",{\"type\":\"ndarray\",\"array\":[\"1960\",\"1961\",\"1962\",\"1963\",\"1964\",\"1965\",\"1966\",\"1967\",\"1968\",\"1969\",\"1970\",\"1971\",\"1972\",\"1973\",\"1974\",\"1975\",\"1976\",\"1977\",\"1978\",\"1979\",\"1980\",\"1981\",\"1982\",\"1983\",\"1984\",\"1985\",\"1986\",\"1987\",\"1988\",\"1989\",\"1990\",\"1991\",\"1992\",\"1993\",\"1994\",\"1995\",\"1996\",\"1997\",\"1998\",\"1999\",\"2000\",\"2001\",\"2002\",\"2003\",\"2004\",\"2005\",\"2006\",\"2007\",\"2008\",\"2009\",\"2010\",\"2011\",\"2012\",\"2013\",\"2014\",\"2015\",\"2016\",\"2017\",\"2018\",\"2019\",\"2020\",\"2021\",\"2022\"],\"shape\":[63],\"dtype\":\"object\",\"order\":\"little\"}],[\"y\",{\"type\":\"ndarray\",\"array\":{\"type\":\"bytes\",\"data\":\"X38SnzuFMEDBkUCDTf0wQNKJBFPNgDFAkGYsms4KMkDTUKOQZJoyQOcBLPLrLzNAR1Sobi7KM0AqOLwgImk0QM0jfzDwDDVApmJjXke0NUCr61BNSV42QOjAcoQMCDdA7gbRWtGyN0B7Szlf7GE4QMxEEVK3EzlAIXcRpijHOUDQRNjw9Ho6QIB/SpUoMztAIZOMnIXxO0Cp2m6Cb7I8QPAXsyWrdj1AN1MhHok7PkDb39kevQU/QLtIoSx83T9Adcdim1RiQEBdiNUfYeBAQI+oUN1ccEFAsirCTUYPQkA7N23GabJCQOKt82+XVUNAsfm4NlTwQ0CZf/RNmnREQF6iemtg4URAUAEwnkFDRUBW9fI7TaJFQO+NIQA4/kVAvvc3aK9URkAm5e5zfKRGQK5hhsYT7UZAfTz03a0uR0BweawZGWhHQHi3skRnnUdATuyhfazUR0Brm+JxUQ1IQISgo1UtR0hAvRx23zGCSEBPzlDc8b5IQPTeGAKA/0hAmdcRh2xISUD76xUW3JVJQMh4lEp45ElA5j+k3744SkCe6/twkJJKQJShKqbS70pAzuFa7WFdS0AWaHdIMfBLQL75DRMNNkxAUHPyIhNSTEDayeAoeatMQAX6RJ4kC01Aw2M/i6VmTUCjWG5pNbJNQEax3NJq8k1A\"},\"shape\":[63],\"dtype\":\"float64\",\"order\":\"little\"}]]}}},\"view\":{\"type\":\"object\",\"name\":\"CDSView\",\"id\":\"p1082\",\"attributes\":{\"filter\":{\"type\":\"object\",\"name\":\"AllIndices\",\"id\":\"p1083\"}}},\"glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1078\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#fc8d59\",\"line_width\":2}},\"nonselection_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1079\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#fc8d59\",\"line_alpha\":0.1,\"line_width\":2}},\"muted_glyph\":{\"type\":\"object\",\"name\":\"Line\",\"id\":\"p1080\",\"attributes\":{\"x\":{\"type\":\"field\",\"field\":\"x\"},\"y\":{\"type\":\"field\",\"field\":\"y\"},\"line_color\":\"#fc8d59\",\"line_alpha\":0.2,\"line_width\":2}}}}],\"toolbar\":{\"type\":\"object\",\"name\":\"Toolbar\",\"id\":\"p1010\",\"attributes\":{\"tools\":[{\"type\":\"object\",\"name\":\"PanTool\",\"id\":\"p1023\"},{\"type\":\"object\",\"name\":\"WheelZoomTool\",\"id\":\"p1024\",\"attributes\":{\"renderers\":\"auto\"}},{\"type\":\"object\",\"name\":\"BoxZoomTool\",\"id\":\"p1025\",\"attributes\":{\"overlay\":{\"type\":\"object\",\"name\":\"BoxAnnotation\",\"id\":\"p1026\",\"attributes\":{\"syncable\":false,\"level\":\"overlay\",\"visible\":false,\"left\":{\"type\":\"number\",\"value\":\"nan\"},\"right\":{\"type\":\"number\",\"value\":\"nan\"},\"top\":{\"type\":\"number\",\"value\":\"nan\"},\"bottom\":{\"type\":\"number\",\"value\":\"nan\"},\"left_units\":\"canvas\",\"right_units\":\"canvas\",\"top_units\":\"canvas\",\"bottom_units\":\"canvas\",\"line_color\":\"black\",\"line_alpha\":1.0,\"line_width\":2,\"line_dash\":[4,4],\"fill_color\":\"lightgrey\",\"fill_alpha\":0.5}}}},{\"type\":\"object\",\"name\":\"SaveTool\",\"id\":\"p1031\"},{\"type\":\"object\",\"name\":\"ResetTool\",\"id\":\"p1032\"},{\"type\":\"object\",\"name\":\"HelpTool\",\"id\":\"p1033\"}]}},\"left\":[{\"type\":\"object\",\"name\":\"LinearAxis\",\"id\":\"p1018\",\"attributes\":{\"ticker\":{\"type\":\"object\",\"name\":\"BasicTicker\",\"id\":\"p1019\",\"attributes\":{\"mantissas\":[1,2,5]}},\"formatter\":{\"type\":\"object\",\"name\":\"BasicTickFormatter\",\"id\":\"p1020\"},\"axis_label\":\"Population, total (in millions)\",\"major_label_policy\":{\"type\":\"object\",\"name\":\"AllLabels\",\"id\":\"p1021\"}}}],\"below\":[{\"type\":\"object\",\"name\":\"LinearAxis\",\"id\":\"p1013\",\"attributes\":{\"ticker\":{\"type\":\"object\",\"name\":\"BasicTicker\",\"id\":\"p1014\",\"attributes\":{\"mantissas\":[1,2,5]}},\"formatter\":{\"type\":\"object\",\"name\":\"BasicTickFormatter\",\"id\":\"p1015\"},\"axis_label\":\"Year\",\"major_label_policy\":{\"type\":\"object\",\"name\":\"AllLabels\",\"id\":\"p1016\"}}}],\"center\":[{\"type\":\"object\",\"name\":\"Grid\",\"id\":\"p1017\",\"attributes\":{\"axis\":{\"id\":\"p1013\"}}},{\"type\":\"object\",\"name\":\"Grid\",\"id\":\"p1022\",\"attributes\":{\"dimension\":1,\"axis\":{\"id\":\"p1018\"}}},{\"type\":\"object\",\"name\":\"Legend\",\"id\":\"p1043\",\"attributes\":{\"location\":\"right\",\"click_policy\":\"mute\",\"items\":[{\"type\":\"object\",\"name\":\"LegendItem\",\"id\":\"p1044\",\"attributes\":{\"label\":{\"type\":\"value\",\"value\":\"BRA\"},\"renderers\":[{\"id\":\"p1040\"}]}},{\"type\":\"object\",\"name\":\"LegendItem\",\"id\":\"p1054\",\"attributes\":{\"label\":{\"type\":\"value\",\"value\":\"CHN\"},\"renderers\":[{\"id\":\"p1051\"}]}},{\"type\":\"object\",\"name\":\"LegendItem\",\"id\":\"p1064\",\"attributes\":{\"label\":{\"type\":\"value\",\"value\":\"IND\"},\"renderers\":[{\"id\":\"p1061\"}]}},{\"type\":\"object\",\"name\":\"LegendItem\",\"id\":\"p1074\",\"attributes\":{\"label\":{\"type\":\"value\",\"value\":\"RUS\"},\"renderers\":[{\"id\":\"p1071\"}]}},{\"type\":\"object\",\"name\":\"LegendItem\",\"id\":\"p1084\",\"attributes\":{\"label\":{\"type\":\"value\",\"value\":\"ZAF\"},\"renderers\":[{\"id\":\"p1081\"}]}}]}}]}}]}};\n", + " const render_items = [{\"docid\":\"6c86f57c-0f70-4648-a27e-ed2b73c3308b\",\"roots\":{\"p1001\":\"d2127207-0be3-46fb-86fa-2b57704ab0fc\"},\"root_ids\":[\"p1001\"]}];\n", + " root.Bokeh.embed.embed_items_notebook(docs_json, render_items);\n", + " }\n", + " if (root.Bokeh !== undefined) {\n", + " embed_document(root);\n", + " } else {\n", + " let attempts = 0;\n", + " const timer = setInterval(function(root) {\n", + " if (root.Bokeh !== undefined) {\n", + " clearInterval(timer);\n", + " embed_document(root);\n", + " } else {\n", + " attempts++;\n", + " if (attempts > 100) {\n", + " clearInterval(timer);\n", + " console.log(\"Bokeh: ERROR: Unable to run BokehJS code because BokehJS library is missing\");\n", + " }\n", + " }\n", + " }, 10, root)\n", + " }\n", + "})(window);" + ], + "application/vnd.bokehjs_exec.v0+json": "" + }, + "metadata": { + "application/vnd.bokehjs_exec.v0+json": { + "id": "p1001" + } + }, + "output_type": "display_data" + } + ], + "source": [ + "output_notebook()\n", + "\n", + "p = figure(title=\"Population, total (World Bank)\", width=700, height=600)\n", + "\n", + "# colors\n", + "colors = itertools.cycle(Spectral6)\n", + "\n", + "# plotting the line graph\n", + "for column, color in zip(df.columns, colors):\n", + " p.line(\n", + " df.index,\n", + " df[column],\n", + " legend_label=column,\n", + " color=color,\n", + " line_width=2,\n", + " )\n", + "\n", + "p.legend.location = \"right\"\n", + "p.legend.click_policy = \"mute\"\n", + "p.title.text_font_size = \"12pt\"\n", + "\n", + "p.xaxis.axis_label = \"Year\"\n", + "p.yaxis.axis_label = \"Population, total (in millions)\"\n", + "\n", + "show(p)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.13" + }, + "vscode": { + "interpreter": { + "hash": "b6702b69e93007336b96338c5a331192f07cedff01d36d4dcfa0f842adb718ad" + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/world-bank-package.ipynb b/notebooks/world-bank-package.ipynb new file mode 100644 index 0000000..bee34a8 --- /dev/null +++ b/notebooks/world-bank-package.ipynb @@ -0,0 +1,281 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "90700fdc-fcc7-4e54-8c9e-449879d8c66d", + "metadata": { + "tags": [] + }, + "source": [ + "# Python Package Example\n", + "\n", + "> The following is an example of on how to use and distribute your project as a [Python package](https://packaging.python.org) using the example template. Remember mix and match to yout project's requirements. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "ef92b033-81e2-4c5f-b56a-63f4f7a37247", + "metadata": { + "editable": true, + "slideshow": { + "slide_type": "" + }, + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "import itertools\n", + "\n", + "from bokeh.palettes import Spectral6\n", + "from bokeh.plotting import figure, output_notebook, show" + ] + }, + { + "cell_type": "markdown", + "id": "14e89727", + "metadata": {}, + "source": [ + "## Usage" + ] + }, + { + "cell_type": "markdown", + "id": "b4c0f3e8-7756-41bb-aa21-cc2eee5ff67f", + "metadata": {}, + "source": [ + "Unlike the [previous example](https://worldbank.github.io/template/notebooks/world-bank-api.html), where the source code was contained on the Jupyter notebok itself, we (re)use a Python package - the [template](https://github.com/worldbank/template/tree/main/src/template) Python package - which will let us (re)use any attributes and methods in the following example.\n", + "\n", + "Let's start by importing `WorldBankIndicatorsAPI`, a Python API wrapper class created to facilitate the usage of the [World Bank Indicators API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d797ef77-6ca4-4f9d-a1f8-abbfd9884b07", + "metadata": {}, + "outputs": [], + "source": [ + "from template.indicators import WorldBankIndicatorsAPI" + ] + }, + { + "cell_type": "markdown", + "id": "17f380e4-3854-4af6-940c-7afe9723a59a", + "metadata": {}, + "source": [ + "Let's continue by creating the API object. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f911a5c3-6994-45a6-a049-4b398f5890c0", + "metadata": {}, + "outputs": [], + "source": [ + "api = WorldBankIndicatorsAPI()" + ] + }, + { + "cell_type": "markdown", + "id": "7fa96741-f4cd-4504-a5f8-6467f9a2345e", + "metadata": {}, + "source": [ + "The `api` wrapper object is now ready to use! We will invoke its `query` method to retrieve data from the [World Bank Indicators API](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation). To learn how to use it, such as information about method signature, valid parameters and return value, we read `help`. Since [PEP 257](https://peps.python.org/pep-0257), Python offers *doctrings*, which are an easy and standard to create code documentation and it is a good practice adopt it. Documentating the source code is crucial to create a maintainable reliable and reproducicle code base and project.\n", + "\n", + "Let's see the `query` method's *docstring* as shown below." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "fb6ca314-d161-40e1-a376-a3013a0711eb", + "metadata": {}, + "outputs": [], + "source": [ + "help(api.query)" + ] + }, + { + "cell_type": "markdown", + "id": "e82fc342-165d-42d6-b3dc-7534c215ca1f", + "metadata": {}, + "source": [ + "The `query` method allows us to select an **indicator** (e.g, [World Development Indicators](https://datatopics.worldbank.org/world-development-indicators)), a list of countries and [query parameters](https://datahelpdesk.worldbank.org/knowledgebase/articles/898581#query-strings). Note that contrary to the [previous example](https://worldbank.github.io/template/notebooks/world-bank-api.html), the method expects a list of country names and converts them to [ISO 3166-1 alpha-3](https://www.iso.org/iso-3166-country-codes.html) automatically." + ] + }, + { + "cell_type": "markdown", + "id": "23b0a1eb-73c1-42e7-8903-98e362ef86de", + "metadata": {}, + "source": [ + "Let's invoke the `query` method and retrieve the results for `SP.POP.TOTL` for the [BRICS](https://infobrics.org) (as before)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "7fb7daea-c5cf-42ea-b746-a565dd9ac4e1", + "metadata": {}, + "outputs": [], + "source": [ + "df = api.query(\n", + " \"SP.POP.TOTL\", country=[\"Brazil\", \"China\", \"India\", \"Russia\", \"South Africa\"]\n", + ")" + ] + }, + { + "cell_type": "markdown", + "id": "46662c1b-4c19-424b-8a61-f651cb486c5b", + "metadata": {}, + "source": [ + "**Voilร !** We just (re)used the [template](https://github.com/worldbank/template/tree/main/src/template) Python package in our example delegating the maintenance and logic, making the notebook easier to understand and reproduce. \n", + "\n", + "```{tip}\n", + "In addition, the `template` makes any Python package automatically [pip installable](https://packaging.python.org/en/latest/tutorials/installing-packages/) and accessible to *anyone* and from *anywhere*!\n", + "\n", + "To install from source:\n", + "\n", + "\tpip install git+https://github.com/worldbank/template.git\n", + "\n", + "To install from version:\n", + "\n", + "\tpip install git+https://github.com/worldbank/template.git@v0.1.0\n", + "\t\n", + "\n", + "When distributing a project release, it is strongly recommended to adhere to release management good practices. It is recommended to create checklists, adopt versioning (e.g, [semantic versioning](https://semver.org/) and to release on [Python Package Index](https://pypi.org/) (instead of GitHub).\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "80887da5-0474-48b3-8c71-fbe3dbd3a8e8", + "metadata": {}, + "source": [ + "```{tip}\n", + "The template will automatically find and install any local `src` packages as long as the `setup.cfg` file is up-to-date.\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "daa4319a-8936-4195-b1fc-aad9c008325b", + "metadata": {}, + "source": [ + "```{caution}\n", + "The `template` Python package should be used for demonstration purposes only. For support, please see the [World Bank Indicators API Documentation](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation).\n", + "```" + ] + }, + { + "cell_type": "markdown", + "id": "e9f14239", + "metadata": {}, + "source": [ + "Finally, let's take a look at the retrieved data." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "b1d7cf70-bf0e-4c12-ae0d-fd26349291db", + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "df = df.pivot_table(values=\"value\", index=\"date\", columns=\"country.value\")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "699a0495-4f06-479c-b517-58336110547f", + "metadata": { + "tags": [ + "output_scroll" + ] + }, + "outputs": [], + "source": [ + "df" + ] + }, + { + "cell_type": "markdown", + "id": "c5daa85a-004d-4e93-be84-72d064d0b83b", + "metadata": {}, + "source": [ + "## Visualization\n", + "\n", + "As before, let's now plot the data as a time series using [Bokeh](https://docs.bokeh.org)." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "60219760", + "metadata": {}, + "outputs": [], + "source": [ + "output_notebook()\n", + "\n", + "# instantiating the figure object\n", + "p = figure(title=\"Population, total (World Bank)\", width=700, height=600)\n", + "\n", + "# colors\n", + "colors = itertools.cycle(Spectral6)\n", + "\n", + "# plotting the line graph\n", + "for column, color in zip(df.columns, colors):\n", + " p.line(\n", + " df.index,\n", + " df[column],\n", + " legend_label=column,\n", + " color=color,\n", + " line_width=2,\n", + " )\n", + "\n", + "p.legend.location = \"right\"\n", + "p.legend.click_policy = \"mute\"\n", + "p.title.text_font_size = \"12pt\"\n", + "\n", + "p.xaxis.axis_label = \"Year\"\n", + "p.yaxis.axis_label = \"Population, total (in millions)\"\n", + "\n", + "show(p)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.13" + }, + "vscode": { + "interpreter": { + "hash": "b6702b69e93007336b96338c5a331192f07cedff01d36d4dcfa0f842adb718ad" + } + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..555153b --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,52 @@ +[build-system] +requires = ["hatchling>=1.21.0", "hatch-vcs>=0.3.0"] +build-backend = "hatchling.build" + +[project] +name = "template" +description = "A template Python package from the World Bank Data Lab" +readme = { file = "README.md", content-type = "text/markdown" } +license = { file = "LICENSE" } +keywords = ["template", "reproducibility"] +authors = [{ name = "Development Data Group", email = "datalab@worldbank.org" }] +classifiers = [ + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.7", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3 :: Only", + "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)", + "Operating System :: OS Independent", + "Intended Audience :: Developers", + "Topic :: Scientific/Engineering", +] +dynamic = ["version"] + +requires-python = ">=3.7" +dependencies = ["requests>=2.28.1", "pandas>=2", "pycountry>=22.3.5"] +[project.optional-dependencies] +docs = [ + "docutils==0.17.1", # https://jupyterbook.org/en/stable/content/citations.html?highlight=docutils#citations-and-bibliographies + "jupyter-book >=1,<2", +] + +[project.urls] +"Homepage" = "https://github.com/worldbank/template" +"Bug Reports" = "https://github.com/worldbank/template/issues" +"Source" = "https://github.com/worldbank/template" + +[tool.codespell] +skip = 'docs/_build,docs/references.bib,*.png,*.gz,*.whl' +ignore-regex = '^\s*"image\/png":\s.*' +ignore-words-list = "gost," + +[tool.hatch.build.targets.wheel] +packages = ["src/*"] + +[tool.hatch.version] +source = "vcs" + +[tool.ruff.lint.pydocstyle] +convention = "numpy" diff --git a/src/template/__init__.py b/src/template/__init__.py new file mode 100644 index 0000000..a535a10 --- /dev/null +++ b/src/template/__init__.py @@ -0,0 +1,7 @@ +from importlib.metadata import version, PackageNotFoundError + +try: + __version__ = version("datalab") +except PackageNotFoundError: + # package is not installed + pass diff --git a/src/template/indicators.py b/src/template/indicators.py new file mode 100644 index 0000000..b98824f --- /dev/null +++ b/src/template/indicators.py @@ -0,0 +1,83 @@ +import pandas +import pycountry +import requests + + +class WorldBankIndicatorsAPI: + URL = "https://api.worldbank.org/v2/country" + + def _get_country_code(self, country): + """ + Using `pycountry`, return the ISO 3166-1 alpha-3 country code for corresponding query term. + + See also: + https://github.com/flyingcircusio/pycountry + + Parameters + ---------- + country : str + + Returns + ------- + str + ISO 3166-1 alpha-3 country code for corresponding query term. + + Raises + ------ + LookupError + If the query term is not a valid country. + """ + return pycountry.countries.search_fuzzy(country)[0].alpha_3 + + def _get(self, indicator, country: str = "all", params: dict = {}): + """ + Retrieve a response, valid JSON response or error, from the World Bank Indicators API. + + See also: + https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation + + Parameters + ---------- + indicator : str + country : str, optional + params : dict, optional + + Returns + ------- + requests.models.Response + Return JSON response from the World Bank Indicators API. + """ + url = f"{self.URL}/{country}/indicator/{indicator}" + + return requests.get(url, params) + + def query(self, indicator, country: list = "all", params: dict = {}): + """ + Retrieve a response, valid JSON response or error, from the World Bank Indicators API. + + See also: + https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation + + Parameters + ---------- + indicator : str + World Bank API Indicator. + country : list, optional + List of countries. The country name is converted to ISO 3166-1 alpha-3 country code. + params : dict, optional + World Bank API Indicator Query Strings. + + Returns + ------- + pandas.core.frame.DataFrame + Return a Pandas DataFrame obtained with response data from World Bank Indicators API. + """ + if isinstance(country, list): + country = ";".join([self._get_country_code(c) for c in country]) + + params.update({"format": "json", "per_page": 1000}) + + response = self._get(indicator, country, params) + data = response.json()[-1] + + return pandas.json_normalize(data)