Import and Analysis of OMR Data from FormScanner

Description

Import data of tests and questionnaires from FormScanner. FormScanner is an open source software that converts scanned images to data using optical mark recognition (OMR) and it can be downloaded from <http://sourceforge.net/projects/formscanner/>. The spreadsheet file created by FormScanner is imported in a convenient format to perform the analyses provided by the package. These analyses include the conversion of multiple responses to binary (correct/incorrect) data, the computation of the number of corrected responses for each subject or item, scoring using weights, the computation and the graphical representation of the frequencies of the responses to each item and the report of the responses of a few subjects.

Details

Data of questionnaires and tests are often collected on paper forms. FormScanner is an open source software that converts scanned images to data using optical mark recognition (OMR). Function read.formscanner of the fsia package can be used to import data from FormScanner in R. The correct response (key) can be specified using function addkey. It is also possible to specify weights for each response using function addweights. If items have a key, data can be converted to binary variables using function resp2binary. In this case, the number of corrected responses for each person and for each item can also be computed by using functions person.stat and item.stat. These functions can also be used to compute a score using the weights previously specified. Function freq calculates the absolute or percentage frequencies of the responses to each item. The frequencies can be printed on screen or plotted on a graph. In both cases, the true responses (if any) are highlighted. The responses given by one or a few subjects can be displayed on a graph by using function report. The key is shown on the right and wrong responses can be immediately identified by the red colour.

The package includes two data sets for illustrative purposes. Data sets test and questionnaire contain the result of importing csv files with function read.formscanner. Data set key contains the correct responses of the items of the test data sets. Data set weights contains the weights of each correct response, while data set weights_multiple contains the weights of each response.

Author(s)

Michela Battauz

Maintainer: Michela Battauz <michela.battauz@uniud.it>

References

Borsetta, A. (2017). FormScanner [Computer Software], URL http://sourceforge.net/projects/formscanner/.

Examples

# IMPORT DATA FROM FORMSCANNER
# find the directory with package fsia
dir_pkg <- find.package("fsia")
# the example files are in the directory examples
# create the path
questionnaire_path <- file.path(dir_pkg, "examples", "scan_results_questionnaire.csv")
test_path <- file.path(dir_pkg, "examples", "scan_results_test.csv")
# import file "scan_results_questionnaire.csv"
questionnaire_imp<-read.formscanner(questionnaire_path, dummy = "Q5.sources")
questionnaire_imp
# questionnaire_imp is equal to the data questionnaire
# import file "scan_results_test.csv"
test_imp <- read.formscanner(test_path, conc = paste("id", 1:6, sep = ""), id = "id1")
test_imp
# test_imp is equal to the data test

# ADD THE KEY
# create the path for file "key.csv"
key_path <- file.path(dir_pkg, "examples", "key.csv")
# add the key 
testk <- addkey(test_imp, keyfile = key_path)
testk$key

# ADD WEIGHTS
# create the path for file "weights.csv"
weights_path <- file.path(dir_pkg, "examples", "weights.csv")
# specify the weights for each correct response
testw <- addweights(testk, weightsfile = weights_path)
testw$weights
# create the path for file "weights_multiple.csv"
weights_mult_path <- file.path(dir_pkg, "examples", "weights_multiple.csv")
# specify the weights for each response
testwm <- addweights(test_imp, weightsfile = weights_mult_path)
testwm$weights

# CONVERT DATA TO BINARY VARIABLES
resp01 <- resp2binary(obj = testk, col = 2:41)
resp01[, 2:5]

# ASSIGN WEIGHTS TO RESPONSES
resps <- resp2scores(obj = testw, col =2:41)
resps[, 2:5]

# ASSIGN WEIGHTS TO RESPONSES (MULTIPLE WEIGHTS)
resps <- resp2scores(obj = testwm, col =2:41)
resps[, 2:5]

# PERSON STATISTICS (selected only 4 items)
pst <- person.stat(obj = testk, col = 2:5)
pst
pst <- person.stat(obj = testw, col = 2:5, weights = TRUE)
pst
pst <- person.stat(obj = testwm, col = 2:5, weights = TRUE)
pst

# ITEM STATISTICS
ist <- item.stat(obj = testk, col = 2:41)
head(ist)
ist <- item.stat(obj = testw, col = 2:41, weights = TRUE)
head(ist)
ist <- item.stat(obj = testwm, col = 2:41, weights = TRUE)
head(ist)

# FREQUENCIES OF THE RESPONSES
fr <- freq(obj = testk, col = c("Question03", "Question04"))
fr
par(mfrow = c(1, 2))
plot(fr, ask = FALSE)

