Response Analyzer Web Service - ddra.its.uiowa.eduS(kl2bex45ia02dw553bvqe1md))/ra... · Response Analyzer Web Service USER/DEVELOPER DOCUMENTATION August 2007 Version 1.0 Credit for

Copyright © 1995 – 2007 The University of Iowa 1

Response Analyzer Web Service USER/DEVELOPER DOCUMENTATION August 2007 Version 1.0

Credit for the instructional design theory and algorithms employed in Response Analyzer goes to Stephen Alessi and Steve Bowers (see Response Analyzer 1.0, The University of Iowa, 1995)


Table of Contents

Getting Started With Response Analyzer ....................................................... 3

The Purpose of Response Analyzer ................................................................................. 3 Requirements for Using Response Analyzer ................................................................... 3 Abbreviations Used in this Manual ................................................................................. 4 Response Analyzer Overview ......................................................................................... 4 Simple Program Flow ...................................................................................................... 5 Notes on Parameter Formats ........................................................................................... 6

Core Response Analyzer Commands ............................................................. 7

raInit ................................................................................................................................ 8 raFound .......................................................................................................................... 10 raDispose ....................................................................................................................... 11 raMessage ...................................................................................................................... 12

Commands for Obtaining Response Difference Information ....................... 13

raDiffAmount ................................................................................................................ 14 raDiffCounts .................................................................................................................. 15 raDiffList ....................................................................................................................... 16 raDiffReport .................................................................................................................. 17

Commands for Customizing Response Analyzer ......................................... 18

raSetWeight ................................................................................................................... 19 raSetWbChars ................................................................................................................ 20 raSetPuncChars .............................................................................................................. 21 raSetReplace .................................................................................................................. 22 raSetRepWithSp ............................................................................................................ 24 raSetRemove .................................................................................................................. 26 raSetRemoveWords ....................................................................................................... 28 raSetRemoveControl ..................................................................................................... 29 raSetRemoveExtended .................................................................................................. 30 raSetRemoveExtraWbs .................................................................................................. 31 raSetEqWords ................................................................................................................ 32

Appendix A: Error Codes and Error Messages ........................................... 33

Error Codes .................................................................................................................... 33 Error Messages .............................................................................................................. 34

Appendix B: How Response Analyzer Analyzes ........................................ 37


Getting Started With Response Analyzer This section contains information that will help you get started with Response Analyzer, explaining the requirements for using it, the basic concepts involved, and some details on calling syntaxes. The Purpose of Response Analyzer Response Analyzer is a tool intended to aid software designers in the processing of natural text, primarily words and short phrases. It allows the software designer to compare expected words or phrases with those typed by end users. End users’ typing may include a very large number of typographical errors. For example, a simple 8-letter word such as “software” can have over 400 different typographical errors due to omitting any single letter (e.g., softwre), adding any extra letter in any position (softwaare), typing a different letter (softwore), or reversing letters (sotfware). The “brute force” method, in which the software designer lists all the possible mistyped forms of a word or phrase is impractical given the number that are possible. Response Analyzer recursively goes through the designer’s expected strings and the end user’s typed strings to determine if they are reasonably similar. It does this not only for the four types of errors just discussed, but for capitalization, punctuation, word-break errors, and word-level errors (e.g., extra word). We created Response Analyzer to assist in educational web sites, where the student may type an answer to a question (e.g., Who was the first president of the United States?) and the program must detect not only possible correct responses even if they are mistyped (e.g., Georg Washington), but also expected incorrect responses even if they are mistyped (e.g., Abraham Lincon) and possibly requests for help or questions from the student (e.g., give me a hintt). However, Response Analyzer is not limited to use in educational web sites, but to any which allow users to type words (e.g., to initiate searches or ask questions). Requirements for Using Response Analyzer Response Analyzer is provided as a web service accessible through the Simple Object Access Protocol (SOAP). If you do not know what a web service is, and haven’t heard of SOAP, we recommend a basic search on these topics using your web browser and your favorite internet search engine. We won’t cover these topics here.

Any web application development tool that supports SOAP can call Response Analyzer routines. This includes the vast majority of languages and tools (Flash, PHP, .NET development languages, JAVA, JavaScript, etc.). Developers should have a good working knowledge of the programming languages and tools they will use.

Developers must have a developer ID (identifier), which can be obtained from the Response Analyzer Information and Registration website at:

http://ddra.its.uiowa.edu

Along with their ID, developers will receive information clarifying the URL to use when connecting to the web service. Developers should also spend time looking around the registration website, as it contains further information they will find useful—running demos, downloadable source samples, and supplemental documentation for using Response Analyzer with specific programming languages.

In order to use Response Analyzer effectively, developers must also have an understanding of the concepts employed in Response Analyzer and detailed knowledge of how routines operate. This document provides comprehensive information on both of these topics.


Abbreviations Used in this Manual

The following abbreviations are used in this manual: <sp> Space character (ASCII/ANSI code 32) <cr> Carriage Return (ASCII/ANSI code 13) <ff> Formfeed (ASCII/ANSI code 12) <lf> Linefeed (ASCII/ANSI code 10) <ht> Horizontal tab (ASCII/ANSI code 9) <vt> Vertical tab (ASCII/ANSI code 11)

Response Analyzer Overview

Response Analyzer is a set of author-customizable routines facilitating intelligent judging of "free-text" answers (answers freely entered from the keyboard by a user). The Response Analyzer is primarily intended for use by developers of instructional software, but its design is flexible enough to be useful to any software developer needing to respond to textual input.

The primary analyzer routine (raFound) takes as parameters an "object string" (a string of characters the author expects the user to enter), a "response string" (the string actually entered by the user—e.g., in response to an interaction), and an integer "leniency value" indicating the extent to which the response string may differ from the object string yet still be considered acceptable. raFound compares the object and response strings, then returns true or false (whether or not the response string "matches" the object string within the leniency). All combinations of the types of differences shown in the table below are recognized. Note that the author may give each difference type an integer weight (the defaults are shown).

Difference Type Weight Author Expects (Object) User Enters (Response) Missing character 1 George Gerge Extra character 1 George Georrge Different character 1 George Jeorge Character reversal 1 George Goerge Different character case 0 George george Missing word-break character 1 George<sp>Washington GeorgeWashington Extra word-break character 0 George<sp>Washington George<sp><sp>Washington Different word-break character 1 George<sp>Washington George<cr>Washington Word-break character reversal 0 George<sp><cr>Washington George<cr><sp>Washington Missing punctuation character 0 Washington,<sp>George Washington<sp>George Extra punctuation character 0 Washington,<sp>George Washington,,<sp>George Different punctuation character 0 Washington,<sp>George Washington.<sp>George Punctuation character reversal 0 "George<sp>Washington!" "George<sp>Washington"! Words or numbers not found 5 George<sp>Washington Washington Extra words or numbers 0 George<sp>Washington Mr.<sp>George<sp>Washington Words or numbers out of order 2 George<sp>Washington Washington<sp>George

The weights for differences found when comparing the object and response strings are totaled. A result of true means the total is less than or equal to the author-supplied leniency value.

It is important to note that the processor compares the object and response in two stages. The first stage is a series of pre-processing steps that perform such actions on the strings as replacing characters with other characters and removing characters such as control characters. In the second stage, the strings are compared and the differences found are totaled. Both stages are completely customizable by the author (see the raSet… routines, below, for information on customization, or Appendix B. for a detailed explanation of the stages).


