Package {icio}

Version:	1.0.0
Title:	Global Value Chain Decomposition of Inter-Country Input-Output Tables
Description:	Four global value chain (GVC) decompositions of gross exports from inter-country input-output tables are implemented. The Leontief decomposition derives the value added origin of exports by country and industry, as in Hummels, Ishii and Yi (2001) <doi:10.1016/S0022-1996(00)00093-3>. The Koopman, Wang and Wei (2014) <doi:10.1257/aer.104.2.459> decomposition splits country-level exports into 9 value added components, and the Wang, Wei and Zhu (2013) <doi:10.3386/w19677> decomposition splits bilateral exports into 16 value added components. The Borin and Mancini (2019) <doi:10.1596/1813-9450-8804> decomposition splits country-, sector- or bilateral-level exports into up to 13 value added and GVC components, and also provides a corrected version of the (biased) Koopman-Wang-Wei decomposition. It is the recommended method and reproduces the 'icio' command for 'Stata' described in Belotti, Borin and Mancini (2021) <doi:10.1177/1536867X211045573>.
Maintainer:	Sebastian Krantz <sebastian.krantz@graduateinstitute.ch>
Depends:	R (≥ 3.5.0)
Imports:	data.table, matrixStats
License:	GPL-3
URL:	https://sebkrantz.github.io/icio/, https://github.com/SebKrantz/icio
BugReports:	https://github.com/SebKrantz/icio/issues
Suggests:	testthat, knitr, rmarkdown
VignetteBuilder:	knitr
Encoding:	UTF-8
NeedsCompilation:	yes
Config/roxygen2/version:	8.0.0
Packaged:	2026-08-05 20:50:35 UTC; sebastiankrantz
Author:	Sebastian Krantz [aut, cre], Bastiaan Quast [aut], Fei Wang [aut], Victor Stolzenburg [aut], Oliver Reiter [ctb]
Repository:	CRAN
Date/Publication:	2026-09-07 10:20:02 UTC

Global Value Chain Decomposition of Inter-Country Input-Output Tables

Description

Four global value chain (GVC) decompositions are implemented. The Leontief decomposition derives the value added origin of exports by country and industry as in Hummels, Ishii and Yi (2001). The Koopman, Wang and Wei (2014) decomposition splits country-level exports into 9 value added components, and the Wang, Wei and Zhu (2013) decomposition splits bilateral exports into 16 value added components. The Borin and Mancini (2019) decomposition splits country-, sector- or bilateral-level exports into up to 13 value added and GVC components, and also provides a corrected version of the (biased) KWW decomposition. It is the recommended method and reproduces the Stata icio command.

Contents

Functions to load an ICIO table and create an 'icio' object

load_icio()
load_icio_csv()

Functions to perform GVC decompositions on an 'icio' object

bm()
leontief()
kww()
wwz()

Interface function dispatching on the method, also for lists of 'icio' objects (e.g. several years)

decomp()

Function to obtain KWW decomposition from WWZ decomposition

wwz2kww()

Example ICIO data

data("leather")

Note

icio is derived from the CRAN package decompr (Quast and Kummritz 2015), of which the author was a co-author and which is no longer maintained. bm() is the R counterpart of decompose() in the Julia package GlobalValueChains.jl.

Author(s)

Sebastian Krantz sebastian.krantz@graduateinstitute.ch
Bastiaan Quast
Fei Wang
Victor Stolzenburg

References

Hummels, D., Ishii, J., & Yi, K. M. (2001). The nature and growth of vertical specialization in world trade. Journal of international Economics, 54(1), 75-96.

Koopman, R., Wang, Z., & Wei, S. J. (2014). Tracing value-added and double counting in gross exports. American Economic Review, 104(2), 459-94.

Wang, Zhi, Shang-Jin Wei, and Kunfu Zhu (2013). Quantifying international production sharing at the bilateral and sector levels (No. w19677). National Bureau of Economic Research.

