psych.misc: Miscellaneous helper functions for the psych package

Description

This is a set of minor, if not trivial, helper functions. lowerCor finds the correlation of x variables and then prints them using lowerMat which is a trivial, but useful, function to round off and print the lower triangle of a matrix. reflect reflects the output of a factor analysis or principal components analysis so that one or more factors is reflected. (Requested by Alexander Weiss.) progressBar prints out ... as a calling routine (e.g., tetrachoric) works through a tedious calculation. shannon finds the Shannon index (H) of diversity or of information. test.all tests all the examples in a package. best.items sorts a factor matrix for absolute values and displays the expanded items names. fa.lookup returns sorted factor analysis output with item labels. cor2 correlates two data.frames (of equal length). levels2numeric and char2numeric convert dataframe columns that are categorical/levels to numeric values.

Usage

psych.misc()
lowerCor(x,digits=2,use="pairwise",method="pearson",minlength=5,cor="cor",show=TRUE)
cor2(x,y,digits=2,use="pairwise",method="pearson",cor="cor",show=TRUE)
lowerMat(R, digits = 2,minlength=5)
matMult(x,y) #multiply two matrices with missing data
tableF(x,y)
reflect(f,flip=NULL)
progressBar(value,max,label=NULL) 
shannon(x,correct=FALSE,base=2)
test.all(pl,package="psych",dependencies 
      = c("Depends", "Imports", "LinkingTo"),find=FALSE,skip=NULL) 
 levels2numeric(x) 
 char2numeric(x,flag=TRUE) 
 nchar2numeric(x,flag=TRUE)
 isCorrelation(x,na.rm=FALSE) #test if an object is a symmetric matrix 
    # with diagonals of 1 and  all values between -1 and 1
 isCovariance(x)  #test if an object is a symmetric matrix   
 fromTo(data,from,to=NULL) #convert character names to locations as specified in colnames
 #of data
 cs(...) #convert a list of text words to  character vector
 acs(...) #convert a list of text words to  a single string
 SAPAfy(x,y)  #sample y columns from x, replace other columns with NA

Value

tableF is fast alternative to the table function for creating two way tables of numeric variables. It does not have any of the elegant checks of the table function and thus is much faster. Used in the tetrachoric and polychoric functions to maximize speed.

lowerCor Finds and prints (using lowerMat) the lower diagonal correlation matrix but returns (invisibly) the full correlation matrix found with the use, method and cor parameters. The default values are for pairwise deletion of variables, "pearson" correlations. Specify cor="tetrachoric", "polychoric", or "mixed" for alternatives. By default, digits is set to print to 2 decimal places. By default, it will change character variables to numeric and flag them.

lowerMatShows the lower triangle of a matrix, rounded to digits with titles abbreviated to digits + 3

progressBar Display a series of dots as we progress through a slow loop (removed from anything using multicores).

tableF (for tableFast) is a cut down version of table that does no error checking, nor returns pretty output, but is significantly faster than table. It will just work on two integer vectors. This is used in polychoric an tetrachoric for about a 50% speed improvement for large problems.

shannon finds Shannon's H index of information. Used for estimating the complexity or diversity of the distribution of responses in a vector or matrix. $$H = -\sum{p_i log(p_i) }$$

test.all allows one to test all the examples in specified package. This allows us to make sure that those examples work when other packages (e.g., psych) are also loaded. This is used when developing revisions to the psych package to make sure the the other packages work. Some packages will not work and/or crash the system (e.g., DeducerPlugInScaling requires Java and even with Java, crashes when loaded, even if psych is not there!). Alternatively, if testing a long list of dependencies, you can skip the first part by specifying them by name.

cor2 will find and display the correlations between two sets of variables, rounded to digits, using the other options. If x is a list of multiple sets (two or more), then all sets are correlated.

levels2numericconverts character data with levels to numeric data. Used in the SAPA analyses where we code some variables, (e.g., gender, education) with character codes to help in the documentation of files, but want to do analyses of correlations with other categorical variables.

char2numericconverts character data with levels to numeric data. Used for cases when data from questionnaires include the response categories rathere than numeric data. Unless the levels of the data are in meaningful order, the numeric results are not useful. Most useful if doing polychoric analyses. Note this is not suitable for recoding numeric data stored as characters, for it will force them to levels first. See nchar2numeric. Note that for very small data sets, because the recoding done by char2numeric is column wise, it might result in different numerical results for the same characters in different columns.

Problems with char2numeric can be solved by using the psychTools::recode function.

