R: Draw plausible values (PVs) from an mml fit

drawPVs {Dire} | R Documentation

## Draw plausible values (PVs) from an mml fit

### Description

Draw plausible values (PVs) from an mml fit

### Usage

    drawPVs(x, npv, pvVariableNameSuffix = "_dire", ...)

    ## S3 method for class 'summary.mmlMeans'
    drawPVs(x, npv = 5L, pvVariableNameSuffix = "_dire", ...)

    ## S3 method for class 'mmlMeans'
    drawPVs(
      x,
      npv = 5L,
      pvVariableNameSuffix = "_dire",
      stochasticBeta = FALSE,
      normalApprox = TRUE,
      newStuDat = NULL,
      newStuItems = NULL,
      returnPosterior = FALSE,
      construct = NULL,
      ...
    )

    ## S3 method for class 'mmlCompositeMeans'
    drawPVs(
      x,
      npv = 5L,
      pvVariableNameSuffix = "_dire",
      stochasticBeta = FALSE,
      normalApprox = TRUE,
      newStuDat = NULL,
      newStuItems = NULL,
      verbose = TRUE,
      ...
    )

### Arguments

`x` | a fit from a call to `mml`
`npv` | integer indicating the number of plausible values to draw
`pvVariableNameSuffix` | suffix added to new PV variables after construct name and before the plausible value ID. For example, if there is a construct `math` and the suffix is the default `_dire`, then the fourth plausible value would have a column name, `math_dire4`.
`...` | additional parameters
`stochasticBeta` | logical when `TRUE` the regression coefficients will be drawn from their posterior distribution. Can also be a data frame of values (see Details).
`normalApprox` | logical must be `TRUE` to use the normal approximation to the posterior distribution rather than drawing from the actual posterior distribution.
`newStuDat` | new `stuDat` object, (see `mml`) for which plausible values will be drawn
`newStuItems` | new `stuItems` object, (see `mml`); unlike in `mml` students with no items can be passed to this function
`returnPosterior` | logical set to `TRUE` to change output to include two additional data frames (see Value).
`construct` | character, changes the name of the columns in the final data frame
`verbose` | logical set to `TRUE` to see the status of the processing

### Details

When the argument passed to `stocasticBeta` is a data frame then each column is an element that will be used as a regression coefficient for that index of the coefficients vector. The row index used for the nth PV will be the nth row.

### Value

when `returnPosterior` is FALSE returns a object of class `DirePV` which is a list of two elements. first, a data frame with a row for every row of newStuDat (or the original stuDat object)

- `id` the value of `idVar` in the model run

- `[construct][pvVariableNameSuffix][L]` every other column is a plausible value of this format. The `[construct]` is the name of the construct, the `[pvVariableNameSuffix]` is the value of the `pvVariableNameSuffix` argument, and the `[L]` part is the plausible value index, from 1 to `npv`.

The second argument is named `newpvvars` and is a list with an element for each set of construct that lists all of the variables in that construct.

When `returnPosterior` is TRUE returns `list` with three elements. One is named `posterior` and has one row per `idvar` level in the `newStuDat` argument and three columns:

- `id` the value of `idVar` in the model run

- `mu` the posterior mean

- `sd` the posterior standard deviation

the second list element is named `X` that is the design matrix for `newStuDat` (see Value for `mml`). The third list element is the `rr1` element returned from `mml` with one column for each individual in `newStuDat` (see Value in `mml`).

### Author(s)

Paul Bailey, Sun-joo Lee, and Eric Buehler

### Examples

    # See Examples in mml

[Package Dire version 2.0.1 Index]