Borin, A., & Mancini, M. (2019). Measuring What Matters in Global Value Chains and Value-Added Trade. World Bank Policy Research Working Paper 8804.

Belotti, F., Borin, A., & Mancini, M. (2021). icio: Economic analysis with inter-country input-output tables. The Stata Journal, 21(3), 708-755.

See Also

https://sebkrantz.github.io/icio/

Borin-Mancini Decomposition of Gross Exports and Imports

Description

Decomposes gross exports (or imports) into value-added and Global Value Chain (GVC) components following the Borin and Mancini (2019) framework, as implemented in the Stata icio command (Belotti, Borin and Mancini 2021). It is the R counterpart of the decompose() function in the Julia package GlobalValueChains.jl, and operates on an icio object created by load_icio.

Usage

bm(
  x,
  aggregation = c("country", "sector", "bilateral"),
  perspective = c("exporter", "world", "self", "importer"),
  approach = c("source", "sink"),
  flow = c("exports", "imports")
)

Arguments

Details

The supported combinations mirror the Stata icio command and GlobalValueChains.jl:

All terms are in the same units as the input-output table (e.g. millions of USD). The following accounting identities hold for exports: GEXP = DC + FC, DC = DVA + DDC, FC = FVA + FDC, DVA = VAX + REF, and (exporter/source only) GVC = GVCB + GVCF = GEXP - DAVAX and GVCB = FC + DDC; for imports GIMP = VA + DC.

The exporter / source decomposition is additive: the "sector" result is the sum of the "bilateral" result over importers, and the "country" result is the sum of the "sector" result over industries. The "sink" approach shares the domestic content DC and foreign content FC with "source" at every cell; only the value-added vs double-counted split differs. The "self" perimeter draws the boundary at the export flow itself, so DVA (there DVA^\star) is weakly larger than under either exporter approach.

Value

A data.table with one row per unit and one column per value-added term, preceded by factor identifier columns: Exporting_Country (country exports); Exporting_Country, Exporting_Industry (sector); Exporting_Country, Exporting_Industry, Importing_Country (bilateral exports); Importing_Country (country imports); or Importing_Country, Origin_Country (bilateral imports). The attribute "decomposition" is set to "bm".

Author(s)

Sebastian Krantz

References

Borin, A. and Mancini, M. (2019). Measuring What Matters in Global Value Chains and Value-Added Trade. World Bank Policy Research Working Paper 8804.

Belotti, F., Borin, A. and Mancini, M. (2021). icio: Economic analysis with intercountry input-output tables. The Stata Journal, 21(3), 708-755.

See Also

kww, wwz, leontief, icio-package

Examples

# Load example data and create an 'icio' object
data(leather)
dec <- load_icio(leather)

# Country-level decomposition (exporter perspective, source approach; 13 terms)
bm(dec)

# Country-level "corrected KWW" (world perspective, sink approach; 9 terms)
bm(dec, perspective = "world", approach = "sink")

# Sector- and bilateral-sector-level decompositions
bm(dec, aggregation = "sector")
bm(dec, aggregation = "bilateral", approach = "sink")   # adds VAXIM

# Self (own-flow) perimeter, and the importer-perspective import decomposition
bm(dec, aggregation = "bilateral", perspective = "self")
bm(dec, flow = "imports")

Run a GVC Decomposition

Description

A compact interface to the four decompositions: it dispatches on method and, given a list of 'icio' objects (e.g. one per year), runs the decomposition on each and stacks the results.

Usage

decomp(x, method = c("bm", "leontief", "kww", "wwz"), ..., idcol = "Label")

Arguments

Details

Building an 'icio' object is by far the most expensive step (it involves inverting a GN x GN matrix), so it is done once by load_icio and reused across decompositions. Pass the object to bm, leontief, kww or wwz directly if you prefer.

Value

A data.table - see bm, leontief, kww or wwz for the columns of each decomposition. If x is a list, the results are stacked with rbindlist and prefixed with idcol.

