Tik-76.115 Individual Project: Guinea Pig
$Id: gpTestItems.html,v 1.5 1996/04/19 19:01:31 hynde Exp $

Test Logic internals - Module gpTestItems

The python module gpTestItems contains the definitions of the test type dependent TestItem classes. These classes implement the different test types.

The gpTestItems module is intended to be used by the gpTestLogic module where it should be loaded like this:

    from gpTestItems import *

The gpTestItems imports only standard python modules and not any GuineaPig specific modules directly. However, indirectly it needs most of the modules imported by the gpTestLogic module which are expected to be available. Thats why the module is imported into gpTestLogic as seen above.

Classes defined by the gpTestItems module are:

gpTestItem - Base class for test items, implements most of the default behaviour.
gpABTestItem - Class for AB-test.
gpABScaleTestItem - Class for AB Scale-test.
gpABXTestItem - Class for ABX-test.
gpABCTestItem - Class for ABC-test.

In addition, a dictionary of available classes is defined:

gpTestClasses - Dictionary containing the test item classes and tags needed to read them.

1 · Class gpTestItem - The Test Items' base class

The class gpTestItem is the base class for the different test item types. Generally each test type (such as A/B, A/B/C, TAFC, etc.) will have a derived class that handles one item of that test type. In the A/B test one item is such that it plays a pair of samples and then waits for the subject's answer.

A new test item is created by calling the class object:

    item = gpTestItem(tags, test, subjects)

(Actually the base class is never instantiated but rather derived classes are used.)

The tags is a dictionary that contains the information for this item (the tags are read from the test.items file) and test is the test object this item is associated with. Subjects is a list of test subjects who are taking the test at the same time.

When new instances are created, the test is stored in item.test and subjects in item.subjects. If tags is given (it usually is) then item.config_item(test, tags) is called to read the information from the test.items file in tags. If item is an instance of some derived class, the derived class's config_item() method is executed. Config_item()s in derived classes are responsible for calling base class's test_config() if one wants the base class to decode some information for it.

1.1 · Instance variables for test items

These are the instance variables that the gpTestItem class (and derived classes) define. It is not necessary to derive a new test item class from gpTestItem but the following variables must work as described below. They are used by the test logic and result analysis routines.

item.id (string)

The ID for this test item (from test.config).

item.type (string)

Type of the test item, 'ab', 'abc', 'abx', etc.

item.test (instance of gpTest)

The test where this test item belongs to.

item.subjects (list of test subjects)

List of test subjects that are taking this test at the same time. Only used internally with gpTest, not in result analysis.

item.result (dictionary)

This dictionary contains the answers the subject gave. The test subject object is the dictionary key and the value is the answer. Answer may be None which means no answer was given (time allowed for giving the answer expired before subject gave his answer). When logging the results, an answer with the value None are not logged. Otherwise the value is the answer the subject gave. It may be a string, value, list of values or whatever is appropiate for this particular test type.

When the results are analyzed, this dictionary contains all answers for this test item given by all subjects. To get the list of subjects who gave answers, use item.result.keys() and item.result.values() to get a list of answers.

item.answertime (dictionary)

This dictionary is similar to the result dictionary above. The difference is that instead of the answer, the time it took the subject to give his answer is stored (in seconds). If no answer was given (timeout), None is used in place of the time (and answer time is not logged into the result file).

1.2 · Required methods for test items

The following methods are required to be present in any class which wants to act like a test item (may or may not be derived from gpTestItem class). They are required to implement the functions described below:

item()

Calling the test item as a function runs the test item and stores the answer and answer time in the item's result and answertime variables.

item.setGUI(gui)

Used to set the GUI for this test object class. Gui is a GUI object. (Only required if init_gui() and close_gui() use it.)

item.init_gui()

Initialize GUI for this test item. Opens the GUI for this test type and sets it for use with the setGUI() method.

All test items share the same GUI so this function is called only for the first test item in the sequence.

item.close_gui()

The reverse of init_gui(). Closes the GUI and sets object's GUI to None.

This method is usually called only for the last test item in the test sequence.

item.log_result([who])

Log the result of this item to the subject's log. If the optional argument who (list of test subjects) is given, results for only those subjects are recorded. Otherwise results are recorded for all subjects who appear in the item's results.

item.config_item(tags, test)

Reads item's configuration information from test and tags (got from the test.items file via file_parser). This method should read the parameters of this item from tags. Tags has the same meaning as above when new instances are created. Also, this method must be able to read the test item as in the result file (read the answer and answer time).

item.merge(other)

Used by result analysis when reading in result files. All answers (for all subjects) for the same test item are stored in the same item. Merge is used to add other's result information into the item. Default is to add other's result and answertime to item's own.

1.3 · Methods defined by gpTestItem

The gpTestItem class also defines additional methods that simplify deriving new test item classes. It also implements the default methods described above using the methods below:

item()

First checks if the GUI is already opened. If not it opens it with init_gui(). Then calls self.start(), self.do() and self.end().

item.setGUI(gui)

Sets GUI (shared by all test items)

item.init_gui()