Besides the simple true/false value returned by raFound, authors may call other routines to retrieve specifics about the differences found. There are many options, such as the total of the associated weights for the differences that were found, the number of particular difference types that were found, etc. The author can also request a textual report listing the number of instances found for each difference type.

Finally, primarily as a development aid, the analyzer can return messages to the author about any errors (such as calling syntax or invalid parameter values) that occurred during the last Response Analyzer call.

Simple Program Flow The commands raInit, raFound, and raDispose form the core of Response Analyzer. Many developers can provide adequate free-text answer judging using just these three commands, and merely taking Response Analyzer’s default settings, which enable analysis of English-language responses and use average leniency. Many developers will also find the command raMessage essential. raMessage, immediately following any other Response Analyzer call, returns a string containing any error messages the previous call produced. Since this information can be essential in debugging, raMessage is included along with raInit, raFound, and raDispose in the “Core Response Analyzer Commands” section. The commands listed in the second section, entitled “Commands for Obtaining Response Difference Information,” are useful when a developer wants more information about differences than the simple true/false indicator returned by raFound. These commands, all beginning with the string “raDiff,” provide means of obtaining aggregate and individual differences, in numerous forms. The third and final section, “Commands for Customizing Response Analyzer,” contains numerous commands allowing a developer to adjust many aspects of Response Analyzer. Each of these commands, whose names begin with the string “raSet,” allows customization of a particular aspect affecting pre-processing or comparison stages. For example, since Response Analyzer is UNICODE-enabled, sets of characters and words can be adjusted to provide for analysis of response strings in German or another language of your choice. The description below outlines the basic flow of an application handling free-text interactions with Response Analyzer. • raInit is the command that sets everything up, and therefore the first command called. The developer

provides some information used in creating a unique session ID, which raInit returns, required by following calls pertaining to the same interaction. As mentioned above, initial Response Analyzer settings ready it to compare English-language strings using average leniency.

• raMessage is used while testing an application during development. A call to raMessage returns a

string containing any error messages and warnings resulting from the previous call (e.g., raInit in this example). When application testing has been completed, the developer can remove raMessage calls.

• raSet… routines may optionally be utilized here to customize the behavior of Response Analyzer. See

the section “Commands for Customizing Response Analyzer” for details on these routines. Also see Appendix B for a description of Response Analyzer’s algorithm, which will be helpful in understanding how to customize settings.


Then, the flow becomes a loop, processing response strings with the current Response Analyzer settings. A response string is obtained from a student/user as a result to an interaction.

• raFound is called, passing the expected (object) string, the response string, and an acceptable leniency value expressed as an integer. Response Analyzer performs analysis, and returns true or false (whether the response string "matches" the object string within the leniency).

Depending upon whether more information is desired:

• raDiff… routines may be utilized to obtain more information about the differences that were found in the response string. This information can be used to provide more specific feedback, or for numerous other purposes.

• raDispose frees the memory used by Response Analyzer session on the server. When the application

is complete, or the user chooses to quit, etc. the developer calls raDispose. Notes on Parameter Formats Each description of a Response Analyzer routine in this document first contains a description of the routine’s calling syntax. Where parameters are necessary, a type and mnemonic descriptor are shown for each parameter, as well as default values, if there are any. Conventions of the C# language are used for all examples in this document. Supplementary documents describing parameter passage and syntax for specific languages (e.g., Flash, JavaScript) can be found at the Response Analyzer Information and Registration website.

Parameter Types int: an integer (number) or a variable containing an integer string: a string or a variable containing a string. String parameters are surrounded by double

quotes ("this is a string") boolean: A value that can be “true” or “false” type[ ]: Brackets following a type indicate a list or array of the variable type. For example,

“new int[] {3, 6, 9, 12}” and ”new int {17}” are both arrays of integers, the latter being an array of only one element.

Enumerations: C# enumerations define some additional parameter types in the Response

Analyzer web service (e.g., DiffType, below) consisting of a set of named constants (e.g., MISS_CHAR, EXT_CHAR, …), having the underlying type of int, where the first enumerator (e.g., MISS_CHAR) has the value 0 and each successive enumerator increases by 1. The enumerations are defined to add meaning to parameters that indicate selected options, in that mnemonic string values (MISS_CHAR) can be passed instead of integer values (0) as selectors. Any language that does not handle enumerations must pass the enumeration as an actual string (e.g., “MISS_CHAR”). (Note: examples of calling syntax for specific languages other than C#, such as Flash or Javascript, are contained in supplemental documents available at the information and registration website.)

The following enumeration types are defined in the Drill Designer web service: DiffType = MISS_CHAR, EXT_CHAR, DIFF_CHAR, REV_CHAR, CASE_CHAR, MISS_WB, EXT_WB, DIFF_WB, REV_WB, MISS_PUNC, EXT_PUNC, DIFF_PUNC, REV_PUNC, WORD_NOT_FOUND, EXT_WORD, WORD_ORD, ALL Locations = BME, B, M, E, A


Core Response Analyzer Commands As mentioned earlier in the description of simple program flow, there are four commands that form the core of Response Analyzer:

raInit raFound raDispose raMessage

These commands are described in this section on the following pages. Using these commands alone, with default settings, developers can provide adequate free-text answer judging for many English-language applications. (Other commands, described in the section “Commands for Customizing Response Analyzer”, can be used to change default settings in order to set up Response Analyzer for use with a language other than English).


raInit

C# Syntax: int raInit (

string developerId, string interactionId, string studentId )

Parameters: PARAMETER

DESCRIPTION DEFAULT VALUE

developerId The secret developer ID given to each developer during registration.

interactionId A name (e.g., “citynames”) uniquely identifying the set of interactions this application makes with Response Analyzer from those made by other applications by the same developer. interactionID is used in creating the returned session ID that is passed in following calls.

studentId The ID associated with the student or user of the application. The ID must be unique to a student/user within the application to prevent collisions with simultaneous users. The literal string “$Unique$” may be passed to have a unique student ID generated by Response Analyzer.

Returns: The session ID to be used for subsequent Response Analyzer calls made in the same session. An error code may be returned instead of the session ID (see Appendix A).

Description: raInit must be called once by any application that uses Response Analyzer, and must be called before any other Response Analyzer routines can be called. raInit initializes the Response Analyzer's weights, character sets, and rules to default values the processor uses when comparing object and response strings. raInit takes three parameters to create a unique session in memory used by following calls from the same client-side application instance. raInit returns a session ID referencing the session. All other Response Analyzer routines pass this session ID as a first parameter. Note: as a convenience for developers when a unique student ID is not obtainable, a studentId of “$Unique$” may be passed, causing Response Analyzer to internally generate and maintain a unique student ID associated with the returned session ID. Up to 100 such sessions are allowed per developer, per interaction. Also note that this limit is not in place when regular student IDs are supplied by the developer. The default weights, character sets, and rules set by raInit are described in the section “Commands for Customizing Response Analyzer,” along with the descriptions of the commands used in modifying them. The default settings enable analysis of English-language responses using an average leniency that is adequate for many applications.


Note that Response Analyzer provides support for UNICODE, and commands listed in the “Commands for Customizing…” section can be used to change Response Analyzer’s behavior for use with languages other than English.

C# Example: sessionId = WebService.raInit(developerId, InteractionId, StudentId);


raFound

C# Syntax: int raFound (

int sessionId, string obj, string resp, int leniencyVal )



sessionId The session ID returned by raInit. obj The string of characters the student/user is

expected to enter to be exactly matched (referred to as the “object string”).

