Skip to content

Commit 5f2c51f

Browse files
freynesfreynes
authored
Merge pull request #3 from KMueller-Lab/Update/2026_03
Prepare 2.0.0 release
2 parents 9a5960e + de5286b commit 5f2c51f

File tree

22 files changed

+2149
-887
lines changed

22 files changed

+2149
-887
lines changed

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 Karsten Mueller, Chenzi Xu, Mohamed Lehbib, Ziliang Chen
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎MANIFEST.in‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
include LICENSE
2+
include tests/conftest.py
3+
recursive-include tests/fixtures *
4+
recursive-include tests *.py

‎README.md‎

Lines changed: 114 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,114 @@
1-
# The Global Macro Database (Python Package)
2-
<a href="https://www.globalmacrodata.com" target="_blank" rel="noopener noreferrer">
3-
<img src="https://img.shields.io/badge/Website-Visit-blue?style=flat&logo=google-chrome" alt="Website Badge">
4-
</a>
5-
6-
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7-
8-
[Link to paper 📄](https://www.globalmacrodata.com/research-paper.html)
9-
10-
This repository complements paper, **Müller, Xu, Lehbib, and Chen (2025)**, which introduces a panel dataset of **46 macroeconomic variables across 243 countries** from historical records beginning in the year **1086** until **2024**, including projections through the year **2030**.
11-
12-
## Features
13-
14-
- **Unparalleled Coverage**: Combines data from **32 contemporary sources** (e.g., IMF, World Bank, OECD) with **78 historical datasets**.
15-
- **Extensive Variables**: GDP, inflation, government finance, trade, employment, interest rates, and more.
16-
- **Harmonized Data**: Resolves inconsistencies and splices all available data together.
17-
- **Scheduled Updates**: Regular releases ensure data reliability.
18-
- **Full Transparency**: All code is open source and available in this repository.
19-
- **Accessible Formats**: Provided in `.dta`, `.csv` and as **<a href="https://github.com/KMueller-Lab/Global-Macro-Database" target="_blank" rel="noopener noreferrer">Stata</a>
20-
/<a href="https://github.com/KMueller-Lab/Global-Macro-Database-Python" target="_blank" rel="noopener noreferrer">Python</a>/<a href="https://github.com/KMueller-Lab/Global-Macro-Database-R" target="_blank" rel="noopener noreferrer">R</a> package**.
21-
22-
## Data access
23-
24-
<a href="https://www.globalmacrodata.com/data.html" target="_blank" rel="noopener noreferrer">Download via website</a>
25-
26-
**Python package:**
27-
```
28-
pip install global_macro_data
29-
```
30-
31-
**How to use (examples)**
32-
```python
33-
from global_macro_data import gmd
34-
35-
# Get data from latest available version
36-
df = gmd()
37-
38-
# Get data from a specific version
39-
df = gmd(version="2025_01")
40-
41-
# Get data for a specific country
42-
df = gmd(country="USA")
43-
44-
# Get data for multiple countries
45-
df = gmd(country=["USA", "CHN", "DEU"])
46-
47-
# Get specific variables
48-
df = gmd(variables=["rGDP", "infl", "unemp"])
49-
50-
# Get raw data for a single variable
51-
df = gmd(variables="rGDP", raw=True)
52-
53-
# List available variables and their descriptions
54-
gmd(vars=True)
55-
56-
# List available countries and their ISO codes
57-
gmd(iso=True)
58-
59-
# Combine parameters
60-
df = gmd(
61-
version="2025_01",
62-
country=["USA", "CHN"],
63-
variables=["rGDP", "unemp", "CPI"]
64-
)
65-
```
66-
67-
## Parameters
68-
- **variables (str or list)**: Variable code(s) to include (e.g., "rGDP" or ["rGDP", "unemp"])
69-
- **country (str or list)**: ISO3 country code(s) (e.g., "SGP" or ["MRT", "SGP"])
70-
- **version (str)**: Dataset version in format 'YYYY_MM' (e.g., '2025_01'). If None or "current", uses the latest version
71-
- **raw (bool)**: If True, download raw data for a single variable
72-
- **iso (bool)**: If True, display list of available countries
73-
- **vars (bool)**: If True, display list of available variables
74-
75-
## Release schedule
76-
| Release Date | Details |
77-
|--------------|-----------------|
78-
| 2025-01-30 | Initial release: 2025_01 |
79-
| 2025-04-01 | 2025_03 |
80-
| 2025-07-01 | 2025_06 |
81-
| 2025-10-01 | 2025_09 |
82-
| 2026-01-01 | 2025_12 |
83-
84-
## Citation
85-
86-
To cite this dataset, please use the following reference:
87-
88-
```bibtex
89-
@techreport{mueller2025global,
90-
title = {The Global Macro Database: A New International Macroeconomic Dataset},
91-
author = {Müller, Karsten and Xu, Chenzi and Lehbib, Mohamed and Chen, Ziliang},
92-
year = {2025},
93-
type = {Working Paper}
94-
}
95-
```
96-
97-
## Acknowledgments
98-
99-
The development of the Global Macro Database would not have been possible without the generous funding provided by the Singapore Ministry of Education (MOE) through the PYP grants (WBS A-0003319-01-00 and A-0003319-02-00), a Tier 1 grant (A-8001749- 00-00), and the NUS Risk Management Institute (A-8002360-00-00). This financial support laid the foundation for the successful completion of this extensive project.
1+
# The Global Macro Database (Python Package)
2+
3+
<a href="https://www.globalmacrodata.com" target="_blank" rel="noopener noreferrer">
4+
<img src="https://img.shields.io/badge/Website-Visit-blue?style=flat&logo=google-chrome" alt="Website Badge">
5+
</a>
6+
7+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8+
9+
This package provides Python access to the Global Macro Database (GMD).
10+
11+
## Installation
12+
13+
Install the latest published release from PyPI:
14+
15+
```bash
16+
pip install global-macro-data
17+
```
18+
19+
Install the latest code directly from GitHub:
20+
21+
```bash
22+
pip install git+https://github.com/KMueller-Lab/Global-Macro-Database-Python.git
23+
```
24+
25+
Install a specific Git ref from GitHub:
26+
27+
```bash
28+
pip install git+https://github.com/KMueller-Lab/Global-Macro-Database-Python.git@<tag-or-commit>
29+
```
30+
31+
## Updating
32+
33+
Upgrade an existing PyPI install:
34+
35+
```bash
36+
pip install --upgrade global-macro-data
37+
```
38+
39+
Upgrade an existing GitHub install:
40+
41+
```bash
42+
pip install --upgrade --force-reinstall git+https://github.com/KMueller-Lab/Global-Macro-Database-Python.git
43+
```
44+
45+
## Quick Start
46+
47+
```python
48+
from global_macro_data import gmd
49+
50+
# Latest dataset
51+
full_df = gmd()
52+
53+
# Specific vintage
54+
df = gmd(version="2025_12")
55+
56+
# Filter countries and variables
57+
subset = gmd(
58+
version="2025_12",
59+
country=["USA", "CHN"],
60+
variables=["rGDP", "infl", "unemp"],
61+
)
62+
63+
# Raw source-level data for one variable
64+
raw_rgdp = gmd(variables="rGDP", raw=True, version="2025_12")
65+
66+
# Load helper tables
67+
varlist_df = gmd(vars="load")
68+
country_df = gmd(country="load")
69+
source_df = gmd(sources="load")
70+
bib_df = gmd(cite="load")
71+
72+
# Print citations
73+
gmd(cite="GMD")
74+
gmd(print_option="GMD")
75+
```
76+
77+
## API Reference
78+
79+
The `gmd()` function supports the following options:
80+
81+
| Parameter | Values | Description |
82+
|-----------|--------|-------------|
83+
| `version` | `"YYYY_MM"`, `"current"`, `"list"` | Select data vintage |
84+
| `country` | ISO3 code(s), `"load"`, `"list"` | Filter by country |
85+
| `variables` | Variable code(s) | Select specific variables |
86+
| `raw` | `True` / `False` | Load raw source-level data |
87+
| `vars` | `"load"`, `"list"` | Load or display variable definitions |
88+
| `sources` | Source name, `"load"`, `"list"` | Query specific data sources |
89+
| `cite` | Source key, `"load"` | Retrieve BibTeX citations |
90+
| `print_option` | `"GMD"`, `"Stata"` | Print APA-style citations |
91+
| `fast` | `"yes"` or `True` | Cache data locally for faster reloading |
92+
| `network` | `"yes"` | Override network detection |
93+
94+
Helper functions are also available:
95+
96+
- `get_available_versions()` -- list all data vintages
97+
- `get_current_version()` -- get the latest version string
98+
- `list_variables()` -- print the variable table
99+
- `list_countries()` -- print the country table
100+
101+
## Citation
102+
103+
When using the Global Macro Database, please cite:
104+
105+
```bibtex
106+
@techreport{mueller2025global,
107+
title = {The Global Macro Database: A New International Macroeconomic Dataset},
108+
author = {M{\"u}ller, Karsten and Xu, Chenzi and Lehbib, Mohamed and Chen, Ziliang},
109+
year = {2025},
110+
institution = {National Bureau of Economic Research},
111+
type = {Working Paper},
112+
number = {33714}
113+
}
114+
```

0 commit comments

Comments
 (0)