Programming Reference:AssociationMap Class

Location

src/shared/modules/application/stimuli/Association

Synopsis

This page describes four closely related classes declared in a common header file, all related to stimulus presentation and target classification.

• Association is a class that associates sets of stimuli with sets of targets.
• AssociationMap maps stimulus codes to Associations, and sorts targets according to classification results given over stimulus codes.
• ClassResult and TargetClassification are auxiliary classes designed as input and output of AssociationMap's ClassifyTargets() function. ClassResult represents accumulated classification output from signal processing, TargetClassification maps Target pointers to a selection likelihood value.

Association Class

An object of type Association defines a set consisting of stimuli, an additional set of targets, and a number of properties associated with a single stimulus code.

A user application based on the StimulusTask class will present stimuli, or groups thereof, in sequence, and may select targets according to stimulus-related responses it obtains from the signal processing module.

The Association class serves to associate stimuli with each other, targets with each other, stimuli with targets, and to store sequencing information about such groups.

Properties

int StimulusDuration (rw)

The duration of stimulus presentation, given in sample blocks.

int ISIMinDuration (rw)

The minimum duration of the inter-stimulus interval, given in sample blocks.

int ISIMaxDuration (rw)

The maximum duration of the inter-stimulus interval, given in sample blocks. When ISIMinDuration is different from ISIMaxDuration, the StimulusTask base class will choose a random interval between the two from a uniform distribution.

The StimulusDuration, ISIMinDuration, ISIMaxDuration properties are not used by the Association class itself but by the StimulusTask application base class to determine application sequencing.

SetOfStimuli Stimuli (rw)

Provides read/write access to the SetOfStimuli object that stores stimulus pointers within the Association object.

SetOfTargets Targets (rw)

Provides read/write access to the SetOfTargets object that stores target pointers within the Association object.

Methods

Clear()

Clears both stimulus and target sets.

DeleteObjects()

Deletes all stimulus and target objects that are part of the association, and clears the association.

NB: You should not call this function for an Association object unless you can be sure that no stimulus is part of multiple associations. Otherwise, you will risk multiple deallocation of stimulus pointers. Typically, you will keep track of existing stimuli in a separate SetOfStimuli object, and call that set's DeleteObjects() member function in order to dispose of stimulus objects.

Add(Stimulus pointer|Target pointer)

Adds a stimulus or target object to the association.

Remove(Stimulus pointer|Target pointer)

Removes a given stimulus object from the association; nothing happens when the specified object is not a member of the set.

bool Contains(Stimulus pointer|Target pointer)

Returns true if the specified object is part of the association, and false otherwise.

bool Intersects(SetOfStimuli|SetOfTargets)

Returns true if any of the elements of the specified set is part of the association, and false otherwise.

Present()

Prompts each stimulus in the association to present itself by calling its Present() method.

Conceal()

Prompts each stimulus in the association to conceal itself by calling its Conceal() method.

Select()

For each target contained in the association, calls its Select() method.

AssociationMap Class

An AssocationMap links Associations, or groups of stimuli and targets, to stimulus codes. Each stimulus code maps to a single Association object, and vice versa.

This way, the AssociationMap controls how stimuli are presented in groups, and sequences of groups, in a stimulus task, and it provides the information required to determine a selected target from a user response.

Methods

AssociationMap inherits publicly from std::map<int, Association, and provides all its member functions. In a StimulusTask descendant, the Associations property provides access to the single AssociationMap object stored inside the StimulusTask object.

Typically, only the subscript operator [] is required to assign stimulus codes to associations:

Associations()[ myStimulusCode ].Add( pMyStimulus );

Similarly, association information may be read when the subscript operator appears on the right hand side of an assignment:

int stimulusDuration = Associations()[ myStimulusCode ].StimulusDuration();

In case there exists no Association object for a specified stimulus code, an empty Association object will be created with default properties.

bool StimuliIntersect(StimulusCode1, StimulusCode2)

Returns true if there is at least one stimulus object common to the two stimulus codes specified, false otherwise.

bool TargetsIntersect(StimulusCode1, StimulusCode2)

Returns true if there is at least one target object common to the two stimulus codes specified, false otherwise.

SetOfStimuli TargetToStimuli(Target pointer)

Returns an intersection of all sets of stimuli that are associated with the specified target.

TargetClassification ClassifyTargets(ClassResult)

Translates a ClassResult object into TargetClassification object. A ClassResult object contains classification values per stimulus code; these values are translated into classification values per target.

ClassResult Class

A mapping of stimulus codes to classification values. Classification values are computed by the P3TemporalFilter in conjunction with the LinearClassifier, and accumulated by the StimulusTask class inside a ClassResult object before translated into a target selection.

TargetClassification Class

A TargetClassification object represents per-target classification values. Such an object is returned from AssociationMap::ClassifyTargets().

Methods

Target pointer MostLikelyTarget()

Returns a pointer to the target associated with the largets classification value, or NULL if there are no targets stored in the TargetClassification object.

See also

Programming Reference:Stimulus Class, Programming Reference:Target Class, Programming Reference:StimulusTask Class