\documentclass[letterpaper]{report}

\usepackage[latin1]{inputenc}
\usepackage{makeidx}
\usepackage{url}
\usepackage{fancybox}
\usepackage{hyperref}
\usepackage{graphicx}
\usepackage[francais,english]{babel}

\title{eirt - Item Response Theory Assistant for Excel}
\author{Stéphane Germain, Pierre Valois and Belkacem Abdous}
\date{september 7 2007}

\makeindex
\newcommand{\idx}[1]{{\bf #1}\index{#1}}

\begin{document}

%\hypersetup{
%     pdftitle={eirt},
%     pdfsubject={Item Response Theory Assistant for Excel},
%     pdfauthor={Stephane Germain}
%}

\selectlanguage{english}

\sloppy

\bibliographystyle{apalike}

\maketitle

%\begin{abstract}
%\end{abstract}

\tableofcontents


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Introduction}

The {\em eirt} program is an add-in for {\em Excel} that does Item
Response Theory estimations. This program is restricted to the case
where the latent variable (the ability) is unidimensional and follow
the normal distribution, and the number of possible response (the
options) is finite. This type of item include the binary case, the
multiple choice case and the graded case.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{icc-en.png}}
\caption{Example of Item Characteristic Curves.}
\end{center}
\end{figure}


The list of supported models includes the logistics models with one,
two and three parameters for the binary data, the nominal response
model for the multiple choice data, and the graded response model for
the graded data.

The estimation of the item parameters is done by the maximum
marginal likelihood estimator or by the Baye modal estimator. In
addition, two non-parametrics estimators are supported; the kernel
estimator and the penalized maximum marginal likelihood estimator.
The abilities are estimated by the expected a posteriori estimator.

The {\em eirt} program uses the numerical routines from the {\em
  libirt} library (\url{http://libirt.sf.net}) also available in {\em
  rirt} a {\em R} package (\url{http://www.r-project.org}).

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Installation}

The {\em eirt} program is available for download at
\url{http://sourceforge.net/projects/libirt/files/eirt}.
The installation program is named {\bf eirt-1.0.0.exe} where 1.0.0 is
the version number.

The \idx{installation program} first ask to select the
\idx{installation language}. Select {\bf english} and click
on the {\bf ok} button. If another language is selected, it will also be used
in the program. It is possible to change the \idx{display language}
after the installation with the \idx{settings} tools(see the
chapter \ref{Config}).

For the rest of the installation, you can keep the default value.
Near the end of the installation, an {\em Excel} macro is run to
install the program into {\em Excel} menu.  It is necessary then to
accept the \idx{macro activation}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Assistant usage}

Before using the assistant, you have to start {\em Excel}
and open the worksheet where your data is. Then you navigate
into the \idx{tools} menu, go to the \idx{eirt} sub-menu
and choose the \idx{start the assistant} option.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{start-en.png}}
\caption{Starting the assistant.}
\end{center}
\end{figure}

The {\em eirt} program is an assistant like program with four step.
At each step, the program gives a brief instruction, you give the
information asked and then click on the \idx{next} button.  At the end
of this process a report is generated.

At any step of the assistant, you can click on the \idx{back} button
to go at the previous step, on the \idx{cancel} button to stop the program, 
or on the \idx{help} button to get help.

%%%%%%%%%%
\section{Step 1 : the data selection}

The first step of the assistant is the data selection. The goal of
this step is simply to enter the position of the data into the
worksheet.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{step1-en.png}}
\caption{Data selection.}
\end{center}
\end{figure}

If before the start of the assistant a range is already selected,
it is automatically used. If the selected range isn't the right one,
you have to click on the \idx{selection} and select a new range.

If the selected range contains the \idx{subject labels} in the first
column, the \idx{item labels} in the first row or the
\idx{correction key} in the next row, then check the appropriate box.

%%%%%%%%%%
\section{Step 2 : the data type definition}

