Metadata-Version: 2.4
Name: ogphl
Version: 0.1.1
Summary: Philippines Calibration for OG-Core
Author: Marcelo LaFleur, Richard W. Evans, and Jason DeBacker
License: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Project-URL: Homepage, https://github.com/EAPD-DRB/OG-PHL/
Project-URL: Issue Tracker, https://github.com/EAPD-DRB/OG-PHL/issues
Keywords: PHL,Philippines,calibration,overlapping generations,fiscal policy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: psutil
Requires-Dist: scipy>=1.7.1
Requires-Dist: pandas>=1.2.5
Requires-Dist: matplotlib
Requires-Dist: dask>=2.30.0
Requires-Dist: distributed>=2.30.1
Requires-Dist: paramtools>=0.20.0
Requires-Dist: requests
Requires-Dist: xlwt
Requires-Dist: openpyxl>=3.1.2
Requires-Dist: statsmodels
Requires-Dist: linearmodels
Requires-Dist: linecheck
Requires-Dist: ogcore>=0.18.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: jupyter; extra == "dev"
Provides-Extra: docs
Requires-Dist: jupyter-book<2.0,>=1.0; extra == "docs"
Requires-Dist: sphinx>=3.5.4; extra == "docs"
Requires-Dist: sphinx-book-theme>=0.1.3; extra == "docs"
Requires-Dist: sphinx-argparse; extra == "docs"
Requires-Dist: sphinx-exercise; extra == "docs"
Requires-Dist: sphinx-proof; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex>=2.0.0; extra == "docs"
Dynamic: license-file

# OG-PHL

