C:/programs/etirm/src/swig_etirm.cpp

Go to the documentation of this file.

/*! \file swig_etirm.cpp
 
  \brief
  Definitions of functions and classes to generate scripting language wrapper 
  functions for ETIRM using SWIG.

  The file swig_etirm_types.h (which is included in swig_etirm.h) must be 
  provided which should contain typedef's for the following types:
 
  ResponseVector  Vector containing item responses.
  item_type   Item class.
  examinee_type Examinee class.
  lvdist_type   Latent variable distribution class.
  random_type   Type of random number generator used for bootstrap.

  For example:

  // Do not process with SWIG, SWIG cannot handle the template arguments
  xx_ifndef SWIG
 
  // Vector of item responses
  typedef std::vector<etirm::Response> ResponseVector;
 
  // Class to hold information about discrete latent variable distribution
  typedef etirm::DiscreteLatentDist<etirm::Real> lvdist_type;
 
  // Class to hold information about examinees
  typedef etirm::ExamineeGrpCov<ResponseVector, etirm::RealVector> examinee_type;
 
  // Type used for array of items. Using ItemNR allows different items to be modeled
  // by different classes descendent from ItemNR (e.g., the 3PL model could be used for
  // some items, and the 2PL model used for other items).
  typedef etirm::ItemNR<lvdist_type> item_type;
 
  // Use the Mersenne Twister (http://www.math.keio.ac.jp/matumoto/emt.html)
  // from the Boost random number library
  // (http://www.boost.org/libs/random/index.html) 
  // as random number generator for bootstrap samples.
  typedef boost::mt19937 random_type;

  xx_endif // SWIG
 
  An application using these wrapper functions should declare a subclass
  of SwigEtirmRun whose constructor initializes the item object pointers, and 
  assigns them to the 'items' data member of SwigEtirmRun. 
  An application should provide functions for creating and deleting an object
  that is a subclass of SwigEtirmRun which is stored in the global variable
  gEtirmRun defined in this file.

  Definitions of the function CheckRunInit must be provided. This
  function is declared in swig_etirm.h, but each application must define it.
  It is not defined in swig_etirm.cpp.
 
  The function CheckRunInit checks whether gEtirmRun has been
  initialized, and if not throws an exception. The message contained
  in the exception will differ for different applications. 

  Estimation Toolkit for Item Response Models (ETIRM)
  http://www.smallwaters.com/software/cpp/etirm.html

  Author(s): 
  Werner Wothke, maintenance (http://www.smallwaters.com)
  Brad Hanson (http://www.b-a-h.com/)
  See the file LICENSE for information on usage and redistribution.

  Copyright (C) 2008, Werner Wothke
  Copyright (c) 2000-2002, Bradley A. Hanson
 */

#ifdef ETIRM_NO_DIR_PREFIX
#include "swig_etirm.h"
#include "MStepIRT.h"
#include "DiscreteNormalDist.h"
#include "ItemParamPriorBeta4.h"
#include "ItemParamPriorLogNormal.h"
#include "ItemParamPriorNormal.h"
#include "BootstrapSample.h"
#include "SimulateResponses.h"
#include "ExamineeThetaMLE.h"
#else
#include "etirm/swig_etirm.h"
#include "etirm/MStepIRT.h"
#include "etirm/DiscreteNormalDist.h"
#include "etirm/ItemParamPriorBeta4.h"
#include "etirm/ItemParamPriorLogNormal.h"
#include "etirm/ItemParamPriorNormal.h"
#include "etirm/BootstrapSample.h"
#include "etirm/SimulateResponses.h"
#include "etirm/ExamineeThetaMLE.h"
#endif

// Use integer random number generator from boost library
// (http://www.boost.org).
#include <boost/random/uniform_int.hpp>

#include <cstdio>  // sprintf prototype
// for compilers which do not put C library functions in std namespace
#ifdef BOOST_NO_STDC_NAMESPACE
namespace std
{ using ::sprintf;}
#endif

// Definitions not wrapped by SWIG
namespace etirm
{

  //! Global variable holding information about a run.
  SwigEtirmRun *gEtirmRun = 0;

