Description Usage Arguments Details Value Note Author(s) References Examples

For k outcomes in a matched observational study, principal() computes the M-scores for the outcomes one at a time, computes the principal components of the M-scores, and uses some of the larger principal components as the outcomes in a sensitivity analysis. The user controls the number of components using w: (i) if is.null(w)==TRUE, then the first principal component is used in a one-sided test, (ii) if length(w)==1, then w=1 and w=-1 both use the first principal component, but direct attention to the upper or lower tails, respectively, (iii) if length(w)>1, then the first length(w) principal components are used with weights w; e.g., w=c(1,1) adds the first two principal components together. Setting Scheffe=TRUE with length(w)=2 permits the user to test every linear combination of the first two principal components – that is, every with length(w)=2 – while controlling the family-wise error rate. Every matched set contains one treated subject and one or more controls.

1 2 3 |

`y` |
A matrix of responses with no missing data. Different columns of y are different variables, and there are k=dim(y)[2] variables. If present, the column names of y are used to label output. |

`z` |
Treatment indicators, z=1 for treated, z=0 for control with length(z)==dim(y)[1]. |

`mset` |
Matched set indicators, 1, 2, ..., sum(z) with length(mset)==dim(y)[1]. The vector mset may contain integers or may be a factor. |

`w` |
A vector of weights to be applied to principal components. There are k=dim(y)[2] variables in y. (i) If is.null(w)=TRUE or if length(w)=1 with w!=0, then the test is applied to the first principal component of the nvars M-test scores, and no adjustment for multiple testing is needed. (ii) If length(w)>1, then w determines a comparison among the first length(w) principal components of the k M-scores. At least one weight must be nonzero. The meaning of the weights is affected by whether cor=FALSE (the default) or cor=TRUE. If Scheffe=TRUE, the dimensionality of the Scheffe correction is length(w), so w=c(1,1) is different from w=(1,1,0), because the latter implies the investigator may consider the third principal component in some comparison, even though w=(1,1,0) ignores it. |

`gamma` |
gamma is the sensitivity parameter |

`inner` |
inner and trim together define the An error will result unless |

`trim` |
inner and trim together define the |

`lambda` |
Before applying the An error will result unless 0 < lambda < 1. |

`TonT` |
TonT refers to the effect of the treatment on the treated; see Rosenbaum and Rubin (1985, equation 1.1.1) The default is TonT=FALSE. If TonT=FALSE, then the total score in matched set i is divided by the number ni of individuals in set i, as in expression (8) in Rosenbaum (2007). This division by ni has few consequences when every matched set has the same number of individuals, but when set sizes vary, dividing by ni is intended to increase efficiency by weighting inversely as the variance; see the discussion in section 4.2 of Rosenbaum (2007). If TonT=TRUE, then the division is by ni-1, not by ni, and there is a further division by the total number of matched sets to make it a type of mean. If TonT=TRUE and trim=Inf, then the statistic is the mean over matched sets of the treated minus mean-control response, so it is weighted to estimate the average effect of the treatment on the treated. |

`apriori` |
If Scheffe=FALSE and apriori=TRUE, then the weights are assumed to have been chosen a priori, and a one-sided, uncorrected P-value is reported for gamma=1 or an upper bound on the one-sided, uncorrected P-value is reported for gamma>1. In either case, this is a Normal approximation based on the central limit theorem and equals 1-pnorm(deviate). |

`Scheffe` |
If Scheffe=TRUE, then the weights are assumed to have been chosen after looking at the data. In this case, the P-value or P-value bound is corrected using Scheffe projections. The approximate corrected P-value or P-value bound is 1-pchisq(max(0,deviate)^2,length(w)). If Scheffe=FALSE and apriori=FALSE, then the deviate is returned, but no P-value is given. See Rosenbaum (2016). Note carefully that length(w) determines the extent of the correction for multiplicity, so that, for example, w=c(1,0) focuses attention on the first principal component but allows for consideration of all comparisons using the first two principal components. See the discussion of w above and the examples below. A Scheffe correction entitles you to look in both tails, which you do by considering both w and -w. See the planScheffe() function for a combination of an apriori and Scheffe comparisons. |

