Software and data sets to do classic and modern psychometrics, and to analyze personality  and experimental psychological data sets. 

The psych package has been developed as a supplement to courses in research methods in psychology, personality research, and graduate level psychometric theory.

The functions are a supplement to the text (in progress): An introduction to psychometric theory with applications in R. 

Additional functions are added sporadically.



To do: 

 o	Add confirmatory clustering to ICLUST
 o	Get cluster scores in ICLUST -- analogous to factor scores (requested by Ben Shalet)
 o	Add signal detetection function as an option for dichotmous data.
 o	Add a function to perform factor extension 
 o	Implement the other ways of doing factor scores (Bartlett, etc.)
 o	Clean up circ.tests to be more compatible with rest of psych
 o	Add the ability to create multiple groups in sim.irt functions
 o	Clean up output from schmid to more match other functions
 o	Make pairs.panels not change options for graphics window   (fixed, maybe?)
 

 ------------
Changes in Version 1.0.94 (2011-01-01)
Additions
 o	Eliminated references to polychor in Yule2poly, 

Bugs Fixed 
 o	fixed read.clipboard.upper so that it will read labels
 o	fixed  mat.regress so that it can work with a single predictor
 
------------
Changes in Version 1.0.93 (2010-12-22)
Additions
 o	Added mixed.cor to do mixtures of Pearson, polychoric and tetrachoric correlations
 o	Added legends to error.bars.by  bar graph
 o	Modified score.items so it will work on correlation matrices as well as raw data.
 o	Improved the plot.irt and plot.poly functions to plot irt output.  Called by plot.psych or generic plot call.
 o	Added a trivial little function, bi.bars to do paired histograms
 o	Modified irt.fa to allow for multiple factors
 o	Modified scrub to be a general recoding function
 o	Modified error.bars.by to allow for ... parameters to be passed into axis
 o	Modified diagram so it will dispatch a number of diagram functions (fa, prinicpal, omega, iclust, lavaan).
 o	Added a biplot.psych function to do biplots of fa or principal results.
 o	Added an unbiased estimate of kurtosis in the kurtosi function.
 o	Added a predict function to fa and principal (predict.fa and predict.principal, both called from predict.psych) 
 o	Added lavaan.diagram to draw the output from a cfa or sem from the lavaan package.
 o	Added a function to calculate Mardia's test for multivariate normality
 o	Added lengends and improved the examples for pairs.panels.by
 o	Removed the "short" option in score.items
 o	Added the ability to score scales with greatly missing data (for SAPA). Modified the impute option to include = "none"
 o	Added the term KR20 and KR21 to documentation of alpha
 o	Modified pairs.panels so that with the cor option it can draw regressions and give correlations.
 o	Modified the documentation for error.crosses to give a better example.
 o	Added the ability to read rownumbers (variable names?) in first column of read.clipboard.lower and read.clipboard.upper
 o	Tweaked the zlim default for cor.plot to be c(-1,1) rather than c(0,1)
 o	Minor adjustments to Yule and phi.demo to call tetrachoric instead of polycor, thus making the package work with fewer dependencies.
 o	Cleaned up the fa summary output 
 Bugs Fixed 
 o	 Fixed dia.curved.arrow to draw one headed curved arrows (as documented)
 o	Fixed a problem with fa.print option sort  -- Although giving the correct communalities and uniquenesses in the unsorted option, when sorted, it was not sorting h2 or u2. 
------------
Changes in Version 1.0.92 (2010-09-22)
Additions
 o	 Added omega total from sem to the omegaSem function.
Bugs Fixed 
 o	error.bars.by was ignoring the user supplied ylim.  (reported by Helena Chui)  Fixed.
 o	Was drawing incorrect  sl solution in omega.graph (reported by Mark Difford).fixed.
 o	omega.Rd and schmid.Rd incorrectly referred to fm=ml as fm=mle. Fixed.