  /*!
    \brief
    Increments counts based on item response.
   
    \section function_args Function Parameters
   
    \param[in]  respIndex "One" offset index corresponding to response to increment 
        count for (1 = first response category, 2 = second response category, etc.).
    \param[in]  count   Amount to increment counts.
    \param[in]  group   Group to increment counts for (1, 2, ...).
   */
  void ItemRespCounts::AddResponse(int respIndex, Real count, int group)
  {

    if (respIndex > catCounts.size() || respIndex < 1)
    {
      throw InvalidArgument("Invalid response index", "ItemRespCounts::AddResponse");
    }

    totalCount[0] += count; // total count
    totalCount[group] += count; // count for group

    catCounts(1, respIndex) += count; // total count
    catCounts(group+1, respIndex) += count; // count for group
  }

  /*!
    \brief
    Class constructor.
   
    \section function_args Function Parameters
   
    \param[in]  nitems    Total number of items.
    \param[in]  nlatentcat  Number of categories of discrete latent variable.
    \param[in]  ngroups   Number of examinee groups.
    \param[in]  minTheta  Minimum value of theta points for discrete latent 
        variable distribution.
    \param[in]  maxTheta  Maximum value of theta points for discrete latent 
        variable distribution.
    \param[in]  uniquePoints  If true then unique latent distribution points 
        are used for each examinee group.
   */
  SwigEtirmRun::SwigEtirmRun(int nitems, int nlatentcat, int ngroups, Real minTheta, Real maxTheta,
      bool uniquePoints) :
    numItems(nitems), numLatentCat(nlatentcat), numGroups(ngroups), examineeCounts(ngroups+1, 0.0),
        items(nitems), itemStats(nitems), minProc(nitems), latentDist(nlatentcat, ngroups,
            uniquePoints), rand_boot(0), base_rand_simulate(0), rand_simulate(0)
  {
    int i;

    // Set default points and weights for latent variable distribution to standard normal
    // for first group
    DiscreteNormalDist(nlatentcat, minTheta, maxTheta, latentDist.begin_points(1),
        latentDist.begin_weights(1));

    // Set points and weights for other groups equal to the points and weights for group 1
    for (i=2; i<=ngroups; ++i)
    {
      DiscreteLatentDist<Real>::weight_iterator w1 = latentDist.begin_weights(1);
      DiscreteLatentDist<Real>::weight_iterator w2 = latentDist.begin_weights(i);
      for (int j = nlatentcat; j--; ++w1, ++w2)
      {
        *w2 = *w1;
      }

      if (uniquePoints)
      {
        // initialize unique points for examinee group
        DiscreteLatentDist<Real>::point_iterator w1p = latentDist.begin_points(1);
        DiscreteLatentDist<Real>::point_iterator w2p = latentDist.begin_points(i);
        for (int j = nlatentcat; j--; ++w1p, ++w2p)
        {
          *w2p = *w1p;
        }
      }
    }

    /* initialize vectors of pointers to null */
    for (i=0; i<nitems; ++i)
    {
      items[i] = 0;
      itemStats[i] = 0;
      minProc[i] = 0;
    }

  }

  //! Releases memory allocated by constructor.
  SwigEtirmRun::~SwigEtirmRun()
  {
    int i;

    for (i=0; i<numItems; i++)
    {
      if (items[i])
      {
        items[i]->DeletePriors();
        delete items[i];
      }

      if (itemStats[i])
        delete itemStats[i];
      if (minProc[i])
        delete minProc[i];
    }

    int n = examinees.size();
    for (i=0; i<n; ++i)
    {
      delete examinees[i];
    }

    delete rand_boot;
    delete base_rand_simulate;
    delete rand_simulate;
  }

  // Check that data for examinees exist
  void SwigEtirmRun::CheckExaminees(const char *funcname)
  {
    if ((gEtirmRun->examinees).size() == 0)
    {
      throw RuntimeError("Error: No examinee data", funcname);
    }
  }

  // Check that examinee number is valid
  void SwigEtirmRun::CheckExamineeNumber(int examno, const char *funcname)
  {
    if ( (examno < 1) || ( examno > (gEtirmRun->examinees).size() ) )
    {
      char errstr[50];
      std::sprintf(errstr, "Invalid examinee number: %d", examno);
      gEtirmRun->returnString = errstr;
      throw RuntimeError((gEtirmRun->returnString).c_str(), funcname);
    }
  }

