        **************************************************
        *                                                *
        *  Changes and Developments in the catR Package  *
        *                                                *
        **************************************************


------------------------------------
- Changes in catR 3.0 (2014-04-25) -
------------------------------------

MAJOR UPDATES

  o  Functions 'startItems', 'nextItem' and 'randomCAT' have 
     been updated thanks to Juan Ramon Barrada (Universidad 
     Zaragoza, Spain), which is now listed as co-author of the
     package.

  o  Function 'nextItem' was also updated thanks to Guido 
     Corradi (Universidad Zaragoza, Spain).

  o  'catR' now supports the Graded Response Model (GRM; 
     Samejima, 1969), the Modified Graded Response Model 
     (MGRM; Muraki, 1990), the Partical Credit Model (PCM; 
     Masters, 1982), the Generalized Partial Credit Model 
     (GPCM; Muraki, 1992), the Rating Scale Model (RSM; 
     Andrich, 1978) and the Nominal Response Model (NRM; Bock, 
     1972).  

  o  Functions 'Pi', 'Ii', 'OIi', 'thetaEst', 'semTheta', 
     'eapEst', 'eapSem', 'startItems', 'EPV', 'MEI', 'MWI',
     'nextItem' and 'randomCAT'allow now the use of polytomous 
     IRT models.

  o  The function 'createItemBank' has been withdrawn from
     this version. The item bank must now be provided
     directly as the matrix of item parameters (plus the group
     membership for content balancing, optionally).

  o  Five new item selection rules have been added: Kullback-
     Leibler (KL), posterior Kullback-Leibler (KLP), the so-
     called thOpt (optimal theta) method, progressive method 
     and proportional method. They are available for both 
     dichotomous and polytomous IRT models (except thOpt).

  o  The 'KL' function was created to support the computation 
     of Kullback-Leibler information for next item selection.

  o  Several CATs can be run in one step by using the new
     'simulateRespondents' function. In addition, summary
     statistics related to all generated tests are provided
     by this function. Corresponding plots can also be drawn
     and saved in a similar way as with 'randomCAT'.

  o  The dependency to the 'sfsmisc' package was withdrawn. To
     do so, an internal function for numerical integration, 
     called 'integrate.catR', was written and works similarly 
     to the 'integrate.xy' function from package 'sfsmisc' 
     (which was considered so far). In other words, the   
     function 'integrate.xy' was replaced by 'integrate.catR' 
     in 'eapEst', 'eapSem' and 'MWI'.

  o  The functions 'genDichoMatrix' and 'genPolyMatrix' were 
     created to partly compensate the withdrawal of 
     'createItemBank'. Those functions allow for easy 
     generation of item banks under either the dichotomous IRT 
     models (1PL, 2PL, 3PL and 4PL) or the polytomous IRT 
     models that are supported by 'catR' (GRM, MGRM, PCM, 
     GPCM, RSM and NRM). The output format is identical to the 
     one required in order to run CATs with dichotomous and 
     polytomous item banks. Random allocation of items into 
     subgroups (for content balancing purposes) is also 
     possible.

  o  The function 'breakBank' was created to separate the 
     item banks in two parts, the matrix of item parameters 
     and the vector of group membership for items. This
     function works with both dichotomous and polytomous
     IRT banks. Its creation resulted from the withdrawal of
     the 'createItemBank' function. 

  o  The function 'Ji' was created to compute the J function 
     (related to WL estimation) under dichotomous and 
     polytomous models. This function was previously embedded 
     into 'thetaEst' for dichotomous models, but is now 
     written independently for both dichotomous and 
     polytomous models. 

  o  The function 'test.cbList' has been updated. The second
     argument does not need to be the full item bank anymore
     but just a vector of group membership (such as the
     fifth column of the 'tcals' data set only). This is to
     remove the connection with the 'createItemBank' function
     (that has been withdrawn from this update) and to
     allow its use with polytomous models.

  o  The functions 'EPV', 'MEI', 'MWI', 'startItems' and
     'nextItem' have been updated. The argument 'itemBank' 
     argument does not need to be the full item bank anymore
     but just a matrix with four columns with item parameters 
     (such as the first four columns of the 'tcals' data set 
     only). This is to remove the connection with the 
     'createItemBank' function (that has been withdrawn from
     this update).

  o  The default value of the 'startSelect' argument of the
     'startItems' function has been changed from "bOpt" to
     "MFI" for compatibility with the 'startItems.poly'
     function.

  o  The function 'genPattern' was created to generate 
     responses patterns under dichotomous and polytomous IRT 
     models. This is helpful mostly for examples but can also
     be considered internally in 'randomCAT'.

  o  The function 'startItems' can now select only a fraction
     of the item bank to select the first items. This is 
     controled by the new 'nAvailable' argument, holding 0's
     and 1's for items that are respectively not available and
     available. By default, all items are available.

  o  The random seed for the selection of the first item(s) in 
     'startItems' can be set to NA in order to remove random 
     seed selection of these items. 

  o  The 'nrItems' argument of 'startItems' can now be set to 
     0 to avoid early selection of starting items. Only NULL 
     values are then returned.

  o  The function 'randomCAT' can now return also ability 
     level estimates and standard errors for the first 
     starting items. This is done by fixing the argument 
     'allTheta' to TRUE (default value is FALSE). If so, 
     provisional ability estimates and standard errors are 
     displayed within parentheses in the output of 'randomCAT' 
     (i.e. when using 'print.cat()' function).

 