Author(s)

Sebastian Krantz, Bastiaan Quast

References

Hummels, D., Ishii, J., & Yi, K. M. (2001). The nature and growth of vertical specialization in world trade. Journal of international Economics, 54(1), 75-96.

Koopman, R., Wang, Z., & Wei, S. J. (2014). Tracing value-added and double counting in gross exports. American Economic Review, 104(2), 459-94.

Wang, Zhi, Shang-Jin Wei, and Kunfu Zhu (2013). Quantifying international production sharing at the bilateral and sector levels (No. w19677). National Bureau of Economic Research.

Borin, A., & Mancini, M. (2019). Measuring What Matters in Global Value Chains and Value-Added Trade. World Bank Policy Research Working Paper 8804.

See Also

load_icio, bm, icio-package

Examples

# Load leather example data
data(leather)

# Explore the data
str(leather)

# Create the 'icio' object
m <- load_icio(leather)

## Decomposing gross exports:

# Borin-Mancini (2019), the recommended method
decomp(m)
decomp(m, aggregation = "bilateral")

# Leontief, Koopman-Wang-Wei and Wang-Wei-Zhu
decomp(m, method = "leontief")
decomp(m, method = "kww")
decomp(m, method = "wwz")

# Multiple tables at once, e.g. one per year, stacked with a 'Year' column
decomp(list(`2015` = m, `2016` = m), idcol = "Year")

Koopman-Wang-Wei Decomposition of Gross Exports

Description

This function performs the Koopman-Wang-Wei (2014) decomposition of a countries gross exports into 9 separate value added components.

Usage

kww(x)

Arguments

Value

A data.table where a country's gross exports is decomposed into 9 components (columns), as detailed in Figure 1 of the AER paper:

Note

The KWW decomposition is known to be biased. As shown by Borin and Mancini (2019), it systematically underestimates the foreign value added in exports – and correspondingly overstates foreign double counting – because the entire foreign content that the direct importer re-exports to third countries is classified as 'foreign double counted', including the part (value added generated in the importing country and re-exported onwards) that is never recorded as foreign value added in any other flow. KWW also overlooks the bilateral dimension of trade, so it cannot correctly split domestic value added between absorption by the direct importer and by third markets (hence indicators such as DAVAX cannot be derived from it). Borin and Mancini (2019) correct these issues using a sink-based, world-level perspective for the foreign content of exports; this corrected KWW decomposition is available as bm(x, perspective = "world", approach = "sink").

Author(s)

Sebastian Krantz

References

Koopman, R., Wang, Z., & Wei, S. J. (2014). Tracing value-added and double counting in gross exports. American Economic Review, 104(2), 459-94.

Borin, A., & Mancini, M. (2019). Measuring What Matters in Global Value Chains and Value-Added Trade. World Bank Policy Research Working Paper 8804.

See Also

bm, wwz, wwz2kww, icio-package

Examples

# Load example data
data(leather)

# Create intermediate object (class 'icio')
m <- load_icio(leather)
 
# Perform the KWW decomposition
kww(m)

Leather Example ICIO Data

Description

An example 3 x 3 ICIO table describing a GVC for leather products with industries 'Agriculture', 'Textile and Leather' and 'Transport Equipment' for the countries 'Argentina', 'Turkey' and 'Germany'.

Usage

data("leather")

Format

A list of class 'iot' with the following elements:

inter

9 x 9 input output matrix where each column gives the value of inputs supplied to the corresponding country-industry by each row country-industry.

final

9 x 3 final demand matrix showing the final demand in each country (column) for each country-industry's (rows) produce.

countries

character vector of country names (matching columns of final).

industries

character vector of industries, such that as.vector(t(outer(countries, industries, FUN = paste, sep = "."))) generates the row- and column-names of inter and the rownames of final.

out

A vector of gross country-industry output. In a complete productive system it should be equal to rowSums(inter) + rowSums(final).