`detail` |
If detail=TRUE, then some detail from the princomp() function in the stats package is returned. |

`cor` |
If cor=FALSE, the principal components of the M-scores are computed
from the covariance matrix, but if cor=TRUE, then they are computed
from the correlation matrix. Because the columns of y were scaled
using lambda and scored by the same |

If y has k columns for k outcomes, then comparison computes k M-scores, one for each outcome, computes principal components from these scores, combines the scores into a single comparison using w, and computes a one-sided, upper-tailed deviate for a randomization test or a sensitivity analysis, as described in Rosenbaum (2007, 2016).

Outcomes are scaled using by the *λ* quantile of
the absolute differences before applying the *ψ*-function. In this
sense, when trim<Inf, the M-scores share a common scaling before
principal components are computed.

Taking Scheffe=TRUE and w=(w1,w2) for all w1 and w2 considers all comparisons based on the first two principal components.

Matched sets of unequal size are weighted using weights that would be efficient in a randomization test under a simple model with additive set and treatment effects and errors with constant variance; see Rosenbaum (2007).

The upper bound on the P-value is based on the separable approximation described in Gastwirth, Krieger and Rosenbaum (2000); see also Rosenbaum (2007).

`deviate ` |
The upper bound on the standardized deviate that is used to approximate P-values using the Normal or chi-square distribution; see apriori and Scheffe in the arguments. |

`aprioriPval ` |
If Scheffe=FALSE and apriori=TRUE, the deviate is compared to the upper tail of the Normal distribution to produce either a P-value for gamma=1 or an upper bound on the P-value for gamma>1. |

`ScheffePval ` |
If Scheffe=TRUE, the deviate is compared to the upper tail of the chi-square distribution to produce either a P-value for gamma=1 or an upper bound on the P-value for gamma>1. |

`weights ` |
The weights are returned. |

For confidence intervals for individual outcomes, use function senmCI().

Under Fisher's hypothesis of no treatment effect, the principal components of the outcomes are unaffected by the treatment, so they may be used in randomization tests of no effect. However, this logic does not permit confidence intervals for the magnitude of effect on a principal component.

The principal() function computes principal components of M-scores, not of the outcomes themselves. This has various implications. The M-scores share a common, resistant scaling, so it is reasonable to consider principal components of the covariance matrix of the M-scores. In contrast, M-tests computed from principal components of outcomes are not resistant to outliers because the components themselves are not resistant to outliers. M-scores add to zero within each matched set; see the example for the mscorev() function. In this specific and limited sense, variation among M-scores reflects variation within matched sets rather than variation between matched sets. For example, if the matched sets had been exactly matched for age, then the M-scores would be uncorrelated with age. In contrast, principal components of outcomes reflect both variation within and variation between matched sets. For instance, principal components of outcomes might be correlated with age even if the sets had been matched exactly for age. When the matched set size is variable, the M-scores incorporate variable weights, and the principal components are affected by these weights. For this reason, principal components of M-scores are more interpretable when every matched set has the same size, say matched pairs or matching 1-to-2, and they may be difficult to interpret if the set sizes vary widely, say 1-1 mixed with 1-5. In thinking about the relationship between outcomes and their M-scores, it can be helpful to examine the small, univariate example for the mscorev() function.

Paul R. Rosenbaum.

Huber, P. (1981) Robust Statistics. New York: John Wiley. (M-estimates based on M-statistics.)

Maritz, J. S. (1979). A note on exact robust confidence intervals for location. Biometrika 66 163–166. (Introduces exact permutation tests based on M-statistics by redefining the scaling parameter.)

Rosenbaum, P. R. (2007). Sensitivity analysis for m-estimates, tests and confidence intervals in matched observational studies. Biometrics 63 456-64. (R package sensitivitymv) <doi:10.1111/j.1541-0420.2006.00717.x>

Rosenbaum, P. R. (2013). Impact of multiple matched controls on design sensitivity in observational studies. Biometrics 69 118-127. (Introduces inner trimming, inner>0.) <doi:10.1111/j.1541-0420.2012.01821.x>

Rosenbaum, P. R. (2015). Two R packages for sensitivity analysis in observational studies. Observational Studies, v. 1. (Free on-line.)

