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

Go to the documentation of this file.

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

  See swig_etirm.cpp for documentation.

  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
 */

#ifndef SWIGETIRM_H_
#define SWIGETIRM_H_

// This must be provided - declares types unique to application 
// (see comments at the top of swig_etirm.cpp).
// It is not provided in ETIRM.
#include "swig_etirm_types.h"

#ifdef ETIRM_NO_DIR_PREFIX
#include "EStepDiscrete.h"
#else
#include "etirm/EStepDiscrete.h"
#endif

#include "Uncmin.h"

#include <vector>
#include <string>

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

#ifndef SWIG
namespace etirm
{
#endif

  // Declarations not wrapped with SWIG
#ifndef SWIG
  //! Vector type for double precision values.
  typedef RealVector double_vector;

  //! Vector type for integer values.
  typedef SCPPNT::Vector<int> int_vector;

  //! Vector type for item pointers
  typedef std::vector<item_type *> ItemVector;

  //! Class used in E-step calculation
  typedef EStepDiscrete<examinee_type, item_type, ItemVector::iterator, lvdist_type> estep_type;

  //! Container to hold Uncmin optimization objects
  typedef std::vector<Uncmin<RealVector, RealMatrix, item_type> *> UncminVector;

  //! Container holding examinee object pointers
  typedef std::vector<examinee_type *> ExamineeVector;

  /*!
    \brief
    Class to hold counts of number of examinees who responded in each response 
    category of an item.
   */
  class ItemRespCounts
  {
public:

    /*! 
      \brief
      Class constructor.
      
      \section function_args Function Parameters
   
      \param[in]  ncat Number of response categories for the item.
      \param[in]  ngroup  Number of examinee groups.
     */
    ItemRespCounts(int ncat, int ngroup) :
      catCounts(ngroup+1, ncat, 0.0), totalCount(ngroup+1, 0.0)
    {
    }

    //! Deconstructor
    virtual ~ItemRespCounts()
    {
    }

    // Increment counts for a particular item response (1-offset)
    void AddResponse(int respIndex, Real count, int group);


    /*!
      \brief
      Returns total number of responses to item.
      
      \section function_args Function Parameters
   
      \param[in]  group Group(1, 2, ...) for which counts are to be returned.
      
      Note: group = 0 returns counts across all groups.
     */
    Real RespCount(int group)
    {
      return totalCount[group];
    }

    /*!
      \brief
      Returns number of responses in each response category.
      
      \section function_args Function Parameters
   
      \param[in]  group Group(1, 2, ...) for which counts are to be returned.
      
      Note: group = 0 returns counts across all groups.
     */      
    RealVector CategoryCounts(int group)
    {
      return RealVector(catCounts.begin_row(group+1), catCounts.begin_row(group+1)
          +catCounts.num_columns());
    } // ww: Edit "num_cols" -> "num_columns", 1/8/2008.


protected:
    /*!
      \brief
      Total number of examinees who have responses for the item.
      
      totalCount[0] is total count across all groups
      totalCount[i], i>0, is count for group i
     */
    RealVector totalCount;

    /*!
      \brief
      Number of responses in each response category.
      
      Columns give counts for response categories
      Row 1 gives counts across all groups.
      Row i, i>1,  gives counts for group i-1.
     */
    RealMatrix catCounts;
  };

  //! Container holding pointers to objects containing item statistics for each item
  typedef std::vector<ItemRespCounts *> ItemStatsVector;

  //! Class holding information used for one modeling problem.
  class SwigEtirmRun
  {

public:

    SwigEtirmRun(int nitems, int nlatentcat, int ngroups, Real minTheta = -4.0,
        Real maxTheta = 4.0, bool uniquePoints = false);

    virtual ~SwigEtirmRun();

    ExamineeVector examinees;
    //!< Vector holding pointers to examinee objects.
    
    ItemVector items;
    //!< Vector holding pointers to item objects.
    
    ItemStatsVector itemStats;
    //!< Vector holding pointers to item count objects.
    