Changes in Version 1.0.91 (2010-09-15)
Additions
 o	Added iclust and vss as an alternative names to ICLUST and vss to be consistent with most naming conventions.
 o	Added the simple utility scrub to do data cleaning.
 o	Added biserial and polyserial to do biserial/polyserial correlations (not to be confused with point biserial)
 o	Modified score.multiple.choice so that it handles missing data without using imputation
 o	Changed the bfi data set to include more subjects and to correctly define the Openness scale.
 o	Modified score.multiple.choice and score.items to report response frequencies for each item (frequencies based upon number of non-missing responses).
 o	Added the burt data set of 11 emotional variables (from Burt, 1915) 
 o	Added draw.tetra to draw tetrachoric correlations for fixed tau values (teaching demo)
 o	Added plot.irt and plot.poly to the plot.psych function. These have options to draw the item characteristic function, the item information function, and the test information.
 o	Added irt.fa to do factor analysis of dichotomous or discrete items by first forming a tetrachoric or polychoric correlation matrix. Then convert the results to IRT form. 
 o	Added tetrachoric and polychoric functions to find tetrachoric/polychoric correlations as well as item discrimination parameters.
 o	Added omegaSem and omegaFromSem to calculate omega from a confirmatory factor model using John Fox's sem package.
 o	Added (with permission) Bond's Logical Operations Test (BLOT) data set.
Bugs Fixed
 o	sim.irt was not properly handling vectors of item discrimination or guessing parameters.  Fixed.
 o	Minor problem in fa.stats that would lead to an error message if chisquare was NaN. 
 o	Minor bug in reverse.code for case of 1 variable (why one would want to use 1 the function for one variable is unclear.)
 o	tetrachoric would not apply the correction for continuity when given a table input but would when given normal data.  Fixed.
------------
Changes in Version 1.0.90 (2010-07-07)
Additions
 o	 Added a few parameters to fa.parallel to a) set the y label and b) to show or not show a legend. Useful for multipanel displays.
 o	Minor improvements to fa.diagram to allow for input of factor loadings and intercorrelations from other functions.
 o	Added sim.omega to simulate multifactorial hierarchical structures as a test (and demonstration) of omega.
 o	Minor changes to the parameter call list for sim.minor to be compatible with sim.omega.
Bugs Fixed
 o	Fixed a problem in ICLUST where it would sometimes not stop at the right number of clusters for n.clus = 1
 o	Fixed problem in omega.diagram where it would sometimes use the incorrect line type for hierarchical (non-Schmid-Leiman) diagrams.
 o	Fixed bug in schmid where it would not rotate exactly orthogonal factors and find exactly omega = 0.
 o	Added a warning message that oblique rotation does not work, and does a cluster based rotation instead in the case of exactly orthogonal factors.  This is just a problem for artificial data sets.