  // Check that item number is valid
  void SwigEtirmRun::CheckItemNumber(int itemno, const char *funcname)
  {
    if (itemno < 1 || itemno >(gEtirmRun->numItems) ) // Syntax edited, ww, 2-24-2008.
    {
      char errstr[50];
      std::sprintf(errstr, "Invalid item number: %d", itemno);
      gEtirmRun->returnString = errstr;
      throw RuntimeError((gEtirmRun->returnString).c_str(), funcname);
    }
  }

  // Check that group number is valid
  //  group   Value to check.
  //  funcname  Name of calling function (used in error message)
  void SwigEtirmRun::CheckGroup(int group, const char *funcname)
  {
    if (group < 1 || group >(gEtirmRun->numGroups) ) // Syntax edited, ww, 2-24-2008
    {
      char errstr[50];
      std::sprintf(errstr, "Invalid examinee group: %d", group);
      gEtirmRun->returnString = errstr;
      throw RuntimeError((gEtirmRun->returnString).c_str(), funcname);
    }
  }

  /*! 
    \brief
    Tests whether item parameter index is valid for the item.
   
    \section function_args Function Parameters
    
    \param[in]  *item   Pointer to item object for which index is checked.
    \param[in]  index   Zero-offset index of item parameter.
    \param[in]  *funcname pointer to name of calling function (used in error message).
   */
  void CheckItemParam(item_type *item, int index, const char *funcname)
  {
    if (item->NumParameters() <= index || index < 0)
    {
      char errstr[100];
      std::sprintf(errstr, "Invalid item parameter index for item %d: %d", item->Index()+1, index);
      gEtirmRun->returnString = errstr;
      throw RuntimeError((gEtirmRun->returnString).c_str(), funcname);
    }
  }

  /*!
    \brief
    Create a prior distribution object and return a pointer to it.
   
    \section function_args Function Parameters

    \param[in]  pstr  Type of prior distribution, valued as ("none", "normal", "lognormal", "beta").
    \param[in]  priorparam  Parameters of prior distribution.
    \param[in]  funcname  Name of calling function (used in error messages)
   */
  ItemParamPrior *CreatePrior(const std::string &pstr, const double_vector &priorparam,
      const char *funcname)
  {
    const char *err_message = "Invalid number of prior parameters";

    if (pstr.compare("none") == 0)
    {
      return 0;
    }
    else if (pstr.compare("normal") == 0)
    {
      if (priorparam.size() != 2)
        throw RuntimeError(err_message, funcname);
      return new ItemParamPriorNormal(priorparam[0], priorparam[1]);
    }
    else if (pstr.compare("lognormal") == 0)
    {
      if (priorparam.size() != 2)
        throw RuntimeError(err_message, funcname);
      return new ItemParamPriorLogNormal(priorparam[0], priorparam[1]);
    }
    else if (pstr.compare("beta") == 0)
    {
      if (priorparam.size() != 4)
        throw RuntimeError(err_message, funcname);
      return new ItemParamPriorBeta4(priorparam[0], priorparam[1], priorparam[2], priorparam[3]);
    }
    else
    {
      throw RuntimeError("Invalid prior type", funcname);
    }
    return 0;
  }

  /*!
    \brief
    Converts a response for an item into a character, where '0' represents the 
    first response, '1' represents the second response, etc.
   
    If the number of response categories for the item is greater than 10, then the 
    characters returned will be ascii characters greater than '9'. For example, a 
    ':' is return for a response in response category 11, since ':' is one greater
    than '9' in the ascii sequence.

    \section function_args Function Parameters
    
    \param[in]  r Item response to be converted.
    \param[in]  *item Pointer to item object.
   */
  char Resp2Char(Response r, const item_type *item)
  {
    const char zero = '0';
    Response np = item_type::NotPresentedResponse();
    char cr;
    if (r == np)
      cr = np - item->FirstResponse() + zero;
    else
      cr = item->ResponseIndex(r) + zero;

    return cr;
  }

  /****** Functions for which SWIG wrappers are generated ******/

  /* Member functions for estep class */