MINOR UPDATES

  o  Currently the formula for the SE of the WL method in the
     'semTheta' function is the same as that for the ML method,
     as it happened that the formula (in versions of catR prior
     to 3.0) was sometiems leading to mathematical problems.
     This formula will be updated once it will be accurately
     corrected.

  o  The 'startItems' function was slightly modified. When        
     items are randomly selected, the random sampling of 
     these items was rewritten using the 'sample' function.

 o   In 'nextItem function, the Urry's procedure to select 
     the next item was renamed as 'bOpt' method (instead of 
     'Urry'), for homogenbeity with the similar argument of
     the 'startItems' function. 

  o  The help file of the 'MEI' function was updated as an
     error was present in the description of both the 
     observed and the expected item information function.         
     Their implementation, however, was correctly written.

  o  When the first items are selected randomly or fixed by
     the user, the 'startSelect' element of the output list
     returns now NA instead of the by-default value of the
     argument 'startSelect'.

  o  To save the output of 'randomCAT', the 'output' argument
     contains now three components, the file path, the file 
     name, and the type of file (in this order). By default,
     the output is stored in working directory, as a csv file
     with name 'name.csv'. Other type is text file.

  o  The order of the components of 'save.options' argument of
     'plot.cat' has been modified to match those of the 
     'output' argument of 'randomCAT'..

  o  Some typos were fixed.

  o  Author's affiliation was updated.



------------------------------------
- Changes in catR 2.6 (2013-12-03) -
------------------------------------

MINOR UPDATE

  o  An error was debugged in the 'nextItem' function. 
     With 'MLWI', 'MPWI', 'MEI' and 'MEPV' the set of 
     parameters of previously administered items was not 
     correctly passed to the corresponding functions in 
     case of content balancing (that is, vector 'OUT' was
     used instead of vector 'out'). This was leading to 
     warning messages and incorrectly computed values of
     the criteria. Many thanks to Irshad Mujawar (Arcadix 
     Infotech Private Limited, Bangalore, India) who 
     noticed this problem.



------------------------------------
- Changes in catR 2.5 (2013-02-07) -
------------------------------------

MINOR UPDATES

  o  An error was debugged in the 'MWI' function. The 
     selection of the information function values to
     compute the MLWI or MPWI was wrong, so that the same
     item was always selected, independently of the current
     response pattern (for the same set of administered
     items). Many thanks to Koken Ozaki (Institute of
     Statistical Mathematics, Tokyo, Japan) who noticed
     this problem.

  o  Some typos were fixed.



------------------------------------
- Changes in catR 2.4 (2013-01-17) -
------------------------------------

