************************************************************************************************************
* Traces: Traces of items
* version 3: July 9, 2003
*
* Historic:
* Version 1 (2003-06-29): Jean-Benoit Hardouin
* Version 2 (2003-07-04): Jean-Benoit Hardouin
*
* Jean-benoit Hardouin, Regional Health Observatory of Orléans - France
* jean-benoit.hardouin@neuf.fr
*
* News about this program : http://anaqol.free.fr
* FreeIRT Project : http://freeirt.free.fr
*
* Copyright 2003 Jean-Benoit Hardouin
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*
************************************************************************************************************

program define traces
version 8.0
syntax varlist(numeric min=2) [, score test restscore logistic ci cumulative repfiles(string) scorefiles(string) restscorefiles(string) logisticfile(string) nodraw nodrawcomb replace]

local nbitems : word count `varlist'
tokenize `varlist'

tempvar varscore
gen `varscore'=0
label variable `varscore' "Total score"
local scoremax=0
local flag=0

if "`score'"==""&"`restscore'"==""&&"`logistic'"=="" {
local score="score"
}

forvalues i=1/`nbitems' {
          qui replace `varscore'=`varscore'+``i''
          qui su ``i''
          local modamax`i'=r(max)
          if r(min)!=0 {
          local flag=1
          }
          local scoremax=`scoremax'+`modamax`i''
          if `modamax`i''!=1 {
              local flagbin=0
          }
}

if `flag'==1 {
di as error "The lower modalities of the item must be 0"
exit
}

qui su `varscore'
local maxscore=r(max)

forvalues i=0/`maxscore' {
          qui count if `varscore'==`i'
          local nscore`i'=r(N)
}

if "`flagbin'"!=""&"`logistic'"!="" {
   di as error "The logistic option is impossible with polytomic items"
   exit
}

global score
global restscore
global logistic

