Merge pull request #49 from rickecon/tests

Testing, Package, and Documentation updates

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,7 @@
+Thanks for filing an issue! Please remove any top-level headers that do not apply.
+
+# Problem or Error
+Please characterize the problem concisely and precisely. You may want to include error message output, other terminal output, your environment characteristics, and a way to replicate the issue. Let us know what solutions you have tried.
+
+# Question
+Please ask the question with clear context and any potential answer directions you can think of.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+Thanks for contributing! Please remove any top-level sections that do not apply to your changes.
+
+- [ ] `make format` and `make documentation` has been run. (You may also want to run `make test`.)
+
+## What's changed
+
+Description of the changes here.
+
+# Bug fix
+
+- [ ] Continuous integration test added
+- [ ] Continuous integration test passing
+
+## What this fixes and how it's fixed
+
+Description of how this fix works goes here. Link any issues this PR fixes.

.github/workflows/build_and_test.yml

@@ -0,0 +1,47 @@
+name: Build and test [Python 3.9, 3.10]
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.9", "3.10"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Miniconda using Python ${{ matrix.python-version }}
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          miniforge-variant: Mambaforge
+          auto-update-conda: true
+          activate-environment: ogzaf-dev
+          environment-file: environment.yml
+          python-version: ${{ matrix.python-version }}
+          auto-activate-base: false
+
+      - name: Build
+        shell: bash -l {0}
+        run: |
+          pip install -e .
+          pip install pytest-cov
+          pip install pytest-pycodestyle
+      - name: Test
+        shell: bash -l {0}
+        working-directory: ./
+        run: |
+          pytest -m 'not local' --cov=./ --cov-report=xml
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage.xml
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: true
+          verbose: true

.github/workflows/check_black.yml → .github/workflows/check_format.yml

@@ -1,13 +1,13 @@
-name: Check Black formatting
+name: Check code formatting
 
 on: [push, pull_request]
 
 jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
       - uses: psf/black@stable
         with:
           options: "-l 79 --check"

.github/workflows/deploy_docs.yml

@@ -0,0 +1,39 @@
+name: Build and Deploy Jupyter Book documentation
+on:
+  push:
+    branches:
+      - main
+jobs:
+  build-and-deploy:
+    if: github.repository == 'EAPD-DRB/OG-ZAF'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Miniconda
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          miniforge-variant: Mambaforge
+          activate-environment: ogzaf-dev
+          environment-file: environment.yml
+          python-version: "3.10"
+          auto-activate-base: false
+
+      - name: Build # Build Jupyter Book
+        shell: bash -l {0}
+        run: |
+          pip install jupyter-book>=0.11.3
+          pip install sphinxcontrib-bibtex>=2.0.0
+          pip install -e .
+          python -m ipykernel install --user --name=ogzaf-dev
+          jb build ./docs/book
+
+      - name: Deploy
+        uses: JamesIves/github-pages-deploy-action@releases/v4
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH: gh-pages # The branch the action should deploy to.
+          FOLDER: docs/book/_build/html # The folder the action should deploy.

.github/workflows/docs_check.yml

@@ -0,0 +1,29 @@
+name: Check that docs build
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Setup Miniconda
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          miniforge-variant: Mambaforge
+          activate-environment: ogzaf-dev
+          environment-file: environment.yml
+          python-version: "3.10"
+          auto-activate-base: false
+
+      - name: Build # Build Jupyter Book
+        shell: bash -l {0}
+        run: |
+          pip install jupyter-book>=0.11.3
+          pip install sphinxcontrib-bibtex>=2.0.0
+          pip install -e .
+          python -m ipykernel install --user --name=ogzaf-dev
+          jb build ./docs/book

.github/workflows/publish_to_pypi.yml

@@ -0,0 +1,30 @@
+name: Publish package to PyPI
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    name: Publish to PyPI
+    if: github.repository == 'EAPD-DRB/OG-ZAF'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Build package
+        shell: bash -l {0}
+        run: |
+          pip install wheel
+          python setup.py sdist bdist_wheel
+      - name: Publish a Python distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI }}
+          skip_existing: true

