debtkit: Debt Sustainability Analysis and Fiscal Risk Assessment

Description

Analyses government debt sustainability using the standard debt dynamics framework from Blanchard (1990) doi:10.1787/budget-v2-art12-en and the IMF Debt Sustainability Analysis methodology (IMF, 2013) and the Sovereign Risk and Debt Sustainability Framework (IMF, 2022). Projects debt-to-GDP paths, decomposes historical debt changes into interest, growth, and primary balance contributions, and estimates fiscal reaction functions following Bohn (1998) doi:10.1162/003355398555793. Produces stochastic fan charts via Monte Carlo simulation, standardised stress tests, and IMF- style heat map risk assessments. Computes S1/S2 sustainability gap indicators used by the European Commission. All methods are pure computation with no external dependencies beyond base R; works with fiscal data from any source.

Author(s)

Maintainer: Charles Coverdale charlesfcoverdale@gmail.com

See Also

Useful links:

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

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

Bohn's Fiscal Reaction Function Test

Description

Estimates the fiscal reaction function following Bohn (1998): pb(t) = rho * d(t-1) + alpha * Z(t) + epsilon(t), where pb is the primary balance-to-GDP ratio, d is lagged debt-to-GDP, and Z is a matrix of control variables.

Usage

dk_bohn_test(
  primary_balance,
  debt,
  controls = NULL,
  method = c("ols", "rolling", "quadratic"),
  window = NULL,
  robust_se = FALSE
)

Arguments

Details

A positive and statistically significant rho indicates that the government systematically raises the primary surplus in response to rising debt, satisfying a sufficient condition for debt sustainability.

Value

An S3 object of class dk_bohn with components:

rho

Estimated fiscal response coefficient (full sample or last rolling window).

rho_se

Standard error of rho.

rho_pvalue

p-value for the test H0: rho = 0.

sustainable

Logical; TRUE if rho > 0 and rho_pvalue < 0.05.

model

The lm object from the full-sample (OLS/quadratic) or last-window (rolling) regression.

method

The method used ("ols", "rolling", or "quadratic").

rho_ts

A data.frame with columns index, rho, rho_lower, rho_upper if method = "rolling"; NULL otherwise.

robust_se

Logical; whether HAC standard errors were used.

rho2

Coefficient on debt squared (only for method = "quadratic").

rho2_se

Standard error of rho2 (quadratic only).

rho2_pvalue

p-value for rho2 (quadratic only).

turning_point

Debt level where fiscal response peaks, -rho/(2*rho2) (quadratic only).

References

Bohn, H. (1998). "The Behavior of U.S. Public Debt and Deficits." Quarterly Journal of Economics, 113(3), 949–963. doi:10.1162/003355398555793

Ghosh, A.R., Kim, J.I., Mendoza, E.G., Ostry, J.D. and Qureshi, M.S. (2013). "Fiscal Fatigue, Fiscal Space and Debt Sustainability in Advanced Economies." The Economic Journal, 123(566), F4–F30.

Examples

# Simulate data with positive fiscal response
set.seed(42)
n <- 50
debt <- cumsum(rnorm(n, 0.01, 0.02)) + 0.6
pb <- 0.04 * debt + rnorm(n, 0, 0.005)
result <- dk_bohn_test(pb, debt)
print(result)

Compare Debt Projections

Description

Produces a side-by-side comparison of multiple debt-to-GDP projections, aligning them by year and computing terminal values.

Usage

dk_compare(..., metric = "debt")

Arguments

Value

An S3 object of class dk_comparison containing:

paths

A data.frame with a year column and one column per scenario, giving the debt-to-GDP path.

terminal

Named numeric vector of terminal debt-to-GDP ratios.

Examples

d <- dk_sample_data()
base <- dk_project(tail(d$debt, 1), 0.03, 0.04, 0.01, horizon = 5)
austerity <- dk_project(tail(d$debt, 1), 0.03, 0.04, 0.03, horizon = 5)
stimulus <- dk_project(tail(d$debt, 1), 0.03, 0.05, -0.01, horizon = 5)