  /*!
    \brief
    Initialize estep object.
   
    \section function_args Function Parameters
   
    \param[in]  *itemno Pointer to list of item numbers to use for computing 
    examinee posteriors distribution in E-Step. If itemno = NUL, use all items (default).
   */
  estep::estep(int_vector *itemno)
  {
    CheckRunInit();

    if (itemno)
    {
      mItems = new ItemVector(ItemSubset(itemno,gEtirmRun->items,"new_estep"));

      mEStep = new estep_type(mItems->begin(), mItems->end(), gEtirmRun->latentDist);
    }
    else
    {
      mItems = 0;
      mEStep = new estep_type((gEtirmRun->items).begin(), (gEtirmRun->items).end(), gEtirmRun->latentDist);
    }
  }

  /*!
    \brief
    Release memory allocated in constructor.
   */
  estep::~estep()
  {
    if (mItems)
      delete mItems;
    delete mEStep;
  }

  /*!
    \brief
    Calls mEStep->DoEStep to perform E-step.
   
    Returns marginal loglikelihood of examinees' responses (sum over examinees of the 
    marginal loglikelihood of an examinee's responses) plus sum of prior likelihoods 
    over all item parameters.  This is the value of the marginal posterior density that 
    the EM algorithm is maximizing at the values of the item parameters computed in the 
    last M-step.
   
    \section function_args Function Parameters
   
    \param[in]  compute_post  Flag: If compute_post == TRUE, then compute posterior 
    distributions for all examinees. If compute_post == FALSE, then use previously 
    stored posteriors for examinees. (Default: TRUE).
   
    \param[in]  store_post  Flag: If store_post == TRUE, then store the posterior 
    distribution computed for each examinee. These posterior distributions are 
    stored as part of the examinee objects.
    (Default: FALSE).
   
    \param[in]  *estep_items  Pointer to list of items for which n and r are updated. If a 
    null pointer is passed then n arnd r are updated for all items used in the E-step 
    to compute examinee posterior distributions.
   */
  double estep::compute(bool compute_post, bool store_post, int_vector *estep_items) // compute_post and store_post retyped as "bool", ww, 2-24-2008.
  {
    const char *fname = "estep_compute";
    CheckRunInit();
    gEtirmRun->CheckExaminees(fname);

    if (estep_items)
    {
      if (estep_items->size() > 0)
      {
        ItemVector itemsub = ItemSubset(estep_items, gEtirmRun->items, fname);
        return mEStep->DoEStep((gEtirmRun->examinees).begin(), (gEtirmRun->examinees).end(), itemsub.begin(), itemsub.end(), compute_post, store_post);
      }
      else // do not update n and r for any items
      {
        return mEStep->DoEStep((gEtirmRun->examinees).begin(), (gEtirmRun->examinees).end(), (gEtirmRun->items).begin(), (gEtirmRun->items).begin(), compute_post, store_post);
      }
    }
    else
    {
      return mEStep->DoEStep((gEtirmRun->examinees).begin(), (gEtirmRun->examinees).end(), compute_post, store_post);
    }
  }

  /*!
    \brief
    Assigns missing response code to identify examinees who did not respond to an item.
   */
  void set_missing_resp(char nr)
  {
    if (gEtirmRun)
    {
      throw RuntimeError("The not presented response can only be set before any items are initialized", 0);
    }
    Item<Real>::SetNotPresentedResponse(nr);
  }

  /*!
    \brief
    Returns the number of items.
   */
  int num_items()
  {
    CheckRunInit();

    return gEtirmRun->numItems;
  }

  /*!
    \brief
    Returns number of categories of the discrete theta distribution.
   */
  int num_latent_dist_points()
  {
    CheckRunInit();

    return gEtirmRun->numLatentCat;
  }

  /*!
    \brief
    Returns number of examinee groups.
   */
  int num_groups()
  {
    CheckRunInit();

    return gEtirmRun->numGroups;
  }

  /*!
    \brief
    Returns number of examinees.
   */
  int num_examinees()
  {
    CheckRunInit();

    return (gEtirmRun->examinees).size();
  }

