various things

## tl;dr

* Two new functions, `describe` and `recode.na`
* … including documentation and examples
* Safer proportion tables that avoiding division by zero
* Raw residuals for the Chi-squared test
* Utilities to quickly scan/load/install packages

## describe – a clone of the Stata function to describe variables

This function complements the `lookfor` function by providing a quick way to describe any number of variables in a dataset, using variable labels when they have been imported with either the `foreign` or `memisc` packages.

The example shows how this works in a minimal way with standard R data frames, using one of the `questionr` example datasets (HDV 2003): 

    > describe(hdv2003, "age", "sexe", "lecture*", "frere|soeur")
    [1] "age"           "sexe"          "freres.soeurs" "lecture.bd"

The function becomes more useful once a dataset has variable labels, as with this SPSS example included in the `memisc` package (ANES 1948):

    > describe(nes1948, "v480050", "version|set", "v48004*")
    
    vversion 'NES VERSION NUMBER'      
    vdsetno  'NES DATASET NUMBER'      
    v480040  '41-USA'S CNCRN W OTHERS' 
    v480041  '41-SATISD USA TWRD RUSS' 
    v480042  '41-INFORMATION LEVEL'    
    v480043  '41-USA GV IN,AGRT RUSS'  
    v480044  '41-USA-RUSS AGRT VIA U.N'
    v480045  'SEX OF RESPONDENT'       
    v480046  'RACE OF RESPONDENT'      
    v480047  'AGE OF RESPONDENT'       
    v480048  'EDUCATION OF RESPONDENT' 
    v480049  'TOTAL 1948 INCOME'       
    v480050  'RELIGIOUS PREFERENCE'

The output is roughly similar for objects imported with `foreign`. The "*" and "|" wildcards trigger `grepl` searches to help finding variable names based on abbreviations, or to help with listing all variables in a series, as in `QA1, QA2, ..., QAx`.

This function complements `lookfor` by making it easy to access or search variable labels from R when working with survey datasets that include variable labels based on the survey questionnaire.

## raw residuals for the Chi-squared test

I have added a `raw` option to `chisq.residuals` to compute observed minus expected values.

## make frequency tables robust to zero values

An issue currently arises with proportion tables that contain completely empty rows or columns, which causes a division by zero while computing the percentages. To avoid that issue, the `drop` option (`TRUE` by default) gets rid of these values.

Here's an example table:

    > prop(table(d$health,d$raceb), drop = FALSE)
                         
                              White Black Hispanic Asian Total
      Excellent                19.3   3.4   5.0      1.2  29.0
      Very Good                21.7   4.1   5.2      1.2  32.1
      Good                     15.6   4.1   5.3      0.9  25.9
      Fair                      5.4   2.0   2.1      0.2   9.8
      Poor                      1.9   0.6   0.6      0.1   3.2
      Unknown-refused           0.0   0.0   0.0      0.0   0.0
      Unknown-not ascertained   0.0   0.0   0.0      0.0   0.0
      Unknown-don't know        0.0   0.0   0.0      0.0   0.0
      Total                    63.8  14.3  18.2      3.6 100.0

Here's the issue:

    > rprop(table(d$health,d$raceb), drop = FALSE)
                         
                              White Black Hispanic Asian Total
      Excellent                66.6  11.8  17.3      4.3 100.0
      Very Good                67.4  12.7  16.2      3.8 100.0
      Good                     60.1  16.0  20.4      3.5 100.0
      Fair                     55.4  20.9  21.5      2.2 100.0
      Poor                     59.0  20.1  19.3      1.7 100.0
      Unknown-refused           NaN   NaN   NaN      NaN   NaN
      Unknown-not ascertained   NaN   NaN   NaN      NaN   NaN
      Unknown-don't know        NaN   NaN   NaN      NaN   NaN
      Ensemble                 63.8  14.3  18.2      3.6 100.0

Here's the fix, applied by default:

    > rprop(table(d$health,d$raceb))
           
                White Black Hispanic Asian Total
      Excellent  66.6  11.8  17.3      4.3 100.0
      Very Good  67.4  12.7  16.2      3.8 100.0
      Good       60.1  16.0  20.4      3.5 100.0
      Fair       55.4  20.9  21.5      2.2 100.0
      Poor       59.0  20.1  19.3      1.7 100.0
      Ensemble   63.8  14.3  18.2      3.6 100.0

## recode.na – a flexible way to deal with missing values

The `recode.na` function recodes any number of levels in a variable to `NA` values. The levels can be numeric values or regular expressions.

The basic behaviour matches one or more exact strings in a factor and recodes them to `NA`:

    > ## With exact string matches.
    > hdv2003$nivetud = recode.na(hdv2003$nivetud, "Inconnu")
    Recoded 0 values to NA.

Just like with `describe`, you can throw regular expressions in the values: "*" and "|" are wildcards that trigger a regex match on the rest of the value.

    > ## With regular expressions.
    > hdv2003$relig = recode.na(hdv2003$relig, "[A|a]ppartenance", "Rejet|NSP")
    Recoded 1292 values to NA.

Numeric variables are converted to factors and recode values are coerced to strings, so you can send a numeric vector to the function and it should still work. Here's a truncation of the `freres.soeurs` variable to values under five:

    > ## Truncate a count variable.
    > freq(recode.na(hdv2003$freres.soeurs, 5:22), total = TRUE)
    Recoded 505 values to NA.
             n     %
    0      167   8.3
    1      407  20.3
    2      427  21.3
    3      284  14.2
    4      210  10.5
    NA     505  25.2
    Total 2000 100.0

## qload and qscan – utilities to deal with package loading/installation

`qload` is a quick way to load one or more packages silently, installing it first if necessary:

    # discourse analysis
    qload("qdap", "tm")

`qscan` scans one or more R scripts, finds all calls to `library` or `require`, and `qload` the list of packages it finds:

    # scan the working directory
    qscan()

Both utilities are ways to gain time with package installation and to avoid red ink when working in student groups. Unfortunately, I am not sure whether `qload` will work on R < 3.0.0 due to the use of the `quiet` argument in `install.packages`.

* * *

If you like these changes, I can add a Stata extract of the [National Health Interview Survey](http://www.cdc.gov/nchs/nhis/new_nhis.htm) (NHIS) in the package and add examples using it into the documentation. That would help illustrating recent changes and would also show how to manipulate a Stata dataset with `questionr`.