python \\ecnswn12p\ems_shared\pub\datatools\installer.py devIMF Datatools
In this tutorial, we will explore how to install IMF Datatools and access data in R.
IMF Datatools is a Python library that allows us to access various internal and external data sources, and retrieve data directly in R.
Pre-requisites
Since IMF Datatools is Python based, we first need download Python 3.11 or above from the IMF Software Center and install our Python library.
After you have downloaded Python 3.11 or the latest version from the IMF Software Center, open the Command Prompt. You can load this by typing “cmd” in the Windows search option, as shown below.
In the command prompt, type the following command to install Datatools.
You should generate something similar to the following message when the installation is complete.
Loading the Python Interpreter
After Python 3.11 is downloaded and Datatools is installed, we need to load it into R Studio. To use IMF Datatools in RStudio, you need to set the location of your Python interpreter.
In the menu tab of R Studio, go to Tools, Global Options, choose Python and then select the interpreter from your computer. When you click select, it should automatically populate under system after download. Click Apply and OK.
Your R session will likely need to be restarted to ensure the changes take into effect. This process only needs to be done once.
Loading additional packages
To bridge the communication between R and Python, you will also need to install and load the reticulate package, only once.
#install.packages("reticulate")
library(reticulate)Handling Dates in Reticulate
When using the reticulate package to work with IMF Datatools, it is important to note that reticulate interprets dates in UTC time by default. This can lead to incorrect date stamps when downloading data if your system time is set to a different timezone.
To prevent this issue, you must set your system timezone to UTC before retrieving data. You can do this in R by running:
Sys.setenv(TZ = "UTC")Lastly, you will need to import the sys module and the IMF Datatools library for calling from R.
sys <- import("sys")
imf_datatools <- import("imf_datatools")You should now be set up to use IMF Datatools in R Studio.
Further documentation on IMF Datatools can also be found at this link.
Datasets available in IMF Datatools
Understanding the available data
IMF Datatools has direct access to a plethora of internal and external databases like EcOS, Haver, EDI, and more. For exploratory work, you can view all the databases or import a specific database.
Let’s look at all the available databases.
#Get all databases
dbnames <- imf_datatools$ecos_sdmx_utilities$get_databases()
#Quickly view the top part of all the databases
head(dbnames) dbpath
ECDATA_ADCP_WB_QEDS Databases/External Databases/International Organizations/World Bank (WB)/Quarterly External Debt Statistics Unified (ADCP_WB_QEDS)
ECDATA_ADCP_WB_WDI_ECDATA Databases/External Databases/International Organizations/World Bank (WB)/World Development Indicators (WDI)
ECDATA_ALBANIA Databases/Country Data/Albania
ECDATA_ANALYTIC_DATABASE_01182024 Databases/External Databases/International Organizations/OECD/Archive/Analytic Database_01182024
ECDATA_ANGOLA Databases/Country Data/Angola
ECDATA_ANNUAL_CENTRAL_GOVERNMENT_BOND_YIELDS_ACGBY Databases/Fiscal Affairs Department (FAD)/Eurostat/Interest Rates/Interest Rates - Historical Data/Central Government Bond Yields/Annual Central Government Bond Yields (ACGBY)This encompasses a very long list. Let’s try to narrow it down to something more relevant.
#Import a specific library under IMF Datatools, e.g., EDI
edi_utilities <- imf_datatools$edi_utilities
#Look at the available databases in EDI
databases <- edi_utilities$get_databases()
head(databases) shortname
bloomberg Bloomberg
bop-published-latest BOP
cofer-published-latest COFER
consensus-forecast-timeseries CONSENSUS
csd-forecasts-ccx CSDCCX
csd-forecasts-desk CSDDesk
description
bloomberg Bloomberg Data License
bop-published-latest Balance of Payments and International Investment Position
cofer-published-latest Currency Composition of Official Foreign Exchange Reserves
consensus-forecast-timeseries Consensus Forecasts (ECDATA)
csd-forecasts-ccx CSD - Cross Country Exercises (CCX)
csd-forecasts-desk CSD - Desk Data
environment
bloomberg production
bop-published-latest production
cofer-published-latest production
consensus-forecast-timeseries production
csd-forecasts-ccx production
csd-forecasts-desk production
primary_keys
bloomberg database/ticker/field/freq
bop-published-latest database/country/indicator/freq
cofer-published-latest database/country/indicator/freq
consensus-forecast-timeseries database/country/indicator/freq
csd-forecasts-ccx database/exercise/country/indicator/vintage/freq
csd-forecasts-desk database/country/indicator/exercise/vintage/vintagetimestamp/freqThis looks better. We can also use the glimpse function from the ‘dplyr’ package to have a more compact and structured overview of our data. This will show the structure of the data frame and previous any contents. Let’s try this for reference.
library(dplyr)
Attaching package: 'dplyr'The following objects are masked from 'package:stats':
filter, lagThe following objects are masked from 'package:base':
intersect, setdiff, setequal, unionglimpse(databases)Rows: 18
Columns: 4
$ shortname <chr> "Bloomberg", "BOP", "COFER", "CONSENSUS", "CSDCCX", "CSDD…
$ description <chr> "Bloomberg Data License", "Balance of Payments and Intern…
$ environment <chr> "production", "production", "production", "production", "…
$ primary_keys <chr> "database/ticker/field/freq", "database/country/indicator…Let’s also take a look at the WEO country codes and groups.
#Get WEO country codes and groups
countrydata <- imf_datatools$ecos_sdmx_utilities$get_weo_country_codes()
#Take a glimpse at data
glimpse(countrydata)Rows: 196
Columns: 38
$ `ISO-3 code` <chr> …
$ Code <chr> …
$ `ISO-2 code` <chr> …
$ `WB region` <chr> …
$ `WB capitalCity` <chr> …
$ `WB incomeLevel` <chr> …
$ `WB latitude` <dbl> …
$ `WB longitude` <dbl> …
$ `Advanced Economies` <dbl> …
$ G7 <dbl> …
$ `Euro area (member states)` <dbl> …
$ `Other Advanced Economies (Advanced Economies excluding G7 and Euro Area countries)` <dbl> …
$ `Other Advanced Economies (Advanced Economies excluding U.S., Euro Area countries, and Japan)` <dbl> …
$ `Emerging and developing economies` <dbl> …
$ `Caucasus and Central Asia (CCA)` <dbl> …
$ `Emerging and Developing Asia` <dbl> …
$ `Emerging and Developing Asia excl. China and India` <dbl> …
$ `ASEAN-5` <dbl> …
$ `Emerging and Developing Europe` <dbl> …
$ `Latin America and the Caribbean` <dbl> …
$ `Middle East and Central Asia` <dbl> …
$ `Middle East and North Africa` <dbl> …
$ `Middle East, North Africa, Afghanistan, and Pakistan` <dbl> …
$ `Sub-Sahara Africa` <dbl> …
$ `Emerging Market and Developing Economies by Source of Export Earnings: Fuel` <dbl> …
$ `Emerging Market and Developing Economies by Source of Export Earnings: Nonfuel` <dbl> …
$ `Emerging Market and Developing Economies by Source of Export Earnings: Manufactures` <dbl> …
$ `Emerging Market and Developing Economies by Source of Export Earnings: Primary Products (excluding Fuel)` <dbl> …
$ `Emerging Market and Developing Economies by Source of Export Earnings: Services (including Income, Transfers)` <dbl> …
$ `Emerging Market and Developing Economies by Source of Export Earnings: Diversified` <dbl> …
$ `Emerging Market and Developing Economies by External Financing: Net Creditors` <dbl> …
$ `Emerging Market and Developing Economies by External Financing: Net Debtors` <dbl> …
$ `Emerging Market and Developing Economies by External Financing: Net Debtors with Arrears and/or Rescheduling During 2019-23` <dbl> …
$ `Emerging Market and Developing Economies by External Financing: Net Debtors without Arrears and/or Rescheduling During 2019-23` <dbl> …
$ `Emerging Market and Middle-Income Economies` <dbl> …
$ `Emerging Market and Developing Economies: Low Income Developing Countries` <dbl> …
$ `Heavily Indebted Poor Countries (HIPC)` <dbl> …
$ `European Union` <dbl> …Using the datasets available in IMF Datatools
Let’s now download some series directly from these databases.
Using EcOS and EDI data
To download the appropriate series, make sure to specify the country code and indicator, for example, 111 for the USA, and NGDP for gross domestic product. Let’s try to download some WEO data.
First let’s start with WEO published data.
#Download WEO Published data for NGDP for country code 111, USA.
df <- imf_datatools$get_ecos_sdmx_data('WEO_WEO_PUBLISHED', '111', 'NGDP')
#You can quickly glance at the tail end of the data
tail(df) 111NGDP.A
2025-01-01 3.050722e+13
2026-01-01 3.171764e+13
2027-01-01 3.294171e+13
2028-01-01 3.434213e+13
2029-01-01 3.571282e+13
2030-01-01 3.715309e+13You will notice that the numbers are a little difficult to interpret, as the units are dollars and they are shown in scientific notation. Let’s change the scale to the one used in the WEO (billions).
#Download WEO Published data for NGDP for country code 111, USA.
df <- imf_datatools$get_ecos_sdmx_data('WEO_WEO_PUBLISHED', '111', 'NGDP', scale='ecos')
#Quickly glance at the tail end of the data
tail(df) 111NGDP.A
2025-01-01 30507.22
2026-01-01 31717.64
2027-01-01 32941.71
2028-01-01 34342.13
2029-01-01 35712.82
2030-01-01 37153.09Now take a closer look at a specific frequency.
#Download this same data, but at a quarterly frequency
df <- imf_datatools$get_ecos_sdmx_data('WEO_WEO_PUBLISHED','111', 'NGDP', scale='ecos', freq='Q')
#Quickly glance at the tail end of the data
tail(df) 111NGDP.Q
2025-07-01 30680.70
2025-10-01 31006.97
2026-01-01 31277.33
2026-04-01 31572.19
2026-07-01 31865.61
2026-10-01 32155.45Finally, download multiple countries and series at once.
#Download multiple countries and series in one command from ECOS
df <- imf_datatools$get_ecos_sdmx_data('WEO_WEO_PUBLISHED',c('111', '193'), c('NGDP', 'GGR'), scale='ecos')
#Quickly glance at the tail end of the data
tail(df) 111GGR.A 111NGDP.A 193GGR.A 193NGDP.A
2025-01-01 9576.032 30507.22 1020.056 2818.239
2026-01-01 10312.742 31717.64 1071.168 2945.565
2027-01-01 10789.839 32941.71 1118.061 3085.038
2028-01-01 11129.959 34342.13 1166.897 3229.983
2029-01-01 11507.495 35712.82 1221.181 3380.686
2030-01-01 11981.010 37153.09 1278.539 3538.743Using Haver data
For Haver data, make sure to specify the series and the database, such as GDP@USECON.
#Download Haver series for one country
df <- imf_datatools$get_haver_data('GDP@USECON')
#Quickly glance at the tail end of the data
tail(df) GDP@USECON
2024-01-01 28708.2
2024-04-01 29147.0
2024-07-01 29511.7
2024-10-01 29825.2
2025-01-01 30042.1
2025-04-01 30485.7You can also download multiple series in one command, but make sure they have compatible scales.
#Download multiple series in one command
df <- imf_datatools$get_haver_data(c('PJ4@USECON', 'PCUP@USECON'))
#Quickly glance at the tail end of the data
tail(df) PJ4@USECON PCUP@USECON
2025-03-01 -0.2 -0.1
2025-04-01 -0.3 0.2
2025-05-01 0.4 0.1
2025-06-01 0.1 0.3
2025-07-01 0.7 0.2
2025-08-01 -0.1 0.4If you need more info on the scales, you can easily browse the metadata for an indicator.
#Obtain details on the metadata for a particular series
metadata <- imf_datatools$haver_utilities$get_haver_metadata('GDP@USECON')
#Quickly glance at the tail end the metadata
tail(metadata) database startdate enddate frequency
gdp usecon 1947-03-31 2025-06-30 Q
descriptor numobs datetimemod magnitude
gdp Gross Domestic Product (SAAR, Bil.$) 314 2025-09-25 12:34:00 9
decprecision diftype aggtype datatype group geography1 geography2
gdp 1 0 AVG US$ N01 111
shortsource longsource
gdp BEA Bureau of Economic AnalysisUsing World Bank data
You can also access World Bank data, but make sure you denote country abbreviation instead of IMF country code.
# Download series for population in USA from World Bank DAta
df <- imf_datatools$get_worldbank_data('SP.POP.TOTL', 'USA')
#Quickly glance at the tail end of the data
tail(df) USA.SP.POP.TOTL
2019-01-01 330226227
2020-01-01 331577720
2021-01-01 332099760
2022-01-01 334017321
2023-01-01 336806231
2024-01-01 340110988Using Bloomberg data
Bloomberg data typically accessible via ECData can also be accessed, ensuring the correct nomenclature.
#Download daily Vix Index Bloomberg data
df <- imf_datatools$get_ecos_bloomberg_data('VIX Index', 'PX_LAST')
#Quickly glance at the tail end of the data
tail(df) VIX IndexPX_LAST.D
2025-09-27 NaN
2025-09-28 NaN
2025-09-29 16.12
2025-09-30 16.28
2025-10-01 16.29
2025-10-02 16.10You have now successfully downloaded and installed IMF Datatools, understood the available datasets, and downloaded relevant series.
Using iData
The new Fund‐wide iData (2025) will replaces EcOS, EDI, and can be accessed via the reticulate package. This is slightly different than the other sites as it includes both publicly available and private datasets. Let’s explore those below.
In order to access publicly available datasets, you need to specify that no token is needed via stating “FALSE” below. Let’s explore how to see the public datasets in iData below.
#alias the imported Python module for brevity of calls
dt <- imf_datatools
#Public datasets (no token needed)
dt$idata_utilities$PRIVATE <- FALSE
head(dt$idata_utilities$get_databases()) name
IMF.STA:FSIBSIS Financial Soundness Indicators (FSI), Balance Sheet, Income Statement and Memorandum Series
IMF.FAD:FM Fiscal Monitor (FM)
IMF.STA:ITG International Trade in Goods (ITG)
IMF.STA:EER Effective Exchange Rate (EER)
IMF.STA:IIPCC Currency Composition of the International Investment Position (IIPCC)
IMF.STA:ITG_WCA International Trade in Goods, World and Country Aggregates
Agency ID Resource ID Latest Version Unique ID
IMF.STA:FSIBSIS IMF.STA FSIBSIS 18.0.0 IMF.STA:FSIBSIS(18.0.0)
IMF.FAD:FM IMF.FAD FM 5.0.0 IMF.FAD:FM(5.0.0)
IMF.STA:ITG IMF.STA ITG 4.0.0 IMF.STA:ITG(4.0.0)
IMF.STA:EER IMF.STA EER 6.0.0 IMF.STA:EER(6.0.0)
IMF.STA:IIPCC IMF.STA IIPCC 13.0.0 IMF.STA:IIPCC(13.0.0)
IMF.STA:ITG_WCA IMF.STA ITG_WCA 2.0.4 IMF.STA:ITG_WCA(2.0.4)You can also list your private datasets, which you have access to.
#Private datasets based on your access level
dt$idata_utilities$PRIVATE <- TRUE
head(dt$idata_utilities$get_databases(refresh = TRUE)) name
IMF.STA:INFORMRISK INFORM Risk Indicators
IMF.STA:IL International Liquidity (IL)
ISORA:ISORA_LATEST_DATA_PUB ISORA Latest Data
IMF.RES.WEO:WEO_LIVE_2023_OCT_VINTAGE WEO Live 2023 October
IMF.STA:NDGAIN IMF-Adapted ND-GAIN Index (NDGAIN)
IMF.STA:ER Exchange Rates (ER)
Agency ID Resource ID
IMF.STA:INFORMRISK IMF.STA INFORMRISK
IMF.STA:IL IMF.STA IL
ISORA:ISORA_LATEST_DATA_PUB ISORA ISORA_LATEST_DATA_PUB
IMF.RES.WEO:WEO_LIVE_2023_OCT_VINTAGE IMF.RES.WEO WEO_LIVE_2023_OCT_VINTAGE
IMF.STA:NDGAIN IMF.STA NDGAIN
IMF.STA:ER IMF.STA ER
Latest Version
IMF.STA:INFORMRISK 1.0.2
IMF.STA:IL 13.0.1
ISORA:ISORA_LATEST_DATA_PUB 4.0.0
IMF.RES.WEO:WEO_LIVE_2023_OCT_VINTAGE 1.0.0
IMF.STA:NDGAIN 1.0.1
IMF.STA:ER 4.0.1
Unique ID
IMF.STA:INFORMRISK IMF.STA:INFORMRISK(1.0.2)
IMF.STA:IL IMF.STA:IL(13.0.1)
ISORA:ISORA_LATEST_DATA_PUB ISORA:ISORA_LATEST_DATA_PUB(4.0.0)
IMF.RES.WEO:WEO_LIVE_2023_OCT_VINTAGE IMF.RES.WEO:WEO_LIVE_2023_OCT_VINTAGE(1.0.0)
IMF.STA:NDGAIN IMF.STA:NDGAIN(1.0.1)
IMF.STA:ER IMF.STA:ER(4.0.1)Once you’ve picked a database (e.g. "IMF.STA:CPI"), you can also check its structure.
get_dimensions()lists all the ways you can slice your data, i.e., by country, frequency etc.dims <- dt$idata_utilities$get_dimensions("IMF.STA:CPI") print(dims)Description Dimension Order COUNTRY Country 0 INDEX_TYPE Index type 1 COICOP_1999 Expenditure Category 2 TYPE_OF_TRANSFORMATION Type of Transformation 3 FREQUENCY Frequency 4
get_dimension_values()this function provides the full list of entries within a specific dimension, e.g., Country.vals <- dt$idata_utilities$get_dimension_values("IMF.STA:CPI", "COUNTRY")
Retrieving a series
Once you have itentified your dataset and explored its dimensions you can build a query by joining dimension codes with period. Leave the key specifications empty to include all values as shown below.
# Example: CPI level for USA & JPN monthly (_T = level, M = monthly)
key <- "USA+JPN.CPI._T..M"
df <- dt$idata_utilities$get_idata_data("IMF.STA:CPI", key)
tail(df) JPN.CPI._T.IX.M JPN.CPI._T.POP_PCH_PA_PT.M JPN.CPI._T.SRP_IX.M
2025-03-01 111.1 0.27075812 117.1735
2025-04-01 111.5 0.36003600 117.5954
2025-05-01 111.8 0.26905830 117.9118
2025-06-01 111.7 -0.08944544 117.8063
2025-07-01 111.9 0.17905103 118.0172
2025-08-01 NaN NaN NaN
JPN.CPI._T.SRP_POP_PCH_PA_PT.M JPN.CPI._T.SRP_YOY_PCH_PA_PT.M
2025-03-01 0.27075812 3.638060
2025-04-01 0.36003600 3.528319
2025-05-01 0.26905830 3.422757
2025-06-01 -0.08944544 3.234750
2025-07-01 0.17905103 3.038674
2025-08-01 NaN NaN
JPN.CPI._T.YOY_PCH_PA_PT.M USA.CPI._T.IX.M
2025-03-01 3.638060 146.6595
2025-04-01 3.528319 147.1162
2025-05-01 3.422757 147.4235
2025-06-01 3.234750 147.9261
2025-07-01 3.038674 148.1494
2025-08-01 NaN 148.5750
USA.CPI._T.POP_PCH_PA_PT.M USA.CPI._T.SRP_IX.M
2025-03-01 0.2247071 146.6595
2025-04-01 0.3114456 147.1162
2025-05-01 0.2088561 147.4235
2025-06-01 0.3409391 147.9261
2025-07-01 0.1509792 148.1494
2025-08-01 0.2872638 148.5750
USA.CPI._T.SRP_POP_PCH_PA_PT.M USA.CPI._T.SRP_YOY_PCH_PA_PT.M
2025-03-01 0.2247071 2.390725
2025-04-01 0.3114456 2.311289
2025-05-01 0.2088561 2.354897
2025-06-01 0.3409391 2.669213
2025-07-01 0.1509792 2.704902
2025-08-01 0.2872638 2.916174
USA.CPI._T.YOY_PCH_PA_PT.M
2025-03-01 2.390725
2025-04-01 2.311289
2025-05-01 2.354897
2025-06-01 2.669213
2025-07-01 2.704902
2025-08-01 2.916174To obtain data in long format, add
longformat = TRUE.# Long lf <- dt$idata_utilities$get_idata_data("IMF.STA:CPI", key, longformat = TRUE) tail(lf)COUNTRY INDEX_TYPE COICOP_1999 TYPE_OF_TRANSFORMATION FREQUENCY 10113 USA CPI _T YOY_PCH_PA_PT M 10114 USA CPI _T YOY_PCH_PA_PT M 10115 USA CPI _T YOY_PCH_PA_PT M 10116 USA CPI _T YOY_PCH_PA_PT M 10117 USA CPI _T YOY_PCH_PA_PT M 10118 USA CPI _T YOY_PCH_PA_PT M dates OBS_VALUE 10113 2025-03-01 2.390725 10114 2025-04-01 2.311289 10115 2025-05-01 2.354897 10116 2025-06-01 2.669213 10117 2025-07-01 2.704902 10118 2025-08-01 2.916174To pivot by a dimension (e.g. COUNTRY), use
panel = "COUNTRY"# Panel by country pf <- dt$idata_utilities$get_idata_data("IMF.STA:CPI", key, panel = "COUNTRY") tail(pf)COUNTRY dates CPI._T.IX.M CPI._T.POP_PCH_PA_PT.M CPI._T.SRP_IX.M 1690 USA 2025-03-01 146.6595 0.2247071 146.6595 1691 USA 2025-04-01 147.1162 0.3114456 147.1162 1692 USA 2025-05-01 147.4235 0.2088561 147.4235 1693 USA 2025-06-01 147.9261 0.3409391 147.9261 1694 USA 2025-07-01 148.1494 0.1509792 148.1494 1695 USA 2025-08-01 148.5750 0.2872638 148.5750 CPI._T.SRP_POP_PCH_PA_PT.M CPI._T.SRP_YOY_PCH_PA_PT.M 1690 0.2247071 2.390725 1691 0.3114456 2.311289 1692 0.2088561 2.354897 1693 0.3409391 2.669213 1694 0.1509792 2.704902 1695 0.2872638 2.916174 CPI._T.YOY_PCH_PA_PT.M 1690 2.390725 1691 2.311289 1692 2.354897 1693 2.669213 1694 2.704902 1695 2.916174
IMF Datatools allows you to easily browse, inspect, and retrieve IMF datasets in R.