"""
Functions for aggregating and analyzing exam-related data, such as calculating
student exam performance.
"""
import csv
import os
import pandas as pd
[docs]def grade_scantron(
input_scantron, correct_answers, drops=[], item_value=1, incorrect_threshold=0.5
):
"""
Calculate student grades from scantron data.
Compiles data collected from a scantron machine (5-option multiple choice
exam) and calculates grades for each student. Also provides descriptive
statistics of exam performance, as well as a list of the questions "most"
students got incorrect, and saves the distribution of answers for those
poorly performing questions.
This function receives 1 scantron text file and produces 2 output files.
Splitting of the scantron data is specific to each scantron machine. The
indices used in this function are correct for the scantron machine in the
UBC Psychology department as of 2015. Indices need to be adjusted for
different machines.
Scantron exams can be finicky. Students who incorrectly fill out scantrons
need to be considered. Make sure to manually inspect the text file output
by the scantron machine for missing answers before running this. This
function does not correct for human error when filling out the scantron.
Parameters
----------
input_scantron : string
Path to the .txt file produced by the scantron machine.
correct_answers : list
A list of strings containing the *correct* exam answers. For example:
["A", "E", "D", "A", B"]. The order must match the order of
presentation on the exam (i.e. the first list item must correspond
to the first exam question)
drops : list, optional
List of integers containing question numbers that should be excluded
from calculation of grades. For example: [1, 5] will not include
questions 1 and 5 when calculating exam scores.
item_value : int, optional
Integer representing how many points each exam question is worth.
incorrect_threshold : float between [0., 1.], optional
Poorly performing questions are those where few students got the
correct answer. This parameter sets the threshold at which an item is
considered poor. For example, a threshold of 0.4 means that a poor
item is considered to be one where less than 40% of students
chose the correct answer.
"""
# Start and end locations of various pieces of information in the scantron text file.
# These need to be adjusted for different scantron machine.
# Currently set for the machine used in UBC Psychology
surname_idx = (0, 12)
first_name_idx = (12, 21)
student_num_idx = (21, 30)
answers_idx = 30
# output directory
directory, filename = os.path.split(input_scantron)
filename = os.path.splitext(filename)[0]
# calculate total number of points available on the exam
total_points = (len(correct_answers) * item_value) - len(drops)
# create a pandas dataframe to hold the scantron data
summary = ["surname", "first_name", "student_number", "points", "percent"]
questions = ["Q-{}".format(i + 1) for i in range(len(correct_answers))]
df = pd.DataFrame(columns=summary + questions)
# calculate grades
with open(input_scantron, "r") as f:
scantron_data = csv.reader(f)
# loop through every row (student) in the input scantron file
for row in scantron_data:
surname = row[0][surname_idx[0] : surname_idx[1]].lstrip().rstrip()
first_name = row[0][first_name_idx[0] : first_name_idx[1]].lstrip().rstrip()
student_num = (
row[0][student_num_idx[0] : student_num_idx[1]].lstrip().rstrip()
)
answers = row[0][answers_idx : (answers_idx + len(correct_answers))]
points = 0
for i, pair in enumerate(zip(answers, correct_answers)):
if i + 1 not in drops:
if pair[0] == pair[1]:
points += item_value
df_summary = {
"surname": surname,
"first_name": first_name,
"student_number": student_num,
"points": points,
"percent": (points / total_points) * 100,
}
df_questions = {"Q-{}".format(i + 1): a for i, a in enumerate(answers)}
df = df.append([{**df_summary, **df_questions}], ignore_index=True)
df.to_excel(
os.path.join(directory, "{}.xls".format(filename + "_grades")),
sheet_name="grades",
index=False,
)
# write summary statistics
with open(
os.path.join(directory, "{}.txt".format(filename + "_summary")), "w"
) as f:
# calculate descriptive statistics
N = df.shape[0]
mean_percent = df["percent"].mean()
mean_points = df["points"].mean()
std_points = df["points"].std()
range_points = (df["points"].min(), df["points"].max())
f.writelines(
[
"Descriptive Statistics: \n\n",
"N: {}\n".format(N),
"Mean %: {:.2f}%\n".format(mean_percent),
"Mean score (out of {} points): {:.2f}\n".format(
total_points, mean_points
),
"Score SD: {:.2f}\n".format(std_points),
"Range: {} (Min: {}, Max: {})\n\n\n".format(
range_points[1] - range_points[0], range_points[0], range_points[1]
),
]
)
if len(drops) > 0:
f.writelines(
["Dropped questions: {}\n\n\n".format(", ".join(map(str, drops)))]
)
f.writelines(
[
"Problem Items (questions that less "
"than {}% of students got correct):\n\n".format(
incorrect_threshold * 100
)
]
)
problems = False
for i, item in enumerate(questions):
cur_q = df[item]
if len(cur_q[cur_q == correct_answers[i]]) < (N * incorrect_threshold):
problems = True
distribution = cur_q.value_counts()
f.writelines(
[
"{} (A: {}, B: {}, C: {}, D: {}, E: {})\n".format(
cur_q.name,
distribution.A,
distribution.B,
distribution.C,
distribution.D,
distribution.E,
)
]
)
if not problems:
f.writelines(["None"])