MINOR UPDATES

  o  An error was debugged in the 'createItemBank' function.
     When creating difficulty parameters with the 'unif' 
     distribution, the selection of specified parameters was
     leading to an error. Many thanks to Przemek Lis and 
     Michel Kosinski (Cambridge University, UK) who noticed
     this problem.

  o  Some typos were fixed.



------------------------------------
- Changes in catR 2.3 (2012-05-09) -
------------------------------------

MINOR UPDATES

  o  The references of several help files have been updated
     with respect to the formal publication of the related
     JSS paper about catR.

  o  The CITATION file has been updated accordingly.



------------------------------------
- Changes in catR 2.2 (2012-03-15) -
------------------------------------

MINOR UPDATES

  o  The references of several help files have been updated.

  o  A basic NAMESPACE file has been added for compatibility
     with R versions 2.14.0 and later.


------------------------------------
- Changes in catR 2.1 (2011-12-05) -
------------------------------------

MINOR UPDATES

  o  It is now possible to save the output of 'randomCAT' into
     a text file, by specifying the new arguments 'save.output'
     and 'output' properly. Similarly, the plots obtained with
     the 'plot.cat' function can be saved as PDF or JPEG files
     by specifying properly the new arguments 'save.plot' and 
     'save.options'. See the corresponding help files for 
     further details.

  o  Some typos have been fixed in the help files.


------------------------------------
- Changes in catR 2.0 (2011-10-21) -
------------------------------------

MAJOR UPDATES

  o  Several distributions are now available for item
     parameter generation of the 'createItemBank' function.
     Possible distributions are: normal and uniform for item
     difficulties; normal, lognormal and uniform
     distributions for item discriminations; uniform and 
     Beta for both item lower and upper asymptotes.

  o  Item exposure control is now feasible with the so-called
     'randomesque' approach (Kingsbury and Zara, 1989). The 
     function 'nextItem' and 'randomCAT' hold now the
     'randomesque' argument that sets the number of optimal
     items to be selected first, among those the next
     administered item will be randomly chosen.

  o  Content balancing can now be controlled by specifying
     subgroups of items in the 'createItemBank' function. The
     subgroups are coded into a fifth column (after item 
     parameters) and they are stored in the item bank by
     setting the new argument 'cb' (for "content balancing")
     to TRUE. If this fifth column is missing, or if 'cb' is
     set to FALSE (default), nothing changes from the previous
     version of catR. See also functions 'nextItem' and 
     'randomCAT', which were modified for content balancing,
     as well as the new function 'test.cbList' for testing
     the format of the 'cbControl' list of 'nextItem'.

  o  Item parameters can now be provided as data frames in 
     the 'createItemBank' function. This also permits to 
     include subgroups of items easily.

  o  As a consequence of the previous major update, many help
     files were updated for comptability with the new function
     'createItemBank' (i.e. 'tcals' is no longer needed to be
     converted into a matrix).

  o  The 'tcals' data set was updated by adding a fifth
     column, holding the subgroups of items as defined by the
     test. See the help file of 'tcals' for further details.

  o  As a consequence of the previous major update, many help
     files were updated for compatibility of the new 'tcals'
     data set (i.e. all examples requiring the matrix of
     item parameters were slightly modified to remove the
     'Group' variable).

  o  The 'print.cat' function was updated to display output
     results of randomesque method for item expoisure control
     as well as for content balancing (whenever required).


MINOR UPDATES

  o  When the 'maxItems' criterion of 'randomCAT' is smaller
     than the 'stop$thr' argument, an error message is 
     returned. Previously it contained a mistake, claiming
     that 'maxItems' is larger than 'stop$thr'. This has 
     been fixed.

  o  Some typos have been fixed in the help file of 'tcals'
     data set and 'nextItem' functin.


------------------------------------
- Changes in catR 1.6 (2011-04-11) -
------------------------------------

MINOR UPDATES

  o  The 'Pi' functin has been slightly modified to avoid
     a technical bug: when probabilities Pi equal exactly
     zero or one, the ability estimates cannot be obtained
     with 'thetaEst' (the boundary conditions cannot be
     tested because of NaN values). Many thanks to Pan Tong
     (University of Texas MD Anderson Cancer Center, USA)
     who noticed this problem.


