#wright map

A (too long in the making) new version of WrightMap is now available on CRAN (Actually, version 1.2.1 is already up).

This new version includes a lot of features that have long been requested, including cut-point lines, alternative item displays (classical Wright Map look, histogram view), and differential item functioning plots among others.

We have updated the package tutorials on our website to reflect the changes to this version, and we will be publishing additional posts showing the new features.

We hope these changes can be of use to you, and we look forward to hearing your feedback!

Change log for this version:

Major changes:

wrightMap split into data handling and plotting, each of which is further split into person & item side. The data handling functions are further split by filetype and the plotting functions are split by plot types. For data handling, this is meant to make it possible to have item and person data of different filetypes. For plotting, this is meant to make the plotting function more flexible and make it easier to add different plot styles. Details:

wrightMap.default, wrightMap.CQmodel, wrightMap.character are now removed. There is only wrightMap.R, which calls the appropriate data handling and plotting functions

helper functions for data handling

parameter person.side accepts person plot functions personHist (default) and personDens

parameter item.side accepts item plot functions itemModern (default), itemClassic, and itemHist

API changes

the "type" parameter in wrightMap is now called "item.type" to avoid collision with the "type" parameter in the "plot" function.

For the same reason, the "type" parameter in fitgraph is now called "fit.type"

the "use.hist" parameter in wrightMap is deprecated. Create a histogram with person.side = personHist (default) and density with person.side = personDens

fitgraph and make.thresholds now explicitly include a version for numeric and matrix respectively. This should fix namespace problems for users who prefer to include external functions with :: notation.

New functions:

plotCI

difplot

ppPlot

New features:

now possible to add points and ranges to person side

can easily add cutpoints on item side

added "classic" and "hist" item map

"throld" parameters added to make.thresholds and wrightMap, allowing for the calculation of thresholds other than .5

"alpha" and "c.params" added to make.thresholds and wrightMap, supporting the 2PL and 3PL models

label.items.cex and dim.lab.cex added to wrightMap to control label sizes

support for ConQuest4 added

"equation" added to CQmodel and wrightMap.CQmodel, to handle CQ output without a summary of estimation table

it is now possible to plot the person and item sides separately

Improvements:

wrightMap now remembers your original graphical parameters and restores them after drawing the map

fitgraph no longer calls a new window

better handling of generics

Bugfix:

Fixes to CQmodel on reading the #IO variance errors and included fix for the var/covar matrix on CQ3

Fixed a bug where thr.lab.pos couldn't take a matrix

Fixed a bug where fitgraph.CQmodel assumed there was always a parameter called "item" in your table

Fixed a bug where CQmodel assumed there were always an error column in the RMP tables

wrightMap will no longer crash if the p.est parameter is null

Other notes:

WrightMap features close integration with Conquest, allowing you to easily read from its output files. However, this is just a nice convenience for Conquest users, as WrightMap was designed to create beautiful item-person plots simply reading standard R matrices; all you need is a matrix of item parameters and a matrix of person estimates and you can start creating nice Wright Maps. For this reason, the WrightMap package can be used to plot the results of any IRT software, and makes it very easy to integrate with other R packages that estimate IRT models.

This post will show you how you can integrate R with one of these estimation packages, the Test Analysis Module (TAM) package in just a couple of lines.

Setup

Let's start by loading TAM

install.packages('TAM') library(TAM)

And we can use one of TAM's simulated datasets (without any missing data in this case) for this example:

data(sim.rasch) str(sim.rasch) ## num [1:2000, 1:40] 1 0 1 1 1 1 1 1 1 1 ... ## - attr(*, "dimnames")=List of 2 ## ..$ : NULL ## ..$ : chr [1:40] "I1" "I2" "I3" "I4" ...

We use the data command to load the sim.rash dataset. A quick look with str confirms that we now have a simulated dataset with responses from 2000 persons (rows) to 40 items (cols). We are ready to go!

Analysis with TAM

In this example we will run a Rasch model using the TAM command tam.mml, which will estimate the model given these responses using a marginal maximum likelihood method.

mod1 <- tam.mml(resp=sim.rasch)

The estimation should take very little time (although I imagine your mileage may vary depending on your computer), and you should see a summary of the results and the total that it took to run the analysis.

Person estimates

You can get person estimates in several ways in TAM, but for this example I will use the tam.wle command, that produces Warm Likelihood Estimates for each respondent.

persons.mod1 <- tam.wle( mod1 ) ## Iteration in WLE/MLE estimation 1 | Maximal change 0.3986 ## Iteration in WLE/MLE estimation 2 | Maximal change 0.073 ## Iteration in WLE/MLE estimation 3 | Maximal change 0.0011 ## Iteration in WLE/MLE estimation 4 | Maximal change 1e-04 ## ---- ## WLE Reliability = 0.894 str(persons.mod1) ## 'data.frame': 2000 obs. of 7 variables: ## $ pid : int 1 2 3 4 5 6 7 8 9 10 ... ## $ N.items : num 40 40 40 40 40 40 40 40 40 40 ... ## $ PersonScores: num 19 14 35 14 27 12 23 17 5 12 ... ## $ PersonMax : num 40 40 40 40 40 40 40 40 40 40 ... ## $ theta : num -0.116 -0.791 2.373 -0.791 0.964 ... ## $ error : num 0.366 0.377 0.498 0.377 0.382 ... ## $ WLE.rel : num 0.894 0.894 0.894 0.894 0.894 ...

If we look at the resulting matrix, we can see that we have several columns, including:

pid: the ID of the respondent

N.items:the number of items

PersonScores: The score of each person

PersonMax: The maximum possible score of each person

theta: The WLE estimate

error: The standard error of the WLE estimate

WLE.rel: The WLE reliability

You can look at the TAM documentation for more details, but for this example, we want to focus on the theta column, which contains the person estimates we need to create our Wright map.

We can get the data we need then by selecting just that column:

WLEestimates.mod1 <- persons.mod1$theta

Item parameters

And we can get our item estimates using the tam.threshold command.

thresholds.mod1 <- tam.threshold(mod1)

Creating the Wright Map

With this two matrices we are ready to plot our Wright Map:

wrightMap(WLEestimates.mod1, thresholds.mod1)

And you can start editing it to make it nicer:

If you are interested in learning a little more about the story of the term "Wright Map", this is a great piece from Mark Wilson narrating how and why he coined the term.

It seemed to me that, in fact, Ben had made his most significant contributions to measurement in the area of conceptualizing measures, and interpreting the results of measurement analyses, and that his central tool in doing so were these (many forms of) items maps. In addition, I knew of no one else who had made an equivalent contribution, especially not in terms of item mapping. Hence, I coined the term "Wright Map" in honor of Ben Wright and his very deep contributions to measurement.