The second step of the program is to define the \idx{data type}.  This
step allow you to define how your data is coded and has an effect on
which models are available in the next step.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{step2-en.png}}
\caption{Definition of the data type.}
\end{center}
\end{figure}


In all the case you have to give how the \idx{missing values} are coded.
This value can be a number, a string or left empty, in which case the
empties cells will be taken as missing values.

\subsection{Binary type}
If all the item have only the same two options, you should choose the
\idx{binary type} that gives access to the univariate logistic models
and make a simpler report. In this case you also have to give how the
\idx{succes} are coded. This value can be a number or a string.
All the responses different from this value and different of a missing value
is assumes to be a failure.

\subsection{Multiple choice type}
If some items have more than two options and each item has only one
good option, you have to choose the \idx{multiple choice type}.  In
this case you also have to give the \idx{correction key}.  The values
in this field have to be comma separated and contains no spaces.  To
help you input the correction key, its length is displayed.  If the
corrction key is in the selected range and the appropriate box was
checked in the first step, then the key is already into this
field.

\subsection{Graded type}
If some items have more than two options, the response to all items
are integers, and a bigger response mean a bigger ability, then you
have to choose the \idx{graded type}. In this case you also have to
give the \idx{minimal} value common to all the items.

%%%%%%%%%%
\section{Step 3 : the model or method choice}

The third step of the program is the \idx{model} choice. 
Depending on the data type, some models are unavailables.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{step3-en.png}}
\caption{Model choice.}
\end{center}
\end{figure}

\subsection{The one parameter logistic model}
The \idx{one parameter logistic model} is available only if the data
type is \idx{binary}. In this model each item has only one parameter,
the \idx{threshold} (or \idx{difficulty}).  The \idx{slope} parameter
(or \idx{discrimination}) is fixed to a constant for all the items.

\subsection{The two parameters logistic model}
The \idx{two parameters logistic model} is available only if the data
type is \idx{binary}. In this model each item has two parameters, the
\idx{threshold} and the \idx{slope}.

\subsection{The three parameters logistic model}
The \idx{three parameters logistic model} is available only if the data
type is \idx{binary}. In this model each item has three parameters, the
\idx{threshold}, the \idx{slope} and the \idx{asymptote} (or \idx{guessing}).
This model is harder to fit and gives greater estimation errors.

\subsection{The nominal response model}
The \idx{nominal response model} is available if the data type is
\idx{multiple choice} or \idx{graded}. Each option of each item has
two parameters, the \idx{threshold} and the \idx{slope}.  Unlike the
\idx{graded response model}, no order is forced on the options.  If
the data type is \idx{graded}, then the value of the options is used
only for the initialisation and to compute the item characteristic
curves.

\subsection{The graded response model}
The \idx{graded response model} isa vailable only if the data type is
\idx{graded}. Each option of each item has one parameter, the
\idx{threshold}, and a common parameter to the item, the \idx{slope}.
The order of the options is forced.

\subsection{The kernel estimator}
The \idx{kernel estimator} is available for all data types.  With this
estimator, no model is imposed to the data and the curves are obtained by
smoothing with the Nadaraya-Watson estimator.  This method is also
used in the {\em Testgraf} program by J.O. Ramsay.

\subsection{The penalized maximum marginal likelihood estimator}
The \idx{penalized maximum marginal likelihood estimator}
is available for all data types. This method is a tradeoff between
the logistics models and the data.

%%%%%%%%%%
\section{Step 4 : the report options}

The fourth and last step of the program is the choice of the elements
to include in the report. Some elements such as \idx{all the data
  points from the plots}, the \idx{ability estimates} or the \idx{test
  of local independance} can take a lot of pages in the report, it is
recommended to activate them only if necessary.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{step4-en.png}}
\caption{The report  options.}
\end{center}
\end{figure}