  /*!
    \brief
    Returns the name of model used for an item.
   
    \section function_args Function Parameters
   
    \param[in]  itemno Item number (1-offset).
   */
  const char * item_get_model(int itemno)
  {

    CheckRunInit();
    std::string &modelName = gEtirmRun->returnString;
    gEtirmRun->CheckItemNumber(itemno, "item_get_model");

    item_type *item = (gEtirmRun->items)[itemno-1];
    modelName = item->ModelName();

    return modelName.c_str();
  }

  /*!
    \brief
    Assigns a value to one item parameter of an item.
   
    \section function_args Function Parameters
   
    \param[in] paramno  1-offset index of parameter in parameter vector for item.
    \param[in] itemno   Item number (1-offset).
    \param[in] paramvalue Value parameter is set to.
   */
  void item_set_param(int paramno, int itemno, double paramvalue)
  {
    const char *fname = "item_set_param";
    CheckRunInit();
    int index = paramno - 1;

    gEtirmRun->CheckItemNumber(itemno, fname);
    item_type *item = (gEtirmRun->items)[itemno-1];
    CheckItemParam(item, index, fname);

    /* Check that value of parameter has nonzero prior density */
    item_type::prior_iterator pri = item->PriorsIterator() + index;
    if (*pri && (*pri)->ZeroDensity(paramvalue))
    {
      char merr[100];
      std::sprintf(merr, "Parameter specified for item %d has zero prior density", itemno);
      gEtirmRun->returnString = merr;
      throw RuntimeError((gEtirmRun->returnString).c_str(), fname);
    }

    item_type::param_iterator pv = item->ParametersIterator();

    pv[index] = paramvalue;
  }

  /*!
    \brief
    Assigns values to all item parameters of an item.
   
    \section function_args Function Parameters
   
    \param[in]  itemno  Item number (1-offset).
    \param[in]  *params  Pointer to params vector containing the values to set the 
        parameters to.
   
    Note: The order of the parameters in the params vector is: 
    a (if there is an a parameter), one or more b's, and
    c (if there is a c parameter).
   */
  void item_set_params(int itemno, double_vector *params)
  {
    const char *fname = "item_set_params";
    CheckRunInit();
    gEtirmRun->CheckItemNumber(itemno, fname);

    item_type *item = (gEtirmRun->items)[itemno-1];

    // Assign new parameters
    item_type::param_iterator pv = item->ParametersIterator();
    double_vector::iterator iv = params->begin();
    int n;
    for (n = item->NumParameters(); n--; ++pv, ++iv)
    {
      *pv = *iv;
    }

    /* Check that values of all parameters have nonzero prior density */
    iv = params->begin();
    item_type::prior_iterator pri = item->PriorsIterator();
    for (n = item->NumParameters(); n--; ++pri, ++iv)
    {
      if (*pri && (*pri)->ZeroDensity(*iv))
      {
        char merr[100];
        std::sprintf(merr, "Parameter specified for item %d has zero prior density", itemno);
        throw InvalidArgument(merr, fname);
      }
    }
  }

  /*!
    \brief
    Assigns values to all fixed and estimated item parameters of an item.
   
    \section function_args Function Parameters
   
    \param[in]  itemno  Item number (1-offset).
    \param[in]  *params  Pointer to params vector containing the values to set the 
        parameters to.
   
    Note: The order of the parameters in the params vector is: 
    a (if there is an a parameter), one or more b's, and
    c (if there is a c parameter).
   */
  void item_set_all_params(int itemno, double_vector *params)
  {
    const char *fname = "item_set_all_params";
    CheckRunInit();
    gEtirmRun->CheckItemNumber(itemno, fname);

    item_type *item = (gEtirmRun->items)[itemno-1];

    // Assign new fixed and estimated parameters
    item->SetAllParameters(*params);

    /* Check that values of estimated parameters all have nonzero prior density */
    item_type::param_iterator iv = item->ParametersIterator();
    item_type::prior_iterator pri = item->PriorsIterator();
    for (int n = item->NumParameters(); n--; ++pri, ++iv)
    {
      if (*pri && (*pri)->ZeroDensity(*iv))
      {
        char merr[100];
        std::sprintf(merr, "Parameter specified for item %d has zero prior density", itemno);
        gEtirmRun->returnString = merr;
        throw InvalidArgument((gEtirmRun->returnString).c_str(), fname);
      }
    }
  }