See Also

icio-package

Leontief Decomposition

Description

The Leontief decomposition of gross flows (exports, final demand, output) into their value added origins.

Usage

leontief(x, post = c("exports", "output", "final_demand", "none"), long = TRUE)

Arguments

Details

The Leontief decomposition is obtained by pre-multiplying the flow measure (e.g. exports) with the value added multiplier matrix [VB = V(I-A)^{-1}], obtained by pre-multiplying the Leontief Inverse matrix [B = (I-A)^{-1}] with a diagonal matrix [V] containing the direct value added share in each industries output.

V is obtained as diag(v / o) where o is total industry output. v is either supplied to load_icio or computed as o - colSums(x) with x the raw IO matrix. If o is not supplied to load_icio, it is computed as rowSums(x) + rowSums(y) where y is the matrix of final demands. If both o and v are not supplied to load_icio, this is equivalent to computing V as diag(1 - colSums(A)), with A is the row-normalized IO matrix also used to compute the Leontief Inverse [B].

Value

If long = TRUE a molten data.table containing the elements of the decomposed flows matrix in the final column, preceded by several identifier columns. If long = FALSE the decomposed flows matrix is simply returned.

Author(s)

Bastiaan Quast

References

Leontief, W. (Ed.). (1986). Input-output economics. Oxford University Press.

Hummels, D., Ishii, J., & Yi, K. M. (2001). The nature and growth of vertical specialization in world trade. Journal of international Economics, 54(1), 75-96.

Wang, Zhi, Shang-Jin Wei, and Kunfu Zhu (2013). Quantifying international production sharing at the bilateral and sector levels (No. w19677). National Bureau of Economic Research.

See Also

bm, kww, wwz, icio-package

Examples

# Load example data
data(leather)

# Create intermediate object (class 'icio')
m <- load_icio(leather)

# Perform the Leontief decomposition of each country-industries 
# exports into their value added origins by country-industry
leontief(m)

Load an Inter-Country Input-Output Table

Description

Reads the raw ICIO matrices and precomputes everything the decompositions need, returning an 'icio' class object. This is the entry point for all decompositions.

Usage

load_icio(
  inter,
  final,
  countries,
  industries,
  output = NULL,
  va = NULL,
  null_inventory = FALSE
)

Arguments

Details

Only A and B are dense GN x GN matrices. The masked and block-diagonal variants of them that the decompositions require (A with the domestic blocks zeroed, the domestic and foreign parts of B) are derived on the fly by the functions that need them, being either recoverable from A and B in a few operations or, in the case of the domestic Leontief inverse, block-diagonal and thus 1 - 1/G structural zeros.

Value added defaults to the column residual of the table (output - colSums(inter)), which reproduces the Stata icio command exactly. Supplying a va that differs from it makes the column sums of V B deviate from 1, so identities such as GEXP = DC + FC may no longer hold exactly - faithful to the supplied data.

Value

An 'icio' class object - a list with the following elements:

The country-industry names identifying the rows and columns are available as names(x$Vc) or dimnames(x$B)[[1L]].

Author(s)

Sebastian Krantz, Bastiaan Quast. Adapted from code by Fei Wang.

See Also

load_icio_csv, decomp, bm, icio-package

Examples

# Load example data
data(leather)

# Create intermediate object (class 'icio') from an 'iot' object
m <- load_icio(leather)

# Equivalent: passing the matrices directly
m <- load_icio(leather$inter, leather$final, leather$countries, leather$industries)

# Examine the object
str(m)

Load an ICIO Table from the 'icio' CSV Format

Description

Reads an Inter-Country Input-Output table from the CSV format used by the Stata icio command and returns an 'icio' class object, ready for decomp and the decomposition functions.

Usage

load_icio_csv(
  table,
  countries,
  industries = NULL,
  output = NULL,
  va = NULL,
  ...
)

Arguments

Value

An 'icio' class object, see load_icio.

Author(s)

