Design                package:Design                R Documentation

_D_e_s_i_g_n _M_e_t_h_o_d_s _a_n_d _G_e_n_e_r_i_c _F_u_n_c_t_i_o_n_s

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

     This is a series of special transformation functions ('asis',
     'pol', 'lsp', 'rcs', 'catg', 'scored', 'strat', 'matrx'), fitting
     functions (e.g.,  'lrm','cph', 'psm', or 'ols'), and generic
     analysis functions ('anova.Design', 'summary.Design',
     'predict.Design',  'plot.Design', 'survplot', 'fastbw',
     'validate', 'calibrate', 'specs.Design', 'which.influence',
     'latex.Design', 'nomogram.Design', 'datadist', 'gendata')  that
     help automate many analysis steps, e.g. fitting restricted
     interactions and multiple stratification variables, analysis of
     variance (with tests of linearity of each factor and pooled
     tests), plotting effects of variables in the model, estimating and
     graphing effects of variables that appear non-linearly in the
     model using e.g. inter-quartile-range hazard ratios, bootstrapping
     model fits, and constructing nomograms for obtaining predictions
     manually.  Behind the scene is the 'Design' function,  called by a
     modified version of 'model.frame.default' to store extra
     attributes. 'Design()' is not intended to be called by users.  
     'Design' causes detailed design attributes and descriptions of the
     distribution of predictors to be stored  in an attribute of the
     'terms' component called 'Design'. In addition to
     'model.frame.default' being replaced by a modified version, '[.'
     and '[.factor' are replaced by versions which carry along the
     'label' attribute of a variable.  In this way, when an 'na.action'
     function is called to subset out NAs, labels are still defined for
     variables in the model.

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

     Design(mf, allow.offset=TRUE, intercept=1)
     # not to be called by the user; called by fitting routines
     # dist <- datadist(x1,x2,sex,age,race,bp)   
     # or dist <- datadist(my.data.frame)
     # Can omit call to datadist if not using summary.Design, plot.Design, 
     # survplot.Design, or if all variable settings are given to them
     # options(datadist="dist")
     # f <- fitting.function(formula = y ~ rcs(x1,4) + rcs(x2,5) + x1%ia%x2 +
     #                       rcs(x1,4)%ia%rcs(x2,5) +
     #                       strat(sex)*age + strat(race)*bp)
     # See Design.trans for rcs, strat, etc.
     # %ia% is restricted interaction - not doubly nonlinear
     # for x1 by x2 this uses the simple product only, but pools x1*x2
     # effect with nonlinear function for overall tests
     # specs(f)
     # anova(f)
     # summary(f)
     # fastbw(f)
     # pred <- predict(f, newdata=expand.grid(x1=1:10,x2=3,sex="male",
     #                 age=50,race="black"))
     # pred <- predict(f, newdata=gendata(f, x1=1:10, x2=3, sex="male"))
     # This leaves unspecified variables set to reference values from datadist
     # pred.combos <- gendata(f, nobs=10)   # Use X-windows to edit predictor settings
     # predict(f, newdata=pred.combos)
     # plot(f, x1=NA)
     # latex(f)
     # nomogram(f)

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

      mf: a model frame

allow.offset: set to 'TRUE' if model fitter allows an offset term

intercept: 1 if an ordinary intercept is present, 0 otherwise

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

     a data frame augmented with additional information about the
     predictors and model formulation

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

     Frank Harrell
      Department of Biostatistics, Vanderbilt University
      f.harrell@vanderbilt.edu

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

     'Design.trans', 'Design.Misc', 'cph', 'lrm', 'ols',
     'specs.Design', 'anova.Design', 'summary.Design',
     'predict.Design', 'gendata', 'plot.Design', 'fastbw',  'validate',
     'calibrate', 'which.influence', 'latex', 'latex.Design',
     'model.frame.default', 'datadist', 'describe', 'nomogram', 'vif',
     'dataRep'

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

     ## Not run: 
     library(Design, first=TRUE)  # omit first for R
     dist <- datadist(data=2)     # can omit if not using summary, plot, survplot,
                                  # or if specify all variable values to them. Can
                                  # also  defer.  data=2: get distribution summaries
                                  # for all variables in search position 2
                                  # run datadist once, for all candidate variables
     dist <- datadist(age,race,bp,sex,height)   # alternative
     options(datadist="dist")
     f <- cph(Surv(d.time, death) ~ rcs(age,4)*strat(race) +
              bp*strat(sex)+lsp(height,60),x=TRUE,y=TRUE)
     anova(f)
     anova(f,age,height)          # Joint test of 2 vars
     fastbw(f)
     summary(f, sex="female")     # Adjust sex to "female" when testing
                                  # interacting factor bp
     plot(f, age=NA, height=NA)   # 3-D plot
     plot(f, age=10:70, height=60)
     latex(f)                     # LaTeX representation of fit

     f <- lm(y ~ x)               # Can use with any fitting function that
                                  # calls model.frame.default, e.g. lm, glm
     specs.Design(f)              # Use .Design since class(f)="lm"
     anova(f)                     # Works since Varcov(f) (=Varcov.lm(f)) works
     fastbw(f)
     options(datadist=NULL)
     f <- ols(y ~ x1*x2)          # Saves enough information to do fastbw, anova
     anova(f)                     # Will not do plot.Design since distributions
     fastbw(f)                    # of predictors not saved
     plot(f, x1=seq(100,300,by=.5), x2=.5) 
                                  # all values defined - don't need datadist
     dist <- datadist(x1,x2)      # Equivalent to datadist(f)
     options(datadist="dist")
     plot(f, x1=NA, x2=.5)        # Now you can do plot, summary
     nomogram(f, interact=list(x2=c(.2,.7)))
     ## End(Not run)