Rosenbaum, P. R. (2016) Using Scheffe projections for multiple outcomes in an observational study of smoking and periondontal disease. Annals of Applied Statistics, 10, 1447-1471. <doi:10.1214/16-AOAS942>

Rosenbaum, P. R. (2017) Combining planned and discovered comparisons in observational studies. Manuscript.

Rosenbaum, P. R., & Rubin, D. B. (1985). The bias due to incomplete matching. Biometrics, 41, 103-116.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 | ```
# Please READ the documentation for artcog, and in particular
# the distinction between simulated and actual data.
# The dontrun section refers to the acutal data and
# reproduces results in Rosenbaum (2017).
# The example immediately below uses the simulated data,
# and is simply a numerical illustration.
data(artcog)
attach(artcog)
# Randomization test using the first principal component of the simulated data.
principal(cbind(words,wordsdelay,animals),arthritis,mset,w=1,apriori=TRUE,detail=TRUE)
# Randomization test exploring a contrast of the first two principal components.
principal(cbind(words,wordsdelay,animals),arthritis,mset,w=c(1,-.1),Scheffe=TRUE)
# Sensitivity analysis using the first principal component of the simulated data.
principal(cbind(words,wordsdelay,animals),arthritis,mset,w=1,gamma=1.2,apriori=TRUE)
amplify(1.2,c(1.5,2))
## Not run:
# For this illustration, obtain the actual data,
# as described in the documentation for artcog.
# An illustration from Rosenbaum (2017) follows.
data(artcog)
attach(artcog)
# A randomization test using the first principal component for the three memory scores.
# The loadings show that the first component gives positive weight to each memory score.
principal(cbind(words,wordsdelay,animals),arthritis,mset,w=1,apriori=TRUE,detail=TRUE)
#
# The comparison above is insensitive to a bias of gamma=1.45
principal(cbind(words,wordsdelay,animals),arthritis,mset,w=1,gamma=1.45,apriori=TRUE,detail=TRUE)
#
# gamma=1.45 is an unobserved covariate that more than triples the odd of a poor memory score
# and more than doubles the odds of arthritis.
amplify(1.45,c(2,3,4))
#
# Although the first principal component is insensitive to a bias of gamma=1.45, each
# of the three individual variables is sensitive to a bias of gamma=1.45
senm(words,arthritis,mset,gamma=1.45)
senm(wordsdelay,arthritis,mset,gamma=1.45)
senm(animals,arthritis,mset,gamma=1.45)
#
# Although not particularly useful or enlightening in this one example, we can
# explore all weighted combinations of the first two principle components,
# correcting for multiple testing using Scheffe projections for dimension 2.
# This would be more interesting in an example with 50 outcomes, where we
# might want to reduce the dimensionality to 2 or 3 from 50, rather than to 1.
# We will do calculations for gamma=1.25. A gamma=1.25 is an unobserved
# covariate that doubles the odds of arthritis and doubles
# the odds of a worse memory score.
amplify(1.25,2)
# The deviate is the same but the corrected P-value is different if w=1 or w=c(1,0),
# because the former is doing a single one-sided test, while the latter is anticipating
# consideration of all possible combinations of the first two components.
principal(cbind(words,wordsdelay,animals),arthritis,mset,w=1,gamma=1.25,apriori=TRUE,detail=TRUE)
principal(cbind(words,wordsdelay,animals),arthritis,mset,w=c(1,0),gamma=1.25,Scheffe =TRUE)
# A weighted combination of the first two principal components, w=c(1,-.1), is ever so
# slightly less sensitive than using the first component alone.
principal(cbind(words,wordsdelay,animals),arthritis,mset,w=c(1,-.1),gamma=1.25,Scheffe =TRUE)
detach(artcog)
## End(Not run)
``` |