# RESPONSES OF TWO SUBJECTS
par(mfrow = c(1, 2))
report(obj = testk, col = 2:11, whichid = c("102344", "245784"))
report(obj = testw, col = 2:11, whichid = c("102344", "245784"), weights = TRUE)
par(mfrow = c(1, 1))
report(obj = testwm, col = 2:11, whichid = c("102344", "245784"), weights = TRUE)

Add a Key to a Data Frame

Description

Adds the correct responses (key) to a data frame.

Usage

addkey(obj, keyline = NULL, keyfile = NULL, keydata = NULL)

Arguments

Details

keyfile and keydata can contain more items than obj. In this case, items not contained in obj are dropped in the output.

Value

A list with data, key, and eventually weights.

Author(s)

Michela Battauz

See Also

addweights

Examples

data(test)
data(key)
testk <- addkey(test, keydata = key)

Add a Weights to a Data Frame

Description

Adds the weights associated with the responses to the items to a data frame.

Usage

addweights(obj, weightsfile = NULL, weightsdata = NULL)

Arguments

Details

If weightsfile and weightsdata have only one row, they should contain the weights that are assigned to the correct responses. These are defined by addkey. To specify a different weight to every response of each item, weightsfile and weightsdata should have one row for each response. In this case there should be a field named response.

weightsfile and weightsdata can contain more items than obj. In this case, items not contained in obj are dropped in the output.

Value

A list with data, eventually key, and weights.

Author(s)

Michela Battauz

See Also

addkey

Examples

data(test)
data(key)
data(weights)
data(weights_multiple)
testk <- addkey(test, keydata = key)
testw <- addweights(testk, weightsdata = weights)
testwm <- addweights(test, weightsdata = weights_multiple)

Absolute and Percentage Frequencies of the Responses to the Items.

Description

Calculates and plots the absolute or percentage frequencies of the responses to each item.

Usage

freq(obj, columns, perc = FALSE)
## S3 method for class 'frlist'
plot(x, display = TRUE, ask = TRUE, ...)

Arguments

Value

Function freq returns an abject of class frlist containing a list with components

Author(s)

Michela Battauz

See Also

read.formscanner

Examples

data(test)
data(key)
testk <- addkey(test, keydata = key)

fr <- freq(obj = testk, col = c("Question03", "Question04"))
fr
par(mfrow=c(1,2))
plot(fr, ask = FALSE)
fr <- freq(obj = testk, col = 2:11, perc = TRUE)
fr
par(mfrow = c(2,5))
plot(fr, ask = FALSE)

Item Statistics

Description

This function computes some statistics for each item.

Usage

item.stat(obj, columns, weights = FALSE)

Arguments

Value

A data frame with the following variables.

Author(s)

Michela Battauz

See Also

person.stat

Examples

data(test)
data(key)
data(weights)
data(weights_multiple)

testk <- addkey(test, keydata = key)
testw <- addweights(testk, weightsdata = weights)
testwm <- addweights(test, weightsdata = weights_multiple)

# number of correct responses for each item
ist <- item.stat(obj = testk, col = 2:41)
head(ist)
# sum of weights of correct responses for each item
ist <- item.stat(obj = testw, col = 2:41, weights = TRUE)
head(ist)
# sum of weights of every response for each item
ist <- item.stat(obj = testwm, col = 2:41, weights = TRUE)
head(ist)

Key of Items

Description

This data set contains the correct responses of the items in the test data set.

Usage

data("key")

Format

A data frame with variables Question01 - Question40.

Author(s)

Michela Battauz

See Also

addkey

Examples

data(key)
key

Person Statistics

Description

This function computes some statistics for each person.

Usage

person.stat(obj, columns, weights = FALSE)

Arguments

Value

A data frame with the following variables.

Author(s)

Michela Battauz

See Also

person.stat

Examples

data(test)
data(key)
data(weights)
data(weights_multiple)

testk <- addkey(test, keydata = key)
testw <- addweights(testk, weightsdata = weights)
testwm <- addweights(test, weightsdata = weights_multiple)

# number of correct responses for each person (only 4 items)
pst <- person.stat(obj = testk, col = 2:5)
pst
# sum of weights of correct responses for each person
pst <- person.stat(obj = testw, col = 2:5, weights = TRUE)
pst
# sum of weights of every response for each person
pst <- person.stat(obj = testwm, col = 2:5, weights = TRUE)
pst

Questionnaire Responses

Description

This data set contains responses to a questionnaire.

Usage

data("questionnaire")

Format

A data frame with 5 observations on the following 14 variables.

Details