    UncminVector minProc;
    //!< Vector holding pointers to minimization objects.
    
    lvdist_type latentDist;
    //!< Latent distribution object.

    random_type *rand_boot;
    //!< Base random number generator object for bootstrap.

    random_type *base_rand_simulate;
    //!< Base random number generator object for simulating item responses.

    boost::uniform_01<random_type> *rand_simulate;
    //!< Uniform random number generator object for simulating item responses.

    std::string returnString;
    //!< Temporary space to hold strings returned by functions.

    int numItems;
    //!< Number of operational/field test items to model.
    
    int numLatentCat;
    //!< Number of discrete categories to approximate the latent ability distribution.
    
    int numGroups;
    //!< Number of non-equivalents groups of examinees.
    
    RealVector examineeCounts;
    //!< Examinee counts in each group: examineeCounts[0] contains count across all groups; examineeCounts[i], i>0, contains count for group i.

    double mstepMaxDiff;
    //!< Maximum relative difference between item parameters computed in last M-Step call.

    /*!
      \brief
      Checks that data for examinees exist.
      
      \section function_args Function Parameters
   
      \param[in] *funcname  Pointer to name of calling routine.
     */
    void CheckExaminees(const char *funcname);

    /*!
      \brief
      Check that the examinee number is within its valid range.
      
      \section function_args Function Parameters
   
      \param[in] examno Examinee number.
      \param[in] *funcname  Pointer to name of calling routine.
     */
    void CheckExamineeNumber(int examno, const char *funcname);

    /*!
      \brief
      Checks for valid item number.
      
      \section function_args Function Parameters
   
      \param[in] itemno Item number.
      \param[in] *funcname  Pointer to name of calling routine.
     */
    void CheckItemNumber(int itemno, const char *funcname);

    /*!
      \brief
      Checks for valid group.
      
      \section function_args Function Parameters
      
      \param[in]  group Group number.
      \param[in] *funcname  Pointer to name of calling routine.
     */
    void CheckGroup(int group, const char *funcname);
  };

  /*!
    \brief
    Check that new_etirm has been called
  
    Note: This function is not defined in swig_etirm.cpp, it must be defined 
    somewhere in the application.
   */
  void CheckRunInit();

  /*! 
    \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);

  //Create a prior distribution object and return a pointer to it.
  ItemParamPrior *CreatePrior(const std::string &pstr, const double_vector &priorparam,
      const char *funcname);

  /*!
    \brief 
    Creates a container holding the elements corresponding to a subset of items.

    ItemSubset is based on a container holding elements corresponding to all items. 
    This container is typically used to create subsets of etirmrun->items (which 
    is an ItemVector) and etirmrun->minProc (which is a UncminVector). 
    
    \section template_args Template Parameters
   
    \param V ItemVector type.
   
    \section function_args Function Parameters
   
    \param[in]  *itemnums   Pointer to vector containing numbers of items to include in subset.
    \param[in]  &all  Address of container containing all items.
    \param[in]  *funcname   Pointer to name of calling function (used in error messages)
   */
  template <class V> V ItemSubset(int_vector *itemnums, V &all, const char *funcname)
  {
    int i;
    int nsub = itemnums->size();
    int nall = all.size();

    if (nsub < 1 || nsub> nall)
    {
      throw RuntimeError("Invalid number of items", funcname);
    }

    V sub(nsub);
    int *flag = new int[nall]; // flags indicating which items are in subset
    for (i = 0; i < nall; ++i) flag[i] = 0;

    typename V::iterator iall = all.begin();
    typename V::iterator isub = sub.begin();
    int_vector::iterator ino = itemnums->begin();
    for(i = 0; i < nsub; ++i, ++isub, ++ino)
    {
      int index = *ino - 1; // elements of itemnums are 1-offset indices
      if (index < 0 || index >= nall)
      {
        delete [] flag;
        throw RuntimeError("Invalid item number", funcname);
      }
      if (flag[index] == 1)
      {
        delete [] flag;
        throw RuntimeError("Duplicate item number", funcname);
      }
      flag[index] = 1;
      *isub = iall[index];
    }
    delete [] flag;

    return sub;
  }

