pydeflate 1.4.2__tar.gz → 2.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {pydeflate-1.4.2 → pydeflate-2.0.1}/LICENSE +1 -1
- pydeflate-2.0.1/PKG-INFO +287 -0
- pydeflate-2.0.1/README.md +260 -0
- pydeflate-2.0.1/pydeflate/__init__.py +42 -0
- pydeflate-2.0.1/pydeflate/core/api.py +404 -0
- pydeflate-2.0.1/pydeflate/core/deflator.py +171 -0
- pydeflate-2.0.1/pydeflate/core/exchange.py +239 -0
- pydeflate-2.0.1/pydeflate/core/source.py +54 -0
- pydeflate-2.0.1/pydeflate/deflate/deflators.py +228 -0
- pydeflate-2.0.1/pydeflate/deflate/legacy_deflate.py +109 -0
- pydeflate-2.0.1/pydeflate/exchange/__init__.py +0 -0
- pydeflate-2.0.1/pydeflate/exchange/exchangers.py +147 -0
- pydeflate-2.0.1/pydeflate/pydeflate_config.py +43 -0
- pydeflate-2.0.1/pydeflate/sources/__init__.py +0 -0
- pydeflate-2.0.1/pydeflate/sources/common.py +287 -0
- pydeflate-2.0.1/pydeflate/sources/dac.py +137 -0
- pydeflate-2.0.1/pydeflate/sources/imf.py +203 -0
- pydeflate-2.0.1/pydeflate/sources/world_bank.py +186 -0
- pydeflate-2.0.1/pydeflate/utils.py +100 -0
- {pydeflate-1.4.2 → pydeflate-2.0.1}/pyproject.toml +15 -14
- pydeflate-1.4.2/PKG-INFO +0 -305
- pydeflate-1.4.2/README.md +0 -278
- pydeflate-1.4.2/pydeflate/__init__.py +0 -34
- pydeflate-1.4.2/pydeflate/deflate/deflate.py +0 -324
- pydeflate-1.4.2/pydeflate/deflate/deflator.py +0 -78
- pydeflate-1.4.2/pydeflate/get_data/deflate_data.py +0 -70
- pydeflate-1.4.2/pydeflate/get_data/exchange_data.py +0 -371
- pydeflate-1.4.2/pydeflate/get_data/imf_data.py +0 -76
- pydeflate-1.4.2/pydeflate/get_data/oecd_data.py +0 -146
- pydeflate-1.4.2/pydeflate/get_data/wb_data.py +0 -75
- pydeflate-1.4.2/pydeflate/pydeflate_config.py +0 -34
- pydeflate-1.4.2/pydeflate/tools/__init__.py +0 -2
- pydeflate-1.4.2/pydeflate/tools/exchange.py +0 -171
- pydeflate-1.4.2/pydeflate/tools/update_data.py +0 -69
- pydeflate-1.4.2/pydeflate/utils.py +0 -67
- {pydeflate-1.4.2 → pydeflate-2.0.1}/pydeflate/.pydeflate_data/README.md +0 -0
- {pydeflate-1.4.2/pydeflate/deflate → pydeflate-2.0.1/pydeflate/core}/__init__.py +0 -0
- {pydeflate-1.4.2/pydeflate/get_data → pydeflate-2.0.1/pydeflate/deflate}/__init__.py +0 -0
- {pydeflate-1.4.2 → pydeflate-2.0.1}/pydeflate/settings/emu.json +0 -0
- {pydeflate-1.4.2 → pydeflate-2.0.1}/pydeflate/settings/oecd_codes.json +0 -0
pydeflate-2.0.1/PKG-INFO
ADDED
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
Metadata-Version: 2.1
|
|
2
|
+
Name: pydeflate
|
|
3
|
+
Version: 2.0.1
|
|
4
|
+
Summary: Package to convert current prices figures to constant prices and vice versa
|
|
5
|
+
License: MIT
|
|
6
|
+
Author: Jorge Rivera
|
|
7
|
+
Author-email: jorge.rivera@one.org
|
|
8
|
+
Requires-Python: >=3.10,<4.0
|
|
9
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
10
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Natural Language :: English
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Requires-Dist: hdx-python-country (>=3.8.1,<4.0.0)
|
|
20
|
+
Requires-Dist: imf-reader (>=1.1.0,<2.0.0)
|
|
21
|
+
Requires-Dist: oda-reader (>=1.0.0,<2.0.0)
|
|
22
|
+
Requires-Dist: pandas (>=2,<3)
|
|
23
|
+
Requires-Dist: pyarrow (>14)
|
|
24
|
+
Requires-Dist: wbgapi (>=1.0.12,<2.0.0)
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# pydeflate
|
|
28
|
+
|
|
29
|
+
[](https://pypi.python.org/pypi/pydeflate)
|
|
30
|
+
[](https://github.com/psf/black)
|
|
31
|
+
[](https://pepy.tech/project/pydeflate)
|
|
32
|
+
|
|
33
|
+
**pydeflate** is a Python package to:
|
|
34
|
+
- Convert current price data to constant prices.
|
|
35
|
+
- Convert constant price data to current prices.
|
|
36
|
+
- Convert data from one currency to another (in both current and constant prices).
|
|
37
|
+
|
|
38
|
+
When converting to or from constant prices, it takes into account changes in prices and exchange rates over time. This allows for accurate comparisons across years, countries, and currencies.
|
|
39
|
+
|
|
40
|
+
## Important Note
|
|
41
|
+
|
|
42
|
+
**pydeflate v2 has recently been released. It includes api changes which break backwards-compatibility**. While a version of the `deflate` function is still available, it is now deprecated and will be removed in future versions. Please use the new deflator functions for improved simplicity, clarity and performance.
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
# Table of Contents
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
- [Installation](#installation)
|
|
49
|
+
|
|
50
|
+
- [Basic Usage](#basic-usage)
|
|
51
|
+
- [Setting Up pydeflate](#setting-up-pydeflate)
|
|
52
|
+
- [DataFrame Requirements](#dataframe-requirements)
|
|
53
|
+
|
|
54
|
+
- [Converting Current to Constant Prices](#converting-current-to-constant-prices)
|
|
55
|
+
- [Example](#example-convert-current-to-constant-prices)
|
|
56
|
+
|
|
57
|
+
- [Available Deflator Functions](#available-deflator-functions)
|
|
58
|
+
|
|
59
|
+
- [Currency Conversion](#currency-conversion)
|
|
60
|
+
- [Example](#example-currency-conversion)
|
|
61
|
+
|
|
62
|
+
- [Example: Using Source-Specific Codes](#example-using-source-specific-codes)
|
|
63
|
+
|
|
64
|
+
- [Data Sources and Method Options](#data-sources-and-method-options)
|
|
65
|
+
- [International Monetary Fund](#international-monetary-fund)
|
|
66
|
+
- [World Bank](#world-bank)
|
|
67
|
+
- [OECD Development Assistance Committee](#oecd-development-assistance-committee)
|
|
68
|
+
- [Sources](#sources)
|
|
69
|
+
|
|
70
|
+
- [Handling Missing Data](#handling-missing-data)
|
|
71
|
+
|
|
72
|
+
- [Updating Underlying Data](#updating-underlying-data)
|
|
73
|
+
|
|
74
|
+
## Installation
|
|
75
|
+
|
|
76
|
+
Install pydeflate using pip:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
pip install pydeflate --upgrade
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Basic Usage
|
|
83
|
+
|
|
84
|
+
### Setting Up pydeflate
|
|
85
|
+
|
|
86
|
+
Before using pydeflate, you must specify where the deflator and exchange data should be saved. This only needs to be done once per script or notebook.
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
from pydeflate import set_pydeflate_path
|
|
90
|
+
|
|
91
|
+
# Specify the path where deflator and exchange data will be saved
|
|
92
|
+
set_pydeflate_path("path/to/data/folder")
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### DataFrame requirements
|
|
96
|
+
You need to provide a pandas DataFrame in order to convert data with `pydeflate`. The DataFrame must have at least the following columns:
|
|
97
|
+
- **An `id_column`**: you must specify its name using the `id_column` parameter. By default, it expects `ISO3` country codes. Previous versions of pydeflate used to convert data automatically, but that could inadvertently introduce errors by mis-identifying countries. You can use tools like `bblocks`, `hdx-python-country` or `country-converter` to help you add `ISO3` codes to your data. If you're working with data from the same source as the one you're using in `pydeflate`, you can also set `use_source_codes=True`. That allows you to use the same encoding as the source data (e.g., DAC codes, IMF entity codes).
|
|
98
|
+
- **A `year_column`**: which can be a string, integer, or datetime. This is needed in order to match the data to the right deflator or exchange rate. By default, pydeflate assumes that the year column is named `year`. You can change this by setting the `year_column` parameter. If the optional parameter `year_format` is not set, pydeflate will try to infer the format of the year column. You can also provide a `year_format` as a string, to specify the format of your data's year column.
|
|
99
|
+
- **A `value_column`**: which contains the data to be converted. By default, pydeflate assumes that the value column is named `value`. You can change this by setting the `value_column` parameter. The type of the value column must be numeric (int, float).
|
|
100
|
+
|
|
101
|
+
## Converting Current to Constant Prices
|
|
102
|
+
|
|
103
|
+
Pydeflate includes multiple sources and methods to deflate data. They all work in a very similar way. For this example, we will use the IMF GDP deflator and exchange rates data.
|
|
104
|
+
|
|
105
|
+
### Example: Convert Current to Constant Prices
|
|
106
|
+
In this example, we first import the `imf_gdp_deflate` function and create a sample DataFrame. We then convert the data to constant 2015 EUR prices using the IMF GDP deflators and exchange rates.
|
|
107
|
+
|
|
108
|
+
Note that both the `source_currency` and the `target_currency` are specified using the ISO3 country codes of the country whose currency is being used. Note that either can also be specified as `LCU` which stands for 'local currency units', or the local currency for each individual country, instead applying a single currency to all values. For convenience `pydeflate` also accepts the currency codes of certain countries (like `USD` in place of `USA`, `EUR` in place of any country that uses the euro, `GBP` in place of `GBR`, etc).
|
|
109
|
+
|
|
110
|
+
If the required data to perform the conversion is not available, pydeflate will download it from the source and save it in the specified data folder. If the stored data is older than 50 days, `pydeflate` will inform you and encourage you to set the `update_data` parameter to `True`.
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from pydeflate import imf_gdp_deflate, set_pydeflate_path
|
|
114
|
+
import pandas as pd
|
|
115
|
+
|
|
116
|
+
# Specify the path where deflator and exchange data will be saved
|
|
117
|
+
set_pydeflate_path("path/to/data/folder")
|
|
118
|
+
|
|
119
|
+
# Example data in current USD prices
|
|
120
|
+
data = {
|
|
121
|
+
'iso_code': ['FRA', 'USA', 'GTM'],
|
|
122
|
+
'year': [2017, 2017, 2017],
|
|
123
|
+
'value': [50, 100, 200]
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
df = pd.DataFrame(data)
|
|
127
|
+
|
|
128
|
+
# Convert to constant EUR prices (base year 2015)
|
|
129
|
+
df_constant = imf_gdp_deflate(
|
|
130
|
+
data=df,
|
|
131
|
+
base_year=2015,
|
|
132
|
+
source_currency="USA", # Data is in USD
|
|
133
|
+
target_currency="FRA", # Convert to Euro
|
|
134
|
+
id_column="iso_code", # must be ISO3 code
|
|
135
|
+
year_column="year", # Can be string, integer or datetime
|
|
136
|
+
value_column="value", # Column to be converted
|
|
137
|
+
target_value_column="value_constant" # It could also be the same as value_column
|
|
138
|
+
)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
### Available Deflator Functions
|
|
142
|
+
|
|
143
|
+
- `imf_gdp_deflate`: Uses GDP deflators and exchange rates from the IMF World Economic Outlook.
|
|
144
|
+
- `imf_cpi_deflate`: Uses Consumer Price Index and exchange rates data from the IMF World Economic Outlook.
|
|
145
|
+
- `imf_cpi_e_deflate`: Uses end-of-period Consumer Price Index and exchange rates data from the IMF World Economic Outlook.
|
|
146
|
+
- `wb_gdp_deflate`: Uses GDP deflators and exchange rates from the World Bank.
|
|
147
|
+
- `wb_gdp_linked_deflate`: Uses the World Bank’s linked GDP deflator and exchange rates data.
|
|
148
|
+
- `wb_cpi_deflate`: Uses Consumer Price Index and exchange rate data from the World Bank.
|
|
149
|
+
- `oecd_dac_deflate`: Uses the OECD DAC deflator series (prices and exchange rates).
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
## Currency Conversion
|
|
154
|
+
Pydeflate includes multiple sources for currency exchange. They all work in a very similar way, using yearly exchange rates. For this example, we will use the OECD DAC exchange rates.
|
|
155
|
+
|
|
156
|
+
### Example: Currency Conversion
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
from pydeflate import oecd_dac_exchange, set_pydeflate_path
|
|
160
|
+
import pandas as pd
|
|
161
|
+
|
|
162
|
+
# Specify the path where deflator and exchange data will be saved
|
|
163
|
+
set_pydeflate_path("path/to/data/folder")
|
|
164
|
+
|
|
165
|
+
# Example data in current local currency units
|
|
166
|
+
data = {
|
|
167
|
+
'iso_code': ['GBR', 'CAN', 'JPN'],
|
|
168
|
+
'year': [2011, 2015, 2015],
|
|
169
|
+
'value': [100, 100, 100]
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
df = pd.DataFrame(data)
|
|
173
|
+
|
|
174
|
+
# Convert from local currency (e.g GBP, CAD, JPY in this case) to Canadian Dollars
|
|
175
|
+
df_can = oecd_dac_exchange(
|
|
176
|
+
data=df,
|
|
177
|
+
source_currency="LCU", # Local currency units
|
|
178
|
+
target_currency="CAN", # Convert to Canadian Dollars (can also use 'CAD')
|
|
179
|
+
id_column="iso_code", # must be ISO3 code
|
|
180
|
+
year_column="year", # Can be string, integer or datetime
|
|
181
|
+
value_column="value", # Column to be converted
|
|
182
|
+
target_value_column="value_can" # It could also be the same as value_column
|
|
183
|
+
)
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
## Example: Using Source-Specific Codes
|
|
187
|
+
|
|
188
|
+
If your data uses source-specific country codes (e.g., DAC codes), set use_source_codes=True and specify the appropriate id_column.
|
|
189
|
+
|
|
190
|
+
```python
|
|
191
|
+
from pydeflate import oecd_dac_deflate, set_pydeflate_path
|
|
192
|
+
import pandas as pd
|
|
193
|
+
|
|
194
|
+
|
|
195
|
+
# Specify the path where deflator and exchange data will be saved
|
|
196
|
+
set_pydeflate_path("path/to/data/folder")
|
|
197
|
+
|
|
198
|
+
# Example data with DAC codes
|
|
199
|
+
data = {
|
|
200
|
+
'dac_code': [302, 4, 4],
|
|
201
|
+
'year': [2010, 2016, 2018],
|
|
202
|
+
'value': [100, 100, 100]
|
|
203
|
+
}
|
|
204
|
+
|
|
205
|
+
df = pd.DataFrame(data)
|
|
206
|
+
|
|
207
|
+
# Convert using DAC deflators and DAC codes
|
|
208
|
+
df_constant = oecd_dac_deflate(
|
|
209
|
+
data=df,
|
|
210
|
+
base_year=2016,
|
|
211
|
+
source_currency="USA", # Data is in USD
|
|
212
|
+
target_currency="LCU", # Convert to local currency units
|
|
213
|
+
id_column="dac_code", # DAC codes
|
|
214
|
+
use_source_codes=True, # Use source-specific codes
|
|
215
|
+
year_column="year", # Can be string, integer or datetime
|
|
216
|
+
value_column="value", # Column to be converted
|
|
217
|
+
target_value_column="value_constant" # It could also be the same as value_column
|
|
218
|
+
)
|
|
219
|
+
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Data Sources and Method Options
|
|
223
|
+
|
|
224
|
+
Pydeflate uses data on price/gdp deflators and exchange rates from various sources. Each source offers different options for deflators and exchange rates.
|
|
225
|
+
|
|
226
|
+
For all sources, Exchange rates between two non USD currency pairs are derived from
|
|
227
|
+
the LCU to USD exchange rates selected.
|
|
228
|
+
|
|
229
|
+
### International Monetary Fund
|
|
230
|
+
The IMF provides estimates where data is not available, including for several
|
|
231
|
+
years into the future. Using these price deflators, combined with the corresponding
|
|
232
|
+
exchange rates, can also allow users to convert data to constant prices for future years.
|
|
233
|
+
|
|
234
|
+
Deflator Functions:
|
|
235
|
+
- `imf_gdp_deflate`: Uses GDP deflators.
|
|
236
|
+
- `imf_cpi_deflate`: Uses Consumer Price Index data.
|
|
237
|
+
- `imf_cpi_e_deflate`: Uses end-of-period Consumer Price Index data.
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
Exchange Function:
|
|
241
|
+
- `imf_exchange`: Uses exchange rates derived from the IMF’s data.
|
|
242
|
+
|
|
243
|
+
Notes:
|
|
244
|
+
- IMF data includes estimates for future years, allowing conversion to constant prices for future dates.
|
|
245
|
+
- Exchange rates are derived from the IMF’s implied rates.
|
|
246
|
+
|
|
247
|
+
### World Bank
|
|
248
|
+
|
|
249
|
+
Deflator Functions:
|
|
250
|
+
- `wb_gdp_deflate`: Uses GDP deflators.
|
|
251
|
+
- `wb_gdp_linked_deflate`: Uses the World Bank’s linked GDP deflator series.
|
|
252
|
+
- `wb_cpi_deflate`: Uses Consumer Price Index data.
|
|
253
|
+
|
|
254
|
+
Exchange Function:
|
|
255
|
+
- `wb_exchange`: Uses yearly average exchange rates.
|
|
256
|
+
|
|
257
|
+
Notes:
|
|
258
|
+
- The linked GDP deflator series counters breaks in series over time due to changes in base years or methodologies.
|
|
259
|
+
- Exchange rates are based on IMF International Financial Statistics data
|
|
260
|
+
|
|
261
|
+
### OECD Development Assistance Committee
|
|
262
|
+
|
|
263
|
+
Deflator Function:
|
|
264
|
+
- `oecd_dac_deflate`: Uses the DAC’s own deflator series.
|
|
265
|
+
|
|
266
|
+
Exchange Function:
|
|
267
|
+
- `oecd_dac_exchange`: Uses exchange rates used and published by the DAC.
|
|
268
|
+
|
|
269
|
+
### Sources
|
|
270
|
+
This package relies on data from the following sources:
|
|
271
|
+
- OECD DAC: https://www.oecd.org/dac/
|
|
272
|
+
- IMF World Economic Outlook: https://www.imf.org/en/Publications/WEO
|
|
273
|
+
- World Bank DataBank: https://databank.worldbank.org/home.aspx
|
|
274
|
+
|
|
275
|
+
This data is provided based on the terms and conditions set by the
|
|
276
|
+
original sources.
|
|
277
|
+
|
|
278
|
+
## Handling Missing Data
|
|
279
|
+
|
|
280
|
+
Pydeflate relies on data from external sources. If there are missing values in the deflator or exchange rate data for certain countries or years, pydeflate will flag this in the output DataFrame. Ensure that your data aligns with the available data from the selected source.
|
|
281
|
+
|
|
282
|
+
## Updating Underlying Data
|
|
283
|
+
|
|
284
|
+
Pydeflate periodically updates its underlying data from the World Bank, IMF, and OECD. If the data on your system is older than 50 days, pydeflate will display a warning upon import.
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
|
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
# pydeflate
|
|
2
|
+
|
|
3
|
+
[](https://pypi.python.org/pypi/pydeflate)
|
|
4
|
+
[](https://github.com/psf/black)
|
|
5
|
+
[](https://pepy.tech/project/pydeflate)
|
|
6
|
+
|
|
7
|
+
**pydeflate** is a Python package to:
|
|
8
|
+
- Convert current price data to constant prices.
|
|
9
|
+
- Convert constant price data to current prices.
|
|
10
|
+
- Convert data from one currency to another (in both current and constant prices).
|
|
11
|
+
|
|
12
|
+
When converting to or from constant prices, it takes into account changes in prices and exchange rates over time. This allows for accurate comparisons across years, countries, and currencies.
|
|
13
|
+
|
|
14
|
+
## Important Note
|
|
15
|
+
|
|
16
|
+
**pydeflate v2 has recently been released. It includes api changes which break backwards-compatibility**. While a version of the `deflate` function is still available, it is now deprecated and will be removed in future versions. Please use the new deflator functions for improved simplicity, clarity and performance.
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
# Table of Contents
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
- [Installation](#installation)
|
|
23
|
+
|
|
24
|
+
- [Basic Usage](#basic-usage)
|
|
25
|
+
- [Setting Up pydeflate](#setting-up-pydeflate)
|
|
26
|
+
- [DataFrame Requirements](#dataframe-requirements)
|
|
27
|
+
|
|
28
|
+
- [Converting Current to Constant Prices](#converting-current-to-constant-prices)
|
|
29
|
+
- [Example](#example-convert-current-to-constant-prices)
|
|
30
|
+
|
|
31
|
+
- [Available Deflator Functions](#available-deflator-functions)
|
|
32
|
+
|
|
33
|
+
- [Currency Conversion](#currency-conversion)
|
|
34
|
+
- [Example](#example-currency-conversion)
|
|
35
|
+
|
|
36
|
+
- [Example: Using Source-Specific Codes](#example-using-source-specific-codes)
|
|
37
|
+
|
|
38
|
+
- [Data Sources and Method Options](#data-sources-and-method-options)
|
|
39
|
+
- [International Monetary Fund](#international-monetary-fund)
|
|
40
|
+
- [World Bank](#world-bank)
|
|
41
|
+
- [OECD Development Assistance Committee](#oecd-development-assistance-committee)
|
|
42
|
+
- [Sources](#sources)
|
|
43
|
+
|
|
44
|
+
- [Handling Missing Data](#handling-missing-data)
|
|
45
|
+
|
|
46
|
+
- [Updating Underlying Data](#updating-underlying-data)
|
|
47
|
+
|
|
48
|
+
## Installation
|
|
49
|
+
|
|
50
|
+
Install pydeflate using pip:
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pip install pydeflate --upgrade
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Basic Usage
|
|
57
|
+
|
|
58
|
+
### Setting Up pydeflate
|
|
59
|
+
|
|
60
|
+
Before using pydeflate, you must specify where the deflator and exchange data should be saved. This only needs to be done once per script or notebook.
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
from pydeflate import set_pydeflate_path
|
|
64
|
+
|
|
65
|
+
# Specify the path where deflator and exchange data will be saved
|
|
66
|
+
set_pydeflate_path("path/to/data/folder")
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### DataFrame requirements
|
|
70
|
+
You need to provide a pandas DataFrame in order to convert data with `pydeflate`. The DataFrame must have at least the following columns:
|
|
71
|
+
- **An `id_column`**: you must specify its name using the `id_column` parameter. By default, it expects `ISO3` country codes. Previous versions of pydeflate used to convert data automatically, but that could inadvertently introduce errors by mis-identifying countries. You can use tools like `bblocks`, `hdx-python-country` or `country-converter` to help you add `ISO3` codes to your data. If you're working with data from the same source as the one you're using in `pydeflate`, you can also set `use_source_codes=True`. That allows you to use the same encoding as the source data (e.g., DAC codes, IMF entity codes).
|
|
72
|
+
- **A `year_column`**: which can be a string, integer, or datetime. This is needed in order to match the data to the right deflator or exchange rate. By default, pydeflate assumes that the year column is named `year`. You can change this by setting the `year_column` parameter. If the optional parameter `year_format` is not set, pydeflate will try to infer the format of the year column. You can also provide a `year_format` as a string, to specify the format of your data's year column.
|
|
73
|
+
- **A `value_column`**: which contains the data to be converted. By default, pydeflate assumes that the value column is named `value`. You can change this by setting the `value_column` parameter. The type of the value column must be numeric (int, float).
|
|
74
|
+
|
|
75
|
+
## Converting Current to Constant Prices
|
|
76
|
+
|
|
77
|
+
Pydeflate includes multiple sources and methods to deflate data. They all work in a very similar way. For this example, we will use the IMF GDP deflator and exchange rates data.
|
|
78
|
+
|
|
79
|
+
### Example: Convert Current to Constant Prices
|
|
80
|
+
In this example, we first import the `imf_gdp_deflate` function and create a sample DataFrame. We then convert the data to constant 2015 EUR prices using the IMF GDP deflators and exchange rates.
|
|
81
|
+
|
|
82
|
+
Note that both the `source_currency` and the `target_currency` are specified using the ISO3 country codes of the country whose currency is being used. Note that either can also be specified as `LCU` which stands for 'local currency units', or the local currency for each individual country, instead applying a single currency to all values. For convenience `pydeflate` also accepts the currency codes of certain countries (like `USD` in place of `USA`, `EUR` in place of any country that uses the euro, `GBP` in place of `GBR`, etc).
|
|
83
|
+
|
|
84
|
+
If the required data to perform the conversion is not available, pydeflate will download it from the source and save it in the specified data folder. If the stored data is older than 50 days, `pydeflate` will inform you and encourage you to set the `update_data` parameter to `True`.
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
from pydeflate import imf_gdp_deflate, set_pydeflate_path
|
|
88
|
+
import pandas as pd
|
|
89
|
+
|
|
90
|
+
# Specify the path where deflator and exchange data will be saved
|
|
91
|
+
set_pydeflate_path("path/to/data/folder")
|
|
92
|
+
|
|
93
|
+
# Example data in current USD prices
|
|
94
|
+
data = {
|
|
95
|
+
'iso_code': ['FRA', 'USA', 'GTM'],
|
|
96
|
+
'year': [2017, 2017, 2017],
|
|
97
|
+
'value': [50, 100, 200]
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
df = pd.DataFrame(data)
|
|
101
|
+
|
|
102
|
+
# Convert to constant EUR prices (base year 2015)
|
|
103
|
+
df_constant = imf_gdp_deflate(
|
|
104
|
+
data=df,
|
|
105
|
+
base_year=2015,
|
|
106
|
+
source_currency="USA", # Data is in USD
|
|
107
|
+
target_currency="FRA", # Convert to Euro
|
|
108
|
+
id_column="iso_code", # must be ISO3 code
|
|
109
|
+
year_column="year", # Can be string, integer or datetime
|
|
110
|
+
value_column="value", # Column to be converted
|
|
111
|
+
target_value_column="value_constant" # It could also be the same as value_column
|
|
112
|
+
)
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Available Deflator Functions
|
|
116
|
+
|
|
117
|
+
- `imf_gdp_deflate`: Uses GDP deflators and exchange rates from the IMF World Economic Outlook.
|
|
118
|
+
- `imf_cpi_deflate`: Uses Consumer Price Index and exchange rates data from the IMF World Economic Outlook.
|
|
119
|
+
- `imf_cpi_e_deflate`: Uses end-of-period Consumer Price Index and exchange rates data from the IMF World Economic Outlook.
|
|
120
|
+
- `wb_gdp_deflate`: Uses GDP deflators and exchange rates from the World Bank.
|
|
121
|
+
- `wb_gdp_linked_deflate`: Uses the World Bank’s linked GDP deflator and exchange rates data.
|
|
122
|
+
- `wb_cpi_deflate`: Uses Consumer Price Index and exchange rate data from the World Bank.
|
|
123
|
+
- `oecd_dac_deflate`: Uses the OECD DAC deflator series (prices and exchange rates).
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
## Currency Conversion
|
|
128
|
+
Pydeflate includes multiple sources for currency exchange. They all work in a very similar way, using yearly exchange rates. For this example, we will use the OECD DAC exchange rates.
|
|
129
|
+
|
|
130
|
+
### Example: Currency Conversion
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
from pydeflate import oecd_dac_exchange, set_pydeflate_path
|
|
134
|
+
import pandas as pd
|
|
135
|
+
|
|
136
|
+
# Specify the path where deflator and exchange data will be saved
|
|
137
|
+
set_pydeflate_path("path/to/data/folder")
|
|
138
|
+
|
|
139
|
+
# Example data in current local currency units
|
|
140
|
+
data = {
|
|
141
|
+
'iso_code': ['GBR', 'CAN', 'JPN'],
|
|
142
|
+
'year': [2011, 2015, 2015],
|
|
143
|
+
'value': [100, 100, 100]
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
df = pd.DataFrame(data)
|
|
147
|
+
|
|
148
|
+
# Convert from local currency (e.g GBP, CAD, JPY in this case) to Canadian Dollars
|
|
149
|
+
df_can = oecd_dac_exchange(
|
|
150
|
+
data=df,
|
|
151
|
+
source_currency="LCU", # Local currency units
|
|
152
|
+
target_currency="CAN", # Convert to Canadian Dollars (can also use 'CAD')
|
|
153
|
+
id_column="iso_code", # must be ISO3 code
|
|
154
|
+
year_column="year", # Can be string, integer or datetime
|
|
155
|
+
value_column="value", # Column to be converted
|
|
156
|
+
target_value_column="value_can" # It could also be the same as value_column
|
|
157
|
+
)
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## Example: Using Source-Specific Codes
|
|
161
|
+
|
|
162
|
+
If your data uses source-specific country codes (e.g., DAC codes), set use_source_codes=True and specify the appropriate id_column.
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
from pydeflate import oecd_dac_deflate, set_pydeflate_path
|
|
166
|
+
import pandas as pd
|
|
167
|
+
|
|
168
|
+
|
|
169
|
+
# Specify the path where deflator and exchange data will be saved
|
|
170
|
+
set_pydeflate_path("path/to/data/folder")
|
|
171
|
+
|
|
172
|
+
# Example data with DAC codes
|
|
173
|
+
data = {
|
|
174
|
+
'dac_code': [302, 4, 4],
|
|
175
|
+
'year': [2010, 2016, 2018],
|
|
176
|
+
'value': [100, 100, 100]
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
df = pd.DataFrame(data)
|
|
180
|
+
|
|
181
|
+
# Convert using DAC deflators and DAC codes
|
|
182
|
+
df_constant = oecd_dac_deflate(
|
|
183
|
+
data=df,
|
|
184
|
+
base_year=2016,
|
|
185
|
+
source_currency="USA", # Data is in USD
|
|
186
|
+
target_currency="LCU", # Convert to local currency units
|
|
187
|
+
id_column="dac_code", # DAC codes
|
|
188
|
+
use_source_codes=True, # Use source-specific codes
|
|
189
|
+
year_column="year", # Can be string, integer or datetime
|
|
190
|
+
value_column="value", # Column to be converted
|
|
191
|
+
target_value_column="value_constant" # It could also be the same as value_column
|
|
192
|
+
)
|
|
193
|
+
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Data Sources and Method Options
|
|
197
|
+
|
|
198
|
+
Pydeflate uses data on price/gdp deflators and exchange rates from various sources. Each source offers different options for deflators and exchange rates.
|
|
199
|
+
|
|
200
|
+
For all sources, Exchange rates between two non USD currency pairs are derived from
|
|
201
|
+
the LCU to USD exchange rates selected.
|
|
202
|
+
|
|
203
|
+
### International Monetary Fund
|
|
204
|
+
The IMF provides estimates where data is not available, including for several
|
|
205
|
+
years into the future. Using these price deflators, combined with the corresponding
|
|
206
|
+
exchange rates, can also allow users to convert data to constant prices for future years.
|
|
207
|
+
|
|
208
|
+
Deflator Functions:
|
|
209
|
+
- `imf_gdp_deflate`: Uses GDP deflators.
|
|
210
|
+
- `imf_cpi_deflate`: Uses Consumer Price Index data.
|
|
211
|
+
- `imf_cpi_e_deflate`: Uses end-of-period Consumer Price Index data.
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
Exchange Function:
|
|
215
|
+
- `imf_exchange`: Uses exchange rates derived from the IMF’s data.
|
|
216
|
+
|
|
217
|
+
Notes:
|
|
218
|
+
- IMF data includes estimates for future years, allowing conversion to constant prices for future dates.
|
|
219
|
+
- Exchange rates are derived from the IMF’s implied rates.
|
|
220
|
+
|
|
221
|
+
### World Bank
|
|
222
|
+
|
|
223
|
+
Deflator Functions:
|
|
224
|
+
- `wb_gdp_deflate`: Uses GDP deflators.
|
|
225
|
+
- `wb_gdp_linked_deflate`: Uses the World Bank’s linked GDP deflator series.
|
|
226
|
+
- `wb_cpi_deflate`: Uses Consumer Price Index data.
|
|
227
|
+
|
|
228
|
+
Exchange Function:
|
|
229
|
+
- `wb_exchange`: Uses yearly average exchange rates.
|
|
230
|
+
|
|
231
|
+
Notes:
|
|
232
|
+
- The linked GDP deflator series counters breaks in series over time due to changes in base years or methodologies.
|
|
233
|
+
- Exchange rates are based on IMF International Financial Statistics data
|
|
234
|
+
|
|
235
|
+
### OECD Development Assistance Committee
|
|
236
|
+
|
|
237
|
+
Deflator Function:
|
|
238
|
+
- `oecd_dac_deflate`: Uses the DAC’s own deflator series.
|
|
239
|
+
|
|
240
|
+
Exchange Function:
|
|
241
|
+
- `oecd_dac_exchange`: Uses exchange rates used and published by the DAC.
|
|
242
|
+
|
|
243
|
+
### Sources
|
|
244
|
+
This package relies on data from the following sources:
|
|
245
|
+
- OECD DAC: https://www.oecd.org/dac/
|
|
246
|
+
- IMF World Economic Outlook: https://www.imf.org/en/Publications/WEO
|
|
247
|
+
- World Bank DataBank: https://databank.worldbank.org/home.aspx
|
|
248
|
+
|
|
249
|
+
This data is provided based on the terms and conditions set by the
|
|
250
|
+
original sources.
|
|
251
|
+
|
|
252
|
+
## Handling Missing Data
|
|
253
|
+
|
|
254
|
+
Pydeflate relies on data from external sources. If there are missing values in the deflator or exchange rate data for certain countries or years, pydeflate will flag this in the output DataFrame. Ensure that your data aligns with the available data from the selected source.
|
|
255
|
+
|
|
256
|
+
## Updating Underlying Data
|
|
257
|
+
|
|
258
|
+
Pydeflate periodically updates its underlying data from the World Bank, IMF, and OECD. If the data on your system is older than 50 days, pydeflate will display a warning upon import.
|
|
259
|
+
|
|
260
|
+
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
__author__ = """Jorge Rivera"""
|
|
2
|
+
__version__ = "2.0.1"
|
|
3
|
+
|
|
4
|
+
from pydeflate.deflate.deflators import (
|
|
5
|
+
oecd_dac_deflate,
|
|
6
|
+
wb_cpi_deflate,
|
|
7
|
+
wb_gdp_deflate,
|
|
8
|
+
wb_gdp_linked_deflate,
|
|
9
|
+
imf_cpi_deflate,
|
|
10
|
+
imf_gdp_deflate,
|
|
11
|
+
imf_cpi_e_deflate,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
from pydeflate.deflate.legacy_deflate import deflate
|
|
15
|
+
from pydeflate.exchange.exchangers import oecd_dac_exchange, wb_exchange, imf_exchange
|
|
16
|
+
from pydeflate.pydeflate_config import setup_logger
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def set_pydeflate_path(path):
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
from pydeflate.pydeflate_config import PYDEFLATE_PATHS
|
|
22
|
+
|
|
23
|
+
"""Set the path to the data folder."""
|
|
24
|
+
global PYDEFLATE_PATHS
|
|
25
|
+
|
|
26
|
+
PYDEFLATE_PATHS.data = Path(path).resolve()
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
__all__ = [
|
|
30
|
+
"set_pydeflate_path",
|
|
31
|
+
"oecd_dac_deflate",
|
|
32
|
+
"oecd_dac_exchange",
|
|
33
|
+
"wb_cpi_deflate",
|
|
34
|
+
"wb_gdp_deflate",
|
|
35
|
+
"wb_gdp_linked_deflate",
|
|
36
|
+
"wb_exchange",
|
|
37
|
+
"imf_cpi_deflate",
|
|
38
|
+
"imf_gdp_deflate",
|
|
39
|
+
"imf_cpi_e_deflate",
|
|
40
|
+
"imf_exchange",
|
|
41
|
+
"deflate",
|
|
42
|
+
]
|