comp <- dk_compare(
  Baseline = base,
  Austerity = austerity,
  Stimulus = stimulus
)
comp
plot(comp)

Decompose Historical Debt Changes

Description

Breaks down observed year-on-year changes in the debt-to-GDP ratio into four components:

Usage

dk_decompose(debt, interest_rate, gdp_growth, primary_balance, years = NULL)

Arguments

Details

1. Interest effect: r_t / (1 + g_t) \cdot d_{t-1}

2. Growth effect: -g_t / (1 + g_t) \cdot d_{t-1}

3. Primary balance effect: -pb_t

4. Stock-flow adjustment (residual): actual change minus the sum of the three identified components.

This is the standard decomposition used by the IMF (2013) and European Commission. The SFA residual captures privatisation receipts, exchange-rate valuation changes, below-the-line operations, and any measurement error.

Value

An S3 object of class dk_decomposition containing:

data

A data.frame with columns year, debt, change, interest_effect, growth_effect, snowball_effect, primary_balance_effect, and sfa.

years

The year labels used.

References

Blanchard, O.J. (1990). Suggestions for a New Set of Fiscal Indicators. OECD Economics Department Working Papers, No. 79. doi:10.1787/budget-v2-art12-en

International Monetary Fund (2013). Staff Guidance Note for Public Debt Sustainability Analysis in Market-Access Countries. IMF Policy Paper.

Examples

d <- dk_sample_data()
dec <- dk_decompose(
  debt = d$debt,
  interest_rate = d$interest_rate,
  gdp_growth = d$gdp_growth,
  primary_balance = d$primary_balance,
  years = d$years
)
dec
plot(dec)

Estimate Joint Distribution of Macro Shocks

Description

Estimates the joint distribution of GDP growth, interest rate, and primary balance shocks for use in stochastic debt sustainability analysis. Three estimation methods are supported: a VAR(1) model (default), residual bootstrap, and a simple multivariate normal fit.

Usage

dk_estimate_shocks(
  gdp_growth,
  interest_rate,
  primary_balance,
  method = c("var", "bootstrap", "normal"),
  years = NULL
)

Arguments

Details

For method = "var", a VAR(1) is estimated equation-by-equation via OLS on the lagged system. The residual variance-covariance matrix captures the joint shock distribution. For method = "bootstrap", the same VAR(1) is estimated and residuals are stored for block resampling. For method = "normal", the sample means and covariance of the raw series are used directly.

Value

An S3 object of class dk_shocks with components:

vcov

3x3 variance-covariance matrix with rows/columns named growth, interest_rate, primary_balance.

means

Named numeric vector of variable means.

method

The estimation method used.

residuals

Matrix of residuals (for "var" and "bootstrap") or NULL (for "normal").

var_coefficients

VAR(1) coefficient matrix (for "var") or NULL.

n_obs

Number of observations used.

Examples

set.seed(1)
n <- 30
g <- rnorm(n, 0.02, 0.015)
r <- rnorm(n, 0.03, 0.01)
pb <- rnorm(n, -0.02, 0.01)
shocks <- dk_estimate_shocks(g, r, pb)
print(shocks)

Stochastic Debt Fan Chart

Description

Projects debt-to-GDP paths via Monte Carlo simulation using the standard debt dynamics equation. At each step, correlated shocks to growth, the interest rate, and the primary balance are drawn from a multivariate normal distribution and added to the baseline paths. The result is a fan chart showing the distribution of projected debt paths.

Usage

dk_fan_chart(
  debt,
  interest_rate,
  gdp_growth,
  primary_balance,
  shocks = NULL,
  shock_vcov = NULL,
  n_sim = 1000L,
  horizon = 5L,
  confidence = c(0.1, 0.25, 0.5, 0.75, 0.9),
  seed = NULL
)

