Sets of bin descriptions written in genblf’s language are stored in files with the extension ".bdf" (Bin Descriptor File) and are not limited in size or complexity.
genblf also requires a log file (from which the list of events is read) and the data sampling rate.
If there are no errors during processing, genblf will output a file with the name supplied to it. Generally, this is a file name ending in ".blf" (Bin List File).
Sample_rate is in hertz.
Optional Parameters:
-c Clears all flags in all log items in the log file before
processing.
-z Ignore Delete and Pause event codes while processing.
GenBlf
GenBlf is a program designed to generate Bin List Files (BLFs) and Response Time data from log files. These BLFs are used by the averager as well as other ERP data analysis programs. Each BLF is generated from a Bin Descriptor File (written in GenBlf’s language) and a Log File from an experiment run. The BLF tells the data analysis programs into which bins the data associated with each log file item should be put. The BDF from which the BLF is made is a set of rules for each bin, telling what kind of event codes an item needs to have, as well as what kind of event codes the items surrounding it need to have in order to be included in that bin.
The Language Concept (ABI GenBlf tutorial).
The simplicity of GenBlf’s language stems from its very basic core concept, which has a direct relationship to what the language needs to accomplish.
The language is designed to provide a method for describing occurances of events in a log file. The event being looked for is referred to as the "home event;" it is this item that will be inserted into a bin. The events that surround the home event are that events’ "context." The context is the critical part of a bin description, since it is tells GenBlf how to include some log items with "home event" codes while excluding the others.
In describing how a bin description is created, it is useful to "sound out" how the proper context and home event are supposed to be arranged. In order to fascilitate understanding of the language concepts, one experiment will be used in this document. The experiment will start out as a fairly simple one and grow more complex later on.
A subject will be asked to identify a partially drawn image. If the subject cannot identify the image, the subject should press the "no" button, otherwise, she should press the "yes" button. If the subject presses "yes", she will then be asked to explain what she thinks it is. The experimenter will then press the "correct" or "incorrect" button depending on the subject’s response. The event codes for the image range from 10 to 20. The "yes" button code is 256, "no" is 257. The "correct" code is 1024, "incorrect" is 1025.
Before we begin the
bin descriptions, we need to set up the condition description for the bins.
The calibration pulses will be condition 0. To set this condition up, we
do the following:
condition 0 "Calibration" bin 0 "Cal Pulses" home %Don’t worry about what the text beneath the "condition" line means, that will be explained later; their function is to put all calibration pulses into bin 0 of condition 0. To start the condition description that will be used for this Experiment (in all of its versions), do this:
condition 1 "Experiment"This line begins with the "condition" keyword, which tells GenBlf to end the current condition description ad start a new one. The number following the keyword is the condition number. There is no limit on the total number of conditions, but they must appear in sequence starting from 0. Following the condition number is the label for this condition. As long as the label is less than 40 characters in length, it can contain any text.
Having begun condition 1, we can now proceed to building the bin descriptions for it. This first version of the experiment clearly separates into 3 bins of data. They could be described in English as follows:
Bin 1) The image presented is the home item. After it should be a "Yes" event followed by a "Correct" event.
Bin 2) The image presented is the home item. After it should be a "Yes" event followed by an "Incorrect" event.
Bin 3) The image presented is the home item. After it should be a "No" event.
In the GenBlf
language, the bins could be described as follows:
bin 1 "Yes Correct" home [10-20] 256 1024 bin 2 "Yes Incorrect" home [10-20] 256 1025 bin 3 "No" home [10-20] 257The lines that begin with "bin" mark the beginnings of bin descriptions. Following the "bin" keyword is the bin number. There is no maximum bin number, but they must be consecutive, starting with 1. The text in quotes immediately following the bin number is the label given to a bin description. This label must be less than 40 characters long, but other than that, there are no limitations on its content. Following the "bin" keyword, the bin number, and the bin label are the description’s event entries. The "home" keyword designates the entry that follows it as the home item. The numbers inside the []’s designate a Number Expression (more on these later) that specifies all event codes between 10 and 20 inclusive. Notice that one event entry separated from another by blank spaces or a tab means that the second event should follow the first event in the logfile’s event list. However, Number Expressions are different from event entries, and so no spaces or tabs are allowed anywhere inside []’s. After all event entries in a bin description, there are two optional keywords, "rt" and "show" that can be added. These are discussed later in this tutorial.
Suppose we’ve decided to combine Bins 2 and 3 into Bin 4. In English:
Bin 4) The image presented is the home item. After it should be either: a) a "Yes" event followed by an "Incorrect" event or b) a "No" event.
And in GenBlf syntax:
bin 4 "Yes Incorrect or No" bin home [10-20] (256 1025) | 257"In the line above, the two event entries from Bin 2 were put inside ()’s and separated from the event entry from Bin 3 by a "|" character. The ()’s have the effect of "grouping" any number of event entries together. The "|" character between the Bin 2 entries and the Bin 3 entry means that one OR the other should follow the image event entry.
GenBlf’s language can describe far more complex bins that those above. In order to see this, the Experiment will need to be expanded.
Instead of asking the subject to identify only one image of a partially drawn picture, the subject will instead be asked to identify increasingly complete (increasingly less fragmented) images of the same picture until she is successful. There will be four different pictures, each with five fragmented images. The event codes are two digits in length, with the first digit designating the picture, and the second digit the fragmented image of that picture. So "23" would be the third fragmented image of picture two. The button codes will remain unchanged.
The first four bins for this version of the experiment will be the same with the exception of the home item. The first, second, third and fourth bin’s home item should be images from the first, second, third and fourth picture, respectively. In all four bins, the home item should be followed by a "Yes" event and a "Correct" event.
In GenBlf syntax, this
would look like:
bin 1 "Y/C first picture" home [11-15] 256 1024 bin 2 "Y/C second picture" home [21-25] 256 1024 bin 3 "Y/C third picture" home [31-35] 256 1024 bin 4 "Y/C fourth picture" home [41-45] 256 1024If we wanted to combine all of the "Yes" "Correct" responses into one bin, we could do this:
bin 5 "Y/C all" home ([11-15] 256 1024) | ([21-25] 256 1024) | ([31-35] 256 1024) | ([41-45] 256 1024)This change involved simply putting each of the separate bin descriptions inside ()’s and ORing them together. The "home" keyword at the beginning of the line means that the first entry inside each of the ()’s becomes the home item.
There is a much simple method of writing this description using
the GenBlf language. It looks like this:
bin 5 "Y/C all" home [..] 256 1024The two "." characters inside the []’s do all the work in this description. This a different kind of the same Number Expressions used in previous descriptions to designate a range of numbers. The "." character in a Number Expression means "match any single digit number." In this expression, two of these have been "concatenated" (joined together) to form the combination of numbers we want. Of course, this expression matches many more pictures and images than the experiment has; in fact, it matches all numbers between "00" and "99". Notice that it does NOT match single digit event codes. This "overmatching" is not a problem here, since we want to include all correct responses in the experiment.
If we want to limit Bin 5 to a specific set of correct
responses, we need another approach. Suppose Bin 5 is instead supposed to
hold all correct responses for the first 3 pictures. This would look like:
bin 5 "Y/C picts 1-3" home [[1-3].] 256 1024In this Number Expression, a range has been specified for the first number, and a "." for the second. These two, concatenated together, match all numbers between "10" and "39". Notice that the entire expression (the range and the ".") has been enclosed in []’s. It is necessary to do this whenever more than one of any Number Expression kind has been included in one event entry. So far, the kinds we have looked at are the group "[]" ([]’s with Number Expressions inside), the range "[x-y]" (where x and y are any positive integer, y > x) and the wildcard "." (known as a "digit wildcard").
More can be done
to limit the correct responses that are added to this Bin 5. For example,
assume that only the last three images from pictures one and four are desired.
We can do this with the following:
bin 5 "Y/C picts 3 and 4, last 3 images" home [[1|4][3-5]] 256 1024For this description, we have had to add a new Number Expression kind, the "|" character, which represents logical OR and does the same thing here as it did in the first three bins. In this case, it means that the first number in this entry should be either a "1" or a "4". This expression used the "|" character between two numbers, but this is not the only place it can appear. A "|" can be used between any two Number Expression kinds (except another logic kind). The second number is specified by a range that includes the last three fragmented images (since there are five total fragmented images per picture).
Finally, we will add one last Bin to this version
of the experiment. The home item of this bin will be the first image in
which the subject responded "Yes" and the experimenter responded "Incorrect".
This bin should only be included if, any number of images later, the subject
pressed "Yes" and the experimenter pressed "Correct". This bin description
would be:
bin 6 "Yes Incorrect, then later Y/C" home [..] 256 1025 [%*] [..] 256 1024Notice the [%*] in between the "Yes" "Incorrect" and "Yes" "Correct" responses. This Number Expression actually contains two different expression kinds. The first is the "%", which is the event wildcard (a wildcard kind) and matches ANY event number. The second is the "*" (known as the star operator, an operator kind). This kind of expression "operates" on the expression kind before it, much like multiplication. This "operator" means that there should be "0 or more" of the previous expression. The previous expression can be any expression kind except logic or operator kinds, and must be provided (e.g. [*] is not a legal entry).
To demonstrate the uses of one
of the other operator kinds, we’ll change the description of Bin 6 slightly.
For instance, as it stands, Bin 6 will match if a "Yes" "Incorrect" is
followed directly by a "Yes" "Correct" (because the "*" operator means
"0 or more"). If we wanted to make sure that at least one other event occured
between these two responses, Bin 6 would look like this:
bin 6 "Y/I, then one or more later Y/C" home [..] 256 1025 [%+] [..] 256 1024The "+" after the "%" is another operator known as the plus operator, another operator kind. This operator means that there should be "1 or more" of the previous expression. Since the previous expression is the "%" (event wildcard), the entire entry "[%+]" will match 1 or more of any event.
NOTE: Bin 6’s description in both of the above cases is neither the most accurate, nor the fastest, method of matching interrupted events. See the subsection on Replacement below and the Tips, Caveats, Etc. section at the end of this manual for some better ways of doing this.
Some important notes before we move on: 1) Remember that Number Expressions containing more than one of any expression kind (even if it is the same) must be enclosed in []’s and 2) No spaces are allowed anywhere inside []’s.
In order to further explore GenBlf’s bin description language, the experiment will be expanded again.
Subjects in the experiment will now be shown some
or all of the pictures and fragmented images a second time. This means
that the event codes for the image shown to the subject must change. The
code will now include the following: whether or not the image has been
shown before (the image’s "age"), the number of the picture being shown,
and the number of the fragmented image of that picture. Additionally, the
number of pictures will be increased from three to six, and the number
of fragmented images per picture will be expanded from five to six. The
"Yes" "Correct" Bin for new and old images can be described as follows:
bin 1 "Yes Correct, new image" home [1[1-6][1-6]] 256 1024 bin 2 "Yes Correct, old image" home [2[1-6][1-6]] 256 1024 Or more generally, bin 1 "Yes Correct, new image" home [1..] 256 1024 bin 2 "Yes Correct, old image" home [2..] 256 1024Where "1" and "2" mean "new image" and "old image" respectively. This old/new distinction will be referred to as the image’s "age."
These bin descriptions
may appear at first to be correct, but there is a subtle and important
problem with Bin 2. Notice that in the first case, Bin 2 is intended to
match entries beginning with a "2" and followed by a number between 1 and
6 then another number between 1 and 6. But this bin also matches the number
"256," which is our "Yes" button code! Similarly, the second case is intended
to match entries beginning with a "2" and followed by any two digits (the
two "." characters). This bin also match the numbers "256" and "257," our
"Yes" and "No" button codes. Fortunately, the GenBlf language has a method
of "weeding out" unwanted codes. The first case of Bin 2 looks like this:
bin 2 "Yes Correct, old image" home [[2[1-6][1-6]]&[^[256]]] 256 1024Notice the two new expressions in this Number Expression: "&" and "^". Also, a "[256]" has been added at the end. First, the "&" (ampersand) character represents an AND (another logic kind, meaning that both the expression kind before it AND the expression kind after it must match the same event in order to match completely. Second, the "^" (circumflex) character represents the NOT (again, a logic kind). This expression only effects the expression kind after it. It inverts the sense of an expression, such as: ^2 means "any number but 2"; ^[3-6] means any number except those between 3 and 6 inclusive. Thus, the Number Expression "[^[256]]" in the bin description above means "any event code except event code 256". Notice that the "^" is outside the [256]. This is very important, since "[^256]" has a completely different meaning, which is: any number but 2, followed by a 5, followed by a 6. Since there is an "&" between the two expression kinds (in this case, both of them are group kinds because they are both enclosed in []’s), the first entry in the bin description matches all the correct event codes for images but does not match "256", the button code.
The second case of Bin 2 slightly
more complex:
bin 2 "Yes Correct, old image" home [[2..]&[^[256]]&[^[257]]] 256 1024Or alternatively,
bin 2 "Yes Correct, old image" home [[2..]&[^[[256]|[257]]]] 256 1024The Number Expression after the "&" in the first of these means that the event code must NOT be "256" AND it must NOT be "257". In the second one, it means that the event code must NOT be either "256" OR "257". Both are equally correct.
To explore some interesting caveats of the GenBlf language, some additional changes will be made to the experiment.
Change the number of pictures from 6 to 20, but have the event numbers
describing the images always 4 digits long. Additionally, the images are
followed by an optional time, in milliseconds, that the image was displayed.
In order to distinguish the duration time from the next image id, one
final stipulation must be made: the durations all have a leading "9". This
"9" is only a marker, used because no other events (responses or image
numbers) begin with it. Using previously know features of the GenBlf language,
the best description of "Yes" "Correct" responses possible is:
bin 1 "Y/C all images" home [[1|2][1-20][1-6]] 256 1024Unfortunately, this description fails for 9 * (2 * 6) = 108 of the possible image numbers. That is, the picture description Number Expression of "[1-20]" will fail for pictures 1-9 because, as is described in the Experiment, all event image numbers are 4 digits long, and "1", "2", ... "9" match single digits. So for an image event such as "1041", this description is looking for "141" and will not match. The solution to this problem is, of course, to make the digits 1-9 look like "01", "02", ... "09" instead, and have 10-20 appear as they would have before. This can be accomplished in the GenBlf language, although with an unfortunately verbose description:
bin 1 "Y/C all images (4 digits each)" home [[1|2][[0[1-9]]|[10-20]][1-6]] 256 1024The middle section "[[0[1-9]]|[10-20]]" is the Number Expression that performs the matching magic. The first part, "[0[1-9]] matches a "0" followed by a number 1-9: "01", "02", ... "09", which is what we wanted. If this number does not match, the "|" (OR expression) tries to match the second part "[10-20]".
Now on to the next part of the Experiment, matching responses with a time
duration following the image event. Take the following bin:
bin 2 "Y/C images w/durations" home [[1|2][[0[1-9]]|[10-20]][1-6]] [9.+] 256 1024The end entry "[9.+]" matches the time durations, which have leading "9"s. The ’+’ in the Number Expression matches one or more single digit numbers.
To construct a bin description that matches "Yes" "Correct" responses
regardless of whether or not their image events are followed by a time
duration, a new operator kind must be used, as follows:
bin 3 "Y/C images, optional duration" home [[1|2][[0[1-9]]|[10-20]][1-6]] [[9.+]?] 256 1024The "?" in "[[9.+]?]" is the "question operator" that tells GenBlf to match 0 or 1 of the previous Number Expression, which in this case is "[9.+]". Thus, if there is a duration after the image event, it will be matched; if there is not, the entry "[[09.+]?]" is ignored. Therefore, in this bin, a duration event is optional and does not impact on whether or not the bin as a whole is accepted.
To exclude events that were displayed for a
time greater than or less than specific number of milliseconds, another
new operator kind needs to be introduced, the "limits operator". The following
bin descriptions accept "Yes" "Correct" responses with durations greater
than or equal to 1000ms, less than or equal to 2000ms, and between 1000
and 1999ms, respectively.
bin 4 "Y/C, duration >= 1000ms"
home [[1|2][[0[1-9]]|[10-20]][1-6]] [91.{3,}] 256 1024
bin 5 "Y/C, duration <= 2000ms"
home [[1|2][[0[1-9]]|[10-20]][1-6]] [91.{0,3}] 256 1024
bin 6 "Y/C, 2000ms > duration >= 1000ms"
home [[1|2][[0[1-9]]|[10-20]][1-6]] [91.{3}] 256 1024
In the above bins, all three forms of the limits operator are given. This
operator is in fact a more expansive version of all other operators in
GenBlf. The "*", "+", and "?" operators are synonyms for more commonly used
forms of the limits operator. The exact definition and the operator synonyms
are in the Reference section below. The duration checking element in each
of the 3 above bins might look strange, but their function is simple. For
instance, "[91.{3,}]" first matches the leading "9", signifying that the
event is a duration. The "1" matches all durations with their first digit
equal to 1. The next part, ".{3,}" is a single number wildcard kind followed
by a limits operator. It means: match a single digit at least 3 times. This
entire element combines to match a 1 followed by 3 or more digits, i.e. a
number greater or equal to 1000. In bin 5, "[91.{0,3}]" means: match a duration
beginning with a 1 and followed by between 0 and 3 other digits, which
is a number between 1 and 2000. Similarly, in bin 6, "[91.{3}]" matches:
a duration beginning with 1 and followed by exactly 3 other digits; a number
between 1000 and 1999. To wrap up the GenBlf tutorial, a last set of features will be examined in the final version of the Experiment.
In the final version of the experiment, no changes will be made to the
procedure or the event numerating system. Instead, we will work to glean
some final pieces of information from the data already obtained. Suppose
that the delay time between the presentation of a fragmented image and
any response given by a the subject is of particular importance, and that
responses given before or after a certain "time window" are to be considered
invalid. The time window for all responses will be between 200ms and 1000ms.
In GenBlf the bin would look like this:
bin 1 "Valid responses, opt. duration" home [[1-2][1-6][1-6]] [[9.+]?] <200-1000>( (256 1024) | (256 1025) | 257 )Notice the "<200-1000>" in the preceding the last entry group. This is the "time conditional" for that group. Both values are in milliseconds, and the first value must be less than the second. Since the time conditional is outside the entry group, it applies to any entries in that group that match. Therefore, GenBlf will first try to match a "Yes" "Correct", a "Yes" "Incorrect", or a "No" and then it will check to see if the first entry of those within the entry group that matched (that is, "Yes", "Yes", and "No") occured within the time window of at least 200ms and not more than 1000ms. Its possible that the response-time window needs to be different for each response type. That is:
bin 2 "Specific valid responses, opt. duration" home [[1-2][1-6][1-6]] [[9.+]?] <200-1000>(256 1024) | <100-700>(256 1025) | <10-600>257This bin (rather arbitrarily) allows the longest time for "Yes" "Correct" but has the least tolerance for quick responses of that type. Similarly, "Yes" "Incorrect" are given a shorter time, but more tolerance for quick answers. "No" responses are given the shortest consideration time, but the most tolerance for answers given quickly. Of course, the duration events explored in version 4 of the Experiment could be combined with the response times. Additionally, the different responses could be put into seperate bins, certain pictures could be given different response times, etc. Most of these would involve simply combining the time conditionals with other bin examples elsewhere in this tutorial.
After investing time in accepting
only responses within a specific time window, it might be nice to record
the response time for each included image event. For bin 1, this would look
like:
bin 1 "Valid responses, opt. duration" home [[1-2][1-6][1-6]] [[9.+]?] <200-1000>( (256 1024) | (256 1025) | 257 ) rt $1 $3 "bin_1.rt"The last line in the description is the one of interest. The "rt" keyword tells GenBlf to output response times. The rest of the line after "rt" contains its arguments. The first two, "$1" and "$3" specify which event entries’ response time is to be output. In this case, the time difference between entry 1 and entry 3. After the two event entry identifiers, is "bin_1.rt". This is the name of a file to which the response time values are output. The values are appended to this file, which means that each time GenBlf processes this bin it adds to the end of the file instead of erasing the old file and beginning a new one. (See the "-r" option at the top of this document for information on avoiding the potential problems with this feature.) There can be only one "rt" keyword per bin, but each bin’s "rt" can output response-times to different files or to the same files. Output from "rt" can be sent to the console ("standard output") by using simply "-" as the filename. The "rt" files output by GenBlf are compatible with the "logrt" program. NOTE: event entry identiers are not the same as entry numbers! Using bin 1 above as an example: Entry Numbers: there are 3 entry numbers in bin 1. "$1" represents the image entry "[[1-2][1-6][1-6]]". "$2" represents the optional duration entry "[[9.+]?]". "$3" represents the time-conditional responses "<200-1000>( (256 1024) | (256 1025) | 257 )". Event Entry Identifiers: There are between 3 and 4 event entry identifiers in bin 1. "$1" and "$2" are the same as their Event Number counterparts. "$3" can be any of three event entries: the "256" in "(256 1024)", the "256" in "(256 1025)", or the "257". "$4" can be any of two event entries: the "1024" in "(256 1024)" or the "1025" in "(256 1025)". Note that "$4" does not exist for images followed by "257". GenBlf will print an error message if such a reference to a non-existant event entry is made. This can be avoided by either not referring to "$4" in an "rt" line or by moving the "257" responses to a seperate bin.
The final feature of the GenBlf language is a diagnostic
keyword, "show", meant to help get the bugs out of bin descriptions. "show"
is very simple and very useful. For instance, to output all of the matched
log items and the event context that matched them for a bin, just add the
"show" keyword to the end of the description, like this:
bin 1 "Valid responses, opt. duration" home [[1-2][1-6][1-6]] [[9.+]?] <200-1000>( (256 1024) | (256 1025) | 257 ) rt $1 $3 "bin_1.rt" show "results.shw"The last line tells GenBlf to place show’s output in a file named "results.shw". The file convention is identical to that of "rt": output is appended to the file specified. Specifying "-" in place of a filename will send the output to the console ("standard output"). Only one "show" keyword is allowed per bin description, and it must be the last entry in a bin description.
Flag Operations.
Every log item in a log file has a storage area for
"flag" values, with each flag set to a value between 0 and 255. These flag
values can be used to include or exclude items from bins, as well as to
"communicate" to consequent bins information about a log item. Suppose
that two bins are to be constructed out of the Experiment. One bin is to
have images from pictures 1 and 2 that are of framentation levels 5 or
6. The other bin is to have all other bins not included in the first bin.
Only images followed by "Yes" "Correct" responses are to be included in
either bin. The first bin would look like this:
bin 1 "Y/C pics 1 & 2, frags 5 & 6" home [[1-2][1-2][5-6]] 256 1024The second bin can be written without flag operators quite easily:
bin 2 "Y/C not in bin 1" home [^[[1-2][1-2][5-6]]] 256 1024This bin was constructed by simply adding a logical NOT to the outside of the entry describing the image. Unfortunately, this is a crude solution that includes many more event codes than might be desired. Of course, the bin could also be written like this:
bin 2 "Y/C not in bin 1" home [[1-2][3-6][1-4]] 256 1024This bin was constructed simply by noticing all of the images that bin 1 did not include, and making sure those were included in bin 2. The difficulty with this method is that it could quickly become mind-boggling to think of and include all previously excluded cases. GenBlf’s flag operations provide an easier way. Take bins 1 and 2 again:
bin 1 "Y/C pics 1 & 2, frags 5 & 6"
home [[1-2][1-2][5-6]] {set <1>} 256 1024
bin 2 "Y/C not in bin 1"
home [[1-2][1-6][1-6]] {test ^<1>} 256 1024
Notice the "{set <1>}" in bin 1. This is a flag operation, telling GenBlf
to set the flag value of the log item matched to the event entry equal
to "1". This operation is Ionly performed if the bin is accepted as a whole.
In bin 2, another flag operation appears: "{test ^<1>}". This is another flag
operation, directing GenBlf to check the log item matched to the event
entry preceding it. The test is for "^<1>" which is a check to see if the flag
value is not 1. The end result of these to bins is that bin 1 includes
the specific subset of image event numbers desired and marks all of those
that it includes. Bin 2 then scans through the superset and includes all
image event numbers not marked with a flag. Additional flag operations
include "clear" (or "clr") and "flip". The clear flag operation removes
a specified value from the flag value of a log item. The flip operation
sets values in a flag that were cleared, and clears values that were set.
The values appearing in <>’s after the flag operation are the operation’s
value. This number can be in three forms: octal, decimal, or hexadecimal.
The limits of the values for each for are: 01 - 0377, 1 - 255, 0x1 - 0xFF.
Notice that octal numbers are prefixed with a "0", and hexadecimal numbers
are prefixed with a "0x". Here are some examples of flag operations, with
the resultant flag values. Assume that the log item’s flag value starts off
at 0. set <0x11> # flag value = 0x11 clr <0x01> # flag value = 0x10 clr <0x20> # flag value = 0x10 flip <0x14> # flag value = 0x04 test <0x04> # true test <0x44> # false test ^<0x10> # trueThe above operations use hexadecimal values, but this is not required. The advantage of hexadecimal (or octal) over decimal is that the effect on the flag value is visually obvious in hexadecimal. For instance:
set <134> # flag value = 134 test <8> # falsebut it is not visually obvious that the result of the test should be false (unless you are well versed in binary conversions). Flag operations can follow any event entry any place in a bin description. They must be enclosed in {}’s and each operation must be seperated by one or more spaces, such as:
bin 1 "Y/I or N, pics 1 & 2"
home [[1-2][1-2][1-6]]
(256 1025) {set <0x01> clr <0x02>} |
257 {set <0x02> clr <0x01>}
bin 2 "Y/I or N, other pics"
home [[1-2][1-6][1-6]]
( (256 1025) | 257 ) {test ^<0x01> test ^<0x02>}
In this instance, the "Yes" "Incorrect" responses to pictures 1 and 2
have flag value 0x02 cleared and flag value 0x01 set. "No" responses to
pictures 1 and 2 have flag value 0x01 cleared and flag value 0x02 set. For
bin 2, all other pictures with "Yes" "Incorrect" or "No" responses are
included. Notice that the tests happen outside the entry group, and they
test for both flag values; if either is set, the image event is not included
in the bin. Note that flag operations are performed in a specific order.
- First, if a bin is otherwise accepted (all matches and time conditionals
passed) all tests for all matched event entries in a bin are performed.
If any of them fail, the home event is not included in the bin. - Second,
if the above tests pass, all of the other flag operations (set, clear
(or clr), and flip) are performed. The order of their performance is guaranteed
to be the order in which they are entered. This order of performance means
that some operation lists that look distinct are not. For example: bin 1 "image events w/ 0x02 set in flag"
home [[1-2][1-6][1-6]] {test <0x02> clr <0x02>}
Is equivalent to: bin 1 "image events w/ 0x02 set in flag"
home [[1-2][1-6][1-6]] {clr <0x02> test <0x02>}
Even though in the second version of bin 1 the clr operation comes first,
the test will still pass, because the test is performed first, and the
clr operation is only done if the test passes. Variable Substitution.
Variable substitutioon provides a simple method for making bin descriptor
files easier to build and understand. It allows for any part of the file
to be given a name which can be used later in the file. For example, in
the Experiment above, a series of numbers have special meanings not immediatly
obvious from their values. Valuable context information can be given to
these numbers with the following:
YES = 1024 NO = 1025 CORRECT = 256 INCORRECT = 257 AGE = [1|2] PICTURE = [1-6] FRAG = [1-6]These lines give easy to understand names to all of the "magic numbers" in the bin descriptor files. A bin description for "Yes" "Correct" responses would be:
bin 1 "Y/C all"
home [[^[${CORRECT}]]&[${AGE}${PICTURE}${FRAG}]] ${YES} ${CORRECT}"
(remember that the [^[${CORRECT}]] prevents "Correct" button response events
from being mistaken for the image with the same number "256")
This is
substantially easier to read than earlier examples. Another variable could
be defined for the image number, such as:
ANY_IMG_ID = [[^[${CORRECT}]]&[${AGE}${PICTURE}${FRAG}]]
and the bin description would then be simply: bin 1 "Y/C all"
home ${ANY_IMG_ID} ${YES} ${CORRECT}
Notice that ANY_IMG_ID contains references to other variables. These variables
need not be defined before ANY_IMG_ID is defined, but they must be defined
before ANY_IMG_ID is used in a bin description. If the definitions of any
of the variables used in the definition of ANY_IMG_ID are changed, the
changes take place in both the individual variable and in ANY_IMG_ID. For
example: ONE = 1
TWO = 2
TWELVE = ${ONE}${TWO}
Here, TWELVE is equal to "12", if later ONE is changed: ONE = 3Then ONE is equal to "3" and TWELVE is equal to "32"
Variables can be redefined at any time. There is no limit to the length of the variable name, but the name cannot contain any spaces. The first letter of a variable name must be either alphabetic "A-Z, a-z" or an underscore "_". letters following the first can be alphanumeric "A-Z, a-z, 0-9" or underscore "_". The text appearing after the "=" in the variable definition is not limited by length or content. Definitions can be continued on following lines if and only if those lines begin with TAB characters.
Replacement.
Sometimes it
is useful to match log item events within a single bin description that
are similar to each other. For example, the entry:
bin 1 "Any image" home [[1-2][1-6][1-6]]will match a wide range of images: they will be of any age, picture, or fragmentation. Suppose that the home item is a "Yes" "Incorrect" event, and it is followed some number of events later by a "Yes" "Correct" event. Any log item matching the home item should only be included if the same image that was incorrectly identified is later correctly identified. Thus, the first incorrectly identified image should be of the same age and picture as the correctly identified image, but the fragmentation levels will be different between them.
Without replacement, this bin description could
be attempted with the following:
bin 2 "Y/I followed by Y/C (wrong)" home [[1-2][1-6][1-6]] 1024 257 [%*] [[1-2][1-6][2-6]] 1024 256Notice, though, that the [%*] entry will match zero or more intervening events, and therefore that the first, incorrectly identified image, does not necessarily have the same age and picture as the later, correctly identified, image. The result of this is that an image that was never correctly identified could match the bin description if a "Yes" "Correct" for any image appears later in the log file.
Replacement was designed to eliminate this problem.
The following example shows how the bin description would be correctly
written:
bin 2 "Y/I followed by Y/C (right)" home [[1-2][1-6][1-6]@] 1024 257 [%*] $1:[2-6] 1024 256Notice first the ’@’ symbol following the "[1-6]" in the first entry. This symbol means that the preceding Number Expression (in this case, the group "[1-6]") should be "marked" for replacement. Notice also that the entry for the second image, which was "[[1-2][1-6][2-6]]", has been changed to "$1:[2-6]". The first part of this new entry, "$1:" (called an "entry reference") means: "place the number of the event matched in entry 1 here." The "1" is the number of the entry to place. It can be any entry less that the entry number with the ’$’. Note that entry numbers are counted starting with 1 at the first entry in a bin. All entries are counted, not simply those with entry number 3. The "[2-6]" following the entry reference "$1:" is the power behind the replacement feature. This is the Number Expression to be put in place of the number or numbers matched by the marked Number Expression in the referenced entry (in this case, entry 1). For example, if the first entry matched the event "123", the entry for the second image will be made into: "[12[2-6]]". This happens because the first event matched like this:
[1-2] matched "1" [1-6] matched "2" [1-6] matched "3" therefore: [[1-2][1-6][1-6]] matches "123"When GenBlf gets to the "$1:[2-6]" it looks for the Number Expression at the first marker in entry 1, in this case, the second "[1-6]", which matched "3". GenBlf then puts the replacement Number Expressions following the entry reference "$1:" in each mark in the matched entry. In this case, we have only one Number Expression to put in, [2-6], and only one mark to replace, the mark at the "3". Therefore, the [2-6] is put in place of the "3", resulting in:
1 2 [2-6] therefore: [12[2-6]]Notice that this entry has not been matched yet, only "constructed". What this means is that GenBlf is building entries as it works, based on what event numbers it matches. The entry constructed above, "[12[2-6]]" will match an image event with age 1, picture 2, fragmentation level 2-6.
It is required
that a substitute Number Expression be supplied for each replacement mark
in an entry identified by an entry reference. This applies even in entries
that contain "|" and "&" logic kinds seperating Number Expressions. For instance:
[1[3-5][1-6]@] | [2[4-6][1-6]@]always needs two replacement Number Expressions after an entry reference that identifies this entry. For example, if this were the fourth entry in a bin description, the replacement entry might look like this:
$4:[1-6];[1-6]Notice that the Number Expressions for each replacement marker are seperated by a ";" (semicolon).
It is important to note that replacement entries only take Number Expressions after the entry reference. This means that features of Event Expressions, such as blank spaces, grouping with ()’s, event sequence matching, are not supported. Replacement entries are for rematching of parts or sections of previously matched events, and therefore, Event Expressions would not be useful or appropriate. GenBlf Language Reference.
| Event Entries | |
| home | Designates the following event entry as the home item. |
| Number Expression | An expression describing the event to match. See below. |
| ( ) | Groups together two or more event entries |
| ^ | Logically negates the preceeding event entry. Thus, "^5" matches all events except 5. |
| & | Forces the event entries preceding and following this symbol to match the same event |
| | | Allows either the event entry preceding or the one following this symbol to match an event |
| Number Expressions | |
| "0" "1" ... "9" | An integer literal which matches only itself. Thisis the only Number Expression kind that can be combined with itself without the need for surrounding []’s. |
| [m-n] | A range from some integer m to some other integer n, such that m < n. |
| . | Matches any single digit number. |
| % | Matches any event code or any series of numbers. Normally used only in conjunction with one of the operators described below. When used inside of a compound Number Expression, it matches all numbers remaining in the event code (it is therefore equivalent to a ".*" placed at the end of an Expression). |
| * | Matches 0 or more of the preceding Number Expression. |
| + | Matches 1 or more of the preceding Number Expression. |
| ? | Matches 0 or 1 of the preceding Number Expression. Analogous to making an Expression "optional." |
| {m} {m,} {m,n} | m and n are any positive integers such that m <= n. The value "m" is the minimum number of applications of the previous Number Expression that are allowed, and the value "n" is the maximum number. In the {m} form, the limits operator applies the previous Number Expression exactly m times. In the {m,} form, it applies the previous Number Expression a minimum of "m" times and an unlimited number of times (analogous to {m, infinity} ). The "*", "+" and "?" are equivalent to the limit operators {0,}, {1,}, and {0,1}, respectively. |
| [ ] | Groups together two or more Number Expressions to form a single Number Expression. |
| ^ | Logically negates the preceeding Number Expression. Thus, "^5" matches all events except 5. |
| & | Forces the Number Expression preceding and following this symbol to match. |
| | | Allows either the Number Expressionp preceding or the one following this symbol to match. |
| Replacement (inside Number Expressions only) | |
| @ | Mark the preceding Number Expression for later replacement. |
| $e:[...];[...] | e is the ordinal number of the event entry in the bin description. The [...]’s are Number Expressions to put in place of the numbers matched at the repective marked Expression in the event entry specified. A Number Expression must be provided for each mark in the event entry. Multiple Expressions must be seperated by a ";" and single Expressions must not have the ";". |
| Variable Substitution | |
| <variable_name> = <var_string> | Define a variable with name <variable_name> to contain a string<var_string>. The variable name’s first letter must be alphabetic or "_", following letters can be alphanumeric or "_". |
| ${variable_name} | Place the current contents of the variable <variable_name> in this location. |
- GenBlf’s language is powerful, but this can also result in idiosyncratic complexities.
- Because
of the way event entries and Number Expressions are matched, certain bin
descriptions can take far longer than others. The general rule is: match
only what you need. The wider open a bin description is, the longer GenBlf
may spend trying to match it, even if there are a small number of matches
in a log file. For Example:
home 1 [%*] 2is necessary if the are an undetermined number of events between 1 and 2. But if there are an exact number or a limited number of interceding events, then the "limits operator" can greatly speed matching. Assuming that 1 and 2 are seperated by at most N (any integer) events, use:
home 1 [%{0,N}] 2
- Make use of the "show" keyword when bin descriptions don’t seem to be matching properly. As discussed in Experiment (5) , "show" can route output to the console or to a specified file. Each bin can have a seperate "show" file. This can be extremely helpful.
- Ask a programmer.