{smcl}
{* *! version 1.4.0  28july2010}{...}
{cmd:help scores}
{hline}

{title:Title}

    {hi:scores -} create scores of variables (depending on user specified number of missings)


{title:Syntax}

    {cmd:scores} {newvar} = {it:fcn}({varlist}) {ifin} [, {it:options}]


{pstd}
where the syntax of {it:fcn} is

{p2colset 5 15 26 2}{...}
{p2col :{it:fcn}}description{p_end}
{p2line}
{p2col:{hi:min}}minima of {it:varlist}{p_end}
{p2col:{hi:max}}maxima of {it:varlist}{p_end}
{p2col:{hi:total}}total (sum) scores of {it:varlist}{p_end}
{p2col:{hi:sd}}standard deviations of {it:varlist}{p_end}
{p2col:{hi:mean}}mean scores of {it:varlist}{p_end}


{p 8 15 2}

{synoptset 18 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Main}
{synopt:{opt mi{ul on}nv{ul off}alid(#)}}minimum number of variables with valid values;
         default is {cmd:(1)}{p_end}
{synopt:{opt sc:ore(argument)}}transformation of mean scores according to {it:argument}{p_end}
{synopt:{opt min:val(#)}}theoretically lowest value of scale items;
         default is {cmd:(0)}{p_end}
{synopt:{opt max:val(#)}}theoretically highest value of scale items;
         default is {cmd:(0)}{p_end}
{synopt:{opt a:uto}}determine range of values of scale items automatically{p_end}
{synopt:{opt replace}}replace existing variable by {it:newvar}{p_end}

{syntab:Sub (arguments of {hi:score()})}
{synopt:{opt z}}z-score transformation of mean scores{p_end}
{synopt:{opt c:entered}}centering of mean scores at the overall mean{p_end}
{synopt:{opt p:omp}}transformation of mean scores to POMP scores{p_end}
{synoptline}
{p2colreset}{...}


{title:Description}

{pstd}
Using row functions of {manhelp egen D}, {cmd:-scores-} calculates scores according to {hi:{it:fcn}}
using variables listed in {hi:({it:varlist})} and assigns them to the new variable {hi:{it:newvar}}. If
the number of valid values of {hi:({it:varlist})} is less than {hi:minvalid({it:#})} the resulting
score will be set to missing.

{pstd}
If {hi:{it:fcn}} is {hi:mean} the {hi:score({it:argument})} can be used to request
a transformation of the scores to z-scores, to scores centered at the overall mean, or to
POMP (= {hi:p}ercent {hi:o}f {hi:m}aximum {hi:p}ossible) scores with 0 and 100 as minimum
and maximum possible values (see: Cohen, P., Cohen, J., Aiken, L.S. & West, S.G. (1999).
{browse "http://www.informaworld.com/smpp/content~content=a785043286~db=all~order=page":The problem of units and the circumstance for POMP}.
{it:Multivariate Behavioral Research}, {it:34}, 315-346). The
latter requires to specify the minimum and maximum possible values of the items listed in
{hi:varlist} by using the options {hi:minval({it:#})} and {hi:maxval({it:#})}.
Alternatively, if all items listed in {hi:varlist} have value labels defining the same range of values,
the minimum and maximum possible values can be determined automatically by using the option {hi:auto}.

{pstd}
If {hi:{it:newvar}} exists already you can use the option {hi:replace} to replace it by the new
variable generated.


{title:Options}

{dlgtab:Main}

{phang}
{opt mi{ul on}nv{ul off}alid(#)} specifies how many values must be valid for calculating a score. If
the number of valid values is less than {it:#} the resulting score will be set to missing.

{phang}
{opt sc:ore(argument)} requests a transformation of the scores. This will only work if mean
scores have been requested by {hi:mean({it:varlist})}. Three transformations are possible
according to {hi:({it:argument})} (see below).

{phang}
{opt min:val(#)} specifies the theoretical minimum value of the items ({it:#} =
lowest value possible) (only useful if POMP scores have been requested by {hi:score(pomp)}).

{phang}
{opt max:val(#)} specifies the theoretical maximum value of the items ({it:#} =
highest value possible) (only useful if POMP scores have been requested by {hi:score(pomp)}).

{phang}
{opt a:uto} requests to determine the range of values of the items (lowest and highest possible values)
automatically. {hi:auto} requires that all items listed in {hi:varlist} have values labels defining
the same range of values. This option overrides values specified using {hi:minval({it:#})} and
{hi:maxval({it:#})} (only useful if POMP scores have been requested by {hi:score(pomp)}).

{phang}
{opt replace} requests that {hi:{it:newvar}} will replace an already existing
variable (if it exists).

{dlgtab:Sub (option score)}

{phang}
{opt sc:ore}{hi:(z)} requests a transformation of the mean scores to z-scores (resulting
mean = 0, sd = 1)

{phang}
{opt sc:ore}{hi:({ul on}c{ul off}entered)} requests to center the mean scores at the overall mean
(resulting mean = 0)

{phang}
{opt sc:ore}{hi:({ul on}p{ul off}omp)} requests to transform the scores to POMP ({hi:p}ercent {hi:o}f
{hi:m}aximum {hi:p}ossible) scores with 0 and 100 as minimum and maximum possible
values. Note that {hi:score(pomp)} requires to specify the minimum and maximum
possible values of the items listed in {hi:({it:varlist})} by using the options
{hi:minval({it:#})} and {hi:maxval({it:#})}, as well.


{title:Examples}

{pstd}
The following data set allows to show how {hi:-scores-} creates scores depending
on the number of missing values defined by the user:

{cmd:. clear all}
{cmd:. input v1-v5}

     {txt}       v1         v2         v3         v4         v5
  1.{cmd: 1 2 3 4 5}
{txt}  2.{cmd: 1 2 3 4 .}
{txt}  3.{cmd: 1 2 3 . .}
{txt}  4.{cmd: 1 . 3 4 .}
{txt}  5.{cmd: 1 2 . . .}
{txt}  6.{cmd: 1 . . . .}
{txt}  7.{cmd: . . . . .}
{txt}  8.{cmd: end}


{pstd}
Generate variable {it:test} containing the {hi:minima} of the four variables v1, v3, v4, and v5
(per default the value of {it:test} is valid if at least one variable of {it:varlist}
has a valid value):

{cmd:. scores test=min(v1 v3-v5)}
{txt}(1 missing value generated)
(0 real changes made)

{cmd:. list}
{txt}
     {c TLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c TRC}
     {c |} {res}v1   v2   v3   v4   v5   test {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c RT}
  1. {c |} {res} 1    2    3    4    5      1 {txt}{c |}
  2. {c |} {res} 1    2    3    4    .      1 {txt}{c |}
  3. {c |} {res} 1    2    3    .    .      1 {txt}{c |}
  4. {c |} {res} 1    .    3    4    .      1 {txt}{c |}
  5. {c |} {res} 1    2    .    .    .      1 {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c RT}
  6. {c |} {res} 1    .    .    .    .      1 {txt}{c |}
  7. {c |} {res} .    .    .    .    .      . {txt}{c |}
     {c BLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c BRC}


{pstd}
Replace variable test by {it:test} containing the minima of variables v1, v3,
v4, and v5. Specify {hi:minvalid(3)} so that {it:test} has valid values only
if least three values of the four variables of {it:varlist} are valid (or equivalently: at most
4-3=1 value may be missing):

{cmd:. scores test=min(v1 v3-v5), nv(3) replace}
{txt}(1 missing value generated)
(3 real changes made, 3 to missing)

{cmd:. list}
{txt}
     {c TLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c TRC}
     {c |} {res}v1   v2   v3   v4   v5   test {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c RT}
  1. {c |} {res} 1    2    3    4    5      1 {txt}{c |}
  2. {c |} {res} 1    2    3    4    .      1 {txt}{c |}
  3. {c |} {res} 1    2    3    .    .      . {txt}{c |}
  4. {c |} {res} 1    .    3    4    .      1 {txt}{c |}
  5. {c |} {res} 1    2    .    .    .      . {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c RT}
  6. {c |} {res} 1    .    .    .    .      . {txt}{c |}
  7. {c |} {res} .    .    .    .    .      . {txt}{c |}
     {c BLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c BRC}


{pstd}
Same as above but using the {hi:maxima} instead of the minima:

{cmd:. scores test=max(v1 v3-v5), nv(3) replace}
{txt}(1 missing value generated)
(3 real changes made, 3 to missing)

{cmd:. list}
{txt}
     {c TLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c TRC}
     {c |} {res}v1   v2   v3   v4   v5   test {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c RT}
  1. {c |} {res} 1    2    3    4    5      5 {txt}{c |}
  2. {c |} {res} 1    2    3    4    .      4 {txt}{c |}
  3. {c |} {res} 1    2    3    .    .      . {txt}{c |}
  4. {c |} {res} 1    .    3    4    .      4 {txt}{c |}
  5. {c |} {res} 1    2    .    .    .      . {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c RT}
  6. {c |} {res} 1    .    .    .    .      . {txt}{c |}
  7. {c |} {res} .    .    .    .    .      . {txt}{c |}
     {c BLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c BRC}


{pstd}
Same as above but creating the {hi:total} (sum) scores instead of the maxima:

{cmd:. scores test=total(v1 v3-v5), nv(3) replace}
{txt}(4 real changes made, 4 to missing)

{cmd:. list}
{txt}
     {c TLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c TRC}
     {c |} {res}v1   v2   v3   v4   v5   test {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c RT}
  1. {c |} {res} 1    2    3    4    5     13 {txt}{c |}
  2. {c |} {res} 1    2    3    4    .      8 {txt}{c |}
  3. {c |} {res} 1    2    3    .    .      . {txt}{c |}
  4. {c |} {res} 1    .    3    4    .      8 {txt}{c |}
  5. {c |} {res} 1    2    .    .    .      . {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c RT}
  6. {c |} {res} 1    .    .    .    .      . {txt}{c |}
  7. {c |} {res} .    .    .    .    .      . {txt}{c |}
     {c BLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 6}{c BRC}


{pstd}
Same as above but creating the standard deviations ({hi:sd}) instead of total scores:

{cmd:. scores test=sd(v1 v3-v5), nv(3) replace}
{txt}(3 missing values generated)
(1 real change made, 1 to missing)

{cmd:. list}
{txt}
     {c TLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c TRC}
     {c |} {res}v1   v2   v3   v4   v5        test {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c RT}
  1. {c |} {res} 1    2    3    4    5   1.7078251 {txt}{c |}
  2. {c |} {res} 1    2    3    4    .   1.5275252 {txt}{c |}
  3. {c |} {res} 1    2    3    .    .           . {txt}{c |}
  4. {c |} {res} 1    .    3    4    .   1.5275252 {txt}{c |}
  5. {c |} {res} 1    2    .    .    .           . {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c RT}
  6. {c |} {res} 1    .    .    .    .           . {txt}{c |}
  7. {c |} {res} .    .    .    .    .           . {txt}{c |}
     {c BLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c BRC}


{pstd}
Same as above but creating {hi:mean} scores instead of the standard deviations:

{cmd:. scores test=mean(v1 v3-v5), nv(3) replace}
{txt}(1 missing value generated)
(3 real changes made, 3 to missing)

{cmd:. list}
{txt}
     {c TLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c TRC}
     {c |} {res}v1   v2   v3   v4   v5        test {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c RT}
  1. {c |} {res} 1    2    3    4    5        3.25 {txt}{c |}
  2. {c |} {res} 1    2    3    4    .   2.6666667 {txt}{c |}
  3. {c |} {res} 1    2    3    .    .           . {txt}{c |}
  4. {c |} {res} 1    .    3    4    .   2.6666667 {txt}{c |}
  5. {c |} {res} 1    2    .    .    .           . {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c RT}
  6. {c |} {res} 1    .    .    .    .           . {txt}{c |}
  7. {c |} {res} .    .    .    .    .           . {txt}{c |}
     {c BLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c BRC}


{pstd}
Same as above but creating mean scores {hi:centered} around the overall mean:

{cmd:. scores test=mean(v1 v3-v5), nv(3) sc(c) replace}
{txt}(1 missing value generated)
(3 real changes made, 3 to missing)

{cmd:. list}
{txt}
     {c TLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 12}{c TRC}
     {c |} {res}v1   v2   v3   v4   v5         test {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 12}{c RT}
  1. {c |} {res} 1    2    3    4    5    .38888889 {txt}{c |}
  2. {c |} {res} 1    2    3    4    .   -.19444444 {txt}{c |}
  3. {c |} {res} 1    2    3    .    .            . {txt}{c |}
  4. {c |} {res} 1    .    3    4    .   -.19444444 {txt}{c |}
  5. {c |} {res} 1    2    .    .    .            . {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 12}{c RT}
  6. {c |} {res} 1    .    .    .    .            . {txt}{c |}
  7. {c |} {res} .    .    .    .    .            . {txt}{c |}
     {c BLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 12}{c BRC}


{pstd}
Same as above but creating {hi:z-scores} instead of centered mean scores:

{cmd:. scores test=mean(v1 v3-v5), nv(3) sc(z) replace}
{txt}(1 missing value generated)
(3 real changes made, 3 to missing)

{cmd:. list}
{txt}
     {c TLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 12}{c TRC}
     {c |} {res}v1   v2   v3   v4   v5         test {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 12}{c RT}
  1. {c |} {res} 1    2    3    4    5    1.1547005 {txt}{c |}
  2. {c |} {res} 1    2    3    4    .   -.57735027 {txt}{c |}
  3. {c |} {res} 1    2    3    .    .            . {txt}{c |}
  4. {c |} {res} 1    .    3    4    .   -.57735027 {txt}{c |}
  5. {c |} {res} 1    2    .    .    .            . {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 12}{c RT}
  6. {c |} {res} 1    .    .    .    .            . {txt}{c |}
  7. {c |} {res} .    .    .    .    .            . {txt}{c |}
     {c BLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 12}{c BRC}


{pstd}
Same as above but instead of z-scores transforming the mean scores to {hi:POMP scores} assuming Likert
scale items with anchors ranging from 1 (minimum possible value) to 5 (maximum possible value):

{cmd:. scores test=mean(v1 v3-v5), nv(3) sc(p) min(1) max(5) replace}
{txt}(1 missing value generated)
(3 real changes made, 3 to missing)

{cmd:. list}
{txt}
     {c TLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c TRC}
     {c |} {res}v1   v2   v3   v4   v5        test {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c RT}
  1. {c |} {res} 1    2    3    4    5       56.25 {txt}{c |}
  2. {c |} {res} 1    2    3    4    .   41.666667 {txt}{c |}
  3. {c |} {res} 1    2    3    .    .           . {txt}{c |}
  4. {c |} {res} 1    .    3    4    .   41.666667 {txt}{c |}
  5. {c |} {res} 1    2    .    .    .           . {txt}{c |}
     {c LT}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c RT}
  6. {c |} {res} 1    .    .    .    .           . {txt}{c |}
  7. {c |} {res} .    .    .    .    .           . {txt}{c |}
     {c BLC}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 4}{c -}{hline 11}{c BRC}

{title:Acknowledgements}

    Thanks to Kit Baum for helpful advice!

{title:Author}

    Dirk Enzmann
    http://www2.jura.uni-hamburg.de/instkrim/kriminologie/Mitarbeiter/Enzmann/Enzmann.html
    dirk.enzmann@uni-hamburg.de