How to define variable blocks

Definition and calculation of case variables can be made more efficient by grouping them into variable blocks. Case variables represent a selected trial or the sum, average, etc. of a range of trials of a given case. In the resulting scrollsheet, case variables are represented as columns with one cell per case. Often several different variables need to be computed for the same set of trial ranges. For example, you might want to compute the average escape time, path length, wall distance and swim speed for each single day of a watermaze experiment and for all trials of the experiment together. In such a situation you can predefine a set of trial ranges and then apply it to different analyses to automatically build variable blocks. This is how you do it:

BlockDef
BlockAdd Range=1-6 Name=01x06
BlockAdd Range=7-12 Name=07x12
BlockAdd Range=1-12 Name=all

As shown in this example, you first define a block of trial ranges. The definition starts with a BlockDef statement. It is followed by up to 128 BlockAdd statements, each of which defines the trial range (parameter Range) and the corresponding variable name suffix (parameter Name) for one variable in the block.

Matrix ...
Include ...
Collapse ...

BlockBegin
Extract ...
Tabulate ...
BlockEnd

Once a block of trial ranges has been defined, you can use it as many times you want to build variable blocks. Building a variable block is a two step process. The first step comprises all statements that are not affected by the trial range definitions and need to be processed only once for all variables in the block. This involves the creation of one or several data arrays using an appropriate combination of Matrix, Transform, Include, Exclude, Collapse, Surface, or Collect statements. You arrange these statements just the same way you normally would when creating a case variable. The second step includes those statements that are affected by the trial range definitions and need to be executed repeatedly, once for every trial range you have previously added to the block. The BlockBegin and BlockEnd statement are used to delimit the block of statements that need to be executed repeatedly. Usually, the block contains only Extract and Tabulate statements. You may place as many pairs of Extract and Tabulate statements inside a block as you wish. During each iteration, the proper trial range suffixes will be added to the variable names you have specified in the Tabulate statements inside the block. Because the trial ranges of a variable block have been predefined with the BlockAdd statements, the Range parameters of the Extract or Surface statements become irrelevant inside a variable block. You can omit Range parameters inside variable blocks, any explicit range you specify inside a block will be ingnored.

Defining time windows for variable blocks...

BlockDef
BlockAdd Range=19 Name=19s30 Begin=0 End=30
BlockAdd Range=19 Name=19s60 Begin=30 End=60
BlockAdd Range=19 Name=19all

You can further refine the analysis by defining beginning and end of time windows for all or part of the trial ranges in a block. These parameters will be forwarded to a Window statement which you place between the next BlockBegin and BlockEnd statements. Window statements placed between BlockBegin and BlockEnd statements ignore explicit parameters and instead use the parameters forwarded from previous BlockAdd statements. Window settings are applied during the creation of data arrays with the Collapse statement. As a consequence, not only the Extract and Tabulate statements, but also all Collapse statements that are to be affected by the window settings must be repeated once for every trial range. This means that you must move these Collapse statements to a position after the Window statement and between the BlockBegin and BlockEnd statements. If the Collapse statements inside a block refer to different data matrices and/or selection masks, you can use the Memory statement to store them during the first processing step and to retrieve them again from inside the block. Thus, the following statements may be placed between BlockBegin and BlockEnd: Window, Memory, Collapse, Extract, Surface, Collect, Tabulate.

Matrix ...
Include ...

BlockBegin
Window ...
Collapse ...
Extract ...
Tabulate ...
BlockEnd

Additional information...

• Managing custom variable definition files provides general information on the management of custom variable definition files.
• The Flowchart of advanced data analysis gives a synopsis of data and variable types.
• How to create case variables covers the basics of case variable creation.
• There is a topic describing how to build a custom variable definition file.
• There is a list of all available variable definition statements.
• Using the Memory statement you can build collections of data matrices and selection masks for later reuse in other variables.
• See Analyze Case Document command for basic information on that command.
• Inside case documents provides advanced information on case documents.