Arguments

Value

An S3 object of class dk_fan with components:

simulations

Matrix of dimension n_sim x (horizon + 1) containing all simulated debt paths.

quantiles

Matrix of quantiles at each time step, with rows corresponding to the confidence levels.

baseline

Numeric vector of length horizon + 1; the deterministic baseline debt path.

confidence

The quantile levels used.

horizon

The projection horizon.

prob_above

Named list with the probability of debt exceeding 60 percent, 90 percent, and 120 percent of GDP at the terminal year.

Examples

set.seed(1)
n <- 30
g <- rnorm(n, 0.02, 0.015)
r <- rnorm(n, 0.03, 0.01)
pb <- rnorm(n, -0.02, 0.01)
shocks <- dk_estimate_shocks(g, r, pb)

fan <- dk_fan_chart(
  debt = 0.90,
  interest_rate = 0.03,
  gdp_growth = 0.02,
  primary_balance = -0.02,
  shocks = shocks,
  n_sim = 500,
  horizon = 10,
  seed = 42
)
print(fan)

Gross Financing Needs

Description

Computes gross financing needs (GFN) as a share of GDP over a projection horizon. GFN represents the total amount of new borrowing a government requires each year to cover its primary deficit, interest payments, and maturing debt:

Usage

dk_gfn(debt, interest_rate, maturity_profile, primary_balance, horizon = 5)

Arguments

Details

GFN_t = -pb_t + r_t \cdot d_t + m_t

where pb is the primary balance (positive = surplus), r is the effective interest rate, d is debt-to-GDP, and m is maturing debt as a share of GDP.

Value

A data.frame with columns:

year

Year index (1 to horizon).

primary_deficit

Primary deficit (negative of primary balance).

interest_payments

Interest payments as a share of GDP.

maturing_debt

Maturing debt as a share of GDP.

gfn

Total gross financing needs as a share of GDP.

References

International Monetary Fund (2013). Staff Guidance Note for Public Debt Sustainability Analysis in Market-Access Countries. IMF Policy Paper.

Examples

# Scalar average maturity of 7 years
dk_gfn(debt = 0.90, interest_rate = 0.03,
       maturity_profile = 7, primary_balance = -0.02)

# Explicit maturity profile
dk_gfn(debt = 0.90, interest_rate = 0.03,
       maturity_profile = c(0.15, 0.12, 0.10, 0.08, 0.05),
       primary_balance = -0.02)

IMF-Style Risk Heat Map

Description

Classifies sovereign debt risk as low, medium, or high based on IMF (2013) thresholds for debt-to-GDP, gross financing needs, and optional debt-profile indicators. Advanced economies and emerging markets use different thresholds.

Usage

dk_heat_map(
  debt,
  gross_financing_needs,
  debt_profile = NULL,
  country_type = c("ae", "em")
)

Arguments

Value

An S3 object of class dk_heatmap containing:

ratings

Named list of risk ratings ("low", "medium", or "high") for each indicator.

overall

Character. Overall risk level: "high" if any indicator is high, "medium" if any is medium, otherwise "low".

values

Named list of input values.

thresholds

The thresholds used for classification.

country_type

The country type used.

References

International Monetary Fund (2013). Staff Guidance Note for Public Debt Sustainability Analysis in Market-Access Countries. IMF Policy Paper.

International Monetary Fund (2022). Staff Guidance Note on the Sovereign Risk and Debt Sustainability Framework for Market Access Countries. IMF Policy Paper.

Examples

hm <- dk_heat_map(
  debt = 0.90,
  gross_financing_needs = 0.18,
  debt_profile = list(fx_share = 0.30, share_st_debt = 0.15),
  country_type = "ae"
)
hm

Project Debt-to-GDP Path

Description

Projects a debt-to-GDP ratio forward using the standard debt dynamics equation:

Usage