After this step, the estimation process begin. While the estimation is
running, {\em Excel} will not be usable. The time of the estimation
depends on the number of subject and item, the model and the computer
speed. For a few thousands subject and ten items, the estimation
should not take more than ten seconds for binaries items and two or
three minutes for five options items on a recent computer.

\subsection{The classical test theory statistics}
Check this box to have the \idx{classical test theory statistics},
such as the \idx{item means} (or \idx{difficulties}),
the \idx{item correlation} (or \idx{discriminations}),
and \idx{Cronbach's alpha}.

\subsection{The test of fit}
Check this box to have the \idx{test of fit} global and for each item
by likelihood ratio.

\subsection{The test of local independance}
Check this box to have the \idx{test of local independance}
of each item pairs by likelihood ratio.

\subsection{The item parameters}
Check this box to have the \idx{item parameters}.
This element is not available for the non-parametric methods.

\subsection{The ability estimates}
Check this box to have the \idx{ability estimates} of each subject.

\subsection{The item and option characteristic curves}
Check this box to have the plot of each \idx{item and option
  characteristic curves}.

\subsection{The information functions}
Chech this box to have the \idx{information functions} plots.

\subsection{The standard errors}
Check this box to have the \idx{standard errors} of all the estimates.

\subsection{All the data points from the plots}
Check this box to have all the data necessary to create the given
plots.

\section{The report}

Once the estimation process is finish, a new worksheet is created in
the current {\em Excel} file. This sheet is named \idx{eirt} follow by
a number and contains the report.  Before quiting {\em Excel}, you
have to \idx{save} the file if you want to keep the report.  If you
make more than one report and want to delete some of them, you have to
select them, navigate in the \idx{edit} menu and choose the
\idx{delete a sheet} option.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{report-en.png}}
\caption{Report example.}
\end{center}
\end{figure}

\subsection{The classical test theory statistics}
\begin{itemize}
\item The \idx{number of subject}.
\item The \idx{number of item}.
\item The \idx{number of missing value}.
\item The \idx{score mean}.
\item The \idx{score standard deviation}.
\item The \idx{Cronbach's alpha}.
\item The \idx{mean (difficulty)} of each item.
\item The \idx{standard deviation} of each item.
\item The \idx{correlation (discrimination)} of each item.
\end{itemize}

\subsection{The estimation summary}
\begin{itemize}
\item The \idx{data source}.
\item The \idx{estimation methode}.
\item The \idx{model} if applicable.
\item The \idx{smoothing parameter} if applicable.
\item The number of item \idx{ignored} by the estimation.
\item The number of item that didn't \idx{converged}.
\end{itemize}

\subsection{The test of fit}
\begin{itemize}
\item The \idx{Chi-square} statistics, global and for each item.
\item The number of \idx{degree of freedom}, global and for each item.
\item The \idx{p-value}, global and for each item. The row is in red
  if this value is less than 0.05.
\end{itemize}

\subsection{The test of local independance}
\begin{itemize}
\item The \idx{Chi-square} statistics for each item pair.
\item The number of \idx{degree of freedom} for each item pair.
\item The \idx{p-value} for each item pair. The row is in red
  if this value is less than 0.05.
\end{itemize}

\subsection{The item parameter}
\begin{itemize}
\item The \idx{slope} (a) of each item and option if applicable.
\item The \idx{threshold} (b) of each item and option if applicable.
\item The \idx{asymptote} (c) of each item and option if applicable.
\item The \idx{standard error} (\idx{s.e.}) of each parameter if selected in step 4.
\end{itemize}

\subsection{The ability estimates}
\begin{itemize}
\item The \idx{ability} of each subject.
\item The \idx{standard error} (\idx{s.e.}) of each ability if selected in step 4.
\end{itemize}

\subsection{The item and option characteristic curves}
\begin{itemize}
\item A plot of the item characteristic curve \idx{ICC} of each item.
\item A plot of the option characteristic curve \idx{OCC} of each
  option if applicable.
\end{itemize}

\subsection{The information functions}
\begin{itemize}
\item A plot of all the \idx{information functions}.
\end{itemize}

\subsection{All the data points from the plots}
\begin{itemize}
\item The data points used for the \idx{ICC} plots if applicable.
\item The data points used for the \idx{OCC} plots if applicable.
\item The data points used for the \idx{information functions} plots if applicable.
\end{itemize}

\subsection{The pages header and footer}
If the report is printed, the header and footer contains
the program version, the data file name, the date and time and the
page number.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Settings} \label{Config}

