JointMaximumLikelihoodEstimation

java.lang.Object
- com.itemanalysis.psychometrics.irt.estimation.JointMaximumLikelihoodEstimation

```
public class JointMaximumLikelihoodEstimation
extends java.lang.Object
```
Joint maximum likelihood estimation (JMLE) of the Rasch, partial credit, and rating scale models. Methods conduct item and person parameter estimation, computation of standard errors, and linear transformations of parameters. Fixed common item calibration is also possible. JMLE is an iterative procedure. At each iteration, item and person parameters estimates are updated using a proportional curve fitting algorithm instead of the Newton-Raphson method. For details on the estimation algorithm see:
Meyer, J. P., & Hailey, E. (2012). A study of Rasch partial credit, and rating scale model
parameter recovery in WINSTEPS and jMetrik. Journal of Applied Measurement,
13(3), 248-258.
In additional to parameter estimates, this class also provides a way to obtain item and person fit statistics and scale quality statistics.

Constructor Summary

Constructors
Constructor and Description
`JointMaximumLikelihoodEstimation(byte[][] data, ItemResponseModel[] irm)` The object is created with a set of data and array of item response models (See `ItemResponseModel`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`biasCorrection()` Correct item difficulty and person ability estimates for bias.
`void`	`computeItemCategoryFitStatistics()` After estimation, INFIT and OUTFIT mean square fit statistics for category thresholds can be computed.
`void`	`computeItemFitStatistics()` After parameters have been estimated, fit statistics can be computed.
`void`	`computeItemStandardErrors()` Item difficulty standard error calculation.
`void`	`computePersonStandardErrors()` Person ability parameter standard error calculation.
`boolean`	`estimateParameters(int globalMaxIter, double globalConv)` A shortcut method that only requires input for the maximum number of global iterations and the global convergence criterion.
`boolean`	`estimateParameters(int globalMaxIter, double globalConv, boolean centerItems)` A shortcut method that only requires input for the maximum number of global iterations and the global convergence criterion.
`boolean`	`estimateParameters(int globalMaxIter, double globalConv, int personMaxIter, double personConv, boolean centerItems)` This method is where the estimation is managed.
`int`	`getDroppedStatusAt(int index)` A polytomous item with at least one category with 0 observations is dropped from the analysis.
`int`	`getExtremeItemAt(int index)` Extreme items are items in whih all examinees obtain the maximum possitble item score or the minimum possible item score.
`int`	`getExtremePersonAt(int index)` An extreme person is an examinee that obtains the minimum or maximum possible test score.
`RaschFitStatistics`	`getItemFitStatisticsAt(int index)` Fit statistics for each item are stored in an array.
`ItemResponseModel`	`getItemResponseModelAt(int index)` An `ItemResponseModel` object is stored in an array for each item.
`ItemResponseModel[]`	`getItems()` Item response model objects are stored in an array.
`RaschScaleQualityStatistics`	`getItemSideScaleQuality()` After estimation, overall indices of scale quality can be computed such as reliability and separation.
`double`	`getLogLikelihood()` Compute log-likelihood given the current values of item and person parameters.
`int`	`getMaxCategory()` Each item can have a different number of score categories.
`int`	`getNumberOfItems()` The total number of items on the test is stored.
`int`	`getNumberOfPeople()` The total number of examinees is stored.
`double`	`getPersonEstimateAt(int index)` Person ability estimates are stored in an array.
`double[]`	`getPersonEstimates()` Person ability estimates are stored in an array of doubles.
`double`	`getPersonEstimateStdErrorAt(int index)` Person estimate standard errors are stored in an array of doubles.
`RaschFitStatistics`	`getPersonFitStatisticsAt(int index)` Computes person fit statistics for the examinee at the specified index.
`double[]`	`getPersons()` Person ability estimates are stored as an array of doubles.
`RaschScaleQualityStatistics`	`getPersonSideScaleQuality()` After estimation, overall indices of scale quality can be computed such as reliability and separation.
`double[]`	`getPersonStdError()` Standard errors of person ability estimates are stored as an array of doubles.
`ExploratoryFactorAnalysis`	`getPrincipalComponentsForStandardizedResiduals(int nFactors)` Conducts a principal components analysis of standardized residuals.
`RaschRatingScaleGroup`	`getRatingScaleGroupAt(int index)` Polytomous response models be long to a single `RaschRatingScaleGroup`.
`double`	`getResidualAt(int i, int j)` A residual is the difference between the observed and expected item response.
`byte`	`getResponseAt(int i, int j)`
`java.lang.Object[][]`	`getScoreconversionTableForOutputter()`
`double`	`getSumScoreAt(int index)`
`double`	`getValidSumScoreAt(int index)` The valid sum score is the sum score based on the nonextreme items.
`void`	`itemProx()` Computes PROX difficulty estimates for item difficulty.
`void`	`linearTransformation(double intercept, double scale)` Apply linear transformation to person and item parameter estimates.
`int`	`numberOfNonexremeItems()` An extreme iem is one in which all examinees with obtain the lowest possible item score or one in which all examinee obtain the highest possible item score.
`int`	`numberOfNonextremePeople()` An extreme person is one that obtains the minimum possible test score or the maximum possible test score.
`java.lang.String`	`printBasicItemStats()`
`java.lang.String`	`printBasicItemStats(java.lang.String title)` This method is for displaying item parameter estimates, standard errors, and other information.
`java.lang.String`	`printCategoryStats()` Polytomous items have a set of threshold statistics that must be reported.
`java.lang.String`	`printFrequencyTables()` This method is for displaying frequency tables for each item.
`java.lang.String`	`printItemStats(java.lang.String title)` Creates a string of item statistics.
`java.lang.String`	`printIterationHistory()` Joint maximum likelihood estimation is iterative.
`java.lang.String`	`printPersonStats()` This method is for displaying person parameter estimates, standard errors, and other information.
`java.lang.String`	`printRatingScaleTables()` This method is for displaying frequency tables for polytomous items.
`java.lang.String`	`printScoreTable(int maxIter, double converge, double adjustment, DefaultLinearTransformation transformation, int precision)` The sum score is a sufficient statistic for the latent trait in the Rasch family of models.
`void`	`summarizeData(double adjustment)` Summarizes data into frequency counts.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - JointMaximumLikelihoodEstimation
```
public JointMaximumLikelihoodEstimation(byte[][] data,
                                        ItemResponseModel[] irm)
                                 throws org.apache.commons.math3.exception.DimensionMismatchException
```
    The object is created with a set of data and array of item response models (See ItemResponseModel. The data must be arranged such that each row respresents an examinee and each column represents an item. All item responses must be zero or larger (i.e. nonnegative). Use an item response value of -1 to indicate a missing item response. The length of the item response model array must equal the number of columns in the data array.
    
    Parameters:
    
    data - a two-way array of item responses.
    
    irm - an array of item response model.
    
    Throws:
    
    org.apache.commons.math3.exception.DimensionMismatchException
- Method Detail
  - summarizeData
```
public void summarizeData(double adjustment)
                   throws org.apache.commons.math3.exception.NoDataException
```
    Summarizes data into frequency counts. It keeps track of extreme persons (i.e. examinees that earn the minimum or maximum possible test score) and extreme items (i.e. items answered correctly by everyone or no one). Extreme items and persons are flagged. Frequency counts represent the valid counts (i.e. frequencies for non-extreme persons and items). This method is recursive. It continues as long as new extreme items or persons are detected. Otherwise, it stops.
    
    Parameters:
    
    adjustment - and adjustmnet factor applied to the ItemResponseSummary. This adjustment is needed for estimation of extreme persons and items.
    
    Throws:
    
    org.apache.commons.math3.exception.NoDataException
  - estimateParameters
```
public boolean estimateParameters(int globalMaxIter,
                                  double globalConv)
```
    A shortcut method that only requires input for the maximum number of global iterations and the global convergence criterion.
    
    Parameters:
    
    globalMaxIter - maximum number of iteration in JMLE
    
    globalConv - maximum change in logits convergen criterion
    
    Returns:
  - estimateParameters
```
public boolean estimateParameters(int globalMaxIter,
                                  double globalConv,
                                  boolean centerItems)
```
    A shortcut method that only requires input for the maximum number of global iterations and the global convergence criterion.
    
    Parameters:
    
    globalMaxIter - maximum number of iteration in JMLE
    
    globalConv - maximum change in logits convergen criterion
    
    centerItems - establish identification by centering item about the item difficulty mean (the approach typically used in Rasch measurement). If false establish identification by centering persons around the mean ability. Centering only done for nonextreme persons and items.
    
    Returns:
  - estimateParameters
```
public boolean estimateParameters(int globalMaxIter,
                                  double globalConv,
                                  int personMaxIter,
                                  double personConv,
                                  boolean centerItems)
```
    This method is where the estimation is managed. It corresponds to the global iterations in the Joint Maximum Likelihood Estimation paradigm. First items and thresholds are updated, then persons are updated. These cycles continue until the number of iterations reaches the global maximum or the convergence criterion is reached.
    
    Parameters:
    
    globalMaxIter - maximum number of iteration in JMLE
    
    globalConv - maximum change in logits convergen criterion
    
    personMaxIter - maximum number of iterations during the person update. Usually a maximum of one person update is sufficient.
    
    personConv - convergence criterion during the person update only.
    
    centerItems - establish identification by centering item about the item difficulty mean (the approach typically used in Rasch measurement). If false establish identification by centering persons around the mean ability. Centering only done for nonextreme persons and items.
    
    Returns:
    
    true if estimation is possible. False if data are not suited for estimation.
  - itemProx
```
public void itemProx()
```
    Computes PROX difficulty estimates for item difficulty. These are used as starting values in JMLE.
  - getLogLikelihood
```
public double getLogLikelihood()
```
    Compute log-likelihood given the current values of item and person parameters.
    
    Returns:
    
    log-likelihood
  - getItems
```
public ItemResponseModel[] getItems()
```
    Item response model objects are stored in an array. Gets the array of item response models.
    
    Returns:
    
    an array of item response models.
  - getPersons
```
public double[] getPersons()
```
    Person ability estimates are stored as an array of doubles. Get the array of person estimates.
    
    Returns:
    
    an array of person estimates.
  - getPersonStdError
```
public double[] getPersonStdError()
```
    Standard errors of person ability estimates are stored as an array of doubles. Gets the array of standard errors. Will return null if computePersonStandardErrors() has not been called.
    
    Returns:
  - computeItemStandardErrors
```
public void computeItemStandardErrors()
```
    Item difficulty standard error calculation. Standard errors for threshold parameters are also computed for polytomous items.
  - computePersonStandardErrors
```
public void computePersonStandardErrors()
```
    Person ability parameter standard error calculation. Must be called before getPersonStdError().
  - numberOfNonexremeItems
```
public int numberOfNonexremeItems()
```
    An extreme iem is one in which all examinees with obtain the lowest possible item score or one in which all examinee obtain the highest possible item score. Gets the count of extreme items.
    
    Returns:
    
    count of extreme items.
  - numberOfNonextremePeople
```
public int numberOfNonextremePeople()
```
    An extreme person is one that obtains the minimum possible test score or the maximum possible test score. Gets the count of extreme persons.
    
    Returns:
    
    count of extreme persons.
  - biasCorrection
```
public void biasCorrection()
```
    Correct item difficulty and person ability estimates for bias. This is like using the STBIAS=Y option in WINSTEPS.
  - printFrequencyTables
```
public java.lang.String printFrequencyTables()
```
    This method is for displaying frequency tables for each item. It is mainly used for binary items and the frequencies involved in calculation of item difficulty.
    
    Returns:
  - printRatingScaleTables
```
public java.lang.String printRatingScaleTables()
```
    This method is for displaying frequency tables for polytomous items. It will show combined frequencies for items in the same rating scale group. These frequencies are mainly used for estimation of threshold parameters.
    
    Returns:
  - getPersonEstimates
```
public double[] getPersonEstimates()
```
    Person ability estimates are stored in an array of doubles. Gets the entire arrya of person ability estimates.
    
    Returns:
    
    person ability estimates.
  - linearTransformation
```
public void linearTransformation(double intercept,
                                 double scale)
```
    Apply linear transformation to person and item parameter estimates. The transformation is Xnew = X(scale) + intercept.
    
    Parameters:
    
    intercept - intercept transformation coefficient.
    
    scale - scale transformation coefficient.
  - computeItemFitStatistics
```
public void computeItemFitStatistics()
```
    After parameters have been estimated, fit statistics can be computed. Fit statistics include INFIT and OUTFIT mean squared error statistic and their standardized versions. See RaschFitStatistics. This method computes fit statistics for all items.
  - getPrincipalComponentsForStandardizedResiduals
```
public ExploratoryFactorAnalysis getPrincipalComponentsForStandardizedResiduals(int nFactors)
```
    Conducts a principal components analysis of standardized residuals. Extreme items and dropped items are excluded from the correlaiton matrix. Extreme persons are not included in the computation of the correlation. Missing data are scored as zero points in computation of the correlation. These conventions are consistent with WINSTEPS.
    
    Parameters:
    
    nFactors - number of factors retained in the principal components analysis.
    
    Returns:
    
    an ExploratoryFactorAnalysis object.
  - getPersonFitStatisticsAt
```
public RaschFitStatistics getPersonFitStatisticsAt(int index)
```
    Computes person fit statistics for the examinee at the specified index. This method computes person fit statistic for a single examinee.
    
    Parameters:
    
    index - array position of examinee for which the fit statistic is computed.
    
    Returns:
  - computeItemCategoryFitStatistics
```
public void computeItemCategoryFitStatistics()
```
    After estimation, INFIT and OUTFIT mean square fit statistics for category thresholds can be computed. This method computes category fit statistics for all items and categories.
  - getItemSideScaleQuality
```
public RaschScaleQualityStatistics getItemSideScaleQuality()
```
    After estimation, overall indices of scale quality can be computed such as reliability and separation. This method returns the scale quality statistics for the entire set of items.
    
    Returns:
    
    scale quality statistics for items.
  - getPersonSideScaleQuality
```
public RaschScaleQualityStatistics getPersonSideScaleQuality()
```
    After estimation, overall indices of scale quality can be computed such as reliability and separation. This method returns the scale quality statistics for the entire group of examinees.
    
    Returns:
  - getMaxCategory
```
public int getMaxCategory()
```
    Each item can have a different number of score categories. Gets the maximum score category.
    
    Returns:
    
    maximum score category among all items.
  - getNumberOfItems
```
public int getNumberOfItems()
```
    The total number of items on the test is stored. It includes all good items and all extreme items.
    
    Returns:
    
    total number of items.
  - getNumberOfPeople
```
public int getNumberOfPeople()
```
    The total number of examinees is stored. It includes all extreme and nonextreme examinees.
    
    Returns:
    
    total number of examinees.
  - getItemResponseModelAt
```
public ItemResponseModel getItemResponseModelAt(int index)
```
    An ItemResponseModel object is stored in an array for each item. Gets the item response model at the given index.
    
    Parameters:
    
    index - array position of the item response model.
    
    Returns:
    
    item response model at the given index.
  - getItemFitStatisticsAt
```
public RaschFitStatistics getItemFitStatisticsAt(int index)
```
    Fit statistics for each item are stored in an array. Gets the fit statistics for the item in the array at position given by the index.
    
    Parameters:
    
    index - array position of the item fit statistics.
    
    Returns:
    
    fit statistics for an item.
  - getRatingScaleGroupAt
```
public RaschRatingScaleGroup getRatingScaleGroupAt(int index)
```
    Polytomous response models be long to a single RaschRatingScaleGroup. Gets the rating scale group for item at the indexed position in the array.
    
    Parameters:
    
    index - array position of the item.
    
    Returns:
    
    rating scale group for the item.
  - getExtremeItemAt
```
public int getExtremeItemAt(int index)
```
    Extreme items are items in whih all examinees obtain the maximum possitble item score or the minimum possible item score. An array stores flag as to whether items are extreme. Gets the indicator of the item's extreme status.
    
    Parameters:
    
    index - position of item in the array.
    
    Returns:
    
    extreme status for the item.
  - getPersonEstimateAt
```
public double getPersonEstimateAt(int index)
```
    Person ability estimates are stored in an array. Gets the estimate of ability for the person at the position given by the index.
    
    Parameters:
    
    index - array position of the examinee.
    
    Returns:
    
    current ability estimate for an examinee.
  - getPersonEstimateStdErrorAt
```
public double getPersonEstimateStdErrorAt(int index)
```
    Person estimate standard errors are stored in an array of doubles. Gets the standard error at the given position of the array. The method computePersonStandardErrors() must be called before this method. Otherwise, it will result in a null pointer exception.
    
    Parameters:
    
    index - position in array.
    
    Returns:
    
    person estimate standard error.
  - getValidSumScoreAt
```
public double getValidSumScoreAt(int index)
```
    The valid sum score is the sum score based on the nonextreme items. Valid sum scores are stored as an array of doubles. Gets the valid sum score at the given position in the array.
    
    Parameters:
    
    index - position of valid sum score in the array.
    
    Returns:
    
    valid sum score.
  - getSumScoreAt
```
public double getSumScoreAt(int index)
```
  - getExtremePersonAt
```
public int getExtremePersonAt(int index)
```
    An extreme person is an examinee that obtains the minimum or maximum possible test score. Ability estimates are not possible with extreme examinees without an adjustment. Extreme persons are flagged in a integer array such that a code of 0 is a nonextreme examinee, -1 is an extreme minimum, and +1 is an extreme maximum.
    
    Parameters:
    
    index - position in array.
    
    Returns:
    
    extreme person code.
  - getResidualAt
```
public double getResidualAt(int i,
                            int j)
```
    A residual is the difference between the observed and expected item response. Computes and returns the residual for person i to item j.
    
    Parameters:
    
    i - index of examinee in data array.
    
    j - index of item in array of item response models.
    
    Returns:
    
    residual for person i to item j.
  - getResponseAt
```
public byte getResponseAt(int i,
                          int j)
```
  - getDroppedStatusAt
```
public int getDroppedStatusAt(int index)
```
    A polytomous item with at least one category with 0 observations is dropped from the analysis. The dropped status of each item is stored in an integer array. The dropped status is coded such that a value of 0 indicates the item is not dropped, a value of -1 indicates a category with no observations, and a +1 indicates a category with all of the observations (hence one or more other categories have 0 observations).
    
    Parameters:
    
    index - array index of item.
    
    Returns:
    
    dropped status.
  - printPersonStats
```
public java.lang.String printPersonStats()
```
    This method is for displaying person parameter estimates, standard errors, and other information. It will display statistic for every examinee.
    
    Returns:
  - printBasicItemStats
```
public java.lang.String printBasicItemStats()
```
  - printBasicItemStats
```
public java.lang.String printBasicItemStats(java.lang.String title)
```
    This method is for displaying item parameter estimates, standard errors, and other information.
    
    Returns:
  - printIterationHistory
```
public java.lang.String printIterationHistory()
```
    Joint maximum likelihood estimation is iterative. An iteration history is saved. The history includes the largest change in logits and the log-likelihood at each iteration. This method provides a string representation of the iteration history.
    
    Returns:
    
    a summary of the iteration history.
  - printScoreTable
```
public java.lang.String printScoreTable(int maxIter,
                                        double converge,
                                        double adjustment,
                                        DefaultLinearTransformation transformation,
                                        int precision)
```
    The sum score is a sufficient statistic for the latent trait in the Rasch family of models. As such, it is easy to create a table that shows the 1:1 correspondence between the sum score and person ability. A score table is created showing this correspondence. It requires its own set of iterations, which is why some parameters concern the iteration.
    
    Parameters:
    
    maxIter - maximum number of iterations to use when estimating ability.
    
    converge - convergence criterion when estimating ability.
    
    adjustment - extreme score adjustment that is applied to extreme persons.
    
    transformation - linear transformation to be applied to person ability estimates.
    
    precision - number of decimal places to use when reporting estimates int eh score table.
    
    Returns:
    
    a score table that ranges from the minimum possible score to the maximum possible score.
  - getScoreconversionTableForOutputter
```
public java.lang.Object[][] getScoreconversionTableForOutputter()
```
  - printItemStats
```
public java.lang.String printItemStats(java.lang.String title)
```
    Creates a string of item statistics. It includes (a) item name, (b) item difficulty, (c) difficulty standard error, (d) four item fit statistics, and (e) a extreme item flag. This method for displaying statistics is the one used in jMetrik for displaying results.
    
    Parameters:
    
    title - a title for the output table.
    
    Returns:
    
    a table of item statistics.
  - printCategoryStats
```
public java.lang.String printCategoryStats()
```
    Polytomous items have a set of threshold statistics that must be reported. They are listed in a separate output table as defined by this method.
    
    Returns:
    
    a table of category statistics.

Class JointMaximumLikelihoodEstimation

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

JointMaximumLikelihoodEstimation

Method Detail

summarizeData

estimateParameters

estimateParameters

estimateParameters

itemProx

getLogLikelihood

getItems

getPersons

getPersonStdError

computeItemStandardErrors

computePersonStandardErrors

numberOfNonexremeItems

numberOfNonextremePeople

biasCorrection

printFrequencyTables

printRatingScaleTables

getPersonEstimates

linearTransformation

computeItemFitStatistics

getPrincipalComponentsForStandardizedResiduals

getPersonFitStatisticsAt

computeItemCategoryFitStatistics

getItemSideScaleQuality

getPersonSideScaleQuality

getMaxCategory

getNumberOfItems

getNumberOfPeople

getItemResponseModelAt

getItemFitStatisticsAt

getRatingScaleGroupAt

getExtremeItemAt

getPersonEstimateAt

getPersonEstimateStdErrorAt

getValidSumScoreAt

getSumScoreAt

getExtremePersonAt

getResidualAt

getResponseAt

getDroppedStatusAt

printPersonStats

printBasicItemStats

printBasicItemStats

printIterationHistory

printScoreTable

getScoreconversionTableForOutputter

printItemStats

printCategoryStats