History (Both of these are probably due to a problem in GPArotation which has since been fixed.)
------------
Changes in Version 1.0.89 (2010-06-21)
Additions
 o	Rearranged the order of parameters for fa so that it is easier to call.
 o	Added various sem stats to fa output (e.g. RMSEA, BIC, rms, crms).  These are also provided for omega output.
 o	Add fit statistics to omega for g solution only.  
 o	Added a measure of general factor adequacy in Omega.  This is just the percent of common variance that is general factor variance for each item. High values and low variances suggest a more meaningful estimate than lower average values or higher variances.
 o	Various clean up of output of ICLUST and iclust.diagram.  Added color option for positive and negative loadings.
 o	Changed ICC to work on complete data (i.e., using na.omit) as the default (following a question) by Ross Culloch
 o	Changed pairs.panels to allow for color choice of histogram (requested by Elaine Kuo) 
 o	Changed describe to handle numeric but annotated vectors (suggested by Soeren Vogel)
 o	Clarified documentation of cohen.kappa and allowed for  using explicitly non-numerical categories  (as suggested by Peter Ehlers  and Scot McNary)
 o	Increased the usefulness of error.bars to allow for input of x values, y values, and confidence interval. Also added the ability to use 1 standard deviation.   
 o	Minor change to print.psych.fa to round before using formatting. 
 o	Removed the cut <- min(cut,max(abs(load))/2)  following a request by  Reinhold Hatzinger to be consisent with factanal
 o	Added an option to omega to allow for analysis of data sets from just the factor loadings and correlation matrices. 
 o	Add a scree function to replace VSS.scree
 
 Bugs Fixed
 o	 Fixed a bug in pairs.panels for the case of not smoothing but with data ellipses (reported by Hirayuki Sato)
 o	 Fixed a serious bug in omega for the case of non-positive manifold items (e.g., personality items). The sign of the group factors was not correctly being set which would lead to incorrect estimates of the multiple R2.
 o	 Fixed bug in ICLUST.diagram  where it would draw on top of other figures in rare cases.
 o	 Fix bug in ICLUST for the path coefficients -- in the case of negative loadings, some of these were much too small.
 o	 Correctly color the paths in omega.diagram. 
 o	 Fixed print.psych.fa to correctly showing item numbers for sorted output. 
 o	 Corrected tetrachor so it would not inappropriately claim that some cells had no data (this did not affect the correlations, just gave an inappropriate warning).
------------
Changes in Version 1.0.88 (2010-04-24)

Additions
 o	Added within option for error.bars and error.bars.by to allow for within subject error estimates.
 o	Reformatted this file (NEWS) so that the command  (e.g.,) news(query=Version > "1.0.85",package="psych")  provides nice information.
 o	Added more detail to the overview vignette to discuss how to find omega.
 o	Added the block.random function to block randomize for experimental designs.
 
Bugs Fixed
 o	Corrected schmid (and thus, omega) so that it finds orthogonal factors before rotating them obliquely.  This corrected an error introduced in version 1.0.86 when the default rotation for fa was switched to be oblimin. 
 o	correct=FALSE option in tetrachor actually works


Changes in Version 1.0.87 (2010-04-04)
------------

Bugs fixed
 
 o	error.bars (and error.bars.by) would not properly draw < 3 variables

Changes in Version 1.0.86 (2010-03-26)
------------
Additions

 o	Added logit, logistic and logistic.grm functions to help teach about IRT.
 o	Added the ability to factor analyze covariance matrices (with resulting loadings of covariances rather than correlations) (suggested by Andreas Moeltner)
 o	Added two new functions to estimate the greatest lower bound (glb.algebraic, written by Andreas Moeltner) and glb.fa.  
 o	Added read.clipboard.fwf to allow reading of fixed width files from clipboard. (Originally this required adding a patch to the read.fwf function but that was subsequentally fixed.)
 o	 Minor adjustment to ICLUST.cluster so that it will produce fewer clusters (if desired) than it thinks are appropriate.  That is, if n.clus is less than the appropriate solution, a warning is issued, but n.clus clusters are found.
 o	Changed the default rotation in fa to be oblimin.  (Subsequently discovered that this introduced a bug into schmid and therefore omega.)
 o	  Added the glb.communality function to calculate the greatest lower bound by using factor communality estimates (based upon correspondece with Andreas Moeltner, although his algorithm (glb.algebraic, which is now included) which uses the Rcsdp provides slightly different estimates).
 o	 added names to communalities in principal (requested by Gumundur Arnkelsson).
 o	 Minor change to headtail
 o	 Added the sim.rasch function to simulate 1 parameter IRT Rasch models.
 o	 Added the data sets bock and income. bock is the source of the lsat data,income is US family income from 2008.
 o	 Seriously modified the estimation of Cohen's Kappa in the wkappa function and added a new function: cohen.kappa to calculate kappa from raw data or from similarity matrices.  Also calculates the variances following Fleiss, Cohen, and Blashfield, and then find the confidence limits.
 o	Modified the sim.minor function to simulate correlation matrices with nfact major factors and nvar/2 minor factors with larger number of variables.   
 
