{smcl}
{* Help file update 2025-09-15}{...}
{hline}
help file for {hi:shapowen}{right:P. Van Kerm (September 2025)}
{hline}

{title:Title}

{pstd}
{hi:shapowen} {hline 2} A generic Shapley-Owen value calculator
{p_end}


{title:Syntax}

{p 8 15 2}
{hi:shapowen}  {it:itemlist}  , {it:options}  :  {it:cmd} ... @ ... 
{p_end}

{phang}where {it:itemlist} is a list of {it:items} and {it: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 {c 39}coalition{c 39} for Owen value calculation. 
Nested structures of any depth are allowed: brackets can be embedded in brackets can be embedded in brackets... 
{p_end}

{synoptset 28 tabbed}
{p2coldent:{it:options}}Description{p_end}
{synoptline}
{synopt: {bf:{ul:sca}larexpressions}({it:string})}Scalar-valued expressions that are evaluated after each call to {it:cmd}{p_end}
{synopt: {bf:{ul:mat}rixexpressions}({it:string})}Matrix-valued expressions that are evaluated after each call to {it:cmd}{p_end}
{synopt: {bf:{ul:sub}stitution}({it:string})}Subsitute instead of remove elements excluded from a coalition in the call to {it:cmd}{p_end}
{synopt: {bf:{ul:sep}arator}({it:string})}Separate items by {it:string} instead of the default blank space when substituting in {it:@}{p_end}
{synopt: {bf:{ul:emptys}ubstitute}({it:string})}Use {it:string} instead of an empty string when substituting the empty set in {it:@}{p_end}
{synopt: {bf:{ul:emptyv}alue}({it:string})}Use {it:string} as output value (for all output expressions) when evaluating {it:cmd} on the empty set{p_end}
{synopt: {bf:{ul:err}orvalue}({it:string})}Use {it:string} as output value (for all output expressions) if execution of {it:cmd} fails after substitution{p_end}
{synopt: {bf:frame}}Store estimates of all combinations of items in new frame called ShapOwen{p_end}
{synopt: {bf:trace}}Display output of all calls to {it:cmd}{p_end}
{synopt: {bf:showfull}}Display output of call to {it:cmd} with the full set of elements{p_end}
{synopt: {bf:showempty}}Display output of call to {it:cmd} with the empty set{p_end}
{synopt: {bf:trace}}Display output of all calls to {it:cmd}{p_end}
{synopt: {bf:nodots}}Suppress display of progression dots{p_end}
{synopt: {bf:treemap}}Plot results as tree map{p_end}
{synopt: {bf:treemapopts(string)}}Tree map plot options{p_end}
{synoptline}


{title:Description}

{pstd}
{hi: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. 
{p_end}

{pstd}
Shapley values (Shapley, 1953) are used to quantify contributions of individual elements of a set {it:N} to the aggregate {it:value} collectively generated by the set {it: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 {c 39}coalitions{c 39}. Contributions to the collective outcome are then evaluated for each coalition and each elements of the coalitions.   
{p_end}

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

{pstd}
Pre-defined coalitions in {it: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.
{p_end}

{pstd}
{hi:shapowen} calculates and reports the Shapley value for all elements in {it: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. 
{p_end}

{pstd}
For the sake of completeness, {hi:shapowen} also reports the Banzhaf value of all elements (Banzhaf, 1965), their marginal contribution to an empty set (under {it:First}), their marginal contribution to a complete set (under {it:Last}), and their marginal contribution in the particular sequence formed by {it:itemlist}. The right panel shows all estimates divided by the value of the {c 39}Grand coalition{c 39} (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. 
{p_end}


{title:Options}

{phang}
{bf:{ul:sca}larexpressions(}{it:string}{bf:)} contains a list of scalar valued expressions evaluated after each call to {it:cmd} and giving the outcome(s) of the {c 39}coalition{c 39}. Expressions are typically formed by {bf:e()} or {bf:r()} scalars available after {it: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.
{p_end}

{phang}
{bf:{ul:mat}rixexpressions(}{it:string}{bf:)} contains a list of matrix valued expressions evaluated after each call to {it:cmd} and giving the outcome(s) of the {c 39}coalition{c 39}. 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. 
{p_end}

{pstd}
At least one of {bf:scalarexpressions(}{it:string}{bf:)} or {bf:matrixexpressions(}{it:string}{bf:)} is required. 
{p_end}


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

{phang}
{bf: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 {bf: _shapowen}.
{p_end}

{phang}
{bf:trace} requests that the output of all calls to {it:cmd} are shown.
{p_end}

{phang}
{bf:showfull} requests display of the output of call to {it:cmd} with the full set of elements.
{p_end}

{phang}
{bf:showempty} requests display of the output of call to {it:cmd} with the empty set.
{p_end}

{phang}
{bf:{ul:sep}arator(}{it:string}{bf:)} requests that the separator {it:string} is used instead of the default blank space to separate items when substituting in {it:@}.
{p_end}

{phang}
{bf:{ul:emptys}ubstitute(}{it:string}{bf:)} requests that {it:string} is used instead of an empty string when substituting an empty set in {it:@}.
{p_end}

{phang}
{bf:{ul:emptyv}alue}({it:string}) requests to use {it:string} as result instead executing {it:cmd} when evaluating {it:cmd} on the empty set. {it:string} is assigned to all output expressions.
{p_end}

{phang}
{bf:{ul:err}orvalue}({it:string}) requests to use {it:string} as result if execution of {it:cmd} fails after substitution and then continue execution. {it:string} is assigned to all output expressions. Use with care.
{p_end}

{phang}
{bf:nodots} suppresses display of progression dots.
{p_end}

{phang}
{bf: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 {stata findit treemap:treemap} plotting commmand (which needs to be pre-installed). {bf:treemapopts(}{it:string}{bf:)} contains options passed directly to {cmd:treemap}. 
{p_end}


{title:Saved results}

{pstd}{hi:shapowen} is an r-class command and stores the following results.{p_end}

{synoptset 15 tabbed}{...}
{p2col 5 15 19 2: Local macros}{p_end}
{synopt: {bf:r(stats)}}list of expressions estimated{p_end}
{synopt: {bf:r(items)}}list of items as provided in input{p_end}
{synopt: {bf:r(cmd)}}{bf:cmd} as passed as argument{p_end}
{synopt: {bf:r(item1)}}level-0 item -- the grand coalition composition{p_end}
{synopt: {bf:r(item2)}, {bf:r(item3)}, ...}items or combinations of items in nested structres{p_end}

{synoptset 15 tabbed}{...}
{p2col 5 15 19 2: Scalars}{p_end}
{synopt: {bf:r(K)}}cardinality of the grand coalition (number of individual items){p_end}
{synopt: {bf:r(neval)}}number of evaluations{p_end}

{synoptset 15 tabbed}{...}
{p2col 5 15 19 2: Matrices}{p_end}
{synopt: {bf:r(ShapOw)}}Shapley-Owen values (items in rows and statistics in columns){p_end}
{synopt: {bf:r(relShapOw)}}Shapley-Owen contributions relative to total (grand coalition) value{p_end}
{synopt: {bf:r(Banzhaf)}}Banzhaf values{p_end}
{synopt: {bf:r(relBanzhaf)}}Banzhaf values divided by total (grand coalition) value{p_end}
{synopt: {bf:r(First)}}Marginal contribution of items when entered first (in isolation){p_end}
{synopt: {bf:r(relFirst)}}Marginal contribution of items when entered first relative to total (grand coalition) value{p_end}
{synopt: {bf:r(Last)}}Marginal contribution of items when entered last{p_end}
{synopt: {bf:r(relLast)}}Marginal contribution of items when entered last relative to total (grand coalition) value{p_end}
{synopt: {bf:r(Sequence)}}Marginal contribution of items when entered in the order of {it:itemlist}{p_end}
{synopt: {bf:r(relSequence)}}Marginal contribution of items when entered in the order of {it:itemlist}{p_end}
{synopt: {bf:r(depth)}}Depth level of items in the (nested) Shapley-Owen structure{p_end}

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

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


{title:Examples}

{p 8 12 2}{inp:. sysuse nlsw88}{p_end}
{p 8 12 2}{inp:. gen lnw = ln(wage)}{p_end}

{p 8 12 2}{inp:. shapowen  i.collgrad i.race c.age##c.age i.south  , sca(e(r2)):  regress lnw @}{p_end}

{p 8 12 2}{inp:. shapowen  i.collgrad i.race c.age##c.age i.south  , sca(e(r2) e(r2_a)):  regress lnw @}{p_end}

{p 8 12 2}{inp:. shapowen  i.collgrad c.age##c.age i.south   , sca(_b[2.race]):  regress lnw i.race @}{p_end}

{p 8 12 2}{inp:. shapowen  i.collgrad c.age##c.age i.race i.south  , sca(e(r2_a)) sep(##) :  regress lnw  @}{p_end}

{p 8 12 2}{inp:. shapowen  i.collgrad c.age##c.age i.race i.south  , sca(e(r2_a)) sep(##) trace :  regress lnw  @}{p_end}

{p 8 12 2}{inp:. shapowen  "i.race i.collgrad c.age##c.age" "i.industry i.occupation" "i.south i.smsa" , sca(e(r2_a)) :  regress lnw @}{p_end}

{p 8 12 2}{inp:. 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 @}{p_end}

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


{title:Also see}

{psee}
Online:  
{helpb shapley} (if installed), 
{helpb shapleyx} (if installed), 
{helpb adecomp} (if installed), 
{helpb drdecomp} (if installed),
{helpb hoishapley} (if installed),
{helpb iop} (if installed),
{helpb treemap} (if installed)


{title:Acknowledgements}

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

{title:Author}

{pstd}
{browse "http://prophil.vankerm.net":Philippe Van Kerm}
{break}University of Luxembourg
{break}philippe.vankerm@uni.lu
{p_end}

{pstd}Bug reports, comments and suggestions welcome.{p_end}


{title:Suggested citation}

{pstd}
Van Kerm, P. (2025).{browse "https://ideas.repec.org/c/boc/bocode/s459513.html":shapowen: A generic Shapley-Owen value calculator}. Statistical Software Components S459513, Boston College Department of Economics. 
{p_end}


{title:References}

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

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

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

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

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