dk_project(
  debt,
  interest_rate,
  gdp_growth,
  primary_balance,
  sfa = 0,
  horizon = 10,
  date = NULL
)

Arguments

Details

d_{t+1} = \frac{1 + r_t}{1 + g_t} d_t - pb_t + sfa_t

where d is the debt-to-GDP ratio, r is the effective nominal interest rate on government debt, g is nominal GDP growth, pb is the primary balance as a share of GDP (positive = surplus), and sfa captures stock-flow adjustments (e.g. privatisation receipts, exchange-rate valuation changes, below-the-line operations).

Value

An S3 object of class dk_projection containing:

debt_path

Numeric vector of length horizon + 1, giving the debt-to-GDP ratio from the initial period through the terminal period.

decomposition

A data.frame with columns year, debt, interest_effect, growth_effect, snowball_effect, primary_balance_effect, sfa_effect, and change.

horizon

The projection horizon.

inputs

A list storing all input parameters.

References

Blanchard, O.J. (1990). Suggestions for a New Set of Fiscal Indicators. OECD Economics Department Working Papers, No. 79. doi:10.1787/budget-v2-art12-en

International Monetary Fund (2013). Staff Guidance Note for Public Debt Sustainability Analysis in Market-Access Countries. IMF Policy Paper.

Examples

d <- dk_sample_data()
proj <- dk_project(
  debt = tail(d$debt, 1),
  interest_rate = 0.03,
  gdp_growth = 0.04,
  primary_balance = 0.01
)
proj
plot(proj)

Interest Rate-Growth Differential and Debt-Stabilising Primary Balance

Description

Computes the interest rate-growth differential (r - g), a key indicator of debt sustainability. When r > g, debt grows faster than the economy (the "snowball effect" is adverse) and a primary surplus is needed to stabilise the debt ratio. When r < g, the government can run a primary deficit and still see the debt ratio fall.

Usage

dk_rg(interest_rate, gdp_growth, inflation = NULL, debt = NULL)

Arguments

Details

If debt is supplied, the function also computes the debt-stabilising primary balance: the primary surplus (as a share of GDP) required to hold the debt-to-GDP ratio constant at its current level. This is given by:

pb^* = \frac{r - g}{1 + g} \cdot d

If inflation is supplied, the function computes the real r - g differential by deflating both the interest rate and GDP growth: r_{real} = (1 + r)/(1 + \pi) - 1 and g_{real} = (1 + g)/(1 + \pi) - 1.

Value

A named list with:

rg_differential

Numeric vector. The nominal r - g differential.

real_rg

Numeric vector. The real r - g differential. Only present if inflation was supplied.

debt_stabilising_pb

Numeric vector. The debt-stabilising primary balance as a share of GDP. Only present if debt was supplied.

References

Blanchard, O.J. (1990). Suggestions for a New Set of Fiscal Indicators. OECD Economics Department Working Papers, No. 79. doi:10.1787/budget-v2-art12-en

Barrett, P. (2018). Interest-Growth Differentials and Debt Limits in Advanced Economies. IMF Working Paper, WP/18/82.

Examples

# Simple scalar case
dk_rg(interest_rate = 0.04, gdp_growth = 0.03)

# With debt: compute stabilising primary balance
dk_rg(interest_rate = 0.04, gdp_growth = 0.03, debt = 0.90)

# With inflation: compute real r-g
dk_rg(interest_rate = 0.04, gdp_growth = 0.05, inflation = 0.02)

# Vector case using sample data
d <- dk_sample_data()
dk_rg(
  interest_rate = d$interest_rate,
  gdp_growth = d$gdp_growth,
  debt = d$debt
)

Sample Fiscal Data

Description

Provides built-in sample datasets for running examples and tests without requiring external data.

Usage

dk_sample_data(country = c("sample", "high_debt"))

Arguments

Value

A list with components:

years

Integer vector of years.

debt

Numeric vector of debt-to-GDP ratios.