Bugs fixed
   o	 Fixed print.psych.fa to give correct communalities for sorted factors (had been not sorting the communalities, although it had the factor loadings).
   o	 Minor change to comorbidity to clean up output (using print.psych)
   o	 Fixed guttman to correctly estimate lambda 4 (error pointed out by Andreas Moeltner). 

------------
Changes in Version 1.0.85 (2009-12-20)

Additions
 o	  Modified the output from fa.parallel to print summary statistics.  Also added an option to use smcs as communality estimates.
 o	  Added the sim.minor function to generate major and minor factor structures. 
 o	  Modified fa to use first derivatives based upon the model rather than just empirically derived.  This results in an impressive speed improvement.
 o	 Continued to improve the dia.x functions.  Labeled the entire set of functions diagram (for easier search).

------------
Changes in version 1.0.84  (2009-11-30)
Additions
 o	Improved documentation for the dia functions to show the power of structure diagrams
 o	Improved structure.diagram to allow graphs to go left to right (default) or bottom to top (which means causal arrows go left to right)
 o	Added the affect data set which includes data from two experimental studies of affect.
 o	Added some features from pairs to allow group coloring in pairs.panels
 o	Modified factor.parallel to allow for other factoring models (including minres)
 o	Modified fa to give eigenvalues of the correlation matrix, and of the common factor space.
 o	Modified pairs.panels so it can plot even if the correlations are NA
 o	Added a legend and improved the output of cor.plot.
 o	Having learned how to use strwidth, have cleaned up the dia.rect, fa.diagram, structure.diagram, and iclust.diagram functions.
 o	Changed the way fa.parallel handles correlation matrices if the number of subjects is not specified. Rather than issuing a warning and proceeding as if n.obs = nvars, it now assumes n.obs =100.
 o	Improved documentation for fa to explain minimum correlation of factor score estimates. 
 
Bugs fixed
 
 o	Fixed a problem with printing of the principal (components) results
 o	Fixed bug in the print.psych.vss function that returned the wrong value (although identifying the correct number) for the  Velicer MAP criterion. (Reported by Maike Luhmann).

------------
Changes in version 1.0.83  (2009-10-26)
Additions
 o	Added Suggests Rgraphviz to DESCRIPTION file to get around CRAN test for 2.10 (as I should have done according to documentation for packages).  Removed all tests of functions which require RGraphviz for 2.9.2 because Rgraphviz does not work on SnowLeopard. 

------------ 
Changes in version 1.0.82  (2009-10-26)
Additions

  o	Improved the output for mat.regress to allow print() and summary().
  o	Corrected bug to fa for case of oblique and negatively correlated factors (reported by Erich Studerus).
  o	Corrected problem in describe.by to properly identify the matrix output 
Bugs fixed
  o	Minor improvements to the dia.x functions 
  o	Fixed the formatting of the news file to follow the appropriate format
  o	Removed the old supplementary  manual from the docs folder to make for a cleaner installation

------------
Changes in version  1.0.81 (2009-10-04) 
Additions
 o	Improved the documentation for the dia.X functions and made some of the calls simpler.  

Changes in version  1.0.80 (2009-09-30) 
Additions
  o	Added the ability to draw "diagrams" to replace the functions that required Rgraphviz.  These are path diagrams with rectangles for observed variables and ellipses for latent variables.  A set of graphic functions for drawing diagrams includes dia.ellipse, dia.rect, dia.arrow, dia.curve and dia.self.  This allows the  function omega and ICLUST to draw structural diagrams without using Rgraphviz.
  o	The documentation for these new functions is a bit less than desirable and the dia primitives will be modified slightly for the next release.

Changes in version  1.0.79 (2009-08-25)
Additions
  o	added the Schmid data set which includes the original Schmid-Leiman correlation matrix as well as data from Chen, West, and Sousa (2006).
  o	modified geometric.mean and harmonic.mean to allow for missing data.
  o	Cleaned up describe.by so that it can handle matrix output of multiple grouping variables and then print correctly.

