pydeflate 1.4.2__tar.gz → 2.0.0__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.
Files changed (40) hide show
  1. {pydeflate-1.4.2 → pydeflate-2.0.0}/LICENSE +1 -1
  2. pydeflate-2.0.0/PKG-INFO +287 -0
  3. pydeflate-2.0.0/README.md +260 -0
  4. pydeflate-2.0.0/pydeflate/__init__.py +42 -0
  5. pydeflate-2.0.0/pydeflate/core/api.py +404 -0
  6. pydeflate-2.0.0/pydeflate/core/deflator.py +171 -0
  7. pydeflate-2.0.0/pydeflate/core/exchange.py +237 -0
  8. pydeflate-2.0.0/pydeflate/core/source.py +54 -0
  9. pydeflate-2.0.0/pydeflate/deflate/deflators.py +228 -0
  10. pydeflate-2.0.0/pydeflate/deflate/legacy_deflate.py +109 -0
  11. pydeflate-2.0.0/pydeflate/exchange/__init__.py +0 -0
  12. pydeflate-2.0.0/pydeflate/exchange/exchangers.py +147 -0
  13. pydeflate-2.0.0/pydeflate/pydeflate_config.py +43 -0
  14. pydeflate-2.0.0/pydeflate/sources/__init__.py +0 -0
  15. pydeflate-2.0.0/pydeflate/sources/common.py +278 -0
  16. pydeflate-2.0.0/pydeflate/sources/dac.py +137 -0
  17. pydeflate-2.0.0/pydeflate/sources/imf.py +203 -0
  18. pydeflate-2.0.0/pydeflate/sources/world_bank.py +186 -0
  19. pydeflate-2.0.0/pydeflate/utils.py +100 -0
  20. {pydeflate-1.4.2 → pydeflate-2.0.0}/pyproject.toml +15 -14
  21. pydeflate-1.4.2/PKG-INFO +0 -305
  22. pydeflate-1.4.2/README.md +0 -278
  23. pydeflate-1.4.2/pydeflate/__init__.py +0 -34
  24. pydeflate-1.4.2/pydeflate/deflate/deflate.py +0 -324
  25. pydeflate-1.4.2/pydeflate/deflate/deflator.py +0 -78
  26. pydeflate-1.4.2/pydeflate/get_data/deflate_data.py +0 -70
  27. pydeflate-1.4.2/pydeflate/get_data/exchange_data.py +0 -371
  28. pydeflate-1.4.2/pydeflate/get_data/imf_data.py +0 -76
  29. pydeflate-1.4.2/pydeflate/get_data/oecd_data.py +0 -146
  30. pydeflate-1.4.2/pydeflate/get_data/wb_data.py +0 -75
  31. pydeflate-1.4.2/pydeflate/pydeflate_config.py +0 -34
  32. pydeflate-1.4.2/pydeflate/tools/__init__.py +0 -2
  33. pydeflate-1.4.2/pydeflate/tools/exchange.py +0 -171
  34. pydeflate-1.4.2/pydeflate/tools/update_data.py +0 -69
  35. pydeflate-1.4.2/pydeflate/utils.py +0 -67
  36. {pydeflate-1.4.2 → pydeflate-2.0.0}/pydeflate/.pydeflate_data/README.md +0 -0
  37. {pydeflate-1.4.2/pydeflate/deflate → pydeflate-2.0.0/pydeflate/core}/__init__.py +0 -0
  38. {pydeflate-1.4.2/pydeflate/get_data → pydeflate-2.0.0/pydeflate/deflate}/__init__.py +0 -0
  39. {pydeflate-1.4.2 → pydeflate-2.0.0}/pydeflate/settings/emu.json +0 -0
  40. {pydeflate-1.4.2 → pydeflate-2.0.0}/pydeflate/settings/oecd_codes.json +0 -0
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2022, Jorge Rivera
3
+ Copyright (c) 2021-2024, Jorge Rivera
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -0,0 +1,287 @@
1
+ Metadata-Version: 2.1
2
+ Name: pydeflate
3
+ Version: 2.0.0
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
+ [![pypi](https://img.shields.io/pypi/v/pydeflate.svg)](https://pypi.python.org/pypi/pydeflate)
30
+ [![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
31
+ [![Downloads](https://pepy.tech/badge/pydeflate/month)](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
+ [![pypi](https://img.shields.io/pypi/v/pydeflate.svg)](https://pypi.python.org/pypi/pydeflate)
4
+ [![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
5
+ [![Downloads](https://pepy.tech/badge/pydeflate/month)](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.0"
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
+ ]