Package {readimf}

readimf: Access International Monetary Fund Data via the 'SDMX' 3.0 API

Description

Download macroeconomic and financial statistics from the International Monetary Fund data portal (https://data.imf.org), served through an 'SDMX' 3.0 REST API. Provides a tidy interface to the Fund's flagship databases, beginning with the World Economic Outlook, and reads the compact 'SDMX-CSV' representation of each query for fast, dependency-light parsing.

Author(s)

Maintainer: Charles Coverdale charlesfcoverdale@gmail.com

See Also

Useful links:

• https://github.com/charlescoverdale/readimf

• Report bugs at https://github.com/charlescoverdale/readimf/issues

Fetch an IMF codelist

Description

Download a codelist (the valid codes and labels for a dimension), for example the country list or an indicator list, as a tidy data frame.

Usage

imf_codelist(id, agency = "IMF", version = "+")

Arguments

Value

A data frame with columns code and label.

Examples

imf_codelist("CL_WEO_INDICATOR", agency = "IMF.RES")

Currency composition of official foreign exchange reserves (COFER)

Description

The share, or nominal value, of a reserve currency in allocated world foreign exchange reserves, from the IMF COFER data flow. COFER is published only for world and country-group aggregates, never individual economies.

Usage

imf_cofer(
  currency = "USD",
  measure = c("share", "value"),
  group = "G001",
  freq = "Q",
  start = NULL,
  end = NULL
)

Arguments

Value

An object of class imf_tbl (a data frame).

See Also

imf_data()

Examples

# US dollar share of world allocated reserves
imf_cofer(currency = "USD", measure = "share")

Primary commodity prices

Description

Commodity price levels or indices, from the IMF PCPS data flow (Primary Commodity Price System). Prices are global, so no country is required.

Usage

imf_commodity(
  indicator = "PALLFNF",
  measure = c("index", "usd", "pch_year", "pch"),
  freq = "M",
  start = NULL,
  end = NULL
)

Arguments

Value

An object of class imf_tbl (a data frame).

See Also

imf_data()

Examples

imf_commodity("POILWTI", measure = "usd", start = 2015)
imf_commodity("PALLFNF", measure = "index")

IMF country codelist

Description

Convenience wrapper returning the master country and area codelist (ISO 3-letter codes and names).

Usage

imf_countries()

Value

A data frame with columns code and label.

Examples

imf_countries()

Consumer prices

Description

Consumer price index or year-on-year inflation, from the IMF CPI data flow.

Usage

imf_cpi(
  country,
  measure = c("index", "inflation"),
  freq = "M",
  start = NULL,
  end = NULL
)

Arguments

Value

An object of class imf_tbl (a data frame).

See Also

imf_data(), imf_ifs()

Examples

imf_cpi("GBR", measure = "inflation", start = 2015)

Fetch data from any IMF data flow

Description

The general-purpose accessor behind the database-specific wrappers. Supply a data flow id and a key. Use imf_dimensions() to discover the dimension order and imf_codelist() to discover valid codes.

Usage

imf_data(
  dataflow,
  key = NULL,
  agency = NULL,
  version = "+",
  start = NULL,
  end = NULL
)

Arguments

Value

An object of class imf_tbl (a data frame).

Examples

imf_data("WEO", "GBR.NGDP_RPCH.A", start = 2015, end = 2024)

List the IMF data flow catalogue

Description

Return every dataset (data flow) published on the IMF 'SDMX' 3.0 portal: its id, descriptive name, owning agency and version. The catalogue is fetched once per session and memoised; pass refresh = TRUE to refetch. If the API cannot be reached, a snapshot bundled with the package is returned.

Usage

imf_dataflows(refresh = FALSE)

Arguments

Value

A data frame with columns id, name, agency and version.

Examples

flows <- imf_dataflows()
head(flows)

Inspect the dimensions of a data flow

Description

Return the ordered dimensions of a data flow's data structure. This is the order in which values must be supplied when building a key for imf_data().

Usage

imf_dimensions(dataflow, agency = NULL)

Arguments

Value

A data frame with columns position (zero-based) and dimension.

Examples

imf_dimensions("WEO")

Bilateral goods trade (Direction of Trade)

Description

Goods exports or imports between a reporter and a partner economy, from the IMF IMTS data flow (the successor to Direction of Trade Statistics).

Usage

imf_dots(
  reporter,
  partner,
  flow = c("exports", "imports"),
  freq = "M",
  start = NULL,
  end = NULL
)

Arguments

Value

An object of class imf_tbl (a data frame).

See Also

imf_data()

Examples

# US goods exports to the UK
imf_dots("USA", "GBR", flow = "exports", start = 2020)

Government finance statistics

Description

General government revenue or expenditure, from the IMF GFS_SOO data flow (Government Finance Statistics, Statement of Operations).

Usage

imf_gfs(
  country,
  indicator = c("revenue", "expenditure"),
  measure = c("xdc", "pct_gdp"),
  sector = "S13",
  freq = "A",
  start = NULL,
  end = NULL
)

Arguments

Value

An object of class imf_tbl (a data frame).

See Also

imf_data()

Examples

imf_gfs("GBR", indicator = "revenue", measure = "pct_gdp")

Fetch a legacy IFS series from its new home

Description

International Financial Statistics (IFS) was retired when the IMF moved to the 'SDMX' 3.0 portal. Its content was split across several thematic data flows (consumer prices, exchange rates, monetary statistics and others) with no official code crosswalk, which broke every workflow built on the old IFS series codes. imf_ifs() accepts a legacy IFS indicator code and routes the request to the correct new data flow and key.

Use imf_ifs_map() to see which legacy series are supported and where each one now lives. Country coverage in the new data flows varies, especially for interest rates; if a country returns nothing, try another.

Usage

imf_ifs(indicator, country = NULL, freq = NULL, start = NULL, end = NULL)

Arguments

Value

An object of class imf_tbl (a data frame). The originating IFS code is retained in the imf_ifs_code attribute.

See Also

imf_ifs_map(), imf_data()

Examples

# UK consumer price index, the series formerly known as IFS PCPI_IX
imf_ifs("PCPI_IX", country = "GBR", start = 2015)

Show the IFS migration crosswalk

Description

Reveal which new data flow and key each supported legacy IFS indicator maps to. This is the documentation behind imf_ifs() and a migration aid in its own right: it shows where a retired IFS series now lives without fetching any data.

Usage

imf_ifs_map(indicator = NULL)

Arguments

Value

A data frame with columns ifs_code, description, agency, dataflow, key_template and default_freq.

See Also

imf_ifs()

Examples

imf_ifs_map()
imf_ifs_map("PCPI_IX")

Search the IMF data flow catalogue

Description

Case-insensitive search over data flow ids and names.

Usage

imf_search(pattern)

Arguments

Value

A data frame: the matching rows of imf_dataflows().

Examples

imf_search("consumer price")
imf_search("balance of payments")

Download World Economic Outlook data

Description

Fetch series from the IMF World Economic Outlook (WEO), the Fund's flagship forecast database. The WEO is openly available, so no API key is required.

Usage

imf_weo(
  indicator = NULL,
  country = NULL,
  start = NULL,
  end = NULL,
  vintage = "latest"
)

Arguments

Value

An object of class imf_tbl (a data frame) with columns country, indicator, freq, period and value, carrying provenance attributes.

Examples

imf_weo("NGDP_RPCH", country = c("GBR", "USA"), start = 2015, end = 2024)

Print an IMF data table

Description

Print an IMF data table

Usage

## S3 method for class 'imf_tbl'
print(x, n = 10L, ...)

Arguments

Value

x, invisibly.