Changes in version  1.0.78  (2009-07-28)

Additions
  o	Modified factor.stats to allow for statistics even if the matrix is very singular (i.e., N var >> n.obs).
Bugs fixed
  o	Corrected bug to ICLUST introduced in version 74 that can, in some conditions, produce negative betas. 

Changes in version  1.0.77 (2009-7-24)
Bugs fixed
  o	Fixed an error in printing communalities for rotated factor solutions reported by Tamaki Hattori. Also resolved a problem of extra lines appearing in error.bars.  Minor revision to polar. 

Changes in version  1.0.76 (2009-7-4)
Bugs fixed
  o	Finally resolved the problem of not passing the CRAN tests for Mac (even though developed on a Mac, the test package assumes no other packages).

Changes in version  1.0.75 (2009-07-01)
Additions
  o	Reinstituted reporting communalities and uniquenesses for principal components and for factor analysis.  This feature had been dropped sometime in the past and reported missing by Ista Zahn.
  o	Added two new data sets: Harman.Holzinger and Harman.Burt.  The former is used by Peter Bentler as an example of alternative methods for estimating   reliability, the latter is a nice example of what happens if the correlation matrix is singular.  smc estimates are inappropriate in this case and need to be checked.

Changes in version  1.0.74 (2009-06-25) 
Additions
  o	Added a weighting option to ICLUST.  Weighted beta finds the average between cluster correlation and takes the ratio of the  n ^2 * average between cluster correlation to the total variance of the pooled clusters as a measure of the general factor.  That is, Unweighted beta calculates beta based upon the correlation between  two clusters, corrected for test length using the Spearman-Brown prophecy formala, while weighted beta finds the average interitem correlation between the items  within two clusters and then finds beta from this.  That is, for two clusters A and B of size N and M with between average correlation rb, weighted beta is (N+M)^2 rb/(Va +Vb + 2Cab).  Raw (unweighted) beta is 2rab/(1+rab) where rab = Cab/sqrt(VaVb).   Weighted beta seems a more appropriate estimate and is now the default.  Unweighted beta is still available for consistency with prior versions. (Unfortunately, in doing this, a bug was introduced that could produce negative betas.  Fixed in Version 78).
  o	Modified the fa function to include maximimum likelihood factor analysis.

Changes in version  1.0.73 (2009-06-08) 
Additions
  o	Added gls fit option to fa
  o	Added mat.sort to sort correlation matrices by factor loadings.  
  o	Revised the overview vignette to make more readable.
  o	Fixed (I hope) the documentation error that has been preventing being loaded onto CRAN for Mac.

Changes in version  1.0.72 (2009-06-02)
Additions
  o	Added factor stats to omega
Bugs fixed
  o	Minor fix to print.psych.omega to correct printing error introduced in .71

Changes in version  1.0.71 (2009-06-01) 
Additions
  o	Combined principal axis, unweighted least squares (minres) and weighted least squares into one combined function (fa). Eventually the three other functions (factor.pa,factor.wls, and factor.minres) will be phased out. Added more rotation and transformation options (basically by making calls to the GPArotation package).
  o	factor.stats now reports the factor weights matrix for factor scores.
  o	A new factor analysis function factor.wls will give weighted least squares (wls).
  o	Omega will now give an estimate for  1  factor and a message about how there are alternatives for 2 factors.
Bugs fixed
  o	Fixed a bug in print.psych.omega so that it will now report the item numbers correctly when sorting.
  o	Fixed call in phi.demo so that it checks if the polycor package is installed.  This was causing problems in the Mac version on CRAN.