.gitignore

@@ -38,6 +38,8 @@ envs/
 *dask-worker-space*
 .ipynb_checkpoints*
 */__pycache__/*
+*.coverage*
+*coverage.xml*
 docs/book/_build/*
 */OG-ZAF_example_plots/*
 *ogzaf_example_output.csv

CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2023-10-30 8:00:00
+
+### Added
+
+- Adds CI tests `check_format.yml`, `build_and_test.yml`, `docs_build.yml`, `deploy_docs.yml`, `publish_to_pypi.yml`
+- Adds `/tests/` directory with test files in it
+- Added `Makefile`
+- Updated `environment.yml` and `setup.py`
+- Updated `pyproject.toml`
+- Updates the `README.md`
+
+## [0.0.0] - 2022-10-15 12:00:00
+
+### Added
+
+- This version is a pre-release alpha. The example run script OG-ZAF/examples/run_og_zaf.py runs, but the model is not currently calibrated to represent the South African economy and population.
+
+
+
+[0.0.1]: https://github.com/EAPD-DRB/OG-ZAF/compare/v0.0.0...v0.0.1

Makefile

@@ -0,0 +1,16 @@
+all: build
+format:
+	black . -l 79
+	linecheck . --fix
+install:
+	pip install -e .
+test:
+	pip install pytest-cov
+	pip install pytest-pycodestyle
+	pytest -m 'not local' --cov=./ --cov-report=xml
+documentation:
+	jupyter-book clean docs/book
+	jupyter-book build docs/book
+pip-package:
+	pip install wheel
+	python setup.py sdist bdist_wheel

README.md

@@ -1,8 +1,11 @@
-[![Python 3.9](https://img.shields.io/badge/python-3.9-blue.svg)](https://www.python.org/downloads/release/python-3916/)
-[![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-3108/)
-![example event parameter](https://github.com/EAPD-DRB/OG-ZAF/actions/workflows/check_black.yml/badge.svg?branch=main)
-
 # OG-ZAF
+
+| | |
+| --- | --- |
+| Org | [![United Nations DESA](https://img.shields.io/badge/United%20Nations%20DESA-blue)](https://www.un.org/en/desa) [![PSL cataloged](https://img.shields.io/badge/PSL-cataloged-a0a0a0.svg)](https://www.PSLmodels.org) [![OS License: CC0-1.0](https://img.shields.io/badge/OS%20License-CC0%201.0-yellow)](https://github.com/EAPD-DRB/OG-ZAF/blob/main/LICENSE) |
+| Package | [![Python 3.9](https://img.shields.io/badge/python-3.9-blue.svg)](https://www.python.org/downloads/release/python-3917/) [![Python 3.10](https://img.shields.io/badge/python-3.10-blue.svg)](https://www.python.org/downloads/release/python-31013/) [![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org/downloads/release/python-3116/) [![PyPI Latest Release](https://img.shields.io/pypi/v/ogzaf.svg)](https://pypi.org/project/ogzaf/) [![PyPI Downloads](https://img.shields.io/pypi/dm/ogzaf.svg?label=PyPI%20downloads)](https://pypi.org/project/ogzaf/) |
+| Testing | ![example event parameter](https://github.com/EAPD-DRB/OG-ZAF/actions/workflows/build_and_test.yml/badge.svg?branch=main) ![example event parameter](https://github.com/EAPD-DRB/OG-ZAF/actions/workflows/deploy_docs.yml/badge.svg?branch=main) ![example event parameter](https://github.com/EAPD-DRB/OG-ZAF/actions/workflows/check_format.yml/badge.svg?branch=main) [![Codecov](https://codecov.io/gh/EAPD-DRB/OG-ZAF/branch/main/graph/badge.svg)](https://codecov.io/gh/EAPD-DRB/OG-ZAF) |
+
 OG-ZAF is an overlapping-generations (OG) model that allows for dynamic general equilibrium analysis of fiscal policy for South Africa. OG-ZAF is built on the OG-Core framework. The model output includes changes in macroeconomic aggregates (GDP, investment, consumption), wages, interest rates, and the stream of tax revenues over time. Regularly updated documentation of the model theory--its output, and solution method--and the Python API is available at https://pslmodels.github.io/OG-Core and documentation of the specific South African calibration of the model will be available soon.
 
 

environment.yml

@@ -3,10 +3,8 @@ channels:
 - conda-forge
 dependencies:
 - python>=3.7.7
-- ipython
-- setuptools
-- psutil
 - numpy
+- numba>=0.54
 - scipy>=1.7.1
 - pandas>=1.2.5
 - matplotlib
@@ -25,12 +23,15 @@ dependencies:
 - coverage
 - requests
 - xlwt
-- openpyxl>=3.1.2
 - statsmodels
 - linearmodels
 - black
 - jupyter
+- ipython
+- setuptools
 - pip:
   - jupyter-book>=0.9.1
+  - openpyxl>=3.1.2
   - pandas-datareader
+  - linecheck
   - ogcore

pyproject.toml

@@ -1,3 +1,7 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
 # Configuration for Black.
 
 # NOTE: you have to use single-quoted strings in TOML for regular expressions.
@@ -7,5 +11,5 @@
 
 [tool.black]
 line-length = 79
-target-version = ['py36', 'py37', 'py38']
+target-version = ["py39", "py310", "py311"]
 include = '\.pyi?$'

setup.py

@@ -1,59 +1,59 @@
-import setuptools
+"""This file contains the OG-ZAF package's metadata and dependencies."""
 
-with open("README.md", "r", encoding="utf-8") as fh:
-    longdesc = fh.read()
+from setuptools import find_packages, setup
 
-setuptools.setup(
+with open("README.md", "r") as readme_file:
+    readme = readme_file.read()
+
+setup(
     name="ogzaf",
-    version="0.0.0",
-    author="Marcelo LaFleur and Richard W. Evans",
+    version="0.0.1",
+    author="Marcelo LaFleur, Richard W. Evans, and Jason DeBacker",
     license="CC0 1.0 Universal (CC0 1.0) Public Domain Dedication",
     description="South Africa Calibration for OG-Core",
+    long_description=readme,
     long_description_content_type="text/markdown",
-    long_description=longdesc,
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "Natural Language :: English",
+        "License :: OSI Approved :: Common Public License",
+        "Operating System :: POSIX",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Topic :: Scientific/Engineering :: Information Analysis",
+        "Topic :: Software Development :: Libraries :: Python Modules",
+    ],
+    keywords="South Africa calibration of large scale overlapping generations model of fiscal policy",
     url="https://github.com/EAPD-DRB/OG-ZAF/",
     download_url="https://github.com/EAPD-DRB/OG-ZAF/",
     project_urls={
         "Issue Tracker": "https://github.com/EAPD-DRB/OG-ZAF/issues",
     },
     packages=["ogzaf"],
-    package_data={
-        "ogzaf": [
-            "ogzaf_default_parameters.json",
-            "data/*",
-        ]
-    },
+    package_data={"ogzaf": ["ogusa_default_parameters.json", "data/*"]},
     include_packages=True,
     python_requires=">=3.7.7",
     install_requires=[
-        "psutil",
         "numpy",
+        "psutil",
         "scipy>=1.7.1",
         "pandas>=1.2.5",
         "matplotlib",
         "dask>=2.30.0",
         "distributed>=2.30.1",
         "paramtools>=0.15.0",
         "requests",
+        "pandas-datareader",
         "xlwt",
-        "openpyxl",
+        "openpyxl>=3.1.2",
         "statsmodels",
         "linearmodels",
         "black",
-        "pandas-datareader",
+        "linecheck",
         "ogcore",
     ],
-    classifiers=[
-        "Development Status :: 2 - Pre-Alpha",
-        "Intended Audience :: Developers",
-        "Natural Language :: English",
-        "License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication",
-        "Operating System :: OS Independent",
-        "Programming Language :: Python",
-        "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.9",
-        "Programming Language :: Python :: 3.10",
-        "Topic :: Software Development :: Libraries :: Python Modules",
-    ],
     tests_require=["pytest"],
 )