  /*!
    \brief
    Returns value of one item parameter of an item.
   
    \section function_args Function Parameters
    
    \param[in]  paramno  1-offset index of the parameter in the item's parameter vector.
    \param[in]  itemno  Item number (1-offset).
   
    Note: The order of the parameters in the params vector is: 
    a (if there is an a parameter), one or more b's, and
    c (if there is a c parameter).
   */
  double item_get_param(int paramno, int itemno)
  {
    const char *fname = "item_get_param";
    CheckRunInit();
    int index = paramno - 1;

    gEtirmRun->CheckItemNumber(itemno, fname);
    item_type *item = (gEtirmRun->items)[itemno-1];
    CheckItemParam(item, index, fname);

    item_type::param_iterator pv = item->ParametersIterator();

    return pv[index];
  }

  /*!
    \brief
    Returns vector of all estimated item parameters values of an item.
   
    \section function_args Function Parameters
   
    \param[in]  itemno  Item number (1-offset).
   
    Note: The order of the parameters in the params vector is: 
    a (if there is an a parameter), one or more b's, and
    c (if there is a c parameter).
   */
  double_vector *item_get_params(int itemno)
  {
    CheckRunInit();
    gEtirmRun->CheckItemNumber(itemno, "item_get_params");

    item_type *item = (gEtirmRun->items)[itemno-1];

    int n = item->NumParameters();
    double_vector *params = new double_vector(n);

    item_type::param_iterator pv = item->ParametersIterator();
    double_vector::iterator iv = params->begin();
    for (; n--; ++pv, ++iv)
    {
      *iv = *pv;
    }

    return params;
  }

  /*!
    \brief
    Returns vector of all fixed and estimated item parameters values of an item.
   
    \section function_args Function Parameters
   
    \param[in]  itemno  Item number (1-offset).
   
    Note: The order of the parameters in the params vector is: 
    a (if there is an a parameter), one or more b's, and
    c (if there is a c parameter).
   */
  double_vector *item_get_all_params(int itemno)
  {
    CheckRunInit();
    gEtirmRun->CheckItemNumber(itemno, "item_get_all_params");

    item_type *item = (gEtirmRun->items)[itemno-1];

    RealVector allparam = item->GetAllParameters();
    int n = allparam.size();
    double_vector *params = new double_vector(n);

    RealVector::iterator pv = allparam.begin();
    double_vector::iterator iv = params->begin();
    for (; n--; ++pv, ++iv)
    {
      *iv = *pv;
    }

    return params;
  }

  /*!
    \brief
    Returns the number of parameters of an item.

    \section function_args Function Parameters
   
    \param[in]  itemno  Item number (1-offset).
   */
  int item_num_params(int itemno)
  {
    CheckRunInit();
    gEtirmRun->CheckItemNumber(itemno, "item_num_params");

    item_type *item = (gEtirmRun->items)[itemno-1];

    return item->NumParameters();
  }

  /*!
    \brief
    Returns the number of response categories of an item.

    \section function_args Function Parameters
   
    \param[in]  itemno  Item number (1-offset).
   */
  int item_num_resp_cat(int itemno)
  {
    CheckRunInit();
    gEtirmRun->CheckItemNumber(itemno, "item_num_resp_cat");

    item_type *item = (gEtirmRun->items)[itemno-1];

    return item->NumRespCat();
  }

  /*!
    \brief
    Assigns prior distribution parameters for one item parameter.

    \section function_args Function Parameters
   
    \param[in]  paramno 1-offset index of parameter in parameter vector for item.
    \param[in]  itemno  Number of item for which prior is set (1-offset).
    \param[in]  *priortype Pointer to type of prior distribution ("normal", "lognormal", "beta", "none").
    \param[in]  *dlist Pointer to vector of prior distribution parameters.
   */
  void item_set_prior(int paramno, int itemno, char *priortype, double_vector *dlist)
  {
    const char *funcname = "item_set_prior";
    CheckRunInit();
    int index = paramno - 1;

    gEtirmRun->CheckItemNumber(itemno, funcname);
    item_type *item = (gEtirmRun->items)[itemno-1];
    CheckItemParam(item, index, funcname);

    item_type::prior_iterator pv = item->PriorsIterator() + index;

    if (*pv)
      delete *pv;

    std::string pstr(priortype);
    *pv = CreatePrior(pstr, *dlist, funcname);
  }