Before you can change the \idx{settings} of {\em eirt}, you have to
start {\em Excel}. Then you navigate into the \idx{tools} menu, go to
the \idx{eirt} sub-menu and choose the \idx{settings} option.  If you
are satisfied with your changes, click on the \idx{ok} button and you
changes are applied and saved.

\section{The language}
Under this tab you can change the \idx{display language} of the program.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{lang-en.png}}
\caption{Language settings.}
\end{center}
\end{figure}

\section{The priors}
Under this tab you can change the \idx{prior distributions}.
These parameters are applicable only for the binary logistic model.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{priors-en.png}}
\caption{Priors settings.}
\end{center}
\end{figure}

\subsection{The slope prior}
Check this box to use a log-normal distribution on the slope
parameter. This option is recommended to correct
the Heywood cases. If this option is activated, you can also change
the \idx{slope mean} and \idx{slope standard deviation}.

\subsection{The threshold prior}
Check this box to use a normal distribution on the threshold
parameter. If this option is activated, you can also change
the \idx{threshold mean} and \idx{threshold standard deviation}.

\subsection{The asymptote prior}
Check this box to use a beta distribution on the asymptote
parameter. If this option is activated, you can also change
the \idx{asymptote mean} and \idx{asymptote weight}.

\section{The algorithm}
Under this tab you can change some parameters of the \idx{algorithms}
used.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{algo-en.png}}
\caption{Algorithm settings.}
\end{center}
\end{figure}

\subsection{The number of EM iteration}
This option controls the \idx{number of iteration} done by the EM
(Expectation-Maximisation) algorithm of the maximum marginal
likelihood estimators.

\subsection{The number of Newton iteration}
This option controls the maximal \idx{number of iteration} done
by the Newton algorithm (root finding) of the the maximum marginal
likelihood estimators.

\subsection{The precision}
This option controls the \idx{precision} seeked by the Newton
algorithm (root finding) of the the maximum marginal likelihood
estimators.

\subsection{The kernel smoothing factor}
This option controls the \idx{bandwidth} used by the kernel estimator.
This factor is multiplied to the number of subject to the -1/5 power.
A greater bandwith give smoother and less steep curves.

\subsection{The penalization smoothing factor}
This option controls the quantity of \idx{penalization} used by the 
penalized maximum marginal likelihood estimator.
This factor is multiplied to the number of subject to the 1/5 power.
More penalization give curves more like the logistic model.

\subsection{The data aggregation}
If this box is checked, the data are \idx{aggregated} before the
estimation.  The estimation time is reduced and this dosen't changes
the results.  This option is recommended if the number of subject is
greater than the number of item.

\section{The quadratures}
Under this tab you can change the \idx{quadratures} used.

\begin{figure}[htb]
\begin{center}
\shadowbox{\includegraphics[scale=0.5]{quad-en.png}}
\caption{Quadratures settings.}
\end{center}
\end{figure}

\subsection{The number of quadrature}
This option controls the \idx{number of quadrature} used to integrate
the latent variable (the ability). This number has to be
a power of 2 (16, 32, 64, 128, ...).

\subsection{The first middle point}
This option controls the \idx{first middle point} of the quadratures.

\subsection{The last middle point}
This option controls the \idx{last middle point} of the quadratures.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Copyright}

The {\em eirt} program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, see : \url{http://www.gnu.org/licenses/}.

\printindex

\end{document}