Opens a new GUI by requesting a new GUI (whose type is same as item's) from the GUI server.

item.close_gui()

Closes GUI if it is open.

item.log_result([who])

Log the result of this item to the subject's log. First writes information common to all test types to log file and then calls self.result_str() which returns a string containing test type dependent log entries and the writes it to the result file.

item.config_item(tags, test)

Reads item's configuration information from test and tags. Sets id and answertime (if present, usually when reading in result files for analysis).

item.start()

Does nothing. A place for things to be done before samples are played, for example, enable GUI, reset GUI's sliders, etc.

item.do()

Does nothing. The actual execution of the item might be here.

item.end()

Does nothing. A place for things to be done after the item was executed.

item.result_str(subject)

This method should return text that is written to the result file of subject as the answer for this item. This default method first sees whether the is an answer. If there isn't (answer = None), return empty string. If there is an answer, it is written into the result file. If the answer is a tuple or a list, the items in them are written on the same line one after another. Other types of answers are printed as a single item.

Returns: string containing results to be written in test results file.

2 · Class gpABTestItem - AB test item

The gpABTestItem class is derived from the gpTestitem base class. It implements the test logic for the AB Test.

A new test item is created by calling the class object:

    ab = gpABTestItem(tags, test, subjects)

2.1 · Instance variables

In addition to the variables of the base class(es), new variables are:

ab.samples (dictionary): Tells which sample is the A-sample, B-sample, etc. Key is 'A', 'B', ... and values are sample IDs.
ab.sequence (list): Contains the test sequence defined in test.config-file.
ab.answerTO (number): How much time subject has to give his answer after the answering is enabled (0 = forever).
ab.warnTO (number): The lights on the GUI change from green to yellow after this time after answering was enabled for this item (0 = never). Indicates that subject is running out of time.

2.2 · Methods

New methods:

ab.play_sequence([seq])

Plays the test sequence in ab.sequence (or seq if given) .

Returns: the time when sequence ended.

Overridden methods:

ab.config_item(tags, test)

Reads item's configuration information from test and tags. First calls gpTestItem.config_item() to do the defaults, then reads timeout values and test sequence from test and from tags samples and result if present (when analyzing results).

ab.start()

'Arms' the GUI with GUI's arm()-method.

ab.do()

Plays test sequence (with ab.play_sequence(), enables GUI for answering, waits for answer and stores it.

ab.result_str(subject)

First adds the ab.samples to the result string. Then calls gpTestItem.result_str() for the answer string.

Returns: result string.

3 · Class gpABScaleTestItem - AB-scale test item

The gpABScaleTestItem class is derived from the gpABTestitem class. It implements the test logic for the AB-scale Test.

A new test item is created by calling the class object:

    abs = gpABScaleTestItem(tags, test, subjects)

3.1 · Instance variables

In addition to the variables of the base class(es), new variables are:

ab.scale_params (tuple): Scaling parameters for the ABScale GUI sliders.

3.2 · Methods

Overridden and new methods:

abs.config_item(tags, test): Reads item's configuration information from test and tags. First calls gpABTestItem.config_item() to do the defaults, then reads scale parameters from test.
abs.start(): 'Arms' the GUI with GUI's arm()-method and passes the scale parameters as arguments..

4 · Class gpABXTestItem - ABX test item

The gpABXTestItem class is derived from the gpABTestitem class. It implements the test logic for the ABX Test.

A new test item is created by calling the class object:

    abx = gpABXTestItem(tags, test, subjects)

4.1 · Instance variables

No new variables are defined.

4.2 · Methods

Overridden and new methods:

abx.config_item(tags, test): Reads item's configuration information from test and tags. First calls gpABTestItem.config_item() to do the defaults, then changes any 'C' samples into 'X' samples in samples (This way same items file can be used for abc and abx tests).
ab.do(): Waits for messages from the GUI, plays the samples based on subject's choices and finally stores the answer the subject gave.

5 · Class gpABCTestItem - ABC test item

The gpABCTestItem class is derived from the gpABScaleTestitem class. It implements the test logic for the ABC Test.

A new test item is created by calling the class object:

    abc = gpABCTestItem(tags, test, subjects)

5.1 · Instance variables

No new variables are defined.

5.2 · Methods

Overridden and new methods:

abc.config_item(tags, test): Reads item's configuration information from test and tags. First calls gpABScaleTestItem.config_item() to do the defaults, then changes any 'C' samples into 'X' samples in samples (This way same items file can be used for abc and abx tests).
abc.do(): Waits for messages from the GUI, plays the samples based on subject's choices and finally stores the answer the subject gave.

6 · Dictionary gpTestClasses - available test item classes

The gpTestClasses dictionary contains the available test item classes and respective tags needed by file_parser (as a tuple) indexed by test type names. To get the class and tags for the ABC test, use:

    item_class, item_tags = gpTestClasses['abc']

The item_tags are needed to read the test.items file. Currently the dictionary looks like this:

gpTestClasses = { 'ab' : (gpABTestItem, gpABTestItemTags),
                  'ab_scale' : (gpABScaleTestItem, gpABScaleTestItemTags),
                  'abc' : (gpABCTestItem, gpABScaleTestItemTags),
                  'abx' : (gpABXTestItem, gpABTestItemTags)  }

The gp*TestItemTags are tags needed by the file_parser for reading test items. They are also defined in this module.

· Test Logic index · Document index · Guinea Pig ·