help file for shapowenP. Van Kerm (September 2025)

Title

shapowen -- A generic Shapley-Owen value calculator

Syntax

shapowen itemlist , options : cmd ... @ ...

where itemlist is a list of items and cmd is a Stata command. The list of items is a set of blank separated words.
Words enclosed in double quotes are treated as a single item.
Items grouped in brackets are treated as a pre-defined 'coalition' for Owen value calculation.
Nested structures of any depth are allowed: brackets can be embedded in brackets can be embedded in brackets...

options Description

scalarexpressions(string) Scalar-valued expressions that are evaluated after each call to cmd

matrixexpressions(string) Matrix-valued expressions that are evaluated after each call to cmd

substitution(string) Subsitute instead of remove elements excluded from a coalition in the call to cmd

separator(string) Separate items by string instead of the default blank space when substituting in @

emptysubstitute(string) Use string instead of an empty string when substituting the empty set in @

emptyvalue(string) Use string as output value (for all output expressions) when evaluating cmd on the empty set

errorvalue(string) Use string as output value (for all output expressions) if execution of cmd fails after substitution

frame Store estimates of all combinations of items in new frame called ShapOwen

trace Display output of all calls to cmd

showfull Display output of call to cmd with the full set of elements

showempty Display output of call to cmd with the empty set

trace Display output of all calls to cmd

nodots Suppress display of progression dots

treemap Plot results as tree map

treemapopts(string) Tree map plot options

Description

shapowen is a generic Shapley-Owen value calculator. It is designed as a generic prefix command to allow for a broad spectrum of implementations of Shapley value decompositions.

Shapley values (Shapley, 1953) are used to quantify contributions of individual elements of a set N to the aggregate value collectively generated by the set N. This is used, e.g., to apportion contributions in order to distribute payoffs (or costs) fairly when only the collective outcome is observable. The Owen value (Owen, 1975) applies to nested structures where elements in the set can form preset 'coalitions'. Contributions to the collective outcome are then evaluated for each coalition and each elements of the coalitions.

shapowen takes as main argument a 'pseudo instruction' cmd containing a placeholder character @. @ can, in principle, appear anywhere in cmd, e.g., as a variable list argument, as part of option specifications, as part of an if clause, as part of a weight specification, etc. shapowen executes cmd for all possible combinations of elements of items substituted in turn for @.
Items can be anything (strings, numbers). At each iteration, scalar-valued or matrix-value expressions specified in options scalarexpressions(string) and matrixexpressions(string) are evaluated. Evaluations are aggregated to form the Shapley or Owen value of every element in items.

Pre-defined coalitions in itemlist for calculation of Owen values are specified by grouping elements in brackets. Nested structures of arbitrary depth are allowed: any number of sub-coalitions can be formed within any coalition by using nested bracket groupings.

shapowen calculates and reports the Shapley value for all elements in itemlist. If a nested structure is given, what is reported is the Owen value of all individual elements as well as the value of all preset coalitions.

For the sake of completeness, shapowen also reports the Banzhaf value of all elements (Banzhaf, 1965), their marginal contribution to an empty set (under First), their marginal contribution to a complete set (under Last), and their marginal contribution in the particular sequence formed by itemlist. The right panel shows all estimates divided by the value of the 'Grand coalition' (formed by all elements in the set). The relative values under the Shapley-Owen column therefore provide a measure of the share of each element to the total and sum up to 1.

Options

scalarexpressions(string) contains a list of scalar valued expressions evaluated after each call to cmd and giving the outcome(s) of the 'coalition'. Expressions are typically formed by e() or r() scalars available after cmd. Expressions may contain Stata functions but must evaluate to a scalar. Expressions that contain blank spaces must be enclosed in double quotes. Multiple expressions are allowed.

matrixexpressions(string) contains a list of matrix valued expressions evaluated after each call to cmd and giving the outcome(s) of the 'coalition'. Expressions may contain Stata functions but must evaluate to a Stata matrix. Expressions that contain blank spaces must be enclosed in double quotes. Multiple expressions are allowed.

At least one of scalarexpressions(string) or matrixexpressions(string) is required.

substitution(string) modifies the treatment of elements excluded from a coalition. By default, these are removed from the list of items when substituted into @ in the call to cmd. Instead, if a substitution(string) is provided, then excluded elements are replaced by the element in the same position given in the substitution string. The number of elements in string must therefore match the number of elements in itemlist.

frame requests that estimates of all stored expressions for all combinations of items needed to evaluate the Shapley-Owen value are stored in a new frame called _shapowen.

trace requests that the output of all calls to cmd are shown.

showfull requests display of the output of call to cmd with the full set of elements.

showempty requests display of the output of call to cmd with the empty set.

separator(string) requests that the separator string is used instead of the default blank space to separate items when substituting in @.

emptysubstitute(string) requests that string is used instead of an empty string when substituting an empty set in @.