| | |
| --- | --- |
| 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-PHL/blob/main/LICENSE) [![Jupyter Book Badge](https://raw.githubusercontent.com/jupyter-book/jupyter-book/next/docs/media/images/badge.svg)](https://eapd-drb.github.io/OG-PHL) |
| Package | [![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/release/python-3129/) [![Python 3.13](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/release/python-3137/) [![PyPI Latest Release](https://img.shields.io/pypi/v/ogphl.svg)](https://pypi.org/project/ogphl/) [![PyPI Downloads](https://img.shields.io/pypi/dm/ogphl.svg?label=PyPI%20downloads)](https://pypi.org/project/ogphl/) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
| Testing | ![example event parameter](https://github.com/EAPD-DRB/OG-PHL/actions/workflows/build_and_test.yml/badge.svg?branch=main) ![example event parameter](https://github.com/EAPD-DRB/OG-PHL/actions/workflows/deploy_docs.yml/badge.svg?branch=main) ![example event parameter](https://github.com/EAPD-DRB/OG-PHL/actions/workflows/check_ruff.yml/badge.svg?branch=main) [![Codecov](https://codecov.io/gh/EAPD-DRB/OG-PHL/branch/main/graph/badge.svg)](https://codecov.io/gh/EAPD-DRB/OG-PHL) |

OG-PHL is an overlapping-generations (OG) model that allows for dynamic general equilibrium analysis of fiscal policy for the Philippines. OG-PHL 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 Philippines calibration of the model is available at https://eapd-drb.github.io/OG-PHL.


## Using and contributing to OG-PHL

Install and run OG-PHL by cloning this GitHub repository and installing the `ogphl` package with its dependencies using [`uv`](https://docs.astral.sh/uv/), as detailed below. (Installing the `ogphl` package from [PyPI](https://pypi.org/project/ogphl/) with `pip` is no longer the recommended path: on older Python versions `pip` silently resolves a years-old release of the model, and the PyPI route does not pin the `ogcore` version the repository is tested against. The `uv` workflow installs the exact tested versions of every dependency, including a compatible Python interpreter.)

### Installation

There are two ways to install OG-PHL: the easy way, using the OG model family's universal installer, and a manual install that runs the same steps one command at a time. Both start from a terminal, put the model in a new OG-PHL folder inside your current directory (a freshly opened terminal starts in your home folder), and need git.

#### Before you start: git

On a Mac where you have never used git before, run this line first and accept the dialog that appears:

```
xcode-select --install
```

On Windows, install Git first (skip this if you already have it):

```
winget install --id Git.Git -e --source winget
```

#### The easy way: the universal installer

The OG model family has a [universal installer](https://github.com/PSLmodels/OG-Core/blob/master/scripts/QUICK_INSTALL.md) that installs the uv tool, downloads the model, builds its environment, and verifies it — for OG-PHL or any of its sibling country models.

On macOS and Linux, paste:

```
curl -fsSL https://raw.githubusercontent.com/PSLmodels/OG-Core/master/scripts/install.sh -o og-install.sh
bash og-install.sh --repo og-phl --yes
```

On Windows (PowerShell), paste:

```
$f = "$env:TEMP\og-install.ps1"; irm https://raw.githubusercontent.com/PSLmodels/OG-Core/master/scripts/install.ps1 -OutFile $f; powershell -ExecutionPolicy Bypass -File $f -Repo og-phl -Yes
```

When the installer finishes, run the example. On macOS and Linux, paste:

```
source $HOME/.local/bin/env
cd OG-PHL
uv run python examples/run_og_phl.py
```

On Windows, open a new PowerShell window (so the just-installed tools are found) and paste:

```
cd OG-PHL
uv run python examples/run_og_phl.py
```

#### Manual install

The same setup as individual commands. On macOS and Linux, paste:

```
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
git clone https://github.com/EAPD-DRB/OG-PHL.git
cd OG-PHL
uv run python examples/run_og_phl.py
```

The second line makes the just-installed uv available in the current terminal; from your next terminal session it is available automatically.

On Windows (PowerShell), install uv:

```
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Then open a new PowerShell window (so the just-installed tools are found) and paste:

```
git clone https://github.com/EAPD-DRB/OG-PHL.git
cd OG-PHL
uv run python examples/run_og_phl.py
```

#### What happens

The first `uv run` creates the project environment if it does not exist yet — downloading a compatible Python interpreter if needed and installing the exact locked dependencies — and then runs the example. Early in the run you may be asked for a UN API token; just press return, and the model reads the same population data from a public mirror and continues. A full baseline-plus-reform run takes from 35 minutes to more than two hours; when it finishes, its plots and tables are saved under `./examples/OG-PHL-Example/` (see the list of outputs below).

### Installing for development or contributing

* Fork this repository and clone your fork to a directory on your computer.
* From the terminal, navigate to the cloned directory and run `uv sync --extra dev` to create a local `.venv` and install OG-PHL with its development dependencies (`uv` downloads a compatible Python if you don't already have one).
* For docs/Jupyter Book work, also run `uv sync --extra dev --extra docs`.
* Run commands in the environment with `uv run <command>`, or activate it first with `source .venv/bin/activate` (macOS/Linux) or `.\.venv\Scripts\Activate.ps1` (Windows).

### Run an example of the model

* From the repository root, run the model with an example reform: `uv run python examples/run_og_phl.py`.
* You can adjust the `./examples/run_og_phl.py` by modifying model parameters specified in the dictionary passed to the `p.update_specifications()` calls.
* Model outputs will be saved in the following files:
  * `./examples/OG-PHL-Example/OG-PHL_example_plots`
    * This folder will contain a number of plots generated from OG-Core to help you visualize the output from your run
  * `./examples/OG-PHL-Example/OG-PHL_example_output.csv`
    * This is a summary of the percentage changes in macro variables over the first ten years and in the steady-state.
  * `./examples/OG-PHL-Example/OUTPUT_BASELINE/model_params.pkl`
    * Model parameters used in the baseline run
    * See [`ogcore.execute.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/execute.py) for items in the dictionary object in this pickle file
  * `./examples/OG-PHL-Example/OUTPUT_BASELINE/SS/SS_vars.pkl`
    * Outputs from the model steady state solution under the baseline policy
    * See [`ogcore.SS.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/SS.py) for what is in the dictionary object in this pickle file
  * `./examples/OG-PHL-Example/OUTPUT_BASELINE/TPI/TPI_vars.pkl`
    * Outputs from the model timepath solution under the baseline policy
    * See [`ogcore.TPI.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/TPI.py) for what is in the dictionary object in this pickle file
  * An analogous set of files in the `./examples/OG-PHL-Example/OUTPUT_REFORM` directory, which represent objects from the simulation of the reform policy

Note that, depending on your machine, a full model run (solving for the full time path equilibrium for the baseline and reform policies) can take from 35 minutes to more than two hours of compute time.

If you run into errors running the example script, please open a new issue in the OG-PHL repo with a description of the issue and any relevant tracebacks you receive.

Once the package is installed, one can adjust parameters in the OG-Core `Specifications` object using the `Calibration` class as follows:

```
from ogcore.parameters import Specifications
from ogphl.calibrate import Calibration
from ogphl.utils import is_connected
p = Specifications()
if is_connected():
    c = Calibration(p, update_from_api=True)
    updated_params = c.get_dict()
    p.update_specifications(updated_params)
```

## Disclaimer
The `OG-PHL/examples/run_og_phl.py` script is kept up to date to run with the `main` branch of this repo.

## Core Maintainers

The core maintainers of the OG-PHL repository are:

* Marcelo LaFleur (GitHub handle: [@SeaCelo](https://github.com/SeaCelo)), Senior Economist, Department of Economic and Social Affairs (DESA), United Nations
* [Richard W. Evans](https://sites.google.com/site/rickecon/) (GitHub handle: [@rickecon](https://github.com/rickecon)), Senior Economist, Abundance Institute; President, Open Research Group, Inc.
* [Jason DeBacker](https://jasondebacker.com) (GitHub handle: [@jdebacker](https://github.com/jdebacker)), Associate Professor, University of South Carolina; Vice President of Research, Open Research Group, Inc.

## Citing OG-PHL

OG-PHL (Version #.#.#)[Source code], https://github.com/EAPD-DRB/OG-PHL.