```
$deviate
[1] 2.928102
$aprioriPVal
[1] 0.00170519
$weights
Comp.1
1
$loadings
Comp.1 Comp.2 Comp.3
words 0.5883238 0.5072090 0.6297731
wordsdelay 0.6085791 0.2350951 -0.7578666
animals 0.5324533 -0.8291377 0.1703648
$princomp.detail
$princomp.detail$sdev
Comp.1 Comp.2 Comp.3
0.4107806 0.1925516 0.1510104
$princomp.detail$center
[1] 0 0 0
$princomp.detail$scale
[1] 1 1 1
$deviate
[1] 2.926947
$ScheffePVal
[1] 0.01379417
$scheffe.dimension
[1] 2
$weights
Comp.1 Comp.2
1.0 -0.1
$loadings
Comp.1 Comp.2 Comp.3
words 0.5883238 0.5072090 0.6297731
wordsdelay 0.6085791 0.2350951 -0.7578666
animals 0.5324533 -0.8291377 0.1703648
$deviate
[1] 1.853873
$aprioriPVal
[1] 0.03187869
$weights
Comp.1
1
$loadings
Comp.1 Comp.2 Comp.3
words 0.5883238 0.5072090 0.6297731
wordsdelay 0.6085791 0.2350951 -0.7578666
animals 0.5324533 -0.8291377 0.1703648
1.5 2
2.666667 1.750000
The following objects are masked from artcog (pos = 3):
animals, arthritis, mset, words, wordsdelay
$deviate
[1] 2.928102
$aprioriPVal
[1] 0.00170519
$weights
Comp.1
1
$loadings
Comp.1 Comp.2 Comp.3
words 0.5883238 0.5072090 0.6297731
wordsdelay 0.6085791 0.2350951 -0.7578666
animals 0.5324533 -0.8291377 0.1703648
$princomp.detail
$princomp.detail$sdev
Comp.1 Comp.2 Comp.3
0.4107806 0.1925516 0.1510104
$princomp.detail$center
[1] 0 0 0
$princomp.detail$scale
[1] 1 1 1
$deviate
[1] 0.7421459
$aprioriPVal
[1] 0.2289995
$weights
Comp.1
1
$loadings
Comp.1 Comp.2 Comp.3
words 0.5883238 0.5072090 0.6297731
wordsdelay 0.6085791 0.2350951 -0.7578666
animals 0.5324533 -0.8291377 0.1703648
$princomp.detail
$princomp.detail$sdev
Comp.1 Comp.2 Comp.3
0.4107806 0.1925516 0.1510104
$princomp.detail$center
[1] 0 0 0
$princomp.detail$scale
[1] 1 1 1
2 3 4
3.454545 2.161290 1.882353
$pval
[1] 0.2744437
$deviate
[1] 0.5994281
$statistic
[1] 11.49774
$expectation
[1] 9.05347
$variance
[1] 16.62745
$pval
[1] 0.4612725
$deviate
[1] 0.09722844
$statistic
[1] 9.492616
$expectation
[1] 9.094878
$variance
[1] 16.73429
$pval
[1] 0.4108348
$deviate
[1] 0.2253982
$statistic
[1] 9.87602
$expectation
[1] 8.972191
$variance
[1] 16.0795
2
2
$deviate
[1] 1.6143
$aprioriPVal
[1] 0.05323116
$weights
Comp.1
1
$loadings
Comp.1 Comp.2 Comp.3
words 0.5883238 0.5072090 0.6297731
wordsdelay 0.6085791 0.2350951 -0.7578666
animals 0.5324533 -0.8291377 0.1703648
$princomp.detail
$princomp.detail$sdev
Comp.1 Comp.2 Comp.3
0.4107806 0.1925516 0.1510104
$princomp.detail$center
[1] 0 0 0
$princomp.detail$scale
[1] 1 1 1
$deviate
[1] 1.6143
$ScheffePVal
[1] 0.2717201
$scheffe.dimension
[1] 2
$weights
Comp.1 Comp.2
1 0
$loadings
Comp.1 Comp.2 Comp.3
words 0.5883238 0.5072090 0.6297731
wordsdelay 0.6085791 0.2350951 -0.7578666
animals 0.5324533 -0.8291377 0.1703648
$deviate
[1] 1.609675
$ScheffePVal
[1] 0.2737535
$scheffe.dimension
[1] 2
$weights
Comp.1 Comp.2
1.0 -0.1
$loadings
Comp.1 Comp.2 Comp.3
words 0.5883238 0.5072090 0.6297731
wordsdelay 0.6085791 0.2350951 -0.7578666
animals 0.5324533 -0.8291377 0.1703648
```

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.