emptyvalue(string) requests to use string as result instead executing cmd when evaluating cmd on the empty set. string is assigned to all output expressions.

errorvalue(string) requests to use string as result if execution of cmd fails after substitution and then continue execution. string is assigned to all output expressions. Use with care.

nodots suppresses display of progression dots.

treemap plots resulting Shapley-Owen decomposition as a tree map. Only the first outcome expression is plotted (see 'Saved results' for plotting additional outcomes). Results are formatted and passed directly to A Naqvi's treemap plotting commmand (which needs to be pre-installed). treemapopts(string) contains options passed directly to treemap.

Saved results

shapowen is an r-class command and stores the following results.

Local macros

r(stats) list of expressions estimated

r(items) list of items as provided in input

r(cmd) cmd as passed as argument

r(item1) level-0 item -- the grand coalition composition

r(item2), r(item3), ... items or combinations of items in nested structres

Scalars

r(K) cardinality of the grand coalition (number of individual items)

r(neval) number of evaluations

Matrices

r(ShapOw) Shapley-Owen values (items in rows and statistics in columns)

r(relShapOw) Shapley-Owen contributions relative to total (grand coalition) value

r(Banzhaf) Banzhaf values

r(relBanzhaf) Banzhaf values divided by total (grand coalition) value

r(First) Marginal contribution of items when entered first (in isolation)

r(relFirst) Marginal contribution of items when entered first relative to total (grand coalition) value

r(Last) Marginal contribution of items when entered last

r(relLast) Marginal contribution of items when entered last relative to total (grand coalition) value

r(Sequence) Marginal contribution of items when entered in the order of itemlist

r(relSequence) Marginal contribution of items when entered in the order of itemlist

r(depth) Depth level of items in the (nested) Shapley-Owen structure

If the option frame is specified, a new frame named _shapowen is created and contains estimates of scalar and matrix expressions for all necessary coalitions.

If the option treemap is specified, a new frame named _shapowen_treemap is created and contains estimates formatted so as to be plotted directly with treemap. This can be used for plotting multiple outcomes or for alternative plotting designs.

Examples

. sysuse nlsw88

. gen lnw = ln(wage)

. shapowen i.collgrad i.race c.age##c.age i.south , sca(e(r2)): regress lnw @

. shapowen i.collgrad i.race c.age##c.age i.south , sca(e(r2) e(r2_a)): regress lnw @

. shapowen i.collgrad c.age##c.age i.south , sca(_b[2.race]): regress lnw i.race @

. shapowen i.collgrad c.age##c.age i.race i.south , sca(e(r2_a)) sep(##) : regress lnw @

. shapowen i.collgrad c.age##c.age i.race i.south , sca(e(r2_a)) sep(##) trace : regress lnw @

. shapowen "i.race i.collgrad c.age##c.age" "i.industry i.occupation" "i.south i.smsa" , sca(e(r2_a)) : regress lnw @

. shapowen (i.race i.collgrad c.age##c.age) (i.industry i.occupation) (i.south i.smsa) , sca(e(r2_a)) showfull treemap : regress lnw @

. ssc install sgini

. shapowen 1 2 3 4 5 6 7 8 9 10 11 12 , sca(r(coeff)) sep(,) emptyvalue(0) : sgini wage if inlist(industry,@)

Also see

Online:
shapley (if installed),
shapleyx (if installed),
adecomp (if installed),
drdecomp (if installed),
hoishapley (if installed),
iop (if installed),
treemap (if installed)

Acknowledgements

The general design of shapowen's syntax largely draws on shapley (and shapleyx) (Kolenikov, 2000). Feedback from participants at the Belgian and UK Stata User Conferences 2025 appreciated.

Author

Philippe Van Kerm

University of Luxembourg

philippe.vankerm@uni.lu

Bug reports, comments and suggestions welcome.

Suggested citation

Van Kerm, P. (2025).shapowen: A generic Shapley-Owen value calculator. Statistical Software Components S459513, Boston College Department of Economics.

References

Banzhaf III, J. F. (1965). Weighted voting doesn't work: A mathematical analysis, Rutgers Law Review 19, pp. 317–343.

Kolenikov, S. (2000). SHAPLEY: Stata module to perform additive decomposition of sample statistic.
Statistical Software Components S411401, Boston College Department of Economics.

Naqvi, A. (2024). Stata package "treemap" version 1.6. Release date 09 October 2024. https://github.com/asjadnaqvi/stata-treemap.

Owen, G. (1977). Values of games with a priori unions, in R. Henn and O. Moeschlin, eds, Mathematical Economics and Game Theory, Springer Berlin Heidelberg, Berlin, Heidelberg, pp. 76–88.

Shapley, L. S. (1953). A value for n-person games, in H. Kuhn and A. W. Tucker, eds, Contributions to the Theory of Games, Vol. II, Princeton: Princeton University Press, Princeton, NJ, pp. 307–317.