resp The string of characters the student/user entered (the “response string”).

leniencyVal An integer value indicating the numeric threshold beyond which the strings are not considered equivalent.

0

Returns: An integer value that can be: zero (0) meaning false, one (1) meaning true, or a negative number, indicating an error code (see Appendix A).

Description: raFound is the primary Response Analyzer routine. It takes as parameters an "object string"—a string the student/user is expected to enter to be exactly matched, a “response string”—the actual string the student/user entered; and leniencyVal, an integer "leniency value" indicating the extent to which differences in the response and object strings are acceptable. RAFound compares the object and response strings, returning an indication of whether the response string matches the object string within the leniency or not. Note that the weights set during initialization (i.e., raInit) or with a call to raSetWeight are used in totaling the amount of difference between the object and response. As an example, consider the following object and response strings with a current weight of 2 for character reversal and 1 for missing character. The difference between the two strings below would equal 4 (1 reversal and 2 missing characters). If raFound was called passing these strings and a leniencyVal of 4 or greater, raFound would return a one (1) meaning true—the response was acceptably equivalent within the leniency allowed.

Object Response George Washington Goerge Wahingto

C# Example: raFoundState = WebService.raFound(sessionId, objStr, respStr, 3);


raDispose

C# Syntax: int raDispose (int sessionId)



sessionId The session ID returned by raInit.

Returns: A 0 (zero) if successful, or an error code (see Appendix A).

Description: raDispose frees the memory used by a Response Analyzer session (identified by sessionId). When an application that uses Response Analyzer has finished (for example, when the user has requested to quit) raDispose should be called to cleanly free memory utilized during the session’s interactions. If raDispose is not called, the session will eventually timeout and be cleared from memory, but until then, memory is being wasted by an unused session.

C# Example: disposeState = WebService.raDispose(sessionId);


raMessage

C# Syntax: string raMessage (int sessionId)




Returns: A string containing one or more error messages generated during the previous Response Analyzer call, or an empty string indicating that no error occurred. Error messages are listed alphabetically in Appendix A.

Description: raMessage returns a string containing the error message(s) that were generated by the previous Response Analyzer call. Some error messages indicate that the previous command could not be executed, while others are merely warnings signifying that, although the command was executed, certain parameters were not specified appropriately and defaults were used instead. raMessage is useful for the developer while creating an application to ensure that all commands are recognized and that parameters are appropriate. Once the application is executing correctly, calls to raMessage may be removed at the developer’s discretion. When there is no error or warning from the previous call, raMessage returns an empty string. Therefore, testing for a zero-length return string can be used as a flag. All error messages are listed in Appendix A, with further clarification of their meaning, and indication of whether the command executed. Important related note: All routines that return an integer type may return an error code instead of the expected return value. Error codes are negative numbers corresponding to particular error types. For any of these where a valid session ID is still held, a following call to raMessage may provide more detail. See Appendix A for details of both error codes and error messages. raMessage itself does not generate error messages or change the last message generated by another call.

C# Example: errMsg = WebService.raMessage(sessionId);


Commands for Obtaining Response Difference Information Response Analyzer contains several commands allowing you to obtain more information about differences found during the last object-response comparison than the simple true/false indicator returned by raFound. These commands all begin with the string “raDiff.”

raDiffAmount raDiffCounts raDiffList raDiffReport


raDiffAmount

C# Syntax: int raDiffAmount (int sessionId)




Returns: A single integer number containing the total difference amount found for the last comparison done through raFound. May also return a negative value, indicating an error code (see Appendix A).

Description: raDiffAmount returns a single number that indicates the total difference found between the last object and response string compared through raFound. The total is the summation of all differences found multiplied by their associated weights. For example, using the following object and response strings, and the default weights set by raInit,


raDiffAmount would return 3, as shown in the following table.

Difference Found Count Weight Total for this difference Missing Character 2 1 2 Character Reversal 1 1 1 Grand total : 3

C# Example: totDiffAmt = WebService.raDiffAmount(sessionId);


raDiffCounts

C# Syntax: int raDiffCounts (

int sessionId, DiffType diff )



sessionId The session ID returned by raInit. diff An enumeration specifying the type of difference

the count is being requested for.

Returns: An integer number containing the count of differences of type diff found for the last comparison done through raFound. May also return a negative value, indicating an error code (see Appendix A).

Description: raDiffCounts returns a single number that indicates the count of differences of type diff found between the last object and response string compared through raFound. The value of parameter diff may be any of those listed in the following table. Note that “all” is included, which will return the count of all differences found (not the same as “difference amount” [see raDiffAmount, above], since weights are not factored in).

Possible values for parameter diff. MISS_CHAR EXT_CHAR DIFF_CHAR REV_CHAR CASE_CHAR MISS_WB EXT_WB DIFF_WB REV_WB MISS_PUNC EXT_PUNC DIFF_PUNC REV_PUNC WORD_NOT_FOUND EXT_WORD WORD_ORD ALL

Using the following object and response strings,


raDiffCounts would return 2 for MISS_CHAR, 1 for REV_CHAR, and 3 for ALL, as can be seen in the following table.

Difference Found Count Missing Character 2 Character Reversal 1 All 3

C# Example: countMissingChars = WebService.raDiffCounts(sessionId, DiffType.MISS_CHAR);


raDiffList

C# Syntax: string raDiffList (int sessionId)




Returns: A string containing a list of space-separated integer values. May also return an error message in the event of a bad session ID being passed.

Description: raDiffList can be called to obtain a list of the individual counts of differences found. The return string contains 17 space-separated integer values in the order of, and corresponding to, the difference types as listed below. raDiffList provides a way for developers to retrieve all of the difference totals at once, but developers will likely need to extract totals from the string.

1) missing character(s) 2) extra character(s) 3) different character(s) 4) reversed character(s) 5) character case difference(s) 6) missing word break character(s) 7) extra word break character(s) 8) different word break character(s) 9) reversed word break character(s) 10) missing punctuation character(s) 11) extra punctuation character(s) 12) different punctuation character(s) 13) reversed punctuation character(s) 14) word(s) not found 15) extra word(s) 16) word(s) out of order 17) total count of all differences found

Using the following object and response strings,


raDiffList would return the following string

2 0 0 1 0 0 0 0 0 0 0 0 0 0 0 0 3

C# Example: diffList = WebService.raDiffList(sessionId);


raDiffReport

C# Syntax: string raDiffReport (int sessionId)




Returns: A string containing a report detailing the differences found. May also return an error message in the event of a bad session ID being passed.

Description: raDiffReport returns a string containing a report detailing the differences found in the last raFound call. Using the following object and response strings, and the default weights,

Object Response George Washington Goorge washingtan!

raDiffReport would return the following string

Object string before pre-processing: George Washington Object string after pre-processing: George Washington Response string before pre-processing: Goorge washingtan! Response string after pre-processing: Goorge washingtan Leniency value = 2 Returned value = True Weight Count Total Difference Type 1 0 0 missing character(s). 1 0 0 extra character(s). 1 2 2 different character(s). 1 0 0 reversed character(s). 0 1 0 case difference(s). 1 0 0 missing word-break character(s). 0 0 0 extra word-break character(s). 1 0 0 different word-break character(s). 0 0 0 reversed word-break character(s). 0 0 0 missing punctuation character(s). 0 0 0 extra punctuation character(s). 0 0 0 different punctuation character(s). 0 0 0 punctuation character reversal(s). 5 0 0 object word(s) or number(s) not found. 0 0 0 extra word(s) or number(s) in the response. 2 0 0 word(s) or number(s) out of order. ----- ----- 3 2