Sebastian Krantz

See Also

load_icio, decomp, icio-package

Examples

# Write the example table out in the 'icio' CSV format: a headerless
# GN x (GN + G) matrix [inter | final], plus a one-column country list
data(leather)
tbl <- tempfile(fileext = ".csv")
cls <- tempfile(fileext = ".csv")
write.table(cbind(leather$inter, leather$final), tbl,
            sep = ",", row.names = FALSE, col.names = FALSE)
write.table(leather$countries, cls,
            sep = ",", row.names = FALSE, col.names = FALSE, quote = FALSE)

# Read it back: industries default to "sector1", ..., "sectorN"
m <- load_icio_csv(tbl, cls)
str(m$i)

# Supplying the real industry codes so they appear in the results
m <- load_icio_csv(tbl, cls, industries = leather$industries)
decomp(m, aggregation = "sector")

# The country list may also be given directly as a character vector
m <- load_icio_csv(tbl, leather$countries, industries = leather$industries)

unlink(c(tbl, cls))

Wang-Wei-Zhu Decomposition of Gross Exports

Description

This function performs the Wang-Wei-Zhu decomposition of country-sector level gross exports into 16 value added components by importing country.

Usage

wwz(x, verbose = FALSE)

Arguments

Details

Adapted from code by Fei Wang.

Value

A long-format data.table with one row per (exporting country-industry, importing country) pair and columns Exporting_Country, Exporting_Industry, Importing_Country followed by the 16 decomposition terms (as detailed in Table E1 in the appendix of Wang, Wei & Zhu 2013) and diagnostic items:

Author(s)

Bastiaan Quast

References

Wang, Zhi, Shang-Jin Wei, and Kunfu Zhu (2013). Quantifying international production sharing at the bilateral and sector levels (No. w19677). National Bureau of Economic Research.

See Also

bm, kww, wwz2kww, icio-package

Examples

# Load example data
data(leather)

# Create intermediate object (class 'icio')
m <- load_icio(leather)

# Perform the WWZ decomposition
wwz(m)

Koopman-Wang-Wei from Wang-Wei-Zhu Decomposition

Description

This function by default returns a disaggregated version of the the Koopman-Wang-Wei (KWW) decomposition breaking up sector-level gross exports into 9 value added terms, from an already computed and more detailed (16 term) Wang-Wei-Zhu decomposition of sector-level gross exports. An aggregation option also allows obtaining the aggregate KWW decomposition.

Usage

wwz2kww(x, aggregate = FALSE)

Arguments

Details

The mapping of the 16 terms in the WWZ decomposition to the 9 terms in the KWW decomposition is provided in table E2 in the appendix of the WWZ (2013) paper. The table is reproduced here using the term naming conventions followed in this package.

Value

A data.table with exports decomposed into 9 components (columns), see the table above and kww for a shorter description of the 9 terms.

Note

If both WWZ and KWW decompositions are required, it is computationally more efficient to call wwz2kww(x, aggregate = TRUE) on an already computed WWZ decomposition, than to call kww on an 'icio' object.

Author(s)

Sebastian Krantz

References

Koopman, R., Wang, Z., & Wei, S. J. (2014). Tracing value-added and double counting in gross exports. American Economic Review, 104(2), 459-94.

Wang, Zhi, Shang-Jin Wei, and Kunfu Zhu (2013). Quantifying international production sharing at the bilateral and sector levels (No. w19677). National Bureau of Economic Research.

See Also

wwz, kww, icio-package

Examples

# Load example data
data(leather)

# Create intermediate object (class 'icio')
m <- load_icio(leather)
 
# Perform the WWZ decomposition
WWZ <- wwz(m)

# Obtain a disaggregated KWW decomposition
KWW <- wwz2kww(WWZ)

# Aggregate KWW 
wwz2kww(WWZ, aggregate = TRUE)

# Same as running KWW directly, but the former is more efficient 
# if we already have the WWZ
kww(m)