  /*!
    \brief
    Returns type of prior distribution ("normal", "lognormal", "beta", "none")
    for one item parameter.

    \section function_args Function Parameters
   
    \param[in]  paramno 1-offset index of parameter in parameter vector for item.
    \param[in]  itemno  Number of item for which prior is returned (1-offset).
   */
  const char *item_get_prior_type(int paramno, int itemno)
  {
    const char *fname = "item_get_prior_type";
    CheckRunInit();
    std::string &priorName = gEtirmRun->returnString;
    int index = paramno - 1;

    gEtirmRun->CheckItemNumber(itemno, fname);
    item_type *item = (gEtirmRun->items)[itemno-1];
    CheckItemParam(item, index, fname);

    item_type::prior_iterator pv = item->PriorsIterator() + index;

    if (*pv != 0)
    {
      priorName = (*pv)->DistributionName();
    }
    else
    {
      priorName = "none";
    }

    return priorName.c_str();
  }

  /*!
    \brief
    Returns vector of prior distribution parameters for one item parameter.

    \section function_args Function Parameters
   
    \param[in]  paramno 1-offset index of parameter in parameter vector for item.
    \param[in]  itemno  Number of item for which prior is returned (1-offset).
   */
  double_vector *item_get_prior_param(int paramno, int itemno)
  {
    const char *fname = "item_get_prior_param";
    CheckRunInit();
    int index = paramno - 1;

    gEtirmRun->CheckItemNumber(itemno, fname);
    item_type *item = (gEtirmRun->items)[itemno-1];
    CheckItemParam(item, index, fname);

    item_type::prior_iterator pv = item->PriorsIterator() + index;

    double_vector *v;
    if (*pv != 0)
    {
      int n = (*pv)->NumParameters();

      v = new double_vector(n);

      *v = (*pv)->GetParameters();
    }
    else
    {
      v = new double_vector();
    }

    return v;
  }

  /*!
    \brief
    Returns vector of response counts in each response category of an item.
   
    \section function_args Function Parameters
   
    \param[in]  itemno  Number of item for which response counts are returned (1-offset).
    \param[in]  group Group to return counts for (1-offset). Specify group = 0 to return 
        counts across all groups.
   */
  double_vector *item_cat_counts(int itemno, int group)
  {
    const char *fname = "item_cat_counts";
    CheckRunInit();

    gEtirmRun->CheckItemNumber(itemno, fname);
    if (group != 0)
      gEtirmRun->CheckGroup(group, "item_resp_count");

    ItemRespCounts *stats = (gEtirmRun->itemStats)[itemno-1];

    double_vector *v = new double_vector(stats->CategoryCounts(group));

    return v;
  }

  /*!
    \brief
    Returns the number of examinees responding to an item.
   
    \section function_args Function Parameters
   
    \param[in]  itemno  Number of item for which response counts are returned (1-offset).
    \param[in]  group Group to return counts for (1-offset). Specify group = 0 to return 
        count across all groups.
   */
  double item_resp_count(int itemno, int group)
  {
    CheckRunInit();

    gEtirmRun->CheckItemNumber(itemno, "item_resp_count");
    if (group != 0)
      gEtirmRun->CheckGroup(group, "item_resp_count");

    return (gEtirmRun->itemStats)[itemno-1]->RespCount(group);
  }
  /*!
    \brief
    Transforms the parameter estimates of an item to a different latent variable scale.
   
    Returns zero if parameters are successfully scaled, or returns nonzero if
    scaling would result in an invalid parameter value.   

    \section function_args Function Parameters
   
    \param[in]  itemno  Number of item for which to transform parameters (1-offset).
    \param[in]  slope  Slope of scale transformation to apply to item parameters.
    \param[in]  intercept Intercept of scale transformation to apply to item parameters.
    \param[in]  ignorePriorError  If true then do not report an error if transformed parameter
        has zero density in prior used for that parameter.
   */
  int item_scale_params(int itemno, double slope, double intercept, bool ignorePriorE