C# Example: diffReport = WebService.raDiffReport(sessionId);


Commands for Customizing Response Analyzer Response Analyzer also contains a set of commands that allow a developer to adjust many aspects of Response Analyzer’s processing mechanism, both pre-processing and comparison stages. These commands all begin with the string “raSet.” Appendix B provides a detailed description of Response Analyzer’s entire analysis process. Reviewing Appendix B can help in using and understanding the commands in this section.

raSetWeight raSetWbChars raSetPuncChars raSetReplace raSetRepWithSp raSetRemove raSetRemoveWords raSetRemoveControl raSetRemoveExtended raSetRemoveExtraWbs raSetEqWords


raSetWeight

C# Syntax: int raSetWeight (

int sessionId, DiffType diff, int weight )



sessionId The session ID returned by raInit. diff An enumeration specifying the type of difference

the weight applies to.

weight An integer value to set for the difference type.

Returns: A 0 (zero) if the weight was set successfully, or a negative number, i.e., an error code (see Appendix).

Description: raSetWeight is used to change the weight associated with any difference type. The values passed for parameter diff must be one of the enumeration values listed below, corresponding to the difference types. Note that the value for parameter weight must be between 0 and 100. Values outside this range are ignored (the weight is left at its current setting).

Possible values for parameter diff. MISS_CHAR EXT_CHAR DIFF_CHAR REV_CHAR CASE_CHAR MISS_WB EXT_WB DIFF_WB REV_WB MISS_PUNC EXT_PUNC DIFF_PUNC REV_PUNC WORD_NOT_FOUND EXT_WORD WORD_ORD

The default weights set with the initial call to raInit are:

Missing character 1 Extra character 1 Different character 1 Character reversal 1 Different character case 0 Missing word-break character 1 Extra word-break character 0 Different word-break character 1 Word-break character reversal 0 Missing punctuation character 0 Extra punctuation character 0 Different punctuation character 0 Punctuation character reversal 0 Words or numbers not found 5 Extra words or numbers 0 Words or numbers out of order 2

C# Example: returnValue = WebService.raSetWeight(sessionId, DiffType.CASE_CHAR, 1);


raSetWbChars

C# Syntax: int raSetWbChars (

int sessionId, string wBs )



sessionId The session ID returned by raInit. wBs A string containing the characters Response

Analyzer is to consider as word-break characters.

Returns: A 0 (zero) if command completed successfully, or a negative number indicating an error code (see Appendix A).

Description: raSetWbChars is used to change the set of characters Response Analyzer views as word breaks. Every valid (described below) word-break character in string wBs will be used in defining the word-break set. The following abbreviations indicate the default word-break characters in effect after the raInit call:

<sp><ff><lf><cr><ht><vt> They are: the space character (ASCII or ANSI code 32), the formfeed character (ASCII or ANSI code 12), the linefeed character (ASCII or ANSI code 10), the carriage return (ASCII or ANSI code 13), the horizontal tab (ASCII or ANSI code 9), and the vertical tab (ASCII or ANSI code 11). Alphanumeric characters (e.g., 123 and ABC) are not allowed in this set. The space character is always included in this set, whether the developer specifies it or not. Note that characters are not allowed to be both in the set of word-break characters and in the set defining punctuation characters (see below). If the author specifies as a word break a character that is presently in the set of characters treated as punctuation, the character is removed from the punctuation set. Up to 127 word-break characters are allowed. At this point, it may be worthwhile to clarify what the Response Analyzer views as a "word". As you'd expect, a word is bounded on each side by a word-break character (or the beginning or end of the string). Leading and trailing punctuation characters are not considered part of the word. However, punctuation that occurs within a word is considered part of the word (e.g., “they’re”).

C# Example: returnValue = WebService.raSetWbChars(sessionId, myWordBreakStr);


raSetPuncChars

C# Syntax: int raSetPuncChars (

int sessionId, string puncs )



sessionId The session ID returned by raInit. puncs A string containing the characters Response

Analyzer is to consider as punctuation characters.


Description: raSetPuncChars is used to change the set of characters Response Analyzer views as punctuation. Every valid (described below) punctuation character in string puncs will be used in defining the punctuation set. Parameter puncs may be up to 127 characters in length. The following are the default punctuation characters in effect after the raInit call:

. ? ! , ; : ' " - ( ) [ ] { } They are: the period, question mark, exclamation point, comma, semicolon, colon, single quote, double quote, hyphen, parentheses, square brackets, and curly brackets. Alphanumeric characters (e.g., 123 and ABC) are not allowed in this set. Any characters currently in the word-break character set are also not allowed.

C# Example: returnValue = WebService.raSetPuncChars(sessionId, myPunctuationStr);


raSetReplace

C# Syntax: int raSetReplace (

int sessionId, string replace, string replaceWith )



sessionId The session ID returned by raInit. replace A string containing any characters Response

Analyzer should replace with other characters in the first pre-processing step.

replaceWith A string containing characters Response Analyzer should use in replacing those in corresponding positions in replace during the first pre-processing step.


Description: raSetReplace enables developers to control the first Response Analyzer pre-processing step (listed as step 2 in Appendix B). In that step, Response Analyzer replaces chosen characters in the object and response strings, wherever they occur, with another character. For example, suppose you want to replace any occurrence of an exclamation point character with a space character. To specify this, you place an exclamation point character in the replace parameter and a space in the replaceWith parameter. To be associated, the two characters need to be in the same character position in the two strings. You may also specify that a character should be removed, rather than replaced with another, by not having a corresponding character in the replaceWith parameter. Note in the following example replace replaceWith !% <sp> that there is only one space in the replaceWith parameter, which would be associated with the exclamation point in replace, since they are in the same string position. The percent sign in replace has no associated character in replaceWith, so any occurrence of a percent sign in either the object or response string would be removed (replaced with null). You can see that any characters to be replaced with another character must be listed in replace before those that will just be removed, since the characters to replace with must be listed in the corresponding positions in replaceWith.


Following are the default replace and replaceWith characters that are in effect after the call to raInit: replace replaceWith <cr><ht>?!;:#$%&(*)/<=>@[\]^_`{|}~ <sp><sp><sp><sp><sp><sp> The carriage return, horizontal tab, question mark, exclamation point, semicolon, and colon are replaced with a space. The other listed characters are removed (replaced with null). Note that any characters are allowed in the replace and replaceWith parameters, but developers should take care to avoid unintentionally removing word-break characters, etc. Also note that replace and replaceWith may be up to 255 characters long.

C# Examples: returnValue = WebService.raSetReplace(sessionId, myReplaceStr, myReplaceWithStr); returnValue = WebService.raSetReplace (sessionId, “?!;#”, “”);


raSetRepWithSp

C# Syntax: int raSetRepWithSp (

int sessionId, Locations loc, string nonNum, string num )



sessionId The session ID returned by raInit. loc An enumeration indicating a position around

words and numbers (possible values and meanings described below).

nonNum A string indicating characters to replace with space when encountered in location loc around words.

num A string indicating characters to replace with space when encountered in location loc around numbers.


Description: raSetRepWithSp and raSetRemove (see following command) provide developer control of the Response Analyzer pre-processing steps that replace with space and remove characters from specified locations surrounding words and numbers in the object and response strings (listed as steps 3 - 5 in Appendix B). The possible values for parameter loc, and their meanings are as follows: loc Meaning BME when occurring at the beginning, middle, or end of B when occurring at the beginning of M when occurring in the middle of E when occurring at the end of A when occurring alone (for example, between words or numbers) The following table indicates the defaults in effect for raSetRepWithSp after raInit:

