---
title: "Introduction to PROscorer"
author: "Ray Baser"
date: "`r Sys.Date()`"
output:
rmarkdown::html_vignette:
toc: true
toc_depth: 3
vignette: >
%\VignetteIndexEntry{Introduction to PROscorer}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
## Overview
The _PROscorer_ package is an extensible repository of functions to score
specific patient-reported outcome (PRO), quality of life (QoL), and other
psychometric measures and questionnaire-based instruments commonly used in
research.
(Note: For simplicity, from here forward I will collectively and somewhat
imprecisely refer to these types of instruments as "PRO measures", "PRO-like
instruments", or just "PROs".)
Recent efforts by International Society for Quality of Life Research (ISOQOL)
taskforces have sought to standardize the reporting, analysis, and protocol
descriptions of PRO measures. However, no best practice guidance nor
standardized software exists for scoring PROs. The _PROscorer_ project was
designed to establish best practices for scoring PROs by providing a system to
standardize the scoring and documentation of commonly-used PROs. Importantly,
the _PROscorer_ R package also facilitates the integration of PRO scoring into
scientifically reproducible workflows.
Each function in the *PROscorer* package scores a different PRO measure.
Functions are named using the initials of the PRO measure. For example, the
`fsfi` function scores the Female Sexual Function Index (FSFI).
*PROscorer* also comes with a vignette containing detailed descriptions of each
of the instruments scored by *PROscorer* (see main
[PROscorer](https://cran.r-project.org/package=PROscorer) page on CRAN). The
purpose of including these instrument descriptions, complete with references, is
to help improve the descriptions of PRO measures in protocols, grants, and
published results. In most cases, the descriptions can be used in research
documents with little or no editing.
To minimize the possibility of scoring errors and other bugs, each *PROscorer*
function is composed of simpler, well-tested "helper" functions from the
[PROscorerTools](https://CRAN.R-project.org/package=PROscorerTools) package.
This reliance on a small set of simple functions that have been thoroughly
tested ensures that the underlying code base of *PROscorer* functions is
bug-free, and that the scoring functions produce reliable, consistent, and
accurate results.
*PROscorer*, together with the *PROscorerTools* package, is a system to
facilitate the incorporation of PRO measures into research studies and clinical
settings in a scientifically rigorous and reproducible manner. The overarching
goals of the *PROscorer* and *PROscorerTools* packages are to draw attention to
best-practices for PRO scoring and reporting, and to help eliminate inaccurate
and inconsistent scoring by standardizing the scoring procedures for commonly
used PRO measures.
## The Problem
The scientific rigor and reproducibility of research involving PRO, QoL, and
similar measures is lagging behind other research areas. Three major reasons
for these shortcomings are (1) measurement error introduced by faulty scoring
procedures, (2) inconsistent application of scoring instructions across
different studies using the same PRO measures, and (3) inadequate, incomplete,
and/or inaccurate descriptions of PRO-like measures in research protocols and in
published results of studies that incorporate such measures.
Scoring procedures represent a major source of error in research studies that
rely upon PRO and similar measures. These errors typically go unnoticed,
hidden, and/or ignored, eroding the scientific integrity of the research and
hindering progress in the numerous scientific fields that conduct studies that
use these measures.
Similarly, inconsistent application of PRO scoring procedures and variation in
scoring across studies makes study results less likely to replicate and slows
the accumulation of reliable scientific data from the PRO measure.
Inadequate, incomplete, and/or inaccurate descriptions of PRO-like measures in
research documents can cause confusion and introduce errors, oversights, and
other mistakes at multiple stages in the research process.
## The Proposed Solution
The **PROscorer** package provides a standardized framework for addressing these
problems with research involving PRO-like measures. The lofty goal of the
**PROscorer** package is to eliminate these serious deficiencies in PRO-based
research by serving as the gold-standard open-source repository of scoring
syntax and instrument descriptions for PRO-like measures commonly used in
research and clinical settings.
The features of the **PROscorer** package and supporting infrastructure were
carefully planned with this ambitious goal in mind.
## Summary of Key Features
* **PROscorer** serves as the repository of scoring functions for specific,
commonly-used PRO measures (e.g., the EORTC QLQ-C30).
* Each function scores a specific PRO instrument (e.g., the `qlq_c30` function
scores the EORTC QLQ-C30 quality of life questionnaire).
* Protocol- and manuscript-ready descriptions of each PRO instrument are
included in the supplementary documentation (i.e., vignettes).
* Each function has thorough, helpful documentation.
* Consistent naming conventions are used for functions and function arguments
(e.g., functions are named using the initials of the instrument).
* Scoring functions require minimal user input.
* Functions are composed modularly from a small number of reusable, well-tested
"helper" functions. A separate package, _PROscorerTools_, contains these helper
functions.
* This minimizes the chances of programming errors and other bugs.
* This enhances the scalability and extensibility of _PROscorer_ by making
it easier and faster to update _PROscorer_ to score additional PROs.
* Advanced users can use _PROscorerTools_ to write functions to score their
favorite PROs, and then submit them on GitHub for inclusion in future
_PROscorer_ updates.
* Makes it easy to incorporate PRO scoring into reproducible scientific
workflows.
## Installation and Usage
Install the stable version of *PROscorer* from CRAN:
```{r eval=FALSE}
install.packages("PROscorer")
```
Load *PROscorer* into your R workspace with the following:
```{r eval=FALSE, message = FALSE}
library(PROscorer)
```
As an example, we will use the `makeFakeData` function from the *PROscorerTools*
package to make fake item responses to the EORTC QLQ-C30 quality of life
questionnaire. The created data set (named "dat") has an "id" variable, plus
responses to 30 items (named "q1", "q2", etc.) from 20 imaginary respondents.
There are also missing responses ("NA") scattered throughout.
```{r eval=FALSE}
dat <- PROscorerTools::makeFakeData(n = 20, nitems = 30, values = 1:4, id = TRUE)
dat
```
Below we will use the `qlq_c30` function to score the fake responses in "dat".
We will save the scores from the EORTC QLQ-C30 questionnaire in a data frame
named "c30scores".
```{r eval=FALSE}
c30scores <- qlq_c30(dat, 'q')
c30scores
```
The first argument to `qlq_c30` took our data frame, "dat". With the second
argument, we needed to tell the `qlq_c30` function how to find our items in
"dat". Since our items are all named with the prefix "q" plus the item number,
we gave this quoted prefix to the second argument. These arguments actually
have names, but in most cases you don't have to explicitly use the names. Below
gives the same results, but explicitly uses the argument names.
```{r eval=FALSE}
c30scores <- qlq_c30(df = dat, iprefix = 'q')
c30scores
```
Specifically, the first argument is named `df` (for **d**ata **f**rame) and the
second is named `iprefix` (for **i**tem prefix).
If you want to merge your scores back into your main data frame with the item
responses, there are several different ways to do so. For example, assuming you
have not changed the order of `dat` or `dat_scored`, you can do the following:
```{r eval=FALSE}
dat_scored <- data.frame(dat, c30scores)
dat_scored
```
For more information on the `qlq_c30` function, you can access its "help" page
by typing `?qlq_c30` into R.
## Future Development Plans
The *PROscorer* family of R packages includes
[PROscorer](https://CRAN.R-project.org/package=PROscorer),
[PROscorerTools](https://CRAN.R-project.org/package=PROscorerTools), and
[FACTscorer](https://github.com/raybaser/FACTscorer). With respect to
developing **PROscorer**, my priorities are:
1. Expand *PROscorer* with more scoring functions for specific PROs. Some of
the EORTC instruments are high on my list.
2. Further refine some behind-the-scenes standards for how the functions should
be programmed, and write guides for users wishing to program and contribute
their own PRO scoring functions to *PROscorer*.
3. Finalize the collaborative infrastructure (e.g., on GitHub) by which users
can use *PROscorerTools* to write scoring functions for their favorite PROs and
submit them for inclusion in *PROscorer*. A major component of this is to
create a few instructional vignettes, including a step-by-step guide for writing
the scoring functions, guidelines for writing the instrument descriptions, and
templates for writing the function documentation.
4. Make the unit testing framework of *PROscorer* and *PROscorerTools* more
comprehensive. Most of the code underlying the 8 functions will be already be
tested by the *PROscorerTools* tests; however, I intend to come up with a
standard set of tests for *PROscorer* functions to make it easier for me and
others to add unit tests to their scoring functions.
5. Write some educational vignettes on PRO scoring methods and best practices.
6. Add capability to generate IRT-based scores for PROs that use that scoring
method. I know many researchers that use various PROMIS measures. They would
prefer to use the IRT-based scoring method, but find it too difficult to
integrate into their research workflow. *PROscorer* could make IRT-based scores
accessible to a much wider group of researchers.
## Resources for More Information
* You can access the "help" page for the **PROscorer** package by typing
`?PROscorer` into R.
* Supplemental documentation, including the Instrument Descriptions, can be
found in the [PROscorer
vignettes](https://CRAN.R-project.org/package=PROscorer). You can access them
from the [main PROscorer webpage on
CRAN](https://CRAN.R-project.org/package=PROscorer). More vignettes will be
added in future updates.
* If you need to score PRO measures from the the FACT (Functional Assessment of
Cancer Therapy) and FACIT (Functional Assessment of Chronic Illness Therapy)
family of measures, please see the [FACTscorer
package](https://github.com/raybaser/FACTscorer).
* The underlying code base of the
[PROscorer](https://CRAN.R-project.org/package=PROscorer) package is built from
functions from the [PROscorerTools
package](https://CRAN.R-project.org/package=PROscorerTools).
* The **PROscorerTools** documentation and vignettes might also be helpful. You
can access them from the main [PROscorerTools webpage on
CRAN](https://CRAN.R-project.org/package=PROscorerTools). More vignettes will
be added in future updates.
* If you have any feature requests, or you want to report bugs or other strange
behavior in *PROscorer*, please submit them to me on the [PROscorer
GitHub page](https://github.com/raybaser/PROscorer/issues).