nchar2numericconverts numbers coded as characters (quoted) to numeric without forcing them to factors first.

fromTo selects the columns in data from to (see the examples)

cs concatenates strings without the need to identify variables by " ".

Arguments

R: A rectangular matrix or data frame (probably a correlation matrix)
x: A data matrix or data frame or a vector depending upon the function.
y: A data matrix or data frame or a vector
f: The object returned from either a factor analysis (fa) or a principal components analysis (principal)
digits: round to digits
minlength: Abbreviate to minlength in lowerCor
show: Display the correlations from lowerCor or cor2 (default is TRUE)
use: Should pairwise deletion be done, or one of the other options to cor
na.rm: Should we check for NA on the diagonal of a correlation matices
method: "pearson", "kendall", "spearman"
cor: defaults to the normal cor function, but can also do tetrachoric, polychoric or covariances (cov)
value: the current value of some looping variable
max: The maximum value the loop will achieve
label: what function is looping
flip: The factor or components to be reversed keyed (by factor number)
flag: flag=TRUE in char2numeric will flag (with *) those variables that had been numeric. This changes the variable name. flag = FALSE does not mark those variables.
correct: Correct for the maximum possible information in this item
base: What is the base for the log function (default=2, e implies base = exp(1))
pl: The name of a package (or list of packages) to be activated and then have all the examples tested.
package: Find the dependencies for this package, e.g., psych
dependencies: Which type of dependency to examine?
find: Look up the dependencies, and then test all of their examples
skip: Do not test these dependencies
data: A dataframe or matrix to choose from
from: select from column with name from to column with name to
to: select from column from to column to
...: Any string of legitimate objects

Details

lowerCor prints out the lower off diagonal matrix rounded to digits with column names abbreviated to digits + 3 characters, but also returns the full and unrounded matrix. By default, it uses pairwise deletion of variables. It in turn calls

lowerMat which does the pretty printing.

It is important to remember to not call lowerCor when all you need is lowerMat!

cs is a direct copy of the Cs function in the Hmisc package by Frank Harrell. Added to psych to avoid the overhead of the Hmisc package.

Examples

Run this code

lowerMat(Thurstone)
lb <- lowerCor(psychTools::bfi[1:10])  #finds and prints the lower correlation matrix, 
  # returns the square matrix.
lowerCor(psychTools::ability[,1:5]) #the Pearson correlations, compare with
lowerCor(psychTools::ability[,1:5],cor="tetra")
#fiml <- corFiml(psychTools::bfi[1:10])     #FIML correlations require lavaan package
#lowerMat(fiml)  #to get pretty output
f3 <- fa(Thurstone,3)
f3r <- reflect(f3,2)  #reflect the second factor
#find the complexity of the response patterns of the iqitems.
round(shannon(psychTools::iqitems),2) 
#test.all('BinNor')  #Does the BinNor package work when we are using other packages
bestItems(lb,"A3",cut=.1,dictionary=psychTools::bfi.dictionary[1:2])
#to make this a latex table 
#df2latex(bestItems(lb,2,cut=.2))
#
data(psychTools::bfi.dictionary)
f2 <- fa(psychTools::bfi[1:10],2)
fa.lookup(f2,psychTools::bfi.dictionary)

sa1 <-sat.act[1:2]
sa2 <- sat.act[3:4]
sa3 <- sat.act[5:6]
cor2(sa1,sa2)
cor2(list(sa1,sa2))  #show within set and between set cors
cor2(list(sa1,sa2,sa3))
lowerCor(fromTo(sat.act,"ACT","SATQ")) #show some correlations
vect <- cs(ACT,SATQ)  #skip the quotes
vect   #they are in this vector
#to combine longer terms
vect <- cs("Here is a longish",vector, that, we ,"want to combine", into, several)
vect
temp <- acs("Here is a longish",vector, that, we ,"want to combine", into, one)
temp
lowerCor(fromTo(sat.act,cs(ACT,SATQ)))
lowerCor(fromTo(bfi,cs(A3,C4)),cor="poly") #compare with
lowerCor(fromTo(bfi,cs(A3,C4)))


set.seed(42)  
temp <- SAPAfy(bfi[1:10],3)  #30 % sample from bfi
f2 <- fa(bfi[1:10],2)
 f2s <- fa(temp,2)
 fa.congruence(f2s,f2)  #the two factor structure are almost identical
 #although the scores are not identical
cor2(f2$scores, f2s$scores)