{smcl}
{* 2013}{...}
{hline}
help for {hi:validscale}{right:Bastien Perrot}
{hline}

{title:Syntax}

{p 8 14 2}{cmd:validscale} {it:varlist}, {opt part:ition}({it:numlist}) [{it:options}]

{p 4 4 2}{it:varlist} contains the variables (items) used to compute the scores. The first items of {it:varlist} compose the first dimension, the following items define the second dimension, and so on.

{p 4 4 2}{cmd:partition} allows defining in {it:numlist} the number of items in each dimension.


{synoptset 20 tabbed}{...}
{synopthdr}
{synoptline}
{syntab:Options}
{synopt : {opt scoren:ame(string)}}define the names of the dimensions{p_end}
{synopt : {opt scores(varlist)}}use scores from the dataset{p_end}
{synopt : {opt mod:alities(numlist)}}define minimum and maximum response categories for the items{p_end}
{synopt : {opt imp:ute(method)}}impute missing item responses{p_end}
{synopt : {help validscale##impute_options:{it:impute_options}}}options for imputation of missing data {p_end}
{synopt : {opt comps:core(method)}}define how scores are computed{p_end}
{synopt : {opt desc:items}}display a descriptive analysis of items and dimensions{p_end}
{synopt : {opt graph:s}}display graphs for items description{p_end}
{synopt : {opt cfa}}assess structural validity of the scale by performing a confirmatory factor analysis (CFA){p_end}
{synopt : {help validscale##cfa_options:{it:cfa_options}}}options for confirmatory factor analysis (CFA){p_end}
{synopt : {opt conv:div}}assess convergent and divergent validities assessment{p_end}
{synopt : {help validscale##convdiv_options:{it:conv_div_options}}}options for convergent and divergent validities{p_end}
{synopt : {help validscale##reliability_options:{it:reliability_options}}}options for reliability assessment{p_end}
{synopt : {opt rep:et(varlist)}}assess reproducibility of scores and items{p_end}
{synopt : {help validscale##repet_options:{it:repet_options}}}options for reproducibility{p_end}
{synopt : {opt kgv(varlist)}}assess known-groups validity by using qualitative variable(s){p_end}
{synopt : {help validscale##kgv_options:{it:kgv_options}}}options for known-groups validity assessment{p_end}
{synopt : {opt conc(varlist)}}assess concurrent validity{p_end}
{synopt : {help validscale##conc_options:{it:conc_options}}}options for concurrent validity assessment{p_end}

{p2colreset}{...}


{title:Description}

{phang}{cmd:validscale} assesses validity and reliability of a multidimensional scale. Elements to provide
structural validity, convergent and divergent validity, reproducibility, known-groups validity, internal consistency, scalability and sensitivity are computed. 

{marker options}{...}
{title:Options}

{dlgtab:Options}

{phang}{opt scoren:ame(string)} allows defining the names of the dimensions. If the option is not used, the dimensions are named {it:Dim1}, {it:Dim2},... unless {opt scores(varlist)} is used. 

{phang}{opt scores(varlist)} allows selecting scores from the dataset. {opt scores(varlist)} and {opt scorename(string)} cannot be used together.

{phang}{opt mod:alities(numlist)} allows specifying the minimum and maximum possible values for items responses. If all the items have the same response
categories, the user may specify these 2 values in {it:numlist}. If the items response categories differ from a dimension to another, the user must define the possible minimum and maximum values of items responses for each
dimension. So the number of elements in {it:numlist} must be equal to the number of dimensions times 2. Eventually, the user may specify the minimum and maximum response categories for each item. In this case, the
number of elements in {it:numlist} must be equal to the number of items times 2. By default, the minimum and maximum values are assumed to be the minimum and maximum for each item.      

{phang}{opt imp:ute(method)} imputes missing items responses with Person Mean Substitution ({bf:pms}) or Two-way imputation method applied in each dimension ({bf:mi}). With PMS method, missing data are imputed only if the number of
missing values in the dimension is less than half the number of items in the dimension. 

{marker impute_options}{...}
{phang}{it:impute_options} allow specifying options for imputation of missing values. By default, imputed values are rounded to the nearest whole number but with the {opt nor:ound} option, imputed values
are not rounded. If {opt impute} is absent then {opt noround} is ignored.

{phang}{opt comp:score(method)} defines the method used to compute the scores. {it:method} may be either {bf:mean} (default), {bf:sum} or {bf:stand}(set scores from 0 to 100). {opt comp:score(method)} is ignored
if the {opt scores(varlist)} option is used.

{phang}{opt desc:items} displays a descriptive analysis of the items. This option displays missing data rate per item and distribution of item responses. It also computes for each item the Cronbach's alphas
obtained by omitting each item in each dimension. Moreover, the option computes Loevinger's Hj coefficients and the number of non-significant Hjk. See {help loevh} for details about Loevinger's coefficients.     

{phang}{opt graph:s} displays graphs for items and dimensions descriptive analyses. It provides histograms of scores, a biplot of the scores and a graph showing the correlations between the items.

{phang}{opt cfa} performs a confirmatory factor analysis using {help sem} command. It displays estimations of parameters and several goodness-of-fit indices.

{marker cfa_options}{...}
{phang}{it:cfa_options} allow specifying options for confirmatory factor analysis (CFA). {opt cfam:ethod}({it:method}) specifies the method to estimate the parameters. {it:method} may be either {bf:ml} (maximum
likelihood), {bf:mlmv} ({bf:ml} with missing values) or {bf:adf} (asymptotic distribution free). The {opt cfas:tand} option displays standardized coefficients.
The {opt cfac:ovs} option allows adding covariances between measurement errors. You can look at the examples to see the syntax of this option. The {opt cfaa:uto} option adds automatically the covariances
of measurement errors found with the {help estat mindices} command. The option only adds the covariances of measurement errors within a dimension.

{phang}{opt conv:div} assesses convergent and divergent validities. The option displays the matrix of correlations between items and rest-scores. If {opt scores(varlist)} is used, then the correlations coefficients are computed between
items and scores of {opt scores(varlist)}. 

{marker convdiv_options}{...}
{phang}{it:conv_div_options} allow specifying options for convergent and divergent validity. {opt tconv:div(#)} defines a threshold for highlighting some values. # is a real number between 0 and 1 which is equal to 0.4 by
default. Correlations between items and their own score are displayed
in red if it is less than #. Moreover, if an item has a smaller correlation coefficient with the score of its own dimension than the correlation coefficient computed with other scores, this coefficient is displayed
in red. The {opt convdivb:oxplots} option displays boxplots for assessing convergent and divergent validities. The boxes represent the correlation coefficients between the items of a given dimension and all scores. Thus the
box of correlation coefficients between items of a given dimension and the corresponding score must be higher than other
boxes. There are as many boxplots as dimensions. 

{marker reliability_options}{...}
{phang}{it:reliability_options} allow defining the thresholds for reliability indices. {opt a:lpha(#)} defines a threshold for Cronbach's alpha (see {help alpha}). # is a real number between 0 and 1 which is equal to 0.7
by default. Cronbach's alpha coefficients less than # are printed in red. {opt d:elta(#)} defines a threshold for Ferguson's delta coefficient (see {help delta}). Delta coefficients are computed only if {opt compscore}({it:sum}) is used
and {opt scores}({it:varlist)} is not used. # is a real number between 0 and 1 which is equal to 0.9
by default. Ferguson's delta coefficients less than # are printed in red. {opt h(#)} defines a threshold for Loevinger's H coefficient (see {help loevh}). # is a real number between 0 and 1 which is equal to
0.3 by default. Loevinger's H coefficients less than # are printed in red. {opt hj:min(#)}
defines a threshold for Loevinger's Hj coefficients. The displayed value is the minimal Hj coefficient for a item in the dimension. (see {help loevh}). # is a real number between 0 and 1 which is equal to
0.3 by default. If the minimal Loevinger's Hj coefficient is less than # then it is printed in red and the corresponding item is displayed.
																										                                                                                                                                                                                                            
{phang}{opt rep:et(varlist)} assesses reproducibility of scores by defining in {it:varlist} the variables corresponding to responses at time 2 (in the same order than for time 1). Scores are computed according to
the {opt partition()} option. Intraclass
Correlation Coefficients (ICC) for scores and their 95% confidence interval are computed with Stata's {help icc} command.

{marker repet_options}{...}
{phang}{it:repet_options} display information about reproducibility of items. The {opt kap:pa} option computes kappa statistic for items with Stata's {help kap} command. The {opt ickap:pa(#)} option computes
confidence intervals for
kappa statistics using {help kapci}. # is the number of replications for bootstrap used to estimate confidence intervals if items are polytomous. If they are dichotomous, an analytical method is used. See {help kapci} for more details about
calculation of
confidence intervals for kappa's
coefficients. If the {opt kappa} option is absent then the {opt ickappa(#)} option is ignored. {opt scores2}({it:varlist}) allows selecting scores at time 2 from the dataset. 

{phang}{opt kgv(varlist)} assesses known-groups validity according to the grouping variables defined in {it:varlist}. The option performs an ANOVA which compares the scores between groups of individuals, constructed with variables in {it:varlist}.       

{marker kgv_options}{...}
{phang}{it:kgv_options} allow displaying graphs for known-groups validity. The {opt kgvb:oxplots} option draws boxplots of the scores split into groups of individuals. The {opt kgvg:roupboxplots} option groups
all boxplots in one graph. If {opt kgvboxplots} is absent then the {opt kgvgroupboxplots} option is ignored.  

{phang}{opt conc(varlist)} assesses concurrent validity with variables precised in {it:varlist}. These variables are scores from one or several other scales.  

{marker conc_options}{...}
{phang}{it:conc_options} allow specifying options for concurrent validity. The {opt tc:onc(#)} option defines a threshold for correlation coefficients between the computed scores and the scores of other scales defined in {it:varlist}. Correlation
coefficients greater than # (0.4 by default) are displayed in bold.


{marker examples}{...}
{title:Examples}

{phang2}{cmd:. validscale item1-item20, part(5 4 6 5)}{p_end}

{phang2}{cmd:. validscale item1-item20, part(5 4 6 5) imp graphs cfa cfastand cfacovs(item1*item3 item5*item7 item17*item18) convdiv convdivboxplots kgv(factor_variable) kgvboxplots conc(scoreA-scoreD)}{p_end}

{phang2}{cmd:. validscale item1-item20, part(5 4 6 5) imp scores(s1-s4) rep(item1bis-item20bis) scores2(s1bis-s4bis) kappa}{p_end}


{marker alsosee}{...}
{title:Also see}

{p 4 13 2}help for {help alpha}, {help delta}, {help loevh}, {help icc}, {help kapci}.{p_end}