Chars to repl. with space at begin., mid., or end of at beginning of in middle of at end of when alone

Non-numeric words [.,"+-] ['] [] ['] Outside words (e.g., between words) []

Numbers [] [,'"] [] [,'"]

Clarification: period, comma, double quote, plus sign, and dash (or minus sign) are replaced with space when occurring at the beginning, middle, or end of non-numeric words. Single quote (apostrophe) is replaced with space when occurring at the beginning or end of non-numeric words (but not in the middle).


Comma, single quote, and double quote are replaced with space when occurring at the beginning or end of numbers. Note that with raSetRepWithSp the space character and alphanumeric characters are not allowed in the nonNum and num parameters. nonNum and num may contain up to 127 characters. Also note that characters determined to be a part of a number will not be replaced (for example, an author cannot replace a negative sign at the beginning of a number with a space). With both raSetRepWithSp and raSetRemove, the general pre-processing sequence flows like this:

1) Pre-processing of numbers occurs first. Numbers are found anywhere they occur within the object and response strings (even within words), and characters around the numbers are replaced with space or removed as indicated. A number is any sequence of characters in this pattern: 1) an optional plus or minus sign followed by 2) a sequence of decimal digits possibly containing a single decimal point, and 3) an optional exponent part, consisting of the letter e or E, an optional sign, and a sequence of decimal digits.

2) After the pre-processing of numbers is complete, non-numeric words are pre-processed and

designated characters around them are replaced with space or removed. As mentioned earlier, words are surrounded by word breaks or beginning/end of line and do not include leading or trailing punctuation.

3) After non-numeric words are pre-processed, characters to replace with space or remove when

alone (for example, between words) are found and handled.

C# Example: returnValue = WebService.raSetRepWithSp (sessionId, Locations.BME, “+-”, “”);


raSetRemove

C# Syntax: int raSetRemove (

int sessionId, Locations loc, string nonNum, string num )



sessionId The session ID returned by raInit. loc An enumeration indicating a position around

words and numbers (possible values and meanings described below).

nonNum A string indicating characters to remove when encountered in location loc around words.

num A string indicating characters to remove when encountered in location loc around numbers.


Description: raSetRemove and raSetRepWithSp (see above) provide developer control of the Response Analyzer pre-processing steps that remove and replace with space any characters from specified locations surrounding words and numbers in the object and response strings (listed as steps 3 - 5 in Appendix B). The possible values for parameter loc, and their meanings are as follows: loc Meaning BME when occurring at the beginning, middle, or end of B when occurring at the beginning of M when occurring in the middle of E when occurring at the end of A when occurring alone (for example, between words or numbers) The following table indicates the defaults in effect for raSetRemove after raInit:

Chars to remove at begin., mid., or end of at beginning of in middle of at end of when alone

Non-numeric words [] [] [] [] Outside words (e.g., between words) [.,"'+-]

Numbers [] [] [,'"] [+-]

Clarification: comma, single quote, and double quote are removed when occurring in the middle of numbers. Plus sign and minus sign (or dash/hyphen) are removed when occurring at the end of numbers.


Period, comma, single quote, double quote, plus sign, and minus sign (dash/hyphen) are removed when occurring alone (for example between words). Note that with raSetRemove word-break characters and alphanumeric characters are not allowed in the nonNum and num parameters. nonNum and num may contain up to 127 characters. Also note that characters determined to be a part of a number will not be removed (for example, an author cannot remove a negative sign at the beginning of a number). With both raSetRepWithSp and raSetRemove, the general pre-processing sequence flows like this:

1) Pre-processing of numbers occurs first. Numbers are found anywhere they occur within the object and response strings (even within words), and characters around the numbers are replaced with space or removed as indicated. A number is any sequence of characters in this pattern: 1) an optional plus or minus sign followed by 2) a sequence of decimal digits possibly containing a single decimal point, and 3) an optional exponent part, consisting of the letter e or E, an optional sign, and a sequence of decimal digits.

2) After the pre-processing of numbers is complete, non-numeric words are pre-processed and

designated characters around them are replaced with space or removed. As mentioned earlier, words are surrounded by word breaks or beginning/end of line and do not include leading or trailing punctuation.

3) After non-numeric words are pre-processed, characters to replace with space or remove when

alone (for example, between words) are found and handled.

C# Example: returnValue = WebService.raSetRemove (sessionId, Locations.E, “”, “+-”);


raSetRemoveWords

C# Syntax: int raSetRemoveWords (

int sessionId, String[] words )



sessionId The session ID returned by raInit. words An array of strings indicating words to remove

from the object and response during pre-processing.


Description: raSetRemoveWords provides developer control of the pre-processing step that removes specified words from the object and response strings (listed as step 6 in Appendix B). The default words to remove, set by raInit, are the English articles “a,” “an”, and “the.” Note that when the words specified by raSetRemoveWords are removed, only the words themselves are removed from the object and response—no leading or trailing punctuation characters or word breaks. Also note that parameter words may contain no more than 15 words and each word may be no longer than 64 characters in length.

C# Example: returnValue = WebService.raSetRemoveWords (sessionId, new String[] {“a”, “an”, “the”});


raSetRemoveControl

C# Syntax: int raSetRemoveControl (

int sessionId, bool remove )



sessionId The session ID returned by raInit. remove A Boolean indicating whether control characters

are to be removed from the object and response strings.


Description: raSetRemoveControl provides developer control of the pre-processing step that removes control characters (ASCII or ANSI codes 0 – 31 and 127) from the object and response strings (listed as step 7 in Appendix B). The default for this state, set by raInit, is “true.” raSetRemoveControl can be passed false to cause control characters to be left in the object and response.

C# Example: returnValue = WebService.raSetRemoveControl (sessionId, true);


raSetRemoveExtended

C# Syntax: int raSetRemoveExtended (




sessionId The session ID returned by raInit. remove A Boolean indicating whether extended characters

are to be removed from the object and response strings.


Description: raSetRemoveExtended provides developer control of the pre-processing step that removes extended characters (ASCII or ANSI codes 128 - 255) from the object and response strings (listed as step 8 in Appendix B). The default for this state, set by raInit, is “true.” raSetRemoveExtended can be passed false to cause extended characters to be left in the object and response.

C# Example: returnValue = WebService.raSetRemoveExtended (sessionId, true);


raSetRemoveExtraWbs

C# Syntax: int raSetRemoveExtraWbs (




sessionId The session ID returned by raInit. remove A Boolean indicating whether extra word-break

characters are to be removed from the object and response strings.


Description: raSetRemoveExtraWbs provides developer control of the pre-processing step that removes extra word-break characters from the object and response strings (listed as step 9 in Appendix B). The default for this state, set by raInit, is “true.” When this state is set to true, Response Analyzer changes any stretch of two or more word breaks into one, and removes any word breaks occurring before the first word. raSetRemoveExtraWbs can be passed false to cause extra word-break characters to be left in the object and response.

C# Example: returnValue = WebService.raSetRemoveExtraWbs (sessionId, true);


raSetEqWords

C# Syntax: int raSetEqWords (

int sessionId, float eq )



sessionId The session ID returned by raInit. eq A floating-point numeric value used in determining

how many differences may exist between two words that may still be considered possible matches.