  // Convert an item response to a character, where '0'
  // corresponds to the first response category
  char Resp2Char(Response r, const item_type *item);

#endif // SWIG
  /*** Classes and functions to be wrapped by SWIG ***/

  //! SWIG wrapper for EStepDiscrete object
  class estep
  {

  public:

    estep(int_vector *ilist1 = 0);
    ~estep();

    double compute(bool compute_prior = TRUE, bool store_prior = FALSE, int_vector *ilist4 = 0);
    // calls mEStep->DoEStep  // Retyped compute_prior and store_prior as "bool", ww, 2-24-2008.

#ifndef SWIG
    /*! 
      \brief
      Returns EStepDiscrete object. 
      
      Do not create SWIG wrapper for this member function!
     */
    estep_type *GetEStep()
    { return mEStep;}
#endif

  private:

    estep_type *mEStep; //!< EStepDiscrete object.
    ItemVector *mItems; //!< List of items used to initialize mEStep
  };

  // Set response which indicates an examinee did
  // not respond to an item
  void set_missing_resp(char nr);

  // Return number of items, number of theta points, and number of groups
  // specified in new_etirm
  int num_items();
  int num_latent_dist_points();
  int num_groups();

  // Return number of examinees added by calling add_examinee
  int num_examinees();

  /*** item functions ***/

  // Return name of model used for item
  const char * item_get_model(int itemno);

  // Assign a value to one parameter for one item
  void item_set_param(int paramno, int itemno, double paramvalue);

  // Assign values to all estimated parameters for one item
  void item_set_params(int itemno, double_vector *params);

  // Assign values to all fixed and estimated parameters for one item
  void item_set_all_params(int itemno, double_vector *params);

  // Get one parameter for one item
  double item_get_param(int paramno, int itemno);

  // Get all estimated parameters for one item
  double_vector *item_get_params(int itemno);

  // Get all estimated and fixed parameters for one item
  double_vector *item_get_all_params(int itemno);

  // Return number of parameters for one item
  int item_num_params(int itemno);

  // Return number of response categories for an item.
  int item_num_resp_cat(int itemno);

  // Set prior for one item
  void item_set_prior(int paramno, int itemno, char *priortype, double_vector *dlist4 = 0);

  // Get prior distribution for one parameter and one item
  const char *item_get_prior_type(int paramno, int itemno);

  // Get parameters of prior
  double_vector *item_get_prior_param(int paramno, int item);

  // Get probability of an item response
  double item_prob_resp(int itemno, int response, double theta);

  // Transform item parameters to different IRT scale
  int item_scale_params(int itemno, double slope, double intercept, bool ignorePriorError = 0); 
  // Retyped ignorePriorError from "int" to "bool", ww, 2-26-2008.

  // Return vector of counts of responses in each response category for an item
  // in an examinee group (0=all groups)
  double_vector *item_cat_counts(int itemno, int group = 0);

  // Return counts of number of examinees responding to an item
  // in an examinee group (0=all groups)
  double item_resp_count(int itemno, int group = 0);

  // Compute M-step for indicated items
  double_vector *test_characteristic_curve(double_vector *thetas, int_vector *ilist2 = 0);

  /** Latent distribution functions ***/

  // Set point value for one category of discrete latent variable distribution
  void dist_set_point(int index, double p, int group = 1);

  // Set points of latent discrete distribution
  void dist_set_points(double_vector *dlist, int group = 1);

  // Return value of point for one category of latent variable distribution
  double dist_get_point(int index, int group = 1);

  // Get points of latent discrete distribution
  double_vector *dist_get_points(int group = 1);

  // Set value of the probability for one category of discrete latent variable distribution for one group
  void dist_set_prob(int index, double w, int group = 1);

  // Set probabilities for latent discrete distribution for one group
  void dist_set_probs(double_vector *dlist, int group = 1);

  // Return value of probability for one category of latent variable distribution for one group
  double dist_get_prob(int index, int group = 1);

