Getting Started

Getting Started#

Schedule#

For the October 21-25, 2024 United Nations OG-PHL training in Manila, we will be following the schedule in Table 1.

Table 1 UN OG-PHL 5-day training schedule#

Day

Session

Topic

Materials

Mon.

Morning

Organizer introductions
Setup Python, Git, GitHub, and OG-PHL

Intro slides 1

Afternoon

Theory: “Simple” 3-period-lived agent model

(See doc chapter)

Tue.

Morning

Review 3-period-lived-agent exercises (solutions in this folder)
Review OG-Core and OG-PHL modules
Quick Git and GitHub workflow review

Afternoon

Running OG-PHL, inputs, outputs
Calibrating OG-PHL, current state, still to do

Input/output slides

Wed.

Morning

Running OG-PHL: Revisit some reforms from 2-day visit
Talk about new reforms, create project teams

Afternoon

OG-PHL output: Tools to visualize/tabulate output
OG-PHL built-in calibration helps

Thu.

Morning

Calibrating OG-PHL: Issues and hot spots

Calibration and data slides

Afternoon

Calibrating OG-PHL: Issues and hot spots

Fri.

Morning

Open work, project hackathon, office hours
Advanced topics: Adding trade, connecting to other models

Open source workflow slides

Afternoon

Presentation of projects
Future work, research, collaboration, final topics
Closing remarks

Install uv (which manages Python for you)#

OG-PHL is a large-scale overlapping generations macroeconomic model of Philippine fiscal policy. It is written in the Python programming language, and the project’s Python environments are managed with uv. You do not need to install a Python distribution yourself: uv downloads a compatible Python interpreter automatically and installs the exact package versions the model is tested against.

Verifying you have already installed uv#

Open your terminal (Mac or Linux) or command prompt/PowerShell (Windows) and type uv --version. This command should result in output like uv 0.11.30.

>>> uv --version
uv 0.11.30

Installing uv#

Follow the installation instructions for your platform. On Mac or Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows, use the PowerShell command on the installation page. (If you already have any Python with pip, pip install uv also works on every platform.)

Installing Git and GitHub#

Verifying you have already installed Git#

On Mac or Windows#

Open your terminal (Mac) or command prompt (Windows) and type git --version. You should get output like git version 2.37.2.

>>> git --version
git version 2.37.2

On Linux#

Open your terminal and type git -version. You should get output like `git version 2.37.2.

>>> git -version
git version 2.37.2

Installing Git#

If you do not already have Git installed on your computer, we recommend that you follow the instructions on the GitHub page git-guides/install-git for installing Git. This page has downloadable executable installers that are easy to use.

Basic configuring of Git on your machine#

Once you have Git installed, you will need to configure some of the basic settings in Git. To view all of your Git settings, you can type the following into your computers terminal:

git config --list --show-origin

When getting set up, it’s important to enter your credentials so that git on your local machine is linked to your account on GitHub. You’ll do this by first entering your name:

git config --global user.name "Your Name"

Then, you’ll enter your email (using the email that you used to register your account on GitHub.com):

git config --global user.email yourname@example.com

You can also set your default text editor for use with git by following the example below, which makes vim the default:

git config --global core.editor vim

For more information on configuring git, see the full instructions from git here.

Set up a GitHub account#

You will need a GitHub account to properly interact with OG-PHL. This will allow you to interact with the repository with a wide range of collaborative functionalities, including forking repositories, creating issues and discussions, and submitting pull requests. To set up a GitHub account, follow these instructions at GitHub.com.

Most likely, the free organization account will be the right place to start for you. We recommend choosing a username suitable for a professional setting, as this will be your public profile on GitHub.

Fork and clone OG-PHL repository#

  1. Forking the OG-PHL repository means that you are making a copy of that repository on your GitHub account in the cloud.

    • Go to the UN GitHub organization’s main repository for OG-PHL (EAPD-DRB/OG-PHL).

    • In the upper-right area of the browser page, click the “Fork” button and select “Create fork”. This will create an exact copy of the OG-PHL repository on your account. When you do this, you should see that the URL to the page has changed to https://github.com/[YourGitHubHandle]/OG-PHL.

  2. The next step is to clone the repository from its current place in the cloud to your local computer’s hard drive.

    • Open your terminal or command prompt

    • Navigate to the folder where you want this repository to reside. Make sure this is not a location on your hard drive that is mapped from the cloud. This file should live on your local computer. You already have the repository in the cloud on your GitHub account.

    • Copy the contents of your repository in the cloud to your hard drive by typing: git clone https://github.com/[YourGitHubHandle]/OG-PHL.git

    • Change directory to this new directory by typing: cd OG-PHL

    • Create an additional git remote named “upstream” that points to the main UN remote repository by typing: git remote add upstream https://github.com/EAPD-DRB/OG-PHL.git

../../_images/GitFlowDiag.png

Fig. 10 Flow diagram of Git and GitHub workflow#

Create the OG-PHL environment with uv#

uv creates a project virtual environment — a local .venv folder inside the repository — so that users across operating system platforms and different hardware configurations run the code with the same packages, functionality, and results. The exact package versions are pinned in the repository’s uv.lock file.

If you have installed uv and you have cloned your OG-PHL fork of the repository to your local machine, you can create the environment in a single step:

  • Open your terminal or command prompt and navigate to the OG-PHL repository folder on your hard drive.

  • Type the following command: uv sync --extra dev

This creates the .venv environment with the ogphl package and its development dependencies installed (downloading a compatible Python interpreter if needed). Now you will be able to run the modules of the OG-PHL model from scripts and from Jupyter notebooks: prefix any command with uv run (for example, uv run python examples/run_og_phl.py), or activate the environment first with source .venv/bin/activate (Mac/Linux) or .\.venv\Scripts\Activate.ps1 (Windows PowerShell).

Using Jupyter notebooks#

A nice way to execute lines of code on your local computer is to use Jupyter notebooks. The jupyter package is installed as part of the development dependencies from the previous step. You can open a Jupyter notebook directly in VS Code, or you can open one from your terminal or command prompt.

Open Jupyter notebook from terminal or command prompt#

  • If you are using Mac or Linux, open your terminal. If you are using Windows, open your command prompt.

  • Navigate to the folder of the OG-PHL repository on your local machine.

  • Open a Jupyter notebook session by typing uv run jupyter notebook. This will open a local server page that opens in your browser. This page will show the directory where you are currently working.

  • Either click the “New” button in the upper-right portion of the screen, or select “File” then “New” then “Notebook” from the menu at the upper-right. Make sure to select the kernel from the repository’s .venv environment.

Once you have completed these steps, you can interactively write code and execute it in steps using the Python code cells in the Jupyter notebook. You can also write text descriptions in the markdown cells.

Choosing a text editor#

Using a good text editor for your coding is a key productivity choice. We recommend the VS Code (Visual Studio Code) editor from Microsoft (download from https://code.visualstudio.com/Download). This text editor is free, it is open source, and it has the largest community of active users and active developers. It also has a ton of extensions that help you customize and increase the efficiency of your coding workflow.