Description: After pre-processing (i.e., beginning with step 10 in Appendix B), the analyzer compares the object and response strings. In doing so, it breaks the object and response into "chunks" (roughly "words"—see step 10 in Appendix B for more details) and looks for matches. Matches are not simply identical matches, but sub-strings that are acceptably similar. For example, the sub-strings George and Gerge are possible matches (they differ by 1 missing character). raSetEqWords allows you to specify, as a percentage, how much two chunks may differ yet still be considered possible matches. The amount they may differ (eq) is specified as a floating-point numeric value, with a default of 0.25 set after the raInit call. eq may range from 0 to 0.34 (i.e., chunks may differ by up to roughly 1/3 and still be considered possible matches). If the passed value is out of range, it is ignored (current setting for eq remains in effect). The smallest two compared chunks are 2 characters long (for example, a 1-letter word and an associated word break). A minimum of 1 difference is always allowed for possible matches, regardless of word size (for example, chunks "Ha " and "Ma " would be considered possible matches). The maximum number of differences allowed for a given chunk is determined by the formula max(1, (trunc(chunkLen * eq))). For example, using the default of 0.25, a chunk with 8 characters would be a possible match with any other chunk having 2 or fewer differences (trunc(8 * .25) = 2). Note: differences in character case are NOT considered in this amount. That is, using the last example, an 8-character chunk could have 2 missing-character differences and 5 character case differences and still be considered a possible match.

C# Example: returnValue = WebService.raSetEqWords (sessionId, 0.34);


Appendix A: Error Codes and Error Messages This appendix explains the difference between error codes and error messages, and provides an ordered list of all that can occur with further explanation for help debugging during development. Error Codes All routines that return a numeric type may return an error code instead of the expected return value. Error codes are negative numbers, so a check for this can assist with bullet-proofing code. Some routines (e.g., raSetWbChars) do not have an expected return value, and will merely return 0 when there is no error, to indicate the routine completed successfully. (Clearly, this is really a “success” code, but is included in the below table for completeness.)

Code Occurs In Command Executed? 0 (Success) raSetWeight, raSetWbChars, raSetPuncChars,

raSetReplace, raSetRepWithSp, raSetRemove, raSetRemoveWords, raSetRemoveControl, raSetRemoveExtended, raSetRemoveExtraWbs, raSetEqWords, raDispose

Yes

Explanation: Zero (0) returned for the listed routines merely indicates successful completion. Code Occurs In Command Executed?

-1 (Invalid sessionId) All routines where session ID is passed and an error code can be returned.

No

Explanation: The session ID passed was invalid. Either session ID was erroneous or the session has timed out. Code Occurs In Command Executed?

-2 (Error occurred) All routines that can return an error code. Unknown Explanation: An error has occurred as a result of parameters passed or the condition under which the routine was

called. A call to raMessage inserted immediately after the call producing the error will return a string with more detail about the specific error.

Code Occurs In Command Executed?

-3 (Warning occurred) All routines that can return an error code. Yes Explanation: A warning has occurred as a result of parameters passed or the condition under which the routine

was called. A call to raMessage inserted immediately after the call producing the error will return a string with more detail about the specific warning.


-4 (Invalid developerId) raInit No Explanation: An invalid developer ID has been passed. The command could not be executed and a session could

not be returned. To be valid, a developer ID must exactly match the developer ID provided to you through the Response Analyzer information & registration site (see section “Requirements for Using Response Analyzer” earlier in this manual). Note that any leading or trailing space characters passed are ignored.


-5 (Database error) raInit No Explanation: An error has occurred, due to a problem with the Response Analyzer database. Please contact the

Response analyzer administrator. A session ID was not returned. Code Occurs In Command Executed?

-6 (Invalid interactionId) raInit No Explanation: An invalid interaction ID has been passed. The command could not be executed and a session

could not be returned. Valid interaction IDs must contain at least one non-space character, be less than or equal to 50 characters in length, and contain no control characters (0 – 30 and 127). Any leading or trailing blanks are ignored.



-7 (Invalid studentId) raInit No Explanation: An invalid student ID has been passed. The command could not be executed and a session could

not be returned. Valid student IDs must contain at least one non-space character, be less than or equal to 100 characters in length, and contain no control characters (0 – 30 and 127). Any leading or trailing blanks are ignored.


-10 (developerId not in database) raInit No Explanation: A developer ID has been passed that could not be found in the database. The command could not

be executed and a session could not be returned. The passed developer ID must exactly match the developer ID provided to you through the Response Analyzer information & registration site (see section “Requirements for Using Response Analyzer” earlier in this manual).


-11 (generated ID limit exceeded) raInit No Explanation: The limit of 100 simultaneous generated student IDs/session IDs has been exceeded. This error

occurs when a developer is passing “$Unique$” for studentId to have Response Analyzer generate the student ID and return a session ID. This limit of 100 is not in place for developer-supplied student IDs.

Error Messages A call to raMessage immediately following another Response Analyzer call will return a string containing any error messages generated by the previous call. Note that this is true only if a valid session ID—the same one in effect during the previous call—is passed. Also note that raMessage, raDiffList, and raDiffReport—the only Response Analyzer routines that return strings—have the unique ability to return an error message string directly. They do this in the event that a bad session ID is passed. Following is an alphabetized list of error messages that may be returned with a call to raMessage. In actuality, each message below is preceded by the name of the main web-service routine that was called by the developer (for example, "(raFound) Bad leniency value; default set."). The descriptions below elaborate on possible causes for the error message and how you might fix the problem. Message Command Executed? Bad char(s) removed from punctuation string. Yes

Explanation: Alphanumerics (e.g., 12 and AB) are not allowed as punctuation. Further, any characters currently in the set of word break characters are not allowed. If you want to use a character for punctuation that is currently specified as a word break, you'll need to change the word breaks first.

Message Command Executed? Bad char(s) removed from remove string. Yes

Explanation: Alphanumeric characters (e.g., 12 and AB) and characters in the current word-break set are not allowed in the strings indicating characters to remove in and around words and numbers.

Message Command Executed? Bad char(s) removed from replace string. Yes

Explanation: Alphanumeric characters (e.g., 12 and AB) and the space character are not allowed in the strings indicating characters to replace with space in and around words and numbers.


Message Command Executed? Bad char(s) removed from word break string. Yes

Explanation: Alphanumeric characters (e.g., 12 and AB) are not allowed in the word-break characters.

Message Command Executed? Bad difference value ignored. No

Explanation: The value passed to raSetEqWords in eq must between 0 and 0.34. The value was ignored and the setting was left as it was before the call.

Message Command Executed? Bad leniency value; default set. Yes

Explanation: The value specified for leniency must be a positive integer >= 0. (The value must also be less than the maximum value allowable for a long integer.)

Message Command Executed? Bad weight value; weight value ignored. No

Explanation: The value passed as weight to raSetWeight must be an integer value between 0 and 100. See that command, above, for more information.

Message Command Executed? Invalid sessionId No

Explanation: The session ID passed was invalid. Either session ID was erroneous or the session has timed out.

Message Command Executed? Maximum chunk size exceeded; chunk(s) truncated. Yes

Explanation: The object or response string being analyzed contains one or more chunks that exceed the maximum allowed chunk size of 64 characters. The chunk was truncated to 64 characters for comparison.

Message Command Executed? Memory allocation error; results are unreliable. Yes

Explanation: A memory allocation error occurred during analysis of the object and response. For this reason, any returned results may be unreliable.

Message Command Executed? Oversized chunk(s); eqwords temporarily reduced. Yes

