sensitivityZelig          package:accuracy          R Documentation

_P_e_r_t_u_r_b_a_t_i_o_n_s-_b_a_s_e_d _S_e_n_s_i_t_i_v_i_t_y _A_n_a_l_y_s_i_s _o_f _Z_e_l_i_g _M_o_d_e_l_s

_D_e_s_c_r_i_p_t_i_o_n:

     This is a wrapper to perturb analyses launches through Zelig, with
     extension functions to summarize results.

_U_s_a_g_e:

     sensitivityZelig(z, ptb.R=50, ptb.ran.gen=NULL, ptb.s=NULL, explanatoryOnly=FALSE, summarize=FALSE, simulate=FALSE, simArgs=NULL, ptb.rangen.ismatrix=FALSE)
             pzelig(...)

_A_r_g_u_m_e_n_t_s:

       z: an analysis output by 'zelig' 

   ptb.R: number of replications for perturbation analysis 

ptb.ran.gen: a single function, or a vector of functions to be used to
          perturb each vector see 'PTBi' 

   ptb.s: a size, or vector of sizes, to be used in the vector
          perturbation functions

explanatoryOnly: a flag indicating whether explanatory variables should
          be perturbed by default

summarize: if true, return a sensitivity summary, as would
          'summary(sensitivityZelig())'. 

simulate: if true, return a sensitivity summary, and a zelig
          simulation, as would 'psim(sensitivityZelig())'. This
          decreases system memory use, and can significantly speed up
          analysis for large datasets.

 simArgs: a list of arguments to pass to psim, if simulate is true

     ...: args as in sensitivityZelig

ptb.rangen.ismatrix: If true, expects ptb.ran.gen to be a matrix
          function, for use with correlated noise structure. See below

_D_e_t_a_i_l_s:

     Uses 'sensitivity' to perform sensitivity analysis on a 'zelig'
     model.

_V_a_l_u_e:

     Returns a list which contains the result  of each model run. Along
     with attributes about the settings used in the perturbations. Use
     'summary' to summarize the results or extract a matrix of of the
     model parameters across the entire set of runs.

_N_o_t_e:

     This was originally called "pzelig". If ptb.ran.gen is not
     specified,  then 'PTBdefault' will be used, with q=ptb.s, for each
     explanatory variable in the input data. By default, response
     variables will also  be perturbed, unless 'explanatoryOnly' is
     true.

_A_u_t_h_o_r(_s):

     Micah Altman Micah_Altman@harvard.edu <URL:
     http://www.hmdc.harvard.edu/micah_altman/>

_R_e_f_e_r_e_n_c_e_s:

     Altman, M., J. Gill and M. P. McDonald.  2003.  _Numerical Issues
     in Statistical Computing for the Social Scientist_.  John Wiley &
     Sons. <URL: http://www.hmdc.harvard.edu/numerical_issues/>

_S_e_e _A_l_s_o:

     See Also as 'perturb',  'PTBdefault',  'zelig', 'psim'

_E_x_a_m_p_l_e_s:

     # Sensitivity analysis of the classic longley data, as run through zelig.
     #
     # Note: Compare to the example documented under the main perturb page.

     # example requires Zelig.

     if(!is.R()){
       # splus version of require ignores quietly!
       ow<-options(warn=-1)
     } else {
        data(longley)
        # accuracy supplies longley for SPLUS automagically, for examples only
     }

     # workaround for Zelig < 3.4 & R 2.8 & possible broken build environment
     goodZelig <- require(Zelig,quietly=TRUE) && (!inherits(try(zelig(Employed~GNP,"ls",longley,cite=FALSE),silent=TRUE),"try-error"))
     if (!is.R()) {
           options(ow)
     }
     if (goodZelig) { 
        
        # not used due to zelig bug: zelig.out=zelig(Employed~.,"ls",longley) 
        # run longley regression
        
        zelig.out=try(zelig(Employed~GNP.deflator+GNP+Unemployed+Armed.Forces+Population+Year,"ls",longley),silent=TRUE)

        # default settings
        perturb.zelig.out = sensitivityZelig(zelig.out)                 

        # Note: without zelig, the preceding would be:  perturb.out = perturb(longley,lm,Employed~.) 

        # plots the perturbed lm replications individually
        plot(perturb.zelig.out)        
        # summarizes the overall sensitivity of coefficient estimates
        summary(perturb.zelig.out)             
        plot(summary(perturb.zelig.out))
        
        # since the "ls" model relies on "lm" which supports anova, can summarize
        # using anova
        anova(perturb.zelig.out)
        plot(anova(perturb.zelig.out))
        
        # Up to this point, we could have done this without Zelig... here's the fun part.
       
        # set values of explanatory variables
        setx.out=setx(perturb.zelig.out, Year=1955)       

        # Note: could also have used setx.out=setx(z,Year=1955)  instead of the line above,
        #       or  simply called psim() below without setx.out, which would default to using setx(perturb.zelig.out)

        # use simulation to predict value of explanatory variable based on
        # 
        sim.perturb.zelig.out = psim(perturb.zelig.out,setx.out)

        # this plots the profile of the predicted distribution of the explanatory variable, Employed
        # around the point wher Year=1955, and other explanatory variables are at their midpoints

        plot(sim.perturb.zelig.out)

        # this provides a summary of the predicted distribution of the explanatory variable

        print(summary(sim.perturb.zelig.out))
        
      }
      if (!is.R()) {
        options(ow)
      }