  // Get probabilities for latent discrete distribution for one group
  double_vector *dist_get_probs(int group = 1);

  // Transform points of latent variable distribution to a new scale
  void dist_transform(double slope, double intercept);

  // Scale points to give specific mean and sd in one group
  // Returns slope and intercept of linear scale transformation
  double_vector *dist_scale(double mean, double sd, int group = 1);

  // Return mean and sd of distribution in one group
  double_vector *dist_mean_sd(int group = 1);

  // Returns 1 if unique discrete latent distribution points are used for
  // different examinee groups and number of examinee groups is greater than 1, otherwise returns 0
  int dist_unique_points();

  // Return vector of probabilities for discrete distribution to approximate a normal distribution
  double_vector *normal_dist_prob(int npoints, double minPoint, double maxPoint,
  double mean = 0.0, double sd = 1.0);

  // Return vector of points for discrete distribution to approximate a normal distribution
  double_vector *normal_dist_points(int npoints, double minPoint, double maxPoint, double mean = 0.0,
  double sd = 1.0);

  /*** M-step functions ***/

  // Compute M-step for indicated items
  int mstep_items(bool ignore_max_iter = FALSE, int_vector *ilist2 = 0);
  // Retyped ignore_max_iter from "int" to "bool", ww, 2-25-2008.
  
  // Return maximum relative difference between parameters in current and previous
  // EM iteration computed in last call to mstep_items
  double mstep_max_diff();

  // Return message from optimization procedure generated in
  // last call to mstep_items for an item
  int mstep_message(int itemno);

  // Set maximum number of iterations used by optimization procedure
  // in mstep_items for one item.
  void mstep_max_iter(int itemno, int maxiter);

  // M-step for latent distribution in one group
  // Returns maximum relative difference between new and old probabilities
  double mstep_dist(estep *e, int group);

  /*** Examinee functions ***/

  // add one examinee
  int add_examinee(int_vector *responses, int group = 1, double count = 1.0);

  // Return vector of all item responses for an examinee
  int_vector *examinee_responses(int examineeno);

  // Returns string containing examinee responses to all items.
  // A response in the first response category is '0'.
  const char *examinee_response_str(int examineeno);

  // Return group examinee belongs to
  int examinee_get_group(int examineeno);

  // Sets group examinee belongs to
  void examinee_set_group(int examineeno, int group);

  // Set count for an examinee
  void examinee_set_count(int examineeno, double count);

  // Return count for an examinee
  double examinee_get_count(int examineeno);

  // Return total examinee counts in an examinee group (1, 2, ...).
  // If group==0 then return total count across all groups.
  double examinees_count(int group = 0);

  // Set posterior distribution for an examinee
  void examinee_set_posterior(int examineeno, double_vector *posterior);

  // Return copy of posterior distribution for an examinee
  double_vector* examinee_get_posterior(int examineeno);

  // Return mean of posterior distribution for an examinee
  double examinee_posterior_mean(int examineeno);

  // Return MLE theta estimate for an examinee
  double examinee_theta_MLE(int examineeno, double minTheta, double maxTheta,
  double precision = 0.001, int_vector *ilist5 = 0);

  // Set seed of random number generator used for bootstrap samples
  void bootstrap_seed(unsigned long seed);

  // Generate bootstrap sample of examinees
  void bootstrap_sample();

  // Set seed of random number generator used for simulating item responses
  void simulate_seed(unsigned long seed);

  // Simulate item responses corresponding to latent variable value theta
  int_vector *simulate_responses(double theta, int_vector *ilist2 = 0);

  // Return a string containing simulated item responses
  const char *simulate_response_str(double theta, int_vector *ilist2 = 0);

  // Read item responses from a string
  int_vector *get_responses(char *line, int_vector *offset, int_vector *len);

  // Read item responses for a subset of items from a string
  int_vector *get_responses_missing(char *line, int_vector *offset, int_vector *len,
  int_vector *items);

#ifndef SWIG
} // namespace etirm
#endif // SWIG

#endif

---