Explanation: A chunk was encountered in the object or response string that, when taken times eqwords, produced an allowed number of differences greater than the maximum allowed (8). Eqwords was reduced for that chunk so that the number of differences allowed for it was 8.

Message Command Executed? Session already present in memory, overwritten by new. Yes

Explanation: A session was found already existing in memory for the developerId, interactionId, studentId combination passed to raInit. Since the request was to create a new session, the existing session was overwritten by a new session.

Message Command Executed? String parameter too long; string truncated. Yes

Explanation: A string passed as a parameter exceeded the allowed length for that string. See the above section on the command for details on allowed lengths of parameters.


Message Command Executed? Too many words to remove; list truncated. Yes

Explanation: The parameter passed to raSetRemoveWords contained too many words to remove. A maximum of 15 words are allowed. The list was truncated.

Message Command Executed? Word break chars removed from punctuation string. Yes

Explanation: The string passed as wBs to raSetWbChars contained some characters that are currently in the set of punctuation characters. Those characters were kept as word breaks, but removed from the set of punctuation.

Message Command Executed? Word break char(s) removed from remove string(s). Yes

Explanation: New word-break characters were specified and, since word-break characters are not allowed in the characters to remove (such as characters to remove from the beginning of words), the new word-break characters were removed from one or more remove strings.

Message Command Executed? Word to remove <word> too long; word ignored. Yes

Explanation: A word (<word> is replaced in the error message with the actual word) passed to raSetRemoveWords is too long. Words cannot be longer than 64 characters. The parameter was ignored.


Appendix B: How Response Analyzer Analyzes The description below provides an overview of the sequence of events that occur when Response Analyzer compares the object and response strings (parameters obj and resp) to identify differences. Some example strings are included to show the affects of processing activities. 1. RAFound is called, passing in obj, resp, and leniencyVal. Other global variables set by

RAFound are re-initialized to original settings. Warnings are returned via raMessage if leniencyVal is negative, etc.

obj: Iowa<sp>City,<sp>IA<sp><sp>52240 resp: ity<sp>Iowa<sp>IA<sp>52'40 2. One pass is made through both obj and resp, using the set of characters specified by replace and

replaceWith (see raSetReplace). Any characters encountered in replace are replaced with the corresponding char in replaceWith. If there is no corresponding character in replaceWith, the character is removed. Using the default settings in effect after raInit, the example strings shown below would not change:

obj: Iowa<sp>City,<sp>IA<sp><sp>52240 resp: ity<sp>Iowa<sp>IA<sp>52'40 3. The strings indicating characters to "remove" and "replace with space" (see raSetRepWithSp and

raSetRemove) in and around numbers are next utilized to do just that, first to obj, then to resp. Multiple passes are made until no changes are indicated. This is because, as characters are removed and replaced with spaces, the beginnings and ends of numbers may change (for example, if comma is replaced with space in "44,$55", the numbers 44 and $55 are separated. During the next pass this step may replace or remove the dollar sign at the start of $55, if indicated by the pre-processing strings.

Note that this step pre-processes numbers wherever they are found, regardless of word boundaries.

For example, in the string "1,000th", the comma would be removed from the middle of 1,000 if indicated by the pre-processing strings.

A number is any sequence of characters in this pattern: 1) an optional plus or minus sign followed

by 2) a sequence of decimal digits possibly containing a single decimal point, and 3) an optional exponent part, consisting of the letter e or E, an optional sign, and a sequence of decimal digits.

After step 3, using the default settings, the example strings would look like this: obj: Iowa<sp>City,<sp>IA<sp><sp>52240 resp: ity<sp>Iowa<sp>IA<sp>5240 4. The strings indicating characters to "remove" and "replace with space" (see raSetRepWithSp and

raSetRemove) in and around non-numeric words are next utilized to do just that, first to obj, then to resp. Multiple passes are made until no changes are indicated. This is because as characters are replaced with spaces, new word boundaries are identified. For example, using the default sets, the first pass would replace the comma with space in the string "Smiths',house". A second pass would remove the apostrophe from the end of Smiths.

Note that step 4 works only at the "word" level. A word is any stretch of characters between word

breaks (including beginning/end of line), beginning with a first non-punctuation and ending with the last non-punctuation (punctuation marks may be included in words--for example "they're"). This step also checks whether an entire word is a number; if it is, no pre-processing is done on it, since that was already done in step 3.


After step 4, using the default settings, our examples would look like this: obj: Iowa<sp>City<sp><sp>IA<sp><sp>52240 resp: ity<sp>Iowa<sp>IA<sp>5240 5. Next, the strings indicating characters to "remove" and "replace with space" (see raSetRepWithSp

and raSetRemove) when alone are used. A single pass is made through the object and response strings. This removes miscellaneous punctuation characters, etc., that are included between words, before the first word, or after the last word, as indicated. With the default settings, no change would occur to the example strings.

6. Step 6 removes from obj and resp any "words to remove" as indicated in parameter words (see

raSetRemoveWords). Note that this step removes words themselves, but no leading or trailing word breaks or punctuation. Using the default settings, there would be no affect on the example.

7. Step 7 removes any control characters (codes 0 - 31, 127), if the state indicating to do so is true (see

raSetRemoveControl). 8. Step 8 removes any extended codes (128 - 255), if the state indicating to do so is true (see

raSetRemoveExtended). Steps 7 and 8 also would have no affect on the example strings. 9. In step 9, any extra word-break characters (see raSetWbChars) are removed if the state indicating to

do so is true (see raSetRemoveExtraWbs). Any stretch of more than one word-break character is reduced to one. Also, any leading word breaks before the first word are removed. (Note that since word breaks are kept with the word that precedes them, a single space is added following the last word, if a space is not there, to prevent unnecessary "missing word-break" differences.) The result on the sample strings with the default settings would be:

obj: Iowa<sp>City<sp>IA<sp>52240<sp> resp: ity<sp>Iowa<sp>IA<sp>5240<sp> After this step, all pre-processing is completed and the strings are "normalized". The actual

processing steps begin next. 10. The object and response strings are next gone through in order to pick out "chunks". A chunk is: 1)

any preceding word-break and punctuation characters not part of the previous chunk; 2) a "word", if any, (note a word begins and ends with any non-punc, non-word-break char, but spans inner-word punctuation, e.g., "they're"); 3) any trailing punctuation; and, 4) any following adjacent word-break characters. If a found chunk is longer than 64 characters, it is truncated to 64 and an error message is set.

Each chunk is placed into a linked list of chunknodes. For each chunk, these things are kept: chunk /* original chunk */ upChunk /* chunk upper cased for searching */ chunkLen /* length of chunk, kept for speed */ chunkNum /* number of the chunk, left to right */ matchedWith /* number of chunk matched with in other list, inited to 0*/ wordStart, wordLen /* location, length of word or number kernel in chunk */ Also, while the chunks are picked out of objStr, the size of the largest chunk is gathered and saved

in largestObjChunk. Pointers to the head and tail of the object and response chunks are kept.


For the example, the object and response chunk information would look like this: chunk

upChunk chunkLen

chunkNum matchedWith

wordStart wordLen isANum

Iowa<sp> IOWA<sp> 5 1 0 0 4 false

City<sp> CITY<sp> 5 2 0 0 4 false

IA<sp> IA<sp> 3 3 0 0 2 false

52240<sp> 52240<sp> 6 4 0 0 5 true

chunk upChunk

chunkLen chunkNum

matchedWith wordStart wordLen isANum

ity<sp> ITY<sp> 4 1 0 0 3 false