forvalues i=1/`nbitems' {
          if "`score'"!="" {
             local y`i'
             forvalues k=1/`modamax`i'' {
             tempvar propscore`i'`k' tmp
             if "`cumulative'"!="" {
                gen `tmp'=``i''>=`k'
                bysort `varscore' : egen `propscore`i'`k''=mean(`tmp')
                label variable `propscore`i'`k'' "Item ``i''>=`k'"
             }
             else {
                gen `tmp'=``i''==`k'
                bysort `varscore' : egen `propscore`i'`k''=mean(`tmp')
                label variable `propscore`i'`k'' "Item ``i''=`k'"
             }
             local y`i'="`y`i'' `propscore`i'`k''"
             local style="solid"
             local color="black"
             local width="medthick"
             if `modamax`i''==1&"`ci'"!="" {
                tempvar icscoreminus icscoreplus
                gen `icscoreminus'=`propscore`i'1'-1.96*sqrt(`propscore`i'1'*(1-`propscore`i'1')/`nscore`i'')
                gen `icscoreplus'=`propscore`i'1'+1.96*sqrt(`propscore`i'1'*(1-`propscore`i'1')/`nscore`i'')
                label variable `icscoreminus' "Lower 95% confidence interval"
                label variable `icscoreplus' "Upper 95% confidence interval"
                local y`i'="`icscoreminus' `icscoreplus' `propscore`i'1'"
                local style="dash dash solid"
                local color="red red black"
                local width="thin thin medthick"
             }
             if `modamax`i''==1&"`test'"!="" {
                qui regress `propscore`i'1' `varscore'
                local p=Fden(e(df_m),e(df_r),e(F))
                if `p'<0.0001 {
                   local note="Test: slope=0, p<0.0001"
                }
                else {
                   local p=substr("`p'",1,6)
                   local note="Test: slope=0, p=`p'"
                }
             }
             }
             qui graph twoway (line `y`i'' `varscore', clpattern(`style') clcolor(`color') clwidth(`width')) if `varscore'!=0&`varscore'!=`maxscore' , note("`note'") ylabel(0(.25)1) xlabel(0(1)`scoremax') name(score`i',replace) title("Trace of the item ``i'' in fonction of the score") ytitle("Rate of positive response")  `draw'
             global score "$score score`i'"
             if "`scorefiles'"!="" {
                graph save score`i' `repfiles'\\`scorefiles'``i'' ,`replace'
             }
          }
          if "`restscore'"!="" {
             local y`i'
             tempvar restscore`i'
             gen `restscore`i''=`varscore'-``i''
             label variable `restscore`i'' "Rest score with respect to the item ``i''"
             forvalues k=1/`modamax`i'' {
             tempvar rtmp proprestscore`i'`k'
             if "`cumulative'"!="" {
                gen `rtmp'=``i''>=`k'
                bysort `restscore`i'': egen `proprestscore`i'`k''=mean(`rtmp')
                label variable `proprestscore`i'`k'' "Item ``i''>=`k'"
             }
             else {
                gen `rtmp'=``i''==`k'
                bysort `restscore`i'': egen `proprestscore`i'`k''=mean(`rtmp')
                label variable `proprestscore`i'`k'' "Item ``i''=`k'"
             }
             local y`i'="`y`i'' `proprestscore`i'`k''"
             local style="solid"
             local color="black"
             local width="medthick"
             if `modamax`i''==1&"`ci'"!="" {
                tempvar icrestscoreminus icrestscoreplus
                qui su `restscore`i''
                local maxrestscore=r(max)
                forvalues l=1/`maxrestscore' {
                qui count if `restscore`i''==`l'
                local nrestscore`i'=r(N)
                }
                gen `icrestscoreminus'=`proprestscore`i'1'-1.96*sqrt(`proprestscore`i'1'*(1-`proprestscore`i'1')/`nrestscore`i'')
                gen `icrestscoreplus'=`proprestscore`i'1'+1.96*sqrt(`proprestscore`i'1'*(1-`proprestscore`i'1')/`nrestscore`i'')
                label variable `icrestscoreminus' "Lower 95% confidence interval"
                label variable `icrestscoreplus' "Upper 95% confidence interval"
                local y`i'="`icrestscoreminus' `icrestscoreplus' `proprestscore`i'1'"
                local style="dash dash solid"
                local color="red red black"
                local width="thin thin medthick"
             }
             if `modamax`i''==1&"`test'"!="" {
                qui regress `proprestscore`i'1' `varscore'
                local p=Fden(e(df_m),e(df_r),e(F))
                if `p'<0.0001 {
                   local note="Test: slope=0, p<0.0001"
                }
                else {
                   local p=substr("`p'",1,6)
                   local note="Test: slope=0, p=`p'"
                }
             }
}
             local restscoremax=`scoremax'-`modamax`i''
             qui graph twoway (line `y`i'' `restscore`i'', clpattern(`style') clcolor(`color') clwidth(`width')), note("`note'") ylabel(0(0.25)1) xlabel(0(1)`restscoremax') name(restscore`i',replace) title("Trace of the item ``i'' in fonction of the restscore") ytitle("Rate of positive response") `draw'
             global restscore "$restscore restscore`i'"
             if "`restscorefiles'"!="" {
                graph save restscore`i' `repfiles'\\`restscorefiles'``i''  ,`replace'
             }
          }
          if "logistic"!="" {
          qui logistic ``i'' `varscore'
          tempname coef
          matrix `coef'=e(b)
          local pente`i'=`coef'[1,1]
          local intercept`i'=`coef'[1,2]
          tempvar logit`i'
          gen `logit`i''=exp(`intercept`i''+`pente`i''*`varscore')/(1+exp(`intercept`i''+`pente`i''*`varscore'))
          label variable `logit`i'' "Item ``i''"
          sort `varscore'
          global logistic "$logistic `logit`i''"
          }
}

if "`drawcomb'"!="" {
local drawcomb="nodraw"
}

if "`score'"!="" {
graph combine $score , title("Trace of the items in function of the score") name(score,replace) `drawcomb'
if "`scorefiles'"!="" {
   graph save score `repfiles'\\`scorefiles'  ,`replace'
}
}

if "`restscore'"!="" {
graph combine $restscore  , title("Trace of the items in function of the restscores") name(restscore,replace)  `drawcomb'
if "`restscorefiles'"!="" {
   graph save restscore `repfiles'\\`restscorefiles'   ,`replace'
}
}

if "`logistic'"!="" {
graph twoway (line $logistic `varscore'), ylabel(0(0.25)1) xlabel(0(1)`nbitems') title("Logistic traces") ytitle("") name(logistic,replace) `drawcomb'
if "`logisticfile'"!="" {
   graph save logistic `repfiles'\\`logisticfile'   ,`replace'
}
}


end