interest_rate

Numeric vector of effective interest rates on government debt.

gdp_growth

Numeric vector of nominal GDP growth rates.

primary_balance

Numeric vector of primary balance-to-GDP ratios (positive = surplus).

Examples

d <- dk_sample_data()
d$debt
d$years

IMF Standardised Stress Tests

Description

Applies six standardised IMF stress-test scenarios to a baseline debt projection using the debt dynamics equation:

Usage

dk_stress_test(
  debt,
  interest_rate,
  gdp_growth,
  primary_balance,
  horizon = 5,
  growth_shock = -0.01,
  interest_shock = 0.02,
  exchange_shock = 0.15,
  fx_share = 0,
  pb_shock = -0.01,
  contingent_shock = 0.1,
  calibrate = NULL
)

Arguments

Details

d_{t+1} = \frac{1 + r_t}{1 + g_t} d_t - pb_t + sfa_t

The six scenarios are:

1. Growth shock: GDP growth reduced by growth_shock for the first two years.

2. Interest rate shock: interest rate increased by interest_shock for the full horizon.

3. Exchange rate shock: debt increases by debt * fx_share * exchange_shock in year 1 (one-off stock-flow adjustment from currency depreciation).

4. Primary balance shock: primary balance reduced by pb_shock for the first two years.

5. Combined shock: simultaneous growth shock of growth_shock / 2 and interest rate shock of interest_shock / 2.

6. Contingent liabilities: one-off debt increase of contingent_shock in year 1.

Value

An S3 object of class dk_stress containing:

scenarios

A data.frame with columns year, baseline, growth, interest_rate, exchange_rate, primary_balance, combined, and contingent.

terminal

Named numeric vector of terminal debt-to-GDP under each scenario.

inputs

A list storing all input parameters.

References

International Monetary Fund (2013). Staff Guidance Note for Public Debt Sustainability Analysis in Market-Access Countries. IMF Policy Paper.

International Monetary Fund (2022). Staff Guidance Note on the Sovereign Risk and Debt Sustainability Framework for Market Access Countries. IMF Policy Paper.

Examples

st <- dk_stress_test(
  debt = 0.90,
  interest_rate = 0.03,
  gdp_growth = 0.04,
  primary_balance = 0.01,
  fx_share = 0.20
)
st
plot(st)

S1 and S2 Sustainability Gap Indicators

Description

Computes the S1 and S2 fiscal sustainability gap indicators used by the European Commission to assess the size of the permanent budgetary adjustment required to ensure debt sustainability.

Usage

dk_sustainability_gap(
  debt,
  structural_balance,
  gdp_growth,
  interest_rate,
  ageing_costs = 0,
  target_debt = 0.6,
  target_year = 20,
  indicator = c("both", "S1", "S2")
)

Arguments

Details

S1 measures the permanent adjustment in the structural primary balance needed to bring the debt-to-GDP ratio to target_debt in target_year years, taking into account projected increases in age-related expenditure.

S2 measures the permanent adjustment needed to stabilise the debt-to-GDP ratio over an infinite horizon, incorporating the full net present value of future increases in age-related spending.

Value

An S3 object of class dk_sgap containing:

S1

The S1 sustainability gap (or NA if not requested).

S2

The S2 sustainability gap (or NA if not requested).

risk_S1

Risk classification for S1: "low", "medium", or "high".

risk_S2

Risk classification for S2: "low", "medium", or "high".

required_pb

The required structural primary balance implied by S1.

current_pb

The current structural primary balance.

inputs

A list storing all input parameters.

References

European Commission (2012). Fiscal Sustainability Report 2012. European Economy 8/2012, Directorate-General for Economic and Financial Affairs.

Examples

dk_sustainability_gap(
  debt = 0.90,
  structural_balance = -0.01,
  gdp_growth = 0.015,
  interest_rate = 0.025,
  ageing_costs = 0.02
)