Changes in version  1.0.70 (2009-05-25) 
Additions
  o	Added factor.stats function to report a variety of statistics for factors or components.  In particular, added measures of factorial adequacy.  factor.stats is now called by the factor.pa, factor.minres, and principal, so it is easier to adjust all three of these functions.
  o	Added a new rotation option to target.rot -- if keys are not specified, it will rotate to a cluster solution.
  o	minor tweak to sim.hierarchical to make it consistent with the Jensen and Weng paper
  o	added to omega to calculate omege_infinity
  o	corrected bug in principal for case of singular matrices (reported by Gudmundur Arnkelsson) 
  o	corrected bug in print.psych so that it now sorts by factor loadings correctly 


Changes in version  1.0.69  2009-04-25 
Additions
  o	added cor.plot to graphically display correlation structures
  o	modified cosinor to do regression as well as optimization for fits
  o	minor correction to ICLUST to catch non-invertible matrices

Changes in version  1.0.68  2009-04-15 
Additions
  o	Added method="minres" to do minimal residual (ULS) factor analysis to the factor.pa function. 
  o	Added the target.rot function to do targeted rotation.
  o	Added the sim.anova function to simulate 3 way ANOVA or linear models.
  o	Minor cleanups of code in other functions


Changes in version  1.0.67:  2009-03-15
Additions
  o	Have included the vignettes in the package
  o	Serious modifications to mat.regress to allow for raw data and covariances to be used.
  o	Added corrections for item overlap to use estimated communalities of items to alpha, cluster.cor, etc.
  o	Added estimates of G6+  (Modified Guttman 6) reliabililty to alpha, score.items


Changes in version  1.0.66:  2009-02-15
Additions
  o	Introduced two package vignettes (overview and psych_for_sem)
  o	minor modification to ICLUST with respect to labeling
  o	addition to factor.congruence to allow for comparing omega solutions with factor solutions
  o	modified describe to allow for descriptions of categorical variables.

Changes in version  1.0.64:  2009-02-01
Additions
  o	Added the function alpha to find Cronbach's alpha and Guttman's Lambda 6 for total scales as well as with single item deleted.
  o	Minor enhancements to the structure.graph and structure.sem functions. Further refinements to the psych_for_sem.pdf tutorial.  

Changes in version  1.0.63:  2009-01-15
Additions

  o	Added structure.graph and structure.sem to create graphical output and pre-sem commands for sem.
  o	Modified omega.graph to return sem commands for running the sem function from John Fox.
  o	Added Promax to report factor intercorrelations for promax rotations.
  o	bug fix in VSS and omega to allow for promax rotations.
  o	correction to winsor so that it does not sort the vectors of the input data.frame.
  o	bug fix in principal (for problem of oblique rotations)
  o	continued improvements in the print.psych and summary.psych functions 
  o	cleaned up sim.congeneric to reduce the amount of output (now handled through print.psych)
  o	added super.matrix function (to combine two matrices -- useful for constructing keys and for doing examples in structure.graph)
  o	Improvements to structure graph.

Changes in version  1.0.62:  2008-12-31
Additions
  o	added the structure.graph function
  o	added circadian functions 
  o	renamed some functions to make the index order easier to follow.

Changes in version  1.0.58:  2009-09-15
Additions
  o	Introduced the guttman function to estimate the 6 Guttman (1945) estimates (as well as a few others).

Changes in version  1.0.54:  2009-08-15
Additions
  o	Added print.psych and summary.psych generic functions to clean up the output of many of the functions. 

Changes in version  1.0.50:  2007-11-15
Additions
  o	Introduced several new functions:
  o	headtail   (combines head and tail functions to produce the first N and last M rows of a matrix or dataframe)
  o	error.bars and 
  o	error.bars.by     plot means with error bars by a grouping variable
  o	omega revised to allow for negatively keyed items.  Detects items that should be reversed.

Changes in version  1.0.40:  2007-08-15
Additions

  o	score.multiple.choice   provides scores and item statistics for multiple choice items.
  o	circ.sim modified to be more general item simulations
  o	circ.simulation
  o	item.sim
  o	polar converts two dimensional factor loadings to polar coordinates.
  
 