This data set is obtained by importing file "scan_results_questionnaire.csv" with function read.formscanner.

Author(s)

Michela Battauz

See Also

read.formscanner

Examples

data(questionnaire)
questionnaire

Import Data From FormScanner

Description

This function imports data from the FormScanner software.

Usage

read.formscanner(file, col.names, conc = NULL, id = NULL, dummy = NULL)

Arguments

Details

If some columns are concatenated using argument conc, the name of the newly created variable is the name of the first column.

test and questionnaire are instances of the output of function read.formscanner.

When id is obtained as the concatenation of different columns using argument conc, id should be set equal to the first column concatenated.

Value

A data frame.

Author(s)

Michela Battauz

References

Borsetta, A. (2016). FormScanner, [Computer Software], URL http://sourceforge.net/projects/formscanner/.

See Also

addkey, addweights

Examples

# find the directory with package fsia
dir_pkg <- find.package("fsia")
# the example files are in the directory examples
# create the path
questionnaire_path <- file.path(dir_pkg, "examples", "scan_results_questionnaire.csv")
test_path <- file.path(dir_pkg, "examples", "scan_results_test.csv")
# import file "scan_results_questionnaire.csv"
questionnaire_imp<-read.formscanner(questionnaire_path, dummy = "Q5.sources")
questionnaire_imp
# questionnaire_imp is equal to the data questionnaire
# import file "scan_results_test.csv"
test_imp <- read.formscanner(test_path, conc = paste("id", 1:6, sep = ""), id = "id1")
test_imp
# test_imp is equal to the data test

Report the Responses

Description

This function produces a graphic with the responses given by one or a few subjects and shows the correct ones.

Usage

report(obj, columns, whichid, grid = TRUE, main = "", las = 0, itemlab = NULL, 
  weights = FALSE)

Arguments

Details

Correct responses are colored green, wrong responses are colored red.

Author(s)

Michela Battauz

See Also

read.formscanner

Examples

data(test)
data(key)
data(weights)
data(weights_multiple)

testk <- addkey(test, keydata = key)
testw <- addweights(testk, weightsdata = weights)
testwm <- addweights(test, weightsdata = weights_multiple)

par(mfrow = c(1, 2))
report(obj = testk, col = 2:11, whichid = c("102344", "245784"))
report(obj = testw, col = 2:11, whichid = c("102344", "245784"), weights = TRUE)
par(mfrow = c(1, 1))
report(obj = testwm, col = 2:11, whichid = c("102344", "245784"), weights = TRUE)

Convert Responses to Binary Data

Description

Converts data to binary (correct/incorrect) responses, according to the key.

Usage

resp2binary(obj, columns)

Arguments

Value

The data frame data contained in obj with columns replaced by binary data.

Author(s)

Michela Battauz

See Also

read.formscanner

Examples

data(test)
data(key)

testk <- addkey(test, keydata = key)

resp01 <- resp2binary(obj = testk, col = 2:41)
resp01

Convert Responses to Scores

Description

Assigns a weight to the responses.

Usage

resp2scores(obj, columns)

Arguments

Value

The data frame data contained in obj with columns replaced by scored responses.

Author(s)

Michela Battauz

See Also

read.formscanner

Examples

data(test)
data(key)
data(weights)
data(weights_multiple)

testk <- addkey(test, keydata = key)
testw <- addweights(testk, weightsdata = weights)
testwm <- addweights(test, weightsdata = weights_multiple)

# ASSIGN WEIGHTS TO RESPONSES
resps <- resp2scores(obj = testw, col =2:41)
resps[, 2:5]

# ASSIGN WEIGHTS TO RESPONSES (MULTIPLE WEIGHTS)
resps <- resp2scores(obj = testwm, col =2:41)
resps[, 2:5]

Test Responses

Description

This data set contains multiple choice responses to 40 items.

Usage

data("test")

Format

A data frame with 5 observations on the following 44 variables.

Details

This data set is obtained by importing file "scan_results_test.csv" with function read.formscanner.

Author(s)

Michela Battauz

See Also

key, read.formscanner, weights, weights_multiple

Examples

data(test)
test

Weights of Items

Description

This data set contains the weights of the correct responses of the items in the test data set.

Usage

data("weights")

Format

A data frame with variables Question01 - Question40.

Author(s)

Michela Battauz

See Also

addweights

Examples

data(weights)
weights

Weights of each Response of the Items

Description

This data set contains the weights of each responses of the items in the test data set.

Usage

data("weights_multiple")

Format

A data frame with variables

Author(s)

Michela Battauz

See Also

addweights

Examples

data(weights_multiple)
weights_multiple