Chapter III --
Anatomy of the Battery Framework
The Battery simulation is an object-oriented application
framework for constructing psychophysiological experiments of the sort
described in chapter II. Experimenters
add new experiments to this framework by adding new subclasses to this
framework. The number of new subclasses
that must be added and the amount of new code that must be written will depend
(of course) on the degree of similarity between the requirements for the new
experiment and parts of the existing framework.
This chapter, and
the one that follows it, give a detailed
exposition of all the code in the Battery
simulation. It is hoped that the battery
simulation can serve as a case study in the application of object-oriented
frameworks. Every line of code in the
simulation is presented, warts and all.
The class definitions for this code are organized into 14 major
categories. (The names given are
Smalltalk system category names.) The first
8 categories contain code that is relatively battery specific. These constitute the bulk of the battery
framework. The remaining 6 categories
contain code that is largely battery independent. These classes hence play a role similar to
that of library components in a conventional system. These classes are discussed in Chapter
IV. The categories are:
Battery-Items The
Sternberg, Word and Tone Oddball
Battery-Parameters Parameter carriers for
the Battery Items
Stimulus-Generators Pluggable stimulus
presentation devices
Stimulus-Support Stimulus descriptor
objects
Sequence-Support Stimulus sequences
generation support
Response-Support Subject response
descriptor objects
Data-Management Data archive
simulation objects
Interface-Battery Support for
browsing battery items
Realtime-Support Simulated realtime
timebase code
Realtime-Devices Clocks, digitizers,
digital I/O devices
Waveform-Support Waveform collection and
statistics
Random-Support Random integer and
stream support
Plumbing-Support Objects for connecting
streams together
Accessible-Objects Support for record/dict.
transparency
The Battery-Items
category contains the core of the battery simulation: the abstract class BatteryItem. BatteryItem is the principal component of the
psychophysiological experimental application framework. This class is the superclass of the three
concrete battery items presented here:
WordOddball, ToneOddball, and SternbergTask. One of the central goals of this simulation
was to demonstrate how a class inheritance hierarchy could be used allow a
family of related application programs to share common code.
The
Battery-Parameters category contains a set of record-like objects that carry
the user modifiable parameter values for each battery item. These are organized in a hierarchy that
mirrors the battery item hierarchy. The
use of separate objects to embody the configurable state of battery items
simplifies and isolates the design of the battery parameter viewing mechanism.
The
Stimulus-Generator category embodies an attempt to construct interchangeable
stimulus generation modules that could be fitted into any appropriate
application.
The
Stimulus-Support and Response-Support categories contain classes that function
as descriptors that ferry information between the battery items themselves and
the stimulus generation and response reporting systems.
The
Battery-Parameters, Stimulus-Generator, Stimulus-Support, and Response-Support
categories are examples of objects which have been factored out of the original
battery item design as discrete components.
An experimenter constructing a new experiment will extend BatteryItem,
or some subclass thereof, along with members of these hierarchies. Because these elements are not subclasses of
BatteryItem itself, these components can be mixed and matched as black boxes
among BatteryItems.
The
Sequence-Support category supports the generation of experimental stimulus
sequences.
The Data-Management
category contains a set of descriptor classes that provide the foundation for a
dictionary-based data archiving scheme.
Class BatteryTrial contains waveform data and descriptive scalar
information for each single trial that is performed. A BatteryBlock contains all the trials
collected during a given experimental run.
Each completed BatteryBlock is entered into a DataDictionaryEntry
descriptor and entered into a DataDictionary.
Class BatteryItem contains an instance of DataDictionary that serves as
the master repository for battery data.
The
Interface-Battery category supports the Battery
browser. This browser allows an
experimenter to access a list of battery items, inspect or alter the parameters
for a given battery item, and run a battery item. A running battery item maintains a dynamic
waveform display.
The code for the
battery independent categories is described in the Chapter IV.
The code for each
system category is presented in turn. A
general description of each category is given first, along with a list of the
classes defined in that category. Each class
in the category is then presented. Each
class description begins with a table that resembles a standard Smalltalk class
definition template. The class name and
its superclass are given, first followed by lists of instance and class
variables. Inherited instance variable
names are given in italics. These lists are followed by the pool
dictionary list, the category name, and a table showing the class hierarchy.
Battery-Items
The classes in the
Battery-Items category constitute the framework around which the Battery simulation is built. The classes are:
BatteryItem A generic
battery item
SternbergTask A Sternberg
memory task
ToneOddball An auditory
oddball experiment
WordOddball A visual
semantic oddball experiment
BatteryItem
Class BatteryItem
is the central core of each of the three actual battery items implemented
herein. BatteryItem is an abstract
superclass, since it exists only to provide a repository for the common
behaviors among the three concrete battery items.
A BatteryItem is a
generic psychophysiological experiment.
A BatteryItem object's job is to run a block of experimental single
trials whenever it receives the doBlock
message. A block is a collection of a
designated number of single trials. The
number of trials in a block is an experimental parameter.
A single trial, or trial, corresponds to
the presentation of a stimulus or a sequence of stimuli to an experimental
subject. For each trial, a BatteryItem
must coordinate the timing and presentation of stimuli, the collection of A/D
waveform data (using an analog-to-digital converter, or digitizer), the
collection of discrete response time information, and the maintenance of
cumulative statistics and experimenter displays. A BatteryItem must accurately orchestrate all
these activities in (simulated) real time.
BatteryItem is a
subclass of AccessibleObject, which enables each of its instance variables to
be accessed as though a BatteryItem were a dictionary. AccessibleObjects allow new key/value pairs
to be defined, which will then also respond to the conventional instance
variable accessing protocol (item, item: value). See the discussion of category
Accessible-Objects for more information on what AccessibleObjects can do. BatteryItems inherit the instance variable items
from AccessibleObject. This
instance variable helps to provide the
soft instance variable facility mentioned above.
The class variable BatteryDataDictionary is an important
component of the battery simulation's rudimentary data management scheme. Rather than writing battery data to some
external medium, the battery simulation enters the data collected during each
run of a battery item into a dictionary that is kept in BatteryDataDictionary.
class name BatteryItem
superclass AccessibleObject
instance variable names
items
trialClock
stimulusClock
digitizer
responseDevice
parameters
stimulusSequence
sequenceGenerator
stimulusGenerator
buffer
experimenterLog
waveformDisplay
block
blockNumber
nextTrial
currentTrial
currentTrialNumber
outputStream
averagePipeline
tallyPipeline
class variable names
BatteryDataDictionary
category Battery-Items
hierarchy
Object
AccessibleObject
BatteryItem
SternbergTask
ToneOddball
WordOddball
The block control
methods control block preparations, the sequencing of single trials, and block
termination activities.
The fundamental
operation that a BatteryItem can be called upon to perform is to doBlock, which defines the basic
sequence of block activities. Any time consuming block preparations are
made by prepareBlock. These include updating the block counter,
preparing a stimulus sequence, preparing the data management system, and
setting up the dataflow data processing fixtures. Then, time-critical block
start-up actions are performed by startBlock,
such as informing the stimulus generator object that the block is starting.
The division of
labor among the components that constitute a battery item is such that each
battery item works with a discrete stimulus generating object of some
sort. For some applications, the
internal mechanisms of this object might be quite complex, and hence there is a
need to synchronize it with the block and trial sequencing done by the battery
item.
The runBlock method is the heart of the
block control mechanism. It zeros a
trial counter, and proceeds to generate and execute trials. A trial is executed by sending the doTrial message to a battery item. The trial control code is discussed
below.
When the block has
completed, the finishBlock method is
executed. This method tells the data
management and stimulus generation components to perform any block termination
activities that they might require.
An experiment that
required that basic changes be made to a BatteryItem's block sequencing
behavior might override these methods.
For example, an experiment that required that a sequence of blocks be
run in order with only minor, systematic changes to experimental parameters
might override some of these methods.
doBlock
"To run a block, we
must make adequate preparations, start per block
activity, run the blocks's
trials themselves, and finish up. The
fundamental service a
BatteryItem provides to the outside world is the
ability to do a block when
it is requested to."
self prepareBlock.
self startBlock.
self runBlock.
self finishBlock
finishBlock
"We are done. Clean up.
We perform whatever end-of-block activity
our data management scheme
may require, and tell our stimulus generator
that the block is
over."
self finishDataManagement.
self stimulusGenerator finishBlock
prepareBlock
"Block preparations are
those time-consuming tasks that need to be
performed before a block is
started. These are as opposed to actions
of an
essentially instantaneous
nature, which should be enumerated in
startBlock. "
self blockNumber: self blockNumber + 1.
self prepareStimulusSequence.
self prepareDataManagement.
self prepareProcessingFixtures
runBlock
"To actually run the
block, we have to generate a bunch of trials.
We
overlap the completion of
the current trial and the preparation of the
next in doTrial. Hence, we must prime this process here."
self currentTrialNumber: 0.
self prepareNextTrial.
(1 to: self trials)
do:
[:n |
self currentTrialNumber: n.
self currentTrial: self nextTrial.
self doTrial]
startBlock
"Tell our stimulus
generator we are starting up."
stimulusGenerator startBlock
The trial control
methods are templates for a BatteryItem's basic trial control sequencing.
The doTrial method conducts an experimental
trial. The startTrial method starts the single trial timer (which is returned
by the trialClock method) for an
amount of time indicated by the trialDuration
method. The runTrial method is the generic trial body. It calls collectData
and processData.
The collectData method must be provided by
BatteryItem's subclasses, and is, in this implementation of the battery, the
primary locus of differences among BatteryItem's concrete subclasses.
The processData method takes the data
deposited in the buffer object and per-trial data structures and performs per-trial
processing on them.
The prepareNextTrial method constructs the
per-trial data objects for the next trial. This method allows us to overlap the perhaps
time consuming preparation of the next trial with the often relatively
quiescent period at the end of the current trial.
The finishTrial method simply waits for the
trial clock's time to elapse.
doTrial
"To do a trial, do the
trial start up, run the trial, prepare the next one,
and clean up. We prepare the next trial before waiting for
the time
allotted for the current
trial to elapse (which is done in finishTrial)."
self startTrial.
self runTrial.
self prepareNextTrial.
self finishTrial
finishTrial
"We'll always end by
waiting for the trial clock. In the
interest of tidy
timing, subclasses that
override this method might want to send super
finishTrial last."
trialClock wait
prepareNextTrial
"Do stimulus selection
and preparation here. We allocate a
BatteryTrial
object, and set it up."
self nextTrial: BatteryTrial new.
self nextTrial trialNumber: self currentTrialNumber + 1.
self currentTrialNumber < self trials
ifTrue:
[self selectNextStimulus.
self prepareNextStimulus]
runTrial
"This is our generic
trial body. Each trial first collects
some data,
then processes and stores
them."
self collectData.
self processData
startTrial
"We'll always start by
starting up the trial clock. In the
interest of tidy
timing, subclasses that
override this method might want to send super
startTrial first."
self trialClock startFor: self trialDuration
The methods in this
category allocate battery item resources and set default values.
The methods in this
category are all called in response to an initialize
message to a BatteryItem. The initialize message zeros the block
number instance variable, and sends an allocateResources
message to the BatteryItem. This
method then invokes the remainder of the resource allocation code. They are concerned primarily with the
one-time creation or allocation of per-item resources.
Note that allocateParameters and allocateStimulusGenerator are
responsibilities of the concrete subclasses of BatteryItem. None of the other initialization messages in
this incarnation of the battery are overridden.
allocateBuffers
"Allocate the buffer
our A/D system will use. The A/D system
fills a
pre-existing buffer rather
than creating and returning every time it is
asked to collect data. The buffer: message stores this buffer
somewhere
until it is needed."
self buffer: (WaveformCollection channels: self channels
points: self points)
allocateClocks
"We will use two
timers, a trial timer, and a stimulus presentation timer.
We allocate and store these
here."
self trialClock: Clock new.
self stimulusClock: Clock new
allocateDigitizer
"Let's use a buffered
digitizer for now. (There is a
StreamedDigitizer as
well.) Store this somewhere where we can get at
it."
self digitizer: BufferedDigitizer new
allocateParameters
"Let our subclasses
deal with this..."
self subclassResponsibility
allocateResources
"Create the resources
we will be employing to conduct this experiment,
such as parameter blocks,
clocks, buffers, digitizers, stimulus generators,
sequence generators, and
response devices."
self allocateParameters.
self allocateClocks.
self allocateBuffers.
self allocateDigitizer.
self allocateStimulusGenerator.
self allocateSequenceGenerator.
self allocateResponseDevice
allocateResponseDevice
"Build a button box and
save it somewhere."
self responseDevice:
(ButtonBox bitA: self inputBitA bitB: self inputBitB
usingClock: self stimulusClock)
allocateSequenceGenerator
"Allocate a sequence
generator."
self sequenceGenerator: SequenceGenerator new
allocateStimulusGenerator
"Let our subclasses
worry about this..."
self subclassResponsibility
initialize
"Create our block
resources, and zero the block counter."
self blockNumber: 0.
self allocateResources
Data collection
strategies will usually differ sufficiently among different battery items so as
to make it necessary for this code to be implemented further down in the
inheritance hierarchy.
The collectData method must be
implemented by each subclass of BatteryItem to orchestrate the basic data
collection sequence for that item. This
method will usually contain a sequence of experimental control and data
acquisition method invocations that will together define the heart of the
experiment implemented by a given battery item.
The startDigitizer method will often
(always given the current framework) be called from collectData to start the A/D system.
collectData
"Data collection
requirements differ from item to item, so our subclasses
must implement this."
self subclassResponsibility
startDigitizer
"Start our A/D
converter. We ask ourself for the
various parameters we
need to start this
process. We care not from where these
values actually
come... "
self digitizer
collectChannels: self channels
points: self points
in: self buffer
every: self digitizingRate
thenDo: []
This protocol
category contains a set of generic methods for setting up and processing
collected data.
The prepareProcessingFixtures method
prepares the data averaging and statistical data accumulation pipelines. The averaging fixture set up method, prepareAverageFixtures should be
provided by subclasses of BatteryItem.
Each subclass will typically call average:using:withLabel:
for each average category it wishes to define.
The average:using:withLabel: method
constructs a dataflow pipeline that evaluates a given source block after the
data for each trial are collected, and forces the result of that block down a
pipeline using the indicated valve (conditional) block. If this valve is open, this result can then
flow into the Averager object for the pipeline.
The pipeline is constructed using the pseudo-Stream objects defined in
the system category Plumbing-Supplies.
The average:using:withLabel: method works
as follows: First, an average buffer
into which a running average will be accumulated is created. Next, this buffer (the WaveformCollection) is
entered into the average dictionary in the current TrialBlock object using the
given label as a key. Next, a Pump object
is created, and a ValueSupply object using the given source block as its source
is connected to the input (source) side of the Pump (using the << or connect input
message). Then, the output side of the
dataflow pipeline is connected (using >>)
to the effluent (sink) side of the pump.
The first stage of the output pipeline is the Valve object, and the
final stage is an Averager on the average buffer we created. Finally, the fixture is entered into an
averagePipeline dictionary kept by this instance of BatteryItem.
The tally:using:withLabel: method uses a
similar scheme to construct pipelines for incrementally accumulating
statistical information using Tally objects.
Tally objects are objects into which pipelined data can be fed that
monitor the data that pass through them and accumulate statistical information
about those data. Tally objects can
later be asked for statistical characterizations of the data that have passed
through them. (For instance, they can be
asked to give a count, or an average, of the data they have seen.) The nature of the data collected will of
course depend on the nature of the Tally object itself. The pipelined scheme used here allows the
nature of strategies for accumulating and processing statistical data to be
implemented independently of the contexts in which they are employed.
The prepareStatsFixtures method constructs
a set of fixtures for collecting BatteryItem button box response time
data. First, the tally pipeline and
tally collection dictionaries are created.
The tally pipeline dictionary holds the root of each pipeline we have
built (i.e. its Pump object), so that when the time is right, each pipeline can
be told to move data from its ValueSupply block down (Value permitting) to its
effluent sink (the Tally object). The
TrialBlock's tally dictionary provides access to the Tally objects at the end
of the pipelines for posterity's sake.
The pipeline fixtures and tally objects are entered into these
dictionaries by tally:using:withLabel:. The real work in the prepareStatsFixtures method is performed by calls to tally:using:withLabel:.
For all three of
the pipelines constructed by this method, the values are generated using a
block that asks the current trial for its response time. The pipelines differ in the labels given
them, and in the condition under which the pipeline's Valve object will permit
the data returned as a result of evaluating the value block to be passed
through to the Tally object. The first
pipeline checks only that the value passed it is not nil. Each of the other two
adds at test for whether one or the other of the response buttons was pressed
in addition to the test for nil. Note that the block passed through to the
ValueSuppy takes no arguments, while the block passed to the Valve object takes
one argument. When a Valve object is
passed a value, it will pass this value in turn to its test block as the
block's argument.
The purpose of all
of this is to simplify the process of adding new statistical categories to data
collection programs. Using the
pipelining scheme, all one would have to do to add a new statistical category
is make a single additional call to tally:using:withLabel:
to define the new category. All of the
statistical characterizations of which the Tally objects are capable will then
be available. It is interesting to
contrast the relative ease of this process with the tangle of additional
variables, declarations and code that is typically generated when an
experimenter desires that new statistical categories be added to a program
using a conventional programming language, such as Fortran. The pipeline approach encapsulates the
details of the statistical collection process, such as the temporary variables,
the category criteria, etc.
The processData method is called from runTrial. It outlines our generic mechanism for dealing
with collected data. First, the
subject's response, (if any) is evaluated.
Next, the data for this trial are stored. Then the per-block averages and statistics
are updated. Finally, the waveform and
experimenter log displays are refreshed.
The system
transcript is used as an experimenter log in this implementation of the
battery. Single channel number one of
the (single trial) data buffer is displayed in the BatteryItem's WaveformView.
The updateAverages and updateStatistics methods illustrate how data are extracted from the
ValueSupply blocks of the plumbing fixtures and are flushed down into the
effluent sides of the pipelines. Each
pump object in the average and tally pipeline dictionaries is sent the message nextPut to accomplish this. The nextPut
method moves one value from the intake to the effluent side of a Pump.
average: sourceBlock using: valveBlock withLabel: label
"Build a fixture
dictionary entry."
| fixture averageBuffer |
averageBuffer ¬
WaveformCollection channels: self channels points: self points.
self block averages at: label put: averageBuffer.
fixture ¬ Pump new.
fixture << (ValueSupply using: sourceBlock).
fixture >> (Valve using: valveBlock) >> (Averager
on: averageBuffer).
self averagePipeline at: label put: fixture
prepareAverageFixtures
"Let our subclasses
deal with this..."
self subclassResponsibility
prepareProcessingFixtures
"Prepare the tally and
average pipelines."
self prepareAverageFixtures; prepareStatsFixtures
prepareStatsFixtures
"Prepare the tally
pipelines."
self tallyPipeline: (Dictionary new: 10).
self block tallies: (Dictionary new: 10).
self
tally: [self currentTrial responseTime]
using: [:rt | self currentTrial responseTime ~~ nil]
withLabel: 'RT Statistics (All trials)'.
self
tally: [self currentTrial responseTime]
using: [:rt | self currentTrial responseTime ~~ nil and:
[self currentTrial responseType = #buttonA]]
withLabel: 'RT Statistics (Button A)'.
self
tally: [self currentTrial responseTime]
using: [:rt | self currentTrial responseTime ~~ nil and:
[self currentTrial responseType = #buttonB]]
withLabel: 'RT Statistics (Button B)'
processData
"Data collection is
complete. We must now evaluate the
digitized data
and the subject's response
(if any), and update the experimenter's
waveform and log
displays."
self evaluateResponse.
self storeCurrentTrial.
self updateAverages.
self updateStatistics.
self updateWaveformDisplays.
self updateExperimentalLog
tally: sourceBlock using: valveBlock withLabel: label
"Build a fixture
dictionary entry."
| fixture tally |
tally ¬ Tally new.
self block tallies at: label put: tally.
fixture ¬ Pump new.
fixture << (ValueSupply using: sourceBlock).
fixture >> (Valve using: valveBlock) >> tally.
self tallyPipeline at: label put: fixture
updateAverages
"Give our pipeline
pumps a little push..."
self averagePipeline do: [:fixture | fixture nextPut]
updateExperimentalLog
"Write a message for
each trial. We use the System Transcript
as the log
medium. "
Transcript show: self trialNumber printString , ') '.
Transcript show: 'Stim: ' , self stimulus category printString
, ' '.
Transcript show: 'Resp: ' , self responseType printString , '
'.
Transcript show: self responseTime printString , ' ticks'; cr.
Transcript endEntry
updateStatistics
"Give our pipeline
pumps a little push."
self tallyPipeline do: [:fixture | fixture nextPut]
updateWaveformDisplays
"Show a single trial
channel for now. FLECS battery items
typically
show several single trial
and average channels. First, ask our
parameter's object for the
battery browser object we are to use.
Then, ask
it for its
WaveformView. Change the model for this
view to our first
channel (an arbitrary
choice, I admit) and change the view title to
indicate the current trial
number. Then, send this view a update:
#waveform message"
| aBrowser aWaveformView |
aBrowser ¬ self
parameters browser.
aWaveformView ¬
aBrowser waveformView.
aWaveformView model: (self buffer at: 1).
aWaveformView title: 'Trial ' , self trialNumber printString.
aWaveformView update: #waveform
The methods in this
category implement a generic data management scheme.
This implementation
of the battery uses a class variable common to all instances of BatteryItem to
store a global data dictionary. The dataDictionary method returns this
dictionary.
Every time a
battery item collects a block of data, it enters a DataDictionaryEntry object
containing the TrialBlock object into the data dictionary under a name
generated by the entryName method. The entryLabel
method provides additional descriptive information. This label is stored in the
DataDictionaryEntry object as well.
The prepareDataManagement method allocates
a new BatteryBlock object, and fills it with a copy of the BatteryItem's own
parameter object, and an empty trial array.
It then creates a WriteStream over the trial array, and installs this as
the BatteryItem's output stream. To the
rest of the BatteryItem code, outputStream is merely a sink of some sort down
which single trial objects can flushed.
The storeCurrentTrial method copies data
from the digitizing buffer into the current trial object, and sends this object
down our outputStream.
The finishDataManagment method is charged
with creating the DataDictionaryEntry for a completed block, and storing this
entry in the master data dictionary.
dataDictionary
"Return our data
dictionary. This is a class variable
shared by all
BatteryItems into which the
result of individual battery runs are
entered. "
^BatteryDataDictionary
entryLabel
"Just use the item
label. Each entry we make into the
BatteryDataDictionary will
have an entryLabel and an entryName."
^self label
entryName
"Return the name
parameter with the block number appended.
Each
entry we make into the
BatteryDataDictionary will have an entryLabel
and an entryName."
^self name , ' #' , self blockNumber printString
finishDataManagement
"If we got this far,
we'll presume that it's okay to enter our data in
the data dictionary. We do so here. Note that we could just as easily be
closing a data file or a data stream, should
an alternate data
management strategy require
this. (Note that from the perspective of
the
rest of the BatteryItem code,
the data management scheme appears as one
in which single trial
objects are sent down a WriteStream-like sink.)"
| anEntry aName |
aName ¬ self entryName.
anEntry ¬
DataDictionaryEntry
entryNamed: aName
withLabel: self entryLabel
andData: self block.
BatteryDataDictionary at: aName put: anEntry
prepareDataManagement
"Allocate a block data
object, and set up a stream over it. To
the bulk of
our code, the data
management scheme will appear as one that requires
single trials to be sent
down some sort of outputStream. The code
will
care not whether this is a
file, a collection, or what have you..."
| trialArray |
block ¬ BatteryBlock
new.
block parameters: self parameters shallowCopy.
trialArray ¬ Array new:
self trials.
block singleTrials: trialArray.
self outputStream: (WriteStream on: trialArray)
storeCurrentTrial
"Copy the digitized
data, and set the current trial on its way down
whatever it is we are using
as an outputStream..."
self currentTrial data: self buffer deepCopy.
self outputStream nextPut: currentTrial
The battery
simulation uses discrete stimulus presentation objects to generate stimulus
sequences and present stimuli. The
stimulus control protocol coordinates the various objects involved in stimulus
generation.
The prepareStimulusSequence method sets up
a stream from which individual stimuli can be read for each trial. It does this by first creating a sequence
(using the sequenceGenerator) using a given collection of stimulus template
objects, a trial count, and a collection of relative stimulus probabilities. We then set up a SampledStream over this sequence
so that we may draw from it in a random order without replacement. The sequence generation scheme is interesting
in that it is constructed using parts (WeightedCollections and SampledStreams)
that were much more specific to this application domain earlier in the design
process. The current design broke out
these two potentially general components and employs the Unix philosophy of
constructing special purpose components by composing a handful of general building
blocks rather than building a single special purpose component from scratch.
The selectNextStimulus method merely copies
the next stimulus from the stimulus stream into the current trial object. Note that we make a deepCopy of the stimulus
object rather than passing a reference to it.
This is because the stimulus sequence uses multiple references (via the
WeightedCollection) rather than copies, and because there is no telling whether
a subsequent analysis application might elect to make some destructive
reference to one of these objects. (The
issue of when to copy an object or when to pass a reference to it is one that
arises frequently in languages like Smalltalk and Lisp. [Bobrow 86] describes an approach to this
sort of problem-based on a lazy copy-upon-destructive-reference-scheme.)
The turnOnTheStimulus and turnOffTheStimulus methods pass the
current stimulus object to this BatteryItem's stimulus generator.
prepareNextStimulus
"Tell our stimulus
generator to prepare the stimulus."
stimulusGenerator prepare: self nextTrial stimulus
prepareStimulusSequence
"Prepare a sequence,
and set up a stream over it."
| seq stims count probs |
stims ¬ self stimuli.
count ¬ self trials.
probs ¬ self
probabilities.
seq ¬ self
sequenceGenerator
generateSequenceOn: stims
withSize: count
andProbabilities: probs.
self stimulusSequence: (SampledStream on: seq)
selectNextStimulus
"Pull the next stimulus
from our stimulus sequence, and tell ourself
what it is."
self nextTrial stimulus: self stimulusSequence next deepCopy
turnOffTheStimulus
"Tell our stimulus
generator to turn off the stimulus."
self stimulusGenerator turnOff: self stimulus
turnOnTheStimulus
"Tell our stimulus
generator to turn on the stimulus."
self stimulusGenerator turnOn: self stimulus
The battery
simulation uses discrete objects for response reporting. The response control protocol coordinates
these.
The response
control protocol for battery items consists of two methods. The enableResponseReporting
method passes an enable method on to
the response device. The evaluateResponse method queries the
response device, and loads the fields of the returned response into the current
trial object. Note that these values are
stored using message sends to self, so that a different data management scheme
might easily be substituted.
enableResponseReporting
"Turn on the response
device."
self responseDevice enable
evaluateResponse
"Ask the response
device for information pertaining to the current
response, and store
it."
| resp |
resp ¬ self
responseDevice response.
self responseType: resp responseButton.
self responseTime: resp responseTime
These methods
translate queries to the battery item into queries to the BatteryItem's
BatteryParameter object. Consult the
Battery-Parameters category description for more information on these
objects.
The use of message
sends to self insulates the bulk of the code in BatteryItem from changes in the
design of the data structures (which have indeed occurred during the evolution
of this project).
baseline
^self parameters baseline
channels
^self parameters channels
digitizingRate
^self parameters digitizingRate
inputBitA
^self parameters inputBitA
inputBitB
^self parameters inputBitB
label
^self parameters label
name
^self parameters name
outputBitA
^self parameters outputBitA
outputBitB
^self parameters outputBitB
points
^self parameters points
probabilities
^self parameters probabilities
responseMax
^self parameters responseMax
stimuli
^self parameters stimuli
stimulusDuration
^self parameters stimulusDuration
trialDuration
^self parameters trialDuration
trials
^self parameters trials
These access
methods translate sends to self into references to the current single trial
data object. Consult the definition of
class BatteryTrial in the Data-Management system category for more information.
The use of message
sends to self helps to encapsulate the bulk of the battery item framework from
the details of our single trial data management strategy. This strategy, like the parameter and
stimulus management strategies, has evolved considerably since the start of
this project.
data
^self currentTrial data
data: anObject
^self currentTrial data: anObject
responseTime
^self currentTrial responseTime
responseTime: time
^self currentTrial responseTime: time
responseType
^self currentTrial responseType
responseType: type
^self currentTrial responseType: type
stimulus
^self currentTrial stimulus
stimulus: stim
^self currentTrial stimulus: stim
trialNumber
^self currentTrial trialNumber
trialNumber: n
^self currentTrial trialNumber: n
The methods in this
category provide explicit read/write access to all of BatteryItem's instance
variables.
Perhaps the most
interesting thing about this protocol category is that it was generated
automatically, using
the accessingSubclass: instanceVariableNames:
classVariableNames: poolDictionaries: category: method found on page 289 of the Smalltalk Blue
book [Goldberg 83].
averagePipeline
^averagePipeline
averagePipeline: argument
averagePipeline ¬
argument.
^argument
block
^block
block: argument
block ¬ argument.
^argument
blockNumber
^blockNumber
blockNumber: argument
blockNumber ¬ argument.
^argument
buffer
^buffer
buffer: argument
buffer ¬ argument.
^argument
currentTrial
^currentTrial
currentTrial: argument
currentTrial ¬
argument.
^argument
currentTrialNumber
^currentTrialNumber
currentTrialNumber: argument
currentTrialNumber ¬
argument.
^argument
digitizer
^digitizer
digitizer: argument
digitizer ¬ argument.
^argument
experimenterLog
^experimenterLog
experimenterLog: argument
experimenterLog ¬
argument.
^argument
nextTrial
^nextTrial
nextTrial: argument
nextTrial ¬ argument.
^argument
outputStream
^outputStream
outputStream: argument
outputStream ¬
argument.
^argument
parameters
^parameters
parameters: argument
parameters ¬ argument.
^argument
responseDevice
^responseDevice
responseDevice: argument
responseDevice ¬
argument.
^argument
sequenceGenerator
^sequenceGenerator
sequenceGenerator: argument
sequenceGenerator ¬
argument.
^argument
stimulusClock
^stimulusClock
stimulusClock: argument
stimulusClock ¬
argument.
^argument
stimulusGenerator
^stimulusGenerator
stimulusGenerator: argument
stimulusGenerator ¬ argument.
^argument
stimulusSequence
^stimulusSequence
stimulusSequence: argument
stimulusSequence ¬ argument.
^argument
tallyPipeline
^tallyPipeline
tallyPipeline: argument
tallyPipeline ¬ argument.
^argument
trialClock
^trialClock
trialClock: argument
trialClock ¬ argument.
^argument
waveformDisplay
^waveformDisplay
waveformDisplay: argument
waveformDisplay ¬
argument.
^argument
BatteryItem class
class BatteryItem
class
superclass AccessibleObject
class
This BatteryItem
class category overrides new in
order to make sure that an initialize
message is sent, and the BatteryDataDictionary is initialized. See BatteryBrowser class for an example of a
use of the defaultItemList method.
defaultItemList
"Return a default item
list..."
| list |
list ¬
OrderedCollection new: 10.
list add: SternbergTask new.
list add: ToneOddball new.
list add: WordOddball new.
^list asArray
new
"Create a new battery
item, send it an initialize message, and return
the result..."
| item |
BatteryDataDictionary isNil ifTrue: [self initialize].
item ¬ super new.
item initialize.
^item
The initialize method fcreates a new
BatteryDataDictionary. Thehe standard
fileOut format [Krasner 83] generates a <Class> initialize message send
for any metaclass that implements an initialize method.
initialize
BatteryDataDictionary ¬
DataDictionary new: 100
This protocol
category has served as a repository for a collection of methods I have been
using to manage the Smalltalk code for this project. One can make a case that from the standpoint
of design aesthetics, much of this code should reside elsewhere. Nevertheless, here it is. It is presented in the hope that some of it
might prove of utility to someone entrusted with maintaining a large collection
of classes such the one presented here.
The backUpEverything method first files out all the categories in the
list returned by the batteryCategories
method as separate <Category-Name>.st files using the fileOutCategories: method. It then files out these same categories into
a single file named 'Project-Sources.st' using the fileOutCategories:on: method.
Then it files out the changes set [Goldberg 85] to 'Project-Changes.st'
using the fileOutChangesOn:
method.
The fileOutBundledCategories:on: method
creates a Unix shar archive file that can create a set of individual system
category *.st files on a Unix system.
(Use the Bourne shell). The
comment at the beginning of this method givens an example of how one might use
the matchSystemCategories: method.
The print out
messages printOutBundledCategories:on:,
printOutCategories and printOutCategories:on: are similar in
function to the analogous file out messages, except that they create Unix troff ready output files. These may be processed along with a macro
file named tmac.st using the
command: rditroff -ms <name>.
(The tmac.st file should be in
the default directory when rditroff is run.)
The Smalltalk code to generate troff
ready output was derived from code from the Berkeley Smalltalk distribution kit
[Krasner 83].
backUpEverything
"Update all our back up
files..." "BatteryItem
backUpEverything"
BatteryItem fileOutCategories: BatteryItem batteryCategories.
BatteryItem
fileOutCategories: BatteryItem batteryCategories
on: (FileStream fileNamed: 'Project-Sources.st').
BatteryItem
fileOutChangesOn: (FileStream fileNamed:
'Project-Changes.st')
batteryCategories
"Return all the battery
project categories..."
^#('Battery-Items' 'Battery-Parameters' 'Stimulus-Generators'
'Stimulus-Support' 'Sequence-Support' 'Response-Support' 'Data-Management'
'Realtime-Support' 'Realtime-Devices' 'Waveform-Support' 'Random-Support'
'Plumbing-Support' 'Linear-Algebra' 'Source-Hacking' 'Accessible-Objects'
'Interface-Battery' 'Interface-Protocol' )
fileOutBundledCategories: categories on: aFileStream
"BatteryItem
fileOutBundledCategories: (BatteryItem matchSystemCategories: 'Int*') on:
(FileStream fileNamed:
'shar.Interface-Stuff.st')"
| file line |
categories do:
[:category |
Transcript cr; show: '--> ' , category.
file ¬ 'troff.' ,
category.
file ¬ file copyReplaceAll: ' ' with: '_'.
line ¬ 'echo
"--> "' , file.
aFileStream nextPutAll: line; cr.
line ¬ 'cat >
' , file , ' << ''!!Hehehehe...!!'''.
aFileStream nextPutAll: line; cr.
SystemOrganization fileOutCategory: category on: aFileStream.
aFileStream cr; nextPutAll: '!!Hehehehe...!!'; cr].
aFileStream shorten; close
fileOutCategories: categories
"BatteryItem
fileOutCategories: BatteryItem batteryCategories"
categories do:
[:category |
Transcript cr; show: '--> ' , category.
SystemOrganization fileOutCategory: category]
fileOutCategories: categories on: aFileStream
"BatteryItem
fileOutCategories: BatteryItem
batteryCategories on:
(FileStream fileNamed:
'Project-Sources.st')"
categories do:
[:category |
Transcript cr; show: '--> ' , category.
SystemOrganization fileOutCategory: category on:
aFileStream.
aFileStream cr].
aFileStream shorten; close
fileOutChangesOn: aFileStream
"BatteryItem
fileOutChangesOn: (FileStream fileNamed: 'Project-Changes.st')"
"Remove old DoIt code,
and file out changes..."
Smalltalk allBehaviorsDo:
[:class | class removeSelector: #DoIt; removeSelector:
#DoItIn:].
aFileStream fileOutChanges
fileOutComments: categories on: aFileStream
"BatteryItem
fileOutComments: BatteryItem
batteryCategories on:
(FileStream fileNamed:
'Project-Sources.comments')"
categories do:
[:category |
Transcript cr; show: '--> ' , category.
SystemOrganization fileOutComments: category on:
aFileStream.
aFileStream cr].
aFileStream shorten; close
matchSystemCategories: pattern
"Return a collection of
category names that matches the given pattern..."
^SystemOrganization categories select: [:category | pattern
match: category]
printOutBundledCategories: categories on: aFileStream
"BatteryItem
printOutBundledCategories: (BatteryItem matchSystemCategories: 'Int*') on:
(FileStream fileNamed:
'shar.troff.Interface-Stuff')"
| file line |
categories do:
[:category |
file ¬ 'troff.' ,
category.
file ¬ file
copyReplaceAll: ' ' with: '_'.
line ¬ 'echo
"--> "' , file.
aFileStream nextPutAll: line; cr.
line ¬ 'cat >
' , file , ' << ''!!Hehehehe...!!'''.
aFileStream nextPutAll: line; cr.
Object printOutStartUp: aFileStream.
Object printOutTimeStamp: aFileStream.
SystemOrganization printOutCategory: category on:
aFileStream.
aFileStream cr; nextPutAll: '!!Hehehehe...!!'; cr].
aFileStream shorten; close
printOutCategories: categories
"Print out a list of
categories..."
"BatteryItem
printOutCategories: BatteryItem batteryCategories"
"BatteryItem
printOutCategories: (BatteryItem matchSystemCategories: 'Int*')"
categories do: [:category | SystemOrganization
printOutCategory: category]
printOutCategories: categories on: aFileStream
"BatteryItem printOutCategories:
BatteryItem batteryCategories on: (FileStream
fileNamed:
'troff.Project-Sources')"
Object printOutStartUp: aFileStream.
Object printOutTimeStamp: aFileStream.
categories do:
[:category |
SystemOrganization printOutCategory: category on:
aFileStream.
aFileStream cr].
aFileStream shorten; close
"Brian Foote 9/28/86
Added start up and time stamp calls..."
BatteryItem initialize
SternbergTask
Class SternbergTask
implements a visual Sternberg memory task [Sternberg 69] on top of the
ERP/oddball framework present in BatteryItem.
The variation on the Sternberg paradigm presented here involves the
presentation to a subject, for each trial, of a set of characters or digits
called a memory set. The subject is instructed to remember the
characters in the memory set. After the
memory set is removed from the screen, the subject is presented with another
character called a probe. The subject's task is to indicated whether
the probe belongs to the memory set. A
trial in which the probe was in fact drawn from the memory set is a positive
trial. One in which the probe was
not drawn from the memory set is anegative trial.
class name SternbergTask
superclass BatteryItem
instance variable names
items
trialClock
stimulusClock
digitizer
responseDevice
parameters
stimulusSequence
sequenceGenerator
stimulusGenerator
buffer
experimenterLog
waveformDisplay
block
blockNumber
nextTrial
currentTrial
currentTrialNumber
outputStream
averagePipeline
tallyPipeline
class variable names
BatteryDataDictionary
category Battery-Items
hierarchy
Object
AccessibleObject
BatteryItem
SternbergTask
ToneOddball
WordOddball
The allocateParameters and allocateStimulusGenerator methods
implement item specific parameter and stimulus generator resource allocation
code.
allocateParameters
"Allocate our parameter
object."
self parameters: SternbergTaskParameters new
allocateStimulusGenerator
"Build our stimulus
generator."
self stimulusGenerator: SternbergDisplayGenerator new
The collectData method defines the experimental
control and data acquisition strategy for the Sternberg task battery item. The remainder of the methods in this protocol
category are inherited from BatteryItem.
First, the A/D system is started.
Then, the memory set is prepared, and trial clock is instructed to wait
until a baseline period (relative to the start of the trial) has elapsed. The memory set is then presented for an
appropriate amount of time, and turned off.
The pattern for
presenting the actual stimulus (i.e. the probe) is similar. First, a probe is prepared. The program then waits until the time at
which the probe is to be presented arrives.
Then, a timer is started so that there will be a timebase relative to
the stimulus onset. Next, the probe is
turned on, and the response reporting system is enabled. When the stimulus duration has elapsed, the
stimulus is turned off.
When all the data
have been collected, a check is made to see whether additional time is
necessary for subject response data collection.
collectData
"Do Sternberg data
collection."
"First, start the A/D converter..."
self startDigitizer.
"Now, prepare the memory set, and present it..."
self prepareTheMemorySet.
self trialClock waitUntil: self memorySetBaseline.
self turnOnTheMemorySet.
self trialClock waitUntil: self memorySetBaseline + self
memorySetDuration.
self turnOffTheMemorySet.
"Next, start the stimulus clock and turn on the stimulus.
Enable response reporting too.
Then wait until the stimulus
duration has elapsed, and turn off the stimulus..."
self prepareTheProbe.
self trialClock waitUntil: self probeBaseline.
self stimulusClock startFor: self trialDuration - self
probeBaseline.
self turnOnTheProbe.
self enableResponseReporting.
self stimulusClock waitUntil: self stimulusDuration.
self turnOffTheProbe.
"Finally, wait for the digitizer to finish.
if the RT wait time is greater than the digitizing time,
wait that out..."
self digitizer wait.
self stimulusClock waitUntil: self responseMax
The methods in this
protocol category embody a substantial proportion of the code that makes the
SternbergTask battery item distinct.
The prepareNextStimulus method selects both
a memory set and a probe for the next trial.
The way in which the memory set is selected shows a novel application of
SampledStreams. The memory set should be
a set of a given size drawn at random (without replacement) from a given
vocabulary of characters.
This set is constructed
as follows: First, a SampledStream is
created over the BatteryItem's vocabulary string. Then an empty output string (the memory set)
is created, and a WriteStream is defined over it (memorySetStream). The memory set is constructed by moving the
appropriate number of characters from the input (sampled) stream to the output
stream. The underlying collection of
this output stream is the memory set, which can then be used.
The probe is
selected and prepared as follows: If a
positive trial is called for, a single character is selected at random, using a
RandomStream (sample with replacement) over the memory set. If a negative probe is required, the next
character in the vocabulary stream that was used to create the memory set, from
which the memory set has already been drawn, is selected
as the stimulus character.
The prepareTheMemorySet method simply
forwards the current stimulus descriptor to the stimulus generator. The remaining methods in this protocol
category similarly forward stimulus manipulation requests to the stimulus
generator.
prepareNextStimulus
"Select a memory set
and a probe."
|vocabularyStream memorySet memorySetStream |
vocabularyStream ¬
SampledStream on: self vocabulary.
memorySet ¬ String new:
self memorySetSize.
memorySetStream ¬
WriteStream on: memorySet.
self memorySetSize timesRepeat: [memorySetStream nextPut:
vocabularyStream next].
self nextTrial stimulus memorySet: memorySet.
self nextTrial stimulus category = #positive
ifTrue: [ self nextTrial stimulus probe:
(RandomStream on: memorySet) next asSymbol asString
]
ifFalse: [self nextTrial stimulus probe:
vocabularyStream next asSymbol asString]
prepareTheMemorySet
"Tell our stimulus
generator to get the memory set ready."
self stimulusGenerator prepareMemorySet: self currentTrial
stimulus
prepareTheProbe
"Tell our stimulus
generator to get the memory set ready."
self stimulusGenerator prepareProbe: self currentTrial stimulus
turnOffTheMemorySet
"Tell our stimulus
generator to turn off the memory set."
self stimulusGenerator turnOffMemorySet: self currentTrial
stimulus
turnOffTheProbe
"Tell our stimulus
generator to turn off the probe."
self stimulusGenerator turnOffProbe: self currentTrial stimulus
turnOnTheMemorySet
"Tell our stimulus
generator to turn on the memory set."
self stimulusGenerator turnOnMemorySet: self currentTrial
stimulus
turnOnTheProbe
"Tell our stimulus
generator to turn on the probe."
self stimulusGenerator turnOnProbe: self currentTrial stimulus
The methods in this
category add BatteryItem access methods for the fields that the
SternbergTaskParameters object adds to the BatteryParameters object.
memorySetBaseline
^self parameters memorySetBaseline
memorySetDuration
^self parameters memorySetDuration
memorySetSize
^self parameters memorySetSize
probeBaseline
^self parameters probeBaseline
probeDuration
^self parameters probeDuration
vocabulary
^self parameters vocabulary
Each concrete
battery item provides its own prepareAverageFixtures
method. This is necessary to take
into account item specific stimulus characteristics and labeling
requirements. A detailed discussion of
the mechanics of fixture preparation can be found in the discussion of this
protocol category given for class BatteryItem.
prepareAverageFixtures
"Prepare the average
pipelines."
self averagePipeline: (Dictionary new: 10).
self block averages: (Dictionary new: 10).
self
average: [self currentTrial data]
using: [:data | true]
withLabel: 'Average (All trials)'.
self
average: [self currentTrial data]
using: [:data | self currentTrial stimulus category =
#positive]
withLabel: 'Average (Positive)'.
self
average: [self currentTrial data]
using: [:data | self currentTrial stimulus category =
#negative]
withLabel: 'Average (Negative)'
SternbergTask class
class SternbergTask
class
superclass BatteryItem
class
The example1 method shows how one might
execute a sample block of trials. Note
that before a block can be run, the Timebase object must have been
initialized. In practice, battery blocks
will usually be run by pressing the run
button after having selected an item in the battery browser.
example1
"SternbergTask
example1"
Timebase initialize.
SternbergTask new doBlock
ToneOddball
The ToneOddball
class implements a simple auditory oddball experiment [Duncan-Johnson 77]. In this experiment, a subject is presented
with one of two tones. The subject can
be instructed to count one of the tones, and ignore the other. The subject can also be told to press a
button in response to one or both stimulus categories. A frequent manipulation is to vary the
relative frequency of the two stimulus categories.
class name ToneOddball
superclass BatteryItem
instance variable names
items
trialClock
stimulusClock
digitizer
responseDevice
parameters
stimulusSequence
sequenceGenerator
stimulusGenerator
buffer
experimenterLog
waveformDisplay
block
blockNumber
nextTrial
currentTrial
currentTrialNumber
outputStream
averagePipeline
tallyPipeline
class variable names
BatteryDataDictionary
pool dictionaries
category Battery-Items
hierarchy
Object
AccessibleObject
BatteryItem
SternbergTask
ToneOddball
WordOddball
The allocateParameters and allocateStimulusGenerator methods
implement item specific parameter and stimulus generator resource allocation
code.
allocateParameters
"Allocate our parameter
object."
self parameters: ToneOddballParameters new
allocateStimulusGenerator
"Build our stimulus
generator."
| bitA bitB |
bitA ¬ self outputBitA.
bitB ¬ self outputBitB.
self stimulusGenerator: (ToneGenerator bitA: bitA bitB: bitB)
outputBitA
^self parameters outputBitA
outputBitB
^self parameters outputBitB
The collectData method specifies the
experimental control and data acquisition scheme used for this item. First, the digitizer is started. Then the method waits for a baseline period,
relative to the start of this trial, to elapse.
Next, the stimulus timer is started.
Immediately thereafter, the stimulus is turned on and response reporting
is enabled. When the stimulus
presentation period has elapsed, the stimulus is turned off. The method then waits until data collection
is complete, and the response window time has elapsed.
collectData
"Do tone oddball data
collection."
"First, start the A/D converter, and wait until the baseline
elapses..."
self startDigitizer.
self trialClock waitUntil: self baseline.
"Next, start the stimulus clock and turn on the stimulus.
Enable response reporting too.
Then wait until the stimulus
duration has elapsed, and turn off the stimulus..."
self stimulusClock startFor: self trialDuration - self
baseline.
self turnOnTheStimulus.
self enableResponseReporting.
self stimulusClock waitUntil: self stimulusDuration.
self turnOffTheStimulus.
"Finally, wait for the digitizer to finish.
If the RT wait time is greater than the digitizing time,
wait that out..."
self digitizer wait.
self stimulusClock waitUntil: self responseMax
Each concrete
battery item provides its own prepareAverageFixtures
method. This is necessary to take
into account item specific stimulus characteristics and labeling
requirements. A detailed discussion of
the mechanics of fixture preparation can be found in the discussion of this
protocol category given for class BatteryItem.
prepareAverageFixtures
"Prepare the average
pipelines."
self averagePipeline: (Dictionary new: 10).
self block averages: (Dictionary new: 10).
self
average: [self currentTrial data]
using: [:data | true]
withLabel: 'Average (All trials)'.
self
average: [self currentTrial data]
using: [:data | self currentTrial stimulus category =
#catA]
withLabel: 'Average (Category A)'.
self
average: [self currentTrial data]
using: [:data | self currentTrial stimulus category =
#catB]
withLabel: 'Average (Category B)'
ToneOddball class
class ToneOddball
class
superclass BatteryItem
class
The example1 method shows how one might
execute a sample block of trials. Note
that before a block can be run, the Timebase object must have been
initialized. In practice, battery blocks
will usually be run by pressing the run
button after having selected an item in the battery browser.
example1
"ToneOddball
example1"
Timebase initialize.
ToneOddball new doBlock
WordOddball
The WordOddball
class implements a visual semantic oddball task [Donchin 81].
In this experiment, a subject is presented with a random word drawn from
one of two categories. The subject must
count or respond as with the ToneOddball.
It is instructive
to point out that to implement a concrete BatteryItem, it is necessary for an
experiment to implement just four methods:
allocateParameters, allocateStimulusGenerator, collectData, and prepareAverageFixtures. To
fully exploit the battery framework, an experimenter might also need to create
new subclasses of BatteryParameter, StimulusGenerator, and Stimulus
hierarchies.
class name WordOddball
superclass BatteryItem
instance variable names
items
trialClock
stimulusClock
digitizer
responseDevice
parameters
stimulusSequence
sequenceGenerator
stimulusGenerator
buffer
experimenterLog
waveformDisplay
block
blockNumber
nextTrial
currentTrial
currentTrialNumber
outputStream
averagePipeline
tallyPipeline
class variable names
BatteryDataDictionary
category Battery-Items
hierarchy
Object
AccessibleObject
BatteryItem
SternbergTask
ToneOddball
WordOddball
Subclasses of
BatteryItem are required to provide implementations of two standard resource
allocation messages: allocateParameters, and allocateStimulusGenerator. (Both are defined as being subclass
responsibilities in BatteryItem.) The allocateParameters method simply
ensures that a parameter object belonging to the correct class is
allocated. The allocateStimulusGenerator message's task is potentially more
complicated. It must ensure that an
instance of some sort of StimulusGenerator appropriate to the type of battery
item being constructed is created and initialized.
The battery
simulation has attempted to separate battery items and (simulated) stimulus
generation equipment so that stimulus generators might be mixed and matched
among several different battery items.
Frequently, the major differences among a collection of experimental
designs will be in sorts of stimuli they employ. By separating the stimulus generation code
from the rest of the experimental code, the reusability of both should be
enhanced.
The stimulus
generation and response reporting hierarchies are examples of places in this
battery simulation where tasks handled in the original CPL battery by
(simulated) inheritance are now handled by discrete components. The evolution of inheritance frameworks into
component frameworks is discussed in Chapter VI.
The allocateParameters and allocateStimulusGenerator methods
implement item specific parameter and stimulus generator resource allocation
code. Of interest here is the scheme we
use in allocateStimulusGenerator for
implementing our random word lists. A
dictionary of streams is created which is keyed by the two stimulus
categories. Each stream is a
RandomStream over a vocabulary array.
Since RandomStreams sample with replacement, they will provide, each
time they are asked, a random word from their respective underlying
vocabularies. This dictionary, once
constructed, is given to a newly created WordGenerator (a subclass of
StimulusGenerator).
allocateParameters
"Allocate our parameter
object."
self parameters: WordOddballParameters new
allocateStimulusGenerator
"Build our stimulus
generator."
| streamDictionary animals vegetables |
streamDictionary ¬
Dictionary new: 2.
animals ¬ #(dog cat
mouse ).
vegetables ¬ #(carrot
potato tomato ).
streamDictionary at: #animal put: (RandomStream on: animals).
streamDictionary at: #vegetable put: (RandomStream on:
vegetables).
self stimulusGenerator: (WordGenerator on: streamDictionary)
Each subclass of
BatteryItem is required to implement a collectData
method. This method conducts the
basic per-trial data collection and experimental control activity for each
battery item.
The collectData method specifies
experimental control and data acquisition scheme used for this item. First, the digitizer is started. Then the method waits for a baseline period,
relative to the start of this trial, to elapse.
Then, the stimulus timer is started.
Immediately thereafter, the method turns on the stimulus and enable
response reporting. When the stimulus
presentation period has elapsed, the stimulus is turned off. The method then waits until data collection
is complete, and the response window time has elapsed.
The perceptive
reader will note that the collectData
method given here is identical to the one given in ToneOddball. I could have either defined an intermediate
abstract calls (say, SimpleOddball) between BatteryItem and these two classes
to take advantage of this. Alternately,
I could have made this implementation of collectData
the default in BatteryItem itself. That
I did neither is in recognition of the fact that in a somewhat fuller battery
simulation, detail that would distinguish a larger set of applications from one
another would quickly emerge at this level, just as it does in the
SternbergTask battery item.
collectData
"Do word oddball data
collection."
"First, start the A/D converter, and wait until the baseline
elapses..."
self startDigitizer.
self trialClock waitUntil: self baseline.
"Next, start the stimulus clock and turn on the stimulus.
Enable response reporting too.
Then wait until the stimulus
duration has elapsed, and turn off the stimulus..."
self stimulusClock startFor: self trialDuration - self
baseline.
self turnOnTheStimulus.
self enableResponseReporting.
self stimulusClock waitUntil: self stimulusDuration.
self turnOffTheStimulus.
"Finally, wait for the digitizer to finish.
If the RT wait time is greater than the digitizing time,
wait that out..."
self digitizer wait.
self stimulusClock waitUntil: self responseMax
Each concrete
battery item must provide its own prepareAverageFixtures
method. This is necessary to take
into account item specific stimulus characteristics and labeling
requirements. A detailed discussion of
the mechanics of fixture preparation can be found in the discussion of this protocol
category given for class BatteryItem.
prepareAverageFixtures
"Prepare the average
pipelines."
self averagePipeline: (Dictionary new: 10).
self block averages: (Dictionary new: 10).
self
average: [self currentTrial data]
using: [:data | true]
withLabel: 'Average (All trials)'.
self
average: [self currentTrial data]
using: [:data | self currentTrial stimulus category =
#catA]
withLabel: 'Average (Category A)'.
self
average: [self currentTrial data]
using: [:data | self currentTrial stimulus category =
#catB]
withLabel: 'Average (Category B)'
WordOddball class
class WordOddball
class
superclass BatteryItem
class
The example1 method shows how one might
execute a sample block of trials. Note
that before a block can be run, the Timebase object must have been
initialized. In practice, battery blocks
will usually be run by pressing the run
button after having selected an item in the battery browser.
example1
"WordOddball
example1"
Timebase initialize.
WordOddball new doBlock
Battery-Parameters
The
Battery-Parameters system category contains the following classes:
BatteryParameters Houses common
BatteryItem parameters
SternbergTaskParameters Adds SternbergTask specific
parameters
ToneOddballParameters Adds ToneOddball specific
parameters
WordOddballParameters Adds WordOddball specific
parameters
These parameter
objects are in effect records or dictionaries that contain those values that
can be edited and modified by the experimenter.
(In fact, since these objects are subclasses of AccessibleObject, they
can be treated as records or dictionaries.)
Parameter objects
are distinct objects rather than parts of the items themselves for several
reasons. One is that, as separate
objects, they can be copied and archived along with the collected data without
recording the entire state of the item itself.
This distinction between the parameter objects and the item objects
could become more significant should an external data management scheme be
implemented. The second reason for
keeping parameter objects separate is to distinguish values that should be
presented to the user for alteration via the battery user interface from the
battery item's other instance variables.
Parameter objects might also serve as a components in a more general
(and yet to be designed) user parameter management/interface scheme.
BatteryParameters
class name BatteryParameters
superclass AccessibleObject
instance variable names
items
baseline
channels
points
digitizingRate
responseMax
stimulusDuration
trialDuration
trials
writeDataFlag
probabilities
stimuli
inputBitA
inputBitB
name
label
category Battery-Parameters
hierarchy
Object
AccessibleObject
BatteryParameters
SternbergTaskParameters
ToneOddballParameters
WordOddballParameters
These two methods
establish default values for each basic parameter. Note that by default data are written to the
data dictionary, and that the probability and stimuli fields are Arrays.
establishDefaults
"Set out our
defaults..."
baseline ¬ 1.
channels ¬ 1.
points ¬ 10.
digitizingRate ¬ 1.
responseMax ¬ 9.
stimulusDuration ¬ 2.
trialDuration ¬ 15.
trials ¬ 10.
writeDataFlag ¬ True.
probabilities ¬ #(0.5
0.5).
stimuli ¬ #(catA catB)
initialize
"Set defaults and
return ourself..."
self establishDefaults.
^self
These methods allow
explicit read/write access to all of this object's fields using the
conventional record style protocol.
(Note that since we are a subclass of AccessibleObject, all these
messages would have functioned correctly anyway, albeit much less quickly.)
baseline
^baseline
baseline: argument
baseline ¬ argument.
^argument
channels
^channels
channels: argument
channels ¬ argument.
^argument
digitizingRate
^digitizingRate
digitizingRate: argument
digitizingRate ¬ argument.
^argument
inputBitA
^inputBitA
inputBitA: argument
inputBitA ¬ argument.
^argument
inputBitB
^inputBitB
inputBitB: argument
inputBitB ¬ argument.
^argument
label
^label
label: argument
label ¬ argument.
^argument
name
^name
name: argument
name ¬ argument.
^argument
points
^points
points: argument
points ¬ argument.
^argument
probabilities
^probabilities
probabilities: argument
probabilities ¬ argument.
^argument
responseMax
^responseMax
responseMax: argument
responseMax ¬ argument.
^argument
stimuli
^stimuli
stimuli: argument
stimuli ¬ argument.
^argument
stimulusDuration
^stimulusDuration
stimulusDuration: argument
stimulusDuration ¬ argument.
^argument
trialDuration
^trialDuration
trialDuration: argument
trialDuration ¬ argument.
^argument
trials
^trials
trials: argument
trials ¬ argument.
^argument
writeDataFlag
^writeDataFlag
writeDataFlag: argument
writeDataFlag ¬ argument.
^argument
BatteryParameter
class
class BatteryParameter
class
superclass AccessibleObject
class
The new method is overridden here to enforce the convention that each
new object must explicitly call an initialize
method.
new
"Create a new parameter
object and initialize it..."
^super new initialize
SternbergTaskParameters
class name SternbergTaskParameters
superclass BatteryParameters
instance variable names
items
baseline
channels
points
digitizingRate
responseMax
stimulusDuration
trialDuration
trials
writeDataFlag
probabilities
stimuli
inputBitA
inputBitB
name
label
memorySetBaseline
memorySetDuration
probeBaseline
probeDuration
memorySetSize
vocabulary
class variable names
pool dictionaries
category Battery-Parameters
hierarchy
Object
AccessibleObject
BatteryParameters
SternbergTaskParameters
ToneOddballParameters
WordOddballParameters
The establishDefaults method overrides the
one given in BatteryParameters so that values can be established for item
specific parameters. Note that its first
official act is to initialize the common parameters via a call to its superclass.
establishDefaults
"Do Sternberg
defaults... "
| positive negative |
super establishDefaults.
memorySetBaseline ¬ 1.
memorySetDuration ¬ 1.
memorySetSize ¬ 3.
vocabulary ¬ 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.
probeBaseline ¬ 4.
probeDuration ¬ 1.
positive ¬ SternbergStimulus
new.
positive category: #positive.
negative ¬ SternbergStimulus
new.
negative category: #negative.
stimuli ¬ Array with:
positive with: negative.
name ¬ 'Sternberg/ERP Task'.
label ¬ 'Sternberg/ERP
Experiment'
Allow explicit
read/write access to all of this object's fields using the conventional record
style protocol. (Note that since
SternbergTaskParameters is a subclass of AccessibleObject, all these messages
would have functioned correctly anyway, albeit much less quickly.)
memorySetBaseline
^memorySetBaseline
memorySetBaseline: argument
memorySetBaseline ¬ argument.
^argument
memorySetDuration
^memorySetDuration
memorySetDuration: argument
memorySetDuration ¬ argument.
^argument
memorySetSize
^memorySetSize
memorySetSize: argument
memorySetSize ¬ argument.
^argument
probeBaseline
^probeBaseline
probeBaseline: argument
probeBaseline ¬ argument.
^argument
probeDuration
^probeDuration
probeDuration: argument
probeDuration ¬ argument.
^argument
vocabulary
^vocabulary
vocabulary: argument
vocabulary ¬ argument.
^argument
ToneOddballParameters
class name ToneOddballParameters
superclass BatteryParameters
instance variable names
items
baseline
channels
points
digitizingRate
responseMax
stimulusDuration
trialDuration
trials
writeDataFlag
probabilities
stimuli
inputBitA
inputBitB
name
label
outputBitA
outputBitB
class variable names
pool dictionaries
category Battery-Parameters
hierarchy
Object
AccessibleObject
BatteryParameters
SternbergTaskParameters
ToneOddballParameters
WordOddballParameters
The establishDefaults method overrides the
one given in BatteryParameters so that values can be established for of this
object's item specific parameters. Note
that its first official act is to initialize the common parameters via a call
to its superclass.
establishDefaults
"Do ToneOddball
defaults... "
| toneA toneB |
super establishDefaults.
toneA ¬ ToneStimulus
new.
toneA primary: #toneA ; category: #catA.
toneB ¬ ToneStimulus
new.
toneB primary: #toneB ; category: #catB.
stimuli ¬ Array with:
toneA with: toneB.
outputBitA ¬ 0.
outputBitB ¬ 1.
name ¬ 'Tone Oddball'.
label ¬ 'Auditory Oddball Experiment'
Allow explicit
read/write access to all of this object's fields using the conventional record
style protocol. (Note that since
ToneOddballParameters is a subclass of AccessibleObject, all these messages
would have functioned correctly anyway, albeit much less quickly.)
outputBitA
^outputBitA
outputBitA: argument
outputBitA ¬ argument.
^argument
outputBitB
^outputBitB
outputBitB: argument
outputBitB ¬ argument.
^argument
WordOddballParameters
class name WordOddballParameters
superclass BatteryParameters
instance variable names
items
baseline
channels
points
digitizingRate
responseMax
stimulusDuration
trialDuration
trials
writeDataFlag
probabilities
stimuli
inputBitA
inputBitB
name
label
class variable names
pool dictionaries
category Battery-Parameters
hierarchy
Object
AccessibleObject
BatteryParameters
SternbergTaskParameters
ToneOddballParameters
WordOddballParameters
The establishDefaults method overrides the
one given in BatteryParameters so that values can be established for this
object's item specific parameters.
establishDefaults
"Do WordOddball
defaults... "
| animal vegetable |
super establishDefaults.
animal ¬ WordStimulus new.
animal primary: #animal ; category: #catA.
vegetable ¬
WordStimulus new.
vegetable primary: #vegetable ; category: #catB.
stimuli ¬ Array with:
animal with: vegetable.
name ¬ 'Word Oddball'.
label ¬
'Animal/vegetable Oddball Experiment'
Stimulus-Generators
These classes
simulate the hardware and software one would normally use to generate
experimental stimuli. These classes
might provide a basis for a mix-and-match stimulus generation capability in a
fuller battery simulation.
Stimulus generator
objects are designed to be self-contained embodiments of specific stimulus
generation schemes. Since these schemes
themselves vary with experimental designs as well as with the basic hardware
and software characteristics of the stimulus generators, the external protocols
for these objects vary as well. Note
that though the stimulus generator classes defined here exactly mirror the
BatteryItem hierarchy, this might not necessarily be the case in a fuller
simulation.
The StimulusGenerator
hierarchy shows how a portion of the battery simulation that was formerly
embedded in the BatteryItem hierarchy has, under Smalltalk, evolved into a
separate part of the overall battery framework.
The reuse of pluggable, black-box components is, all other things being
equal, preferable to reuse via inheritance.
The identification of components that may be factored out of an
inheritance hierarchy in this fashion is usually possible only after several
iterations through the design process.
(This issue is discussed in detail in Chapter VI.)
Indeed, the
StimulusGenerator hierarchy is in some respects still in transition between
membership in the original battery hierarchy and clean isolation from it. The degree of coupling seen in the interface
between each battery item and these classes is still somewhat high.
One very intriguing
route by which this coupling might be reduced is via the introduction of
parallelism. Under such an approach,
stimulus generators would run in parallel with battery items, with both tied to
the same underlying timebase. Such an
approach would simplify both the battery item stimulus coordination code, and
the stimulus sequencing code in this stimulus generators. Hence, the use of parallelism could greatly
increase the generality and reusability of components of both hierarchies.
Realtime
application programs frequently exhibit a structure in which the mainline code
must explicitly schedule sequences of otherwise unrelated events. The use of parallel processes can free the
designer from this temporal yoke.
The classes in this
category are:
StimulusGenerator Abstract
StimulusGenerator superclass
SternbergDisplayGenerator The SternbergTask stimulus generator
ToneGenerator The
ToneOddball stimulus generator
WordGenerator The
WordOddball stimulus generator
StimulusGenerator
The
StimulusGenerator class is an abstract superclass for a family of stimulus
generation objects. It defines a common,
default protocol for stimulus generators.
class name StimulusGenerator
superclass Object
instance variable names
class variable names
pool dictionaries
category Stimulus-Generators
hierarchy
Object
StimulusGenerator
SternbergDisplayGenerator
ToneGenerator
WordGenerator
initialize
"Provide nothing as our
default behavior..."
^self
This protocol
defines a default stimulus control protocol to which most clients of any
subclass of StimulusGenerator will subscribe.
Note that not all subclasses of StimulusGenerator will override all
these methods. In these cases, the
default action (given below) will be to do nothing. Some subclasses of StimulusGenerator will
need to provide a superset of the protocol given below for stimulus
control. Such classes will add
additional methods to this protocol.
finishBlock
"Default shall be to do
nothing..."
prepare: aStimulus
"Default shall be to do
nothing..."
startBlock
"Default shall be to do
nothing..."
turnOff: aStimulus
"Default shall be to do
nothing..."
turnOn: aStimulus
"Default shall be to do
nothing..."
StimulusGenerator
class
class StimulusGenerator
class
superclass Object
class
new
"Return an initialized
instance..."
^super new initialize
SternbergDisplayGenerator
The
SternbergDisplayGenerator class simulates the hardware and software that one
would employ to generate the stimuli for a Sternberg task.
class name SternbergDisplayGenerator
superclass StimulusGenerator
instance variable names
class variable names
pool dictionaries
category Stimulus-Generators
hierarchy
Object
StimulusGenerator
SternbergDisplayGenerator
ToneGenerator
WordGenerator
Since the stimulus
control scheme for a Sternberg task is different from the generic oddball
scheme outlined in StimulusGenerator, we override the default (do nothing)
behaviors for the default StimulusGenerator protocol using shouldNotImplement. The
display device itself is simulated by writing the stimulus to the Smalltalk
system transcript. Other messages in the
stimulus generation protocol simply do nothing what so ever in this simulation.
This class is
probably misplaced in the StimulusGenerator hierarchy. The fact that it in effect removes nearly the
entire StimulusGenerator protocol is evidence that this hierarchy needs
reorganization. This class is an example
of a stimulus generation scheme that uses multiple stimulus events. In the CPL Battery, two items exhibited this
structure. The other items exhibited the
simpler structure that is reflected in the standard protocol for stimulus
generation given in StimulusGenerator.
I deferred a major
reorganization of this hierarchy in recognition of the potential a
process-based organization might bring to the battery framework.
prepare: aStimulus
"We distinguish between
probes and memory sets, so we don't do this..."
self shouldNotImplement
prepareMemorySet: aStimulus
"Do nothing here for
now..."
prepareProbe: aStimulus
"Do nothing here for
now..."
turnOff: aStimulus
"We distinguish between
probes and memory sets, so we don't do this..."
self shouldNotImplement
turnOffMemorySet: aStimulus
"Do nothing here for
now..."
turnOffProbe: aStimulus
"Do nothing here for
now..."
turnOn: aStimulus
"We distinguish between
probes and memory sets, so we don't do this..."
self shouldNotImplement
turnOnMemorySet: aStimulus
"Just write the memory
set to the transcript for now..."
Transcript show: '--> Memory Set: ' , aStimulus memorySet; cr; endEntry
turnOnProbe: aStimulus
"Just write the probe
to the transcript for now..."
Transcript show: '--> Probe:
' , aStimulus probe; cr; endEntry
ToneGenerator
The ToneGenerator
class simulates a digital output driven two channel tone generator. Tones are generated by sending set and clear messages to instances of OutputBit.
class name ToneGenerator
superclass StimulusGenerator
instance variable names
bitA
bitB
class variable names
pool dictionaries
category Stimulus-Generators
hierarchy
Object
StimulusGenerator
SternbergDisplayGenerator
ToneGenerator
WordGenerator
These methods
provide read/write access to the instance variables that house the instances of
OutputBit that activate the (simulated) tone generators.
bitA
"Return the output bit
for the first tone..."
^bitA
bitA: aBit
"Set the output bit for
the first tone..."
^bitA ¬ aBit
bitB
"Return the output bit
for the second tone..."
^bitB
bitB: aBit
"Set the output bit for
the second tone..."
^bitB ¬ aBit
The methods in this
category simulate a digital output bit driven tone generation scheme.
When a block is
begun, the startBlock method sends clear messages to both the output bits
to ensure that they are off. The same
thing occurs at the end of a block in finishBlock.
The turnOn: and turnOff: methods both accept a stimulus descriptor, and check its primary stimulus field. If this field is #toneA, the output bit A is
affected, and if it is #toneB, output bit B is affected.
finishBlock
"Make sure both our
bits are off..."
bitA clear.
bitB clear
startBlock
"Make sure both our
bits are off..."
bitA clear.
bitB clear
turnOff: aStimulus
"Turn off the bit
indicated as the primary stimulus by the Stimulus object
that was passed to
us..."
| primary |
primary ¬ aStimulus
primary.
primary == #toneA ifTrue: [bitA clear. ^self].
primary == #toneB ifTrue: [bitB clear. ^self].
self error: 'Bad stimulus...'
turnOn: aStimulus
"Turn on the bit
indicated as the primary stimulus by the Stimulus object
that was passed to
us..."
| primary |
primary ¬ aStimulus
primary.
primary == #toneA ifTrue: [bitA set. ^self].
primary == #toneB ifTrue: [bitB set. ^self].
self error: 'Bad stimulus...'
ToneGenerator class
class ToneGenerator
class
superclass StimulusGenerator
class
The bitA:bitB: message provides a shorthand
for creating a ToneGenerator and assigning it a pair of output bits. (Perhaps new
should be overridden to make this form of initialization mandatory.)
bitA: a bitB: b
"Create a tone
generator, and set up the given bits..."
| gen |
gen ¬ super new.
gen initialize.
gen bitA: (OutputBit onBit: a).
gen bitB: (OutputBit onBit: b).
^gen
WordGenerator
The WordGenerator
class simulates the hardware and software one might employ for presenting word
stimuli in a word oddball task. It is
provided, upon creation, with a dictionary of stream objects that provide it
with the word stimuli themselves. This
dictionary is keyed using the primary field of the stimulus descriptor.
class name WordGenerator
superclass StimulusGenerator
instance variable names
streamDictionary
class variable names
pool dictionaries
category Stimulus-Generators
hierarchy
Object
StimulusGenerator
SternbergDisplayGenerator