5240<sp> 5240<sp> 5 4 0 0 4 true

11. Next, in nested looping, for each chunk in the list of object chunks, each chunk in the list of

response chunks is considered as a possible match. An intricate, recursive comparison routine is called to do the comparing. The routine returns null for no match or a pointer to a possmatch node when a match is found. Possible matches to a given object chunk are any response chunks that that have fewer than diffsAllowed missing, extra, reversed, or different character differences (this includes specialties for word-breaks and punctuation, such as missing word-break). diffsAllowed is set for each objectChunk, based on the chunkLen and eq (a floating-point percentage spelling-tolerance permitted between object and response chunk matches, specified by the author with raSetEqWords). diffsAllowed is:

max(1, (trunc(chunkLen * eqWords))) Note diffsAllowed is an integer value and that it is always at least 1. For each possible match found, a possmatch node is added to the end of a list of possible matches.

Each node has these elements: objChunkNum /* which object chunk was compared */ respChunkNum /* which response chunk was compared */ numMissChars, numExtChars, numDiffChars, numRevChars, numCaseChars, numMissWBs, numExtWBs, numDiffWBs, numRevWBs, numMissPuncs, numExtPuncs, numDiffPuncs, numRevPuncs /* num of these */ numMainDiffs /* total of all above nums other than numCaseChars */ sameNess /* a similarity amount between obj and resp, derived via formula */ Pointers to the head and tail of the possmatch nodes are kept: possMatchHead, possMatchTail. For two words compared by spelling, the formula for sameness is: sameNess = numMainDiffs * ((largestObjChunk + 2) * 2) + numCaseChars if objChunkNum == respChunkNum then sameNess = sameNess - (largestObjChunk + 1) This formula separates matches out according to the number of main differences that were found. If,

for an object chunk, two response chunks were equally good in terms of numMainDiffs, the number of character case differences is next taken into account, with less importance. Finally, if the matches are in the same word-order position, this has more importance than the number of case differences. The matches will be sorted according to this sameNess value, below.


After this step is completed, the possmatch list for the example would contain these (using default settings).

The chunk information is repeated here to make this easier to analyze. Chunk information

chunk upChunk

chunkLen chunkNum





52240<sp> 52240<sp> 6 4 0 0 5 true

chunk upChunk

chunkLen chunkNum





5240<sp> 5240<sp> 5 4 0 0 4 true

Possmatch information

objChunkNum respChunkNum numMissChars

numExtChars numDiffChars numRevChars

numCaseChars numMissWBs

numExtWBs numDiffWBs numRevWBs

numMissPuncs numExtPuncs

numDiffPuncs numRevPuncs numMainDiffs

sameNess

1 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

2 1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 16

3 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -7

4 4 1 0 0 0 0 0 0 0 0 0 0 0 0 1 9

Note that there is no correlation here between the number of object chunks and the number of

possible match nodes. It just happened in this example that there was 1 possible match for each object chunk.


12. Next, the possmatch nodes are sorted according to sameNess, in increasing order. So the order of the nodes would now look like this:

Possmatch information

objChunkNum respChunkNum numMissChars

numExtChars numDiffChars numRevChars

numCaseChars numMissWBs

numExtWBs numDiffWBs numRevWBs

numMissPuncs numExtPuncs

numDiffPuncs numRevPuncs numMainDiffs

sameNess

3 3 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -7

1 2 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0

4 4 1 0 0 0 0 0 0 0 0 0 0 0 0 1 9

2 1 1 0 0 0 0 0 0 0 0 0 0 0 0 1 16

13. A pass is made, left to right, through the possmatch nodes. With each node, chunk objChunkNum is

found within the object chunk information, and chunk respChunkNum is found within the response chunk information. If matchedWith for both the object and response chunk is still 0, then matchedWith for the object chunk is set to respChunkNum and matchedWith for the response chunk is set to objChunkNum. Also, the number of differences for the match are added into the global storage locations for these totals (nMissChars, nExtChars, ...). If matchedWith for either the object or response chunk had already been set, the possmatch node is just skipped.

After this pass, the chunk information would look like the following, and the global totals would

show 2 missing characters (all rest 0).

chunk upChunk

chunkLen chunkNum





52240<sp> 52240<sp> 6 4 4 0 5 true

chunk upChunk

chunkLen chunkNum





5240<sp> 5240<sp> 5 4 4 0 4 true

Now the possmatch list is disposed of and head/tail reset to null.


14. Next, a single pass is made through the object chunk nodes to total up nWordsNotFound. Any node having a matchedWith of 0 and a wordLen > 0 means to add 1 to nWordsNotFound. Any punctuation and extra-word break characters are counted as missing punctuation and missing word break differences. Note that punctuation in the middle of words is counted as part of the word. Also note that one word break is treated as part of the word.

15. Next, a single pass is made through the object chunk nodes to total up nWordOrds. With any node

having a non-zero matchedWith, matchedWith is compared to a curRespMatch temp variable (inited to 0). If matchedWith is less than curRespMatch, 1 is added to nWordOrds. After the comparison, the current matchedWith is moved into curRespMatch before moving on to the next node.

16. Finally, a single pass is made through the response chunk nodes to total up nExtWords. Any node

having a matchedWith of 0 and a wordLen > 0 causes 1 to be added to nExtWords. Any punctuation and extra-word break characters are counted as extra punctuation and extra word break differences. Note that punctuation in the middle of words is counted as part of the word. Also note that one word break is treated as part of the word.

Now the obj and resp chunk lists is disposed of and heads/tails reset to null. 17. diffAmount is now calculated by taking each nDiff (e.g., nMissChars) times its corresponding

weight (e.g., wMissChars) and adding this into diffAmount. 18. Unfortunately, breaking obj and resp into chunks may not have been the way to find the fewest

number of differences between the two (for example, in the case where the user's response has missing word breaks). A second comparison can be done treating the entire obj and resp as single chunks. This test will only be done when the length of the entire object and response are both less than or equal to 24 characters (otherwise, the recursive routine comparing differences slows down unacceptably).

obj and resp are placed in single chunks, with only the necessary information filled in. They are

placed in single chunks, since the recursive comparison routine expects to be passed chunknodes. The chunks for the example would look like these:

chunk

upChunk chunkLen

chunkNum matchedWith

wordStart wordLen isANum

Iowa<sp>City<sp>IA<sp>52240<sp> IOWA<sp>CITY<sp>IA<sp>52240<sp> 19 1 0 0 0 false

chunk upChunk

chunkLen chunkNum


ity<sp>Iowa<sp>IA<sp>5240<sp> ITY<sp>IOWA<sp>IA<sp>5240<sp> 17 1 0 0 0 false

When these two are compared, a possmatch node would not be returned; fewer than 3 differences

would be required, using the default values. However, had a possmatch node been returned, a temp diffAmount is easily calculated using the

numDiffs (e.g., numMissChars) and the corresponding weights (e.g., wMissChars). (Note there


would be no word errors.) If the temp diffAmount is less than diffAmount, then diffAmount is replaced, as are the globals nMissChars, etc.

Note that after this the lists can again be disposed of and heads/tails reset to null. 19. If diffAmount is less than or equal to leniencyVal, RAFound returns true. Otherwise, it returns

false.

Documents

Response Analyzer Web Service - ddra.its.uiowa.eduS(kl2bex45ia02dw553bvqe1md))/ra... · Response Analyzer Web Service USER/DEVELOPER DOCUMENTATION August 2007 Version 1.0 Credit for