Tik-76.115 Individual Project: Guinea Pig
$Id: gpTestLogic.html,v 1.10 1996/04/20 16:06:55 hynde Exp $

Test Logic internals - Module gpTestLogic

The python module gpTestLogic implements most of the functionality of the Test Logic subsystem. It defines the gpTest class which stores information about the test and provides methods for performing the test for the test subject.

The gpTestLogic module uses following modules:

gpSoundPlayer for accessing the Sound Player
gpTestItems for test item object classes
gpDefaults for some defaults
config_parser, file_parser for reading configuration files
gui_client for accessing the test subject's UIs
Various standard python modules

The gpTestLogic module is loaded the usual way:

   import gpTestLogic

Classes defined by the gpTestLogic module are:

gpTest - Test Logic object for performing the test.
gpTestSubject - Information about the test subject.

1 · Class gpTest - The Test object

When the logic module starts, a new instance of the gpTest class is created. This test object contains the information needed to perform the test. The parameters of the test are read from the test.config

A new test object is created, as always in python, by calling the gpTest class as a function:

    test = gpTest()

1.1 · Instance variables

Public instance variables of the gpTest class instances are:

test.type (string): Type of the test: 'ab', 'ab_scale', abx', etc.
test.Status (string): Status of the test. At the end of the test it should be 'Completed' for a succesfully completed test. If the test was aborted, it reads 'Aborted'. If errors happened, it is 'Error'.
test.samples (dictionary): A dictionary containing the sample objects used in the test. The sample IDs defined in the test.config file act as the dictionary keys.
test.config (instance of config_parser): Contains the configuration information from the test.config file.
test.player (instance of SoundPlayer): The Sound player object that is used when accessing the Sound Player.
test.GUIserver (instance of gui_client): The GUI server object that is used to open different GUIs.
test.test_items (list of test items): A list of individual test items. Each item typically is one part of the test, for example, one sample pair. Generally one test item generates one entry into the result file. This list can also be accessed by using the gpTest object like a list (see below).
test.Subjects (list of test subjects): A list of test subjects that are partisipating in the test at the same time. Typically there is only one subject in this list as there are not yet UIs that accept answers from multiple users at the same time. However, multiple subjects are used when the test results are analyzed. Then the list contains the subjects whose results are being analyzed together.

Other test parameters are also included. They will be documented at a later time.

1.2 · Test object as a python sequence

The gpTest class also behaves as a python sequence and thus many python's sequence operations are available. When a gpTest object is used as a sequence the operations refer to the test_item list. For example, test[0] returns the first test item in the test. Other operations, such as:

    test[2] = item1     # set third item in list
    item = test[-1]     # put last item of test in item
    itemlist = test[1:] # copy all but the first item to another list

also work. When the items are run in sequence in the test, it can be done as simply as this:

    for item in test:    # for each test item in test
       item()            # call item as function, performs the test
       item.log_result() # log result in result file

1.3 · Methods

Arguments that are in brackets (like [this]) are optional.

test.quit(): Quit the test. Closes down server processes, saves files, etc.
test.init_player(): Initializes the sound player and starts/connects to it.
test.load_samples(): Loads the sample files specified in the test.config configuration file and places them in the test's samples dictionary.
test.unload_samples(): Unloads all samples that can be found in the test's samples dictionary.
test.quit_player(): Unloads samples and quits soundplayer.
test.load_config([filename]): Load the configuration information. If the optional filename is given, the information is loaded from that file, otherwise the default file is used (usually test.config).
test.connect_GUIserver([port], [gui_port]): Connect to the GUI server. Optional parameters port and gui_port can be used to specify nondefault ports.
test.quit_GUIserver(): Terminate the GUI server.
test.load_items([filename]): Load the test items. If the optional filename is given, the items are loaded from that file, otherwise the default file is used (usually test.items). After loading the items are in the test object's test_items list.
test.load_playlist([filename]): Loads the playlist and rearranges test items accordingly. If the optional filename is given, the playlist is loaded from that file. Otherwise, first looks for personal playlist. If not found, looks for global playlist. If no playlists are found, the items are not rearranged.
test.add_subject(subject): Adds the subject to the list of test subjects. (It is in theory possible to run the same test for multiple persons at the same this).
test.set_MCLL(): Sets the Most Comfortable Listening Level using a GUI. If setting the level is disabled, sets the level to the default defined in the test.config file.
test.do_test(): Performs the test by performing individual test items in the test_items list in sequence and writes the result file.
test.log_header([who]) test.log_trailer([who]) test.log_results([who]): Write the header/trailer/results part in the test subject's result file (for all subjects in the subjects list unless optional argument who (list of subjects) specifies for which subjects to write logs).

1.4 · Using the test objects

First create a new instance of the gpTest class:

   test = gpTestLogic.gpTest()

Then load the configuration information:

   test.load_config()

(Assumed that config information is found in the current directory). Then add the test subject to the test:

   test.add_subject(subject)

where subject is a test subject object. Then load test items and playlist:

   test.load_items()
   test.load_playlist()

Now you run the test:

   test.do_test()

which runs the test (and initializes player, loads samples, etc. if not done already). When test is done, do:

   test.quit()

to quit the test (closes down server processes and files, etc.)

2 · Class gpTestSubject - Test Subject information

The gpTestSubject objects store information about the test subjects. New subjects are created like this:

    subject = gpTestSubject(test)       # this way
    subject = gpTestSubject(test, gpID) # or this way

where test is the test object the subject is associated with. The subject's ID can be given as the second argument, otherwise it must be set manually later.

2.1 · Instance variables

subject.id (string): The test subject ID.
subject.test (instance of gpTest): The test the subject is associated with.
subject.lastname (string): Last name of subject (optional).
subject.firstname (string): First name of subject (optional).
subject.age (number): Age of subject (optional).
subject.sex (number): Sex of subject (optional).
subject.ResultFile (file object): When log file is open for writing contains file object for the file, otherwise 'None'. Test item and test logic objects write to this file when they are logging results from the test for this subject.

Optional variables' have 'None' as value is nothing else is put in them.

2.2 · Methods

subject.filename_info([filename]): Returns path to this subject's personal info file. If filename is given, uses it instead of the default 'personal_info'.
subject.filename_log([filename]): Returns path to this subject's results file. If filename is given, uses it instead of the default 'results.raw'.
subject.filename_playlist([filename]): Returns path to this subject's playlist file. If filename is given, uses it instead of the default 'playlist'.
subject.read_info([filename]): Reads subject's information from personal info file. Filename can be given to specify nondefault filename.
subject.write_info([filename]): Writes subject's information to personal info file. Filename can be given to specify nondefault filename.
subject.log_open([filename]): Open result log file for writing. Filename can be given to specify nondefault filename for logfile. Log file object is stored in subject.ResultFile.
subject.log_close([filename]): Close result file.

· Test Logic index · Document index · Guinea Pig ·