------------------------------------
- Changes in catR 1.5 (2010-10-28) -
------------------------------------

MINOR UPDATES

  o  The help files of the 'thetaEst' and 'semTheta' methods
     have been updated as some information about the EAP
     estimation method was missing.


------------------------------------
- Changes in catR 1.4 (2010-10-17) -
------------------------------------

MINOR UPDATES

  o  The method referred to Owen's rule for selecting items
     in the starting step and in the adaptative process, was
     renamed Urry's rule given that this simple method was
     suggested first by Urry (1970) and that Owen's Bayes
     procedure differs from this one. 
    
  o  Consequently to the point above, 'Owen' optional value
     of the 'itemSelect' argument of the 'test' list was 
     replaced by 'Urry'. 

  o  In addition, the 'nextItem', 'testList', randomCAT' and
     'print.cat' have been updated by the replacement of
     'Owen' by 'Urry'. 
 
  o  A minor problem was fixed in the code of the 'randomCAT' 
     function: the output list was not returning all the
     required elements (in particular, the value of the
     'itemSelect' argument).

  o  A minor issue was fixed in the 'print.cat' function: the
     output was not displayed correctly when only two items
     are selected at the initial step.


------------------------------------
- Changes in catR 1.3 (2010-10-08) -
------------------------------------

MINOR UPDATES

  o  Several typos have been fixed.

  o  The 'randomCAT' help file has been updated as some
     information was incorrect or incomplete.


------------------------------------
- Changes in catR 1.2 (2010-09-07) -
------------------------------------

MAJOR UPDATES

  o  Several procedures for next item selection have been
     added. First, Maximum Likelihood Weighted Information
     (MLWI) and Maximum Posterior Weighted Information (MPWI)
     are now available. The command 'MWI' has been developed
     for that purpose.

  o  Second, Maximum Expected Information (MEI) has been
     implemented for next item selection. The function 'MEI'
     was developed for computing MEI values.

  o  The MEI criterion required the creation of the 'OIi'
     command for computing observed information function. 

  o  The Maximum Expected Posterior Variance (MEPV) is also
     available. The command 'EPV' computes expected posterior
     variances and is used within the 'nextItem' function.

  o  Finally, the completely random selection of the next 
     item is also possible right now.

  o  The functions 'eapEst' and 'eapSem' have been modified
     to speed up their computation. The approximation of the
     integrals is now made by the 'integrate.xy' function 
     from the package 'sfsmisc'.

  o  The function 'startItems' has been modified. First, the
     argument 'bw' has been replaced by 'halfRange' and codes
     now for the half range of the sequence and not the full
     range (this was misleading). Second, the items can be
     selected either according to their difficulty level or
     their information function. This is specified by the
     'startSelect' argument.

  o  Consequently, the functions 'nextItem', 'testList', 
     'randomCAT' and 'print.cat' have been updated.


MINOR UPDATES

  o  The argument 'eapPar' from functions 'eapEst' and 'eapSem'
     has been renamed to 'parInt' for consistency with the 
     'MWI' and 'nextItem' functions. It better refers to the
     parameters for numerical integration and not only for the
     EAP method, but also for MLWI and MPWI computation. 

  o  Several typos have been fixed in the help manual.

  o  The 'plot.cat' function has been modified. Now, the 
     confidence intervals do not appear by default ('ci=FALSE'
     in the code). Moreover, confidence intervals are displayed
     with dotted traits, while the true ability level is drawn
     with a solid horizontal line. Also, any classification
     level can be specified and drawn by a dashed horizontal
     trait.


------------------------------------
- Changes in catR 1.1 (2010-06-15) -
------------------------------------

MAJOR UPDATES

  o  Owen's procedure has been added as a method for next item
     selection. 

  o  Consequently, the functions 'nextItem', 'testList', 
     'randomCAT' and 'print.cat' have been updated.


MINOR UPDATES

  o  Several typos have been fixed in the help manual.
