[LON-CAPA-cvs] cvs: loncom /homework grades.pm
albertel
lon-capa-cvs-allow@mail.lon-capa.org
Wed, 25 Jul 2007 00:00:25 -0000
This is a MIME encoded message
--albertel1185321625
Content-Type: text/plain
albertel Tue Jul 24 20:00:25 2007 EDT
Modified files:
/loncom/homework grades.pm
Log:
- more documentation
- some spelling fixes
--albertel1185321625
Content-Type: text/plain
Content-Disposition: attachment; filename="albertel-20070724200025.txt"
Index: loncom/homework/grades.pm
diff -u loncom/homework/grades.pm:1.423 loncom/homework/grades.pm:1.424
--- loncom/homework/grades.pm:1.423 Tue Jul 24 17:21:31 2007
+++ loncom/homework/grades.pm Tue Jul 24 20:00:23 2007
@@ -1,7 +1,7 @@
# The LearningOnline Network with CAPA
# The LON-CAPA Grading handler
#
-# $Id: grades.pm,v 1.423 2007/07/24 21:21:31 albertel Exp $
+# $Id: grades.pm,v 1.424 2007/07/25 00:00:23 albertel Exp $
#
# Copyright Michigan State University Board of Trustees
#
@@ -4357,9 +4357,47 @@
=head1 Bubble sheet grading routines
- (For this documentation 'scanline' refers to the full line of characters
- from the file that we are parsing 'bubble line' refers to the data
- representing the line of bubbles that are on the physical bubble sheet)
+ For this documentation:
+
+ 'scanline' refers to the full line of characters
+ from the file that we are parsing that represents one entire sheet
+
+ 'bubble line' refers to the data
+ representing the line of bubbles that are on the physical bubble sheet
+
+
+The overall process is that a scanned in bubble sheet data is uploaded
+into a course. When a user wants to grade, they select a
+sequence/folder of resources, a file of bubble sheet info, and pick
+one of the predefined configurations for what each scanline looks
+like.
+
+Next each scanline is checked for any errors of either 'missing
+bubbles' (it's an error because it may have been missed scanned
+because too light bubbling), 'double bubble' (each bubble line should
+have no more that one letter picked), invalid or duplicated CODE,
+invalid student ID
+
+If the CODE option is used that determines the randomization of the
+homework problems, either way the student ID is looked up into a
+username:domain.
+
+During the validation phase the instructor can choose to skip scanlines.
+
+After the validation phase, there is now 3 bubble sheet files
+
+ scantron_original_filename (unmodified original file)
+ scantron_corrected_filename (file where the corrected information has replaced the original information)
+ scantron_skipped_filename (contains the exact text of scanlines that where skipped)
+
+Also there is a separate hash nohist_scantrondata that contains extra
+correction information that isn't representable in the bubble sheet
+file (see &scantron_getfile() for more information)
+
+After all scanlines are either valid, marked as valid or skipped, then
+foreach line foreach problem in the picked sequence, an ssi request is
+made that simulates a user submitting their selected letter(s) against
+the homework problem.
=over 4
@@ -4531,7 +4569,7 @@
Generates the initial screen to start the bubble sheet process.
Allows for - starting a grading run.
- - downloading exisiting scan data (original, corrected
+ - downloading existing scan data (original, corrected
or skipped info)
- uploading new scan data
@@ -4589,7 +4627,7 @@
<td> Options: </td>
<td>
<label><input type="checkbox" name="scantron_options_redo" value="redo_skipped"/> Do only previously skipped records</label> <br />
- <label><input type="checkbox" name="scantron_options_ignore" value="ignore_corrections"/> Remove all exisiting corrections</label> <br />
+ <label><input type="checkbox" name="scantron_options_ignore" value="ignore_corrections"/> Remove all existing corrections</label> <br />
<label><input type="checkbox" name="scantron_options_hidden" value="ignore_hidden"/> Skip hidden resources when grading</label>
</td>
</tr>
@@ -4732,17 +4770,18 @@
'questions' start
Qlength - number of columns comprising a single bubble line from
the sheet. (usually either 1 or 10)
- Qon - either a single charater representing the character used
+ Qon - either a single character representing the character used
to signal a bubble was chosen in the positional setup, or
the string 'letter' if the letter of the chosen bubble is
in the final, or 'number' if a number representing the
chosen bubble is in the file (1->A 0->J)
- Qoff - the character used to represent that a buble was left blank
+ Qoff - the character used to represent that a bubble was
+ left blank
PaperID - if the scanning process generates a unique number for each
sheet scanned the column that this ID number starts in
PaperIDlength - number of columns that comprise the unique ID number
for the sheet of paper
- FirstName - column that the firs tname starts in
+ FirstName - column that the first name starts in
FirstNameLength - number of columns that the first name spans
LastName - column that the last name starts in
@@ -4793,7 +4832,7 @@
$classlist - reference to the class list hash. This is a hash
keyed by student name:domain whose elements are references
- to arrays containng various chunks of information
+ to arrays containing various chunks of information
about the student. (See loncoursedata for more info).
Returns
@@ -4813,7 +4852,7 @@
=pod
-=item scatron_fixup_scanline
+=item scantron_fixup_scanline
Process a requested correction to a scanline.
@@ -4832,12 +4871,12 @@
$args - hash of additional info,
- 'ID'
'newid' -> studentID to use in replacement
- of exisiting one
+ of existing one
- 'CODE'
'CODE_ignore_dup' - set to true if duplicates
should be ignored.
'CODE' - is new code or 'use_unfound'
- if the exisitng unfound code should
+ if the existing unfound code should
be used as is
- 'answer'
'response' - new answer or 'none' if blank
@@ -4920,7 +4959,7 @@
Arguments:
$scan_data - The hash (see scantron_getfile)
$key - shorthand of the key to edit (actual key is
- scatronfilename_key).
+ scantronfilename_key).
$data - New value of the hash entry.
$delete - If true, the entry is removed from the hash.
@@ -5107,13 +5146,13 @@
queue of messages to be shown after grading pass is complete
Arguments:
- $delayqueue - arrary ref of hash ref of erro messages
+ $delayqueue - arrary ref of hash ref of error messages
$scanline - the scanline that caused the error
$errormesage - the error message
$errorcode - a numeric code for the error
Side Effects:
- updates the $dealyqueue to have a new hash ref of the error
+ updates the $delayqueue to have a new hash ref of the error
=cut
@@ -5129,6 +5168,18 @@
=item scantron_find_student
+ Finds the username for the current scanline
+
+ Arguments:
+ $scantron_record - hash result from scantron_parse_scanline
+ $scan_data - hash of correction information
+ (see &scantron_getfile() form more information)
+ $idmap - hash from &username_to_idmap()
+ $line - number of current scanline
+
+ Returns:
+ Either 'username:domain' or undef if unknown
+
=cut
sub scantron_find_student {
@@ -5149,6 +5200,9 @@
=item scantron_filter
+ Filter sub for lonnavmaps, filters out hidden resources if ignore
+ hidden resources was selected
+
=cut
sub scantron_filter {
@@ -5171,6 +5225,9 @@
=item scantron_process_corrections
+ Gets correction information out of submitted form data and corrects
+ the scanline
+
=cut
sub scantron_process_corrections {
@@ -5234,6 +5291,10 @@
=item reset_skipping_status
+ Forgets the current set of remember skipped scanlines (and thus
+ reverts back to considering all lines in the
+ scantron_skipped_<filename> file)
+
=cut
sub reset_skipping_status {
@@ -5246,6 +5307,8 @@
=item start_skipping
+ Marks a scanline to be skipped.
+
=cut
sub start_skipping {
@@ -5263,6 +5326,8 @@
=item should_be_skipped
+ Checks whether a scanline should be skipped.
+
=cut
sub should_be_skipped {
@@ -5284,6 +5349,9 @@
=item remember_current_skipped
+ Discovers what scanlines are in the scantron_skipped_<filename>
+ file and remembers them into scan_data for later use.
+
=cut
sub remember_current_skipped {
@@ -5303,6 +5371,10 @@
=item check_for_error
+ Checks if there was an error when attempting to remove a specific
+ scantron_.. bubble sheet data file. Prints out an error if
+ something went wrong.
+
=cut
sub check_for_error {
@@ -5316,6 +5388,9 @@
=item scantron_warning_screen
+ Interstitial screen to make sure the operator has selected the
+ correct options before we start the validation phase.
+
=cut
sub scantron_warning_screen {
@@ -5354,6 +5429,9 @@
=item scantron_do_warning
+ Check if the operator has picked something for all required
+ fields. Error out if something is missing.
+
=cut
sub scantron_do_warning {
@@ -5391,6 +5469,8 @@
=item scantron_form_start
+ html hidden input for remembering all selected grading options
+
=cut
sub scantron_form_start {
@@ -5414,6 +5494,12 @@
=item scantron_validate_file
+ Dispatch routine for doing validation of a bubble sheet data file.
+
+ Also processes any necessary information resets that need to
+ occur before validation begins (ignore previous corrections,
+ restarting the skipped records processing)
+
=cut
sub scantron_validate_file {
@@ -5423,7 +5509,7 @@
my $default_form_data=&defaultFormData($symb);
# do the detection of only doing skipped records first befroe we delete
- # them when doing the corrections reset
+ # them when doing the corrections reset
if ($env{'form.scantron_options_redo'} ne 'redo_skipped_ready') {
&reset_skipping_status();
}
@@ -5442,7 +5528,7 @@
if ($env{'form.scantron_corrections'}) {
&scantron_process_corrections($r);
}
- $r->print("<p>Gathering neccessary info.</p>");$r->rflush();
+ $r->print("<p>Gathering necessary info.</p>");$r->rflush();
#get the student pick code ready
$r->print(&Apache::loncommon::studentbrowser_javascript());
my $max_bubble=&scantron_get_maxbubble();
@@ -5504,6 +5590,10 @@
=item scantron_remove_file
+ Removes the requested bubble sheet data file, makes sure that
+ scantron_original_<filename> is never removed
+
+
=cut
sub scantron_remove_file {
@@ -5525,6 +5615,11 @@
=item scantron_remove_scan_data
+ Removes all scan_data correction for the requested bubble sheet
+ data file. (In the case that both the are doing skipped records we need
+ to remember the old skipped lines for the time being so that element
+ persists for a while.)
+
=cut
sub scantron_remove_scan_data {
@@ -5554,6 +5649,24 @@
=item scantron_getfile
+ Fetches the requested bubble sheet data file (all 3 versions), and
+ the scan_data hash
+
+ Arguments:
+ None
+
+ Returns:
+ 2 hash references
+
+ - first one has
+ orig -
+ corrected -
+ skipped - each of which points to an array ref of the specified
+ file broken up into individual lines
+ count - number of scanlines
+
+ - second is the scan_data hash possible keys are
+
=cut
sub scantron_getfile {
@@ -5592,6 +5705,15 @@
=item lonnet_putfile
+ Wrapper routine to call &Apache::lonnet::finishuserfileupload
+
+ Arguments:
+ $contents - data to store
+ $filename - filename to store $contents into
+
+ Returns:
+ result value from &Apache::lonnet::finishuserfileupload
+
=cut
sub lonnet_putfile {
@@ -5607,6 +5729,16 @@
=item scantron_putfile
+ Stores the current version of the bubble sheet data files, and the
+ scan_data hash. (Does not modify the original version only the
+ corrected and skipped versions.
+
+ Arguments:
+ $scanlines - hash ref that looks like the first return value from
+ &scantron_getfile()
+ $scan_data - hash ref that looks like the second return value from
+ &scantron_getfile()
+
=cut
sub scantron_putfile {
@@ -5633,6 +5765,22 @@
=item scantron_get_line
+ Returns the correct version of the scanline
+
+ Arguments:
+ $scanlines - hash ref that looks like the first return value from
+ &scantron_getfile()
+ $scan_data - hash ref that looks like the second return value from
+ &scantron_getfile()
+ $i - number of the requested line (starts at 0)
+
+ Returns:
+ A scanline, (either the original or the corrected one if it
+ exists), or undef if the requested scanline should be
+ skipped. (Either because it's an skipped scanline, or it's an
+ unskipped scanline and we are not doing a 'do skipped scanlines'
+ pass.
+
=cut
sub scantron_get_line {
@@ -5647,6 +5795,17 @@
=item scantron_todo_count
+ Counts the number of scanlines that need processing.
+
+ Arguments:
+ $scanlines - hash ref that looks like the first return value from
+ &scantron_getfile()
+ $scan_data - hash ref that looks like the second return value from
+ &scantron_getfile()
+
+ Returns:
+ $count - number of scanlines to process
+
=cut
sub get_todo_count {
@@ -5664,6 +5823,19 @@
=item scantron_put_line
+ Updates the 'corrected' or 'skipped' versions of the bubble sheet
+ data file.
+
+ Arguments:
+ $scanlines - hash ref that looks like the first return value from
+ &scantron_getfile()
+ $scan_data - hash ref that looks like the second return value from
+ &scantron_getfile()
+ $i - line number to update
+ $newline - contents of the updated scanline
+ $skip - if true make the line for skipping and update the
+ 'skipped' file
+
=cut
sub scantron_put_line {
@@ -5680,6 +5852,15 @@
=item scantron_clear_skip
+ Remove a line from the 'skipped' file
+
+ Arguments:
+ $scanlines - hash ref that looks like the first return value from
+ &scantron_getfile()
+ $scan_data - hash ref that looks like the second return value from
+ &scantron_getfile()
+ $i - line number to update
+
=cut
sub scantron_clear_skip {
@@ -5695,6 +5876,9 @@
=item scantron_filter_not_exam
+ Filter routine used by &Apache::lonnavmaps::retrieveResources(), to
+ filter out resources that are not marked as 'exam' mode
+
=cut
sub scantron_filter_not_exam {
@@ -5717,6 +5901,9 @@
=item scantron_validate_sequence
+ Validates the selected sequence, checking for resource that are
+ not set to exam mode.
+
=cut
sub scantron_validate_sequence {
@@ -5746,6 +5933,9 @@
=item scantron_validate_ID
+ Validates all scanlines in the selected file to not have any
+ invalid or underspecified student IDs
+
=cut
sub scantron_validate_ID {
@@ -5814,6 +6004,30 @@
=item scantron_get_correction
+ Builds the interface screen to interact with the operator to fix a
+ specific error condition in a specific scanline
+
+ Arguments:
+ $r - Apache request object
+ $i - number of the current scanline
+ $scan_record - hash ref as returned from &scantron_parse_scanline()
+ $scan_config - hash ref as returned from &get_scantron_config()
+ $line - full contents of the current scanline
+ $error - error condition, valid values are
+ 'incorrectCODE', 'duplicateCODE',
+ 'doublebubble', 'missingbubble',
+ 'duplicateID', 'incorrectID'
+ $arg - extra information needed
+ For errors:
+ - duplicateID - paper number that this studentID was seen before on
+ - duplicateCODE - array ref of the paper numbers this CODE was
+ seen on before
+ - incorrectCODE - current incorrect CODE
+ - doublebubble - array ref of the bubble lines that have double
+ bubble errors
+ - missingbubble - array ref of the bubble lines that have missing
+ bubble errors
+
=cut
sub scantron_get_correction {
@@ -5945,7 +6159,7 @@
=item scantron_bubble_selector
Generates the html radiobuttons to correct a single bubble line
- possibly showing the exisiting the selected bubbles if known
+ possibly showing the existing the selected bubbles if known
Arguments:
$r - Apache request object
@@ -6021,6 +6235,16 @@
=item num_matches
+ Counts the number of characters that are the same between the two arguments.
+
+ Arguments:
+ $orig - CODE from the scanline
+ $code - CODE to match against
+
+ Returns:
+ $count - integer count of the number of same characters between the
+ two arguments
+
=cut
sub num_matches {
@@ -6038,6 +6262,20 @@
=item scantron_get_closely_matching_CODEs
+ Cycles through all CODEs and finds the set that has the greatest
+ number of same characters as the provided CODE
+
+ Arguments:
+ $allcodes - hash ref returned by &get_codes()
+ $CODE - CODE from the current scanline
+
+ Returns:
+ 2 element list
+ - first elements is number of how closely matching the best fit is
+ (5 means best set has 5 matching characters)
+ - second element is an arrary ref containing the set of valid CODEs
+ that best fit the passed in CODE
+
=cut
sub scantron_get_closely_matching_CODEs {
@@ -6054,6 +6292,17 @@
=item get_codes
+ Builds a hash which has keys of all of the valid CODEs from the selected
+ set of remembered CODEs.
+
+ Arguments:
+ $old_name - name of the set of remembered CODEs
+ $cdom - domain of the course
+ $cnum - internal course name
+
+ Returns:
+ %allcodes - keys are the valid CODEs, values are all 1
+
=cut
sub get_codes {
@@ -6082,6 +6331,10 @@
=item scantron_validate_CODE
+ Validates all scanlines in the selected file to not have any
+ invalid or underspecified CODEs and that none of the codes are
+ duplicated if this was requested.
+
=cut
sub scantron_validate_CODE {
@@ -6139,6 +6392,9 @@
=item scantron_validate_doublebubble
+ Validates all scanlines in the selected file to not have any
+ bubble lines with multiple bubbles marked.
+
=cut
sub scantron_validate_doublebubble {
@@ -6168,6 +6424,13 @@
=item scantron_get_maxbubble
+ Returns the maximum number of bubble lines that are expected to
+ occur. Does this by walking the selected sequence rendering the
+ resource and then checking &Apache::lonxml::get_problem_counter()
+ for what the current value of the problem counter is.
+
+ Caches the result to $env{'form.scantron_maxbubble'}
+
=cut
sub scantron_get_maxbubble {
@@ -6200,6 +6463,9 @@
=item scantron_validate_missingbubbles
+ Validates all scanlines in the selected file to not have any
+ bubble lines with missing bubbles that haven't been verified as missing.
+
=cut
sub scantron_validate_missingbubbles {
@@ -6474,7 +6740,7 @@
=item valid_file
- Vaildates that the requested bubble data file has exists in the course.
+ Validates that the requested bubble data file exists in the course.
=cut
--albertel1185321625--