EthoVision XT - 5 Sub-rules
Last updated: Jul 25, 2026
5 - Sub-rules
5 Sub-rules
use sub-rules
A sub-rule is a sequence of actions and conditions separated from the Start-Stop trial rule. You can view a sub-rule like a subroutine in a larger program, where the program is your Trial Control. You can have the sub-rule start at specific times or under specific conditions. Each criterion defined is a Start condition of the sub-rule. A sub-rule can be repeated, that is, when EthoVision finishes executing the instructions contained in the sub-rule, the program can start the sub-rule again from the beginning, for a specified number of times or until a condition is met. You can also have the same sub-rule called from different points of the Trial Control sequence. To do so, define multiple References to the same sub-rule (see page 57).
Why use a sub-rule?
A sub-rule is necessary when your trials involve repetition of tasks. For example, when the animal has to press a lever to obtain a reward, and you want to repeat that 50 times. This is not feasible within the Start-Stop trial rule. A sub-rule is also handy when your Trial Control logic is very complex, because it helps you have a clear overview of the phases within your trial. For example, different tasks within a trial can be kept separated and managed more easily. Figure 18 Schematic representation of the functioning of a Sub-rule along the time line. You can specify a sub-rule to start at specific Start conditions (for example: Start at 12:00). For each start condition, a sub- rule can be repeated one or more times (black bars). The white bars represent the time from the start condition to the last repeat. Note that sub-rule repeats can vary in duration, for example when the behavior of the subject determines when a condition defined in the sub-rule is met. Also note that a sub- rule repeat can only start at least one sample after the end of the previous repeat. 5 - Sub-rules
create a sub-rule
- In the Components pane, under Structures, double-click Sub-rule, or click the button next to it.
- If the Add a sub-rule window appears, choose one of the following: Create a new sub-rule. This creates a new sub-rule. You will be asked to enter a unique name for this sub-rule. Reuse an existing sub-rule. Choose this option if you want to re-use an existing sub- rule. Select the existing sub-rule and, if necessary, the Trial Control Settings where it is stored. Note: You only copy the sub-rule name, the Rule Begin and the Rule End boxes, not the actions and conditions inside the existing sub-rule. See page 36 for re-using Trial Control elements.
- Under Name, enter a name for the sub-rule. The default name is Sub-rule (n) where n is a progressive number.
- Under Comment, enter a description of the sub-rule (optional).
- Click OK. The sub-rule is displayed on your Trial Control screen. It consists of a Rule begin box and a Rule end box.
- Complete the sub-rule by inserting the appropriate conditions and actions between the Rule Begin and Rule End boxes (see page 23).
- Define a reference to this sub-rule (see the next section).
Notes
Sub-rule names. Names of sub-rules must be unique in your Trial Control Settings. You cannot define two sub-rules with the same Name, even if these are defined in two different Trial Control Settings. However, you can create a sub-rule with the same name of an existing sub-rule stored in other Trial Control Settings by Re-using it (see below). Re-using a sub-rule. If you choose to re-use a sub-rule and then change any property of this copy (Name or Comment), a window appears with the message Define the scope of your changes. The program asks you whether you want to apply the properties only to the newly-created sub-rule, or to the sub-rules with the same name in all Trial Control 5 - Sub-rules Settings. Choose the option you require and click OK. See also page 36 for information on re-using elements in Trial Control. Deleting a sub-rule. You cannot delete a sub-rule if at least one reference to that sub-rule is present in the Trial Control. You must first delete its reference. If you create a sub-rule without a valid reference, you can still acquire data but EthoVision informs you that trial control may not work as expected.
create a reference to a sub-rule
A Reference calls the instructions contained in an existing sub-rule. 1. Make sure that the sub-rule has been defined in the Trial Control screen. 2. In the Components pane, under Structures, double-click Reference or click the button next to it. If the Add a reference window appears, choose one of the following, then click OK. Create a new reference. To create a new reference to a sub-rule. Reuse an existing reference. Choose this option if you want to make a copy of an existing reference. Select that reference and, if necessary, the Trial Control Settings where it is stored. For details on re-using elements, see page 36. 3. The Sub-rule Reference window appears. Under Name, enter a name for the reference. The default name is Reference (n), where n is a progressive number. 4. Under Reference, from the Reference to sub-rule list select the sub-rule you have defined in step 1 above. 5. Under Schedule, the Start conditions box shows Without delay. This means that, by default, the sub-rule starts as soon as the reference box becomes active. You can define one or more start conditions. Once the sub-rule starts according to Start condition, you can have it be repeated one or more times (see the picture under point 2 on page 49). Click the Add button to add a Start condition. The Add Start Condition window appears. 6. From the Select type list, select one of the following: Without delay. To start the subrule as soon as the reference is activated. 5 - Sub-rules Delay (default). To start a specific time after the reference becomes active. Enter this time in the Delay field. Clock Time. To start at a specific day and time. Trial Control variable. To start when a Trial Control variable gets a specific value. For details, see sub-rule start conditions on page 60. 7. Repeat steps 5-6 to add more start conditions. If you want to delete a start condition, select this and click the Delete button. 8. Under Stop conditions, select one of the options to specify whether you want the sub-rule to be repeated once or more times (see Sub-rule stop conditions on page 61). 9. If you select to repeat the sub-rule, the Repeat interval option becomes available. Select: Stop to Start (default). To keep a constant time between the stop of a repeat and the start of the next repeat. Start to start. To keep a constant time between the start of successive repeats. For example, start repeats at every hour. Enter this time in the corresponding box (hh:mm:ss). 10.Select one of the options to specify what to do when a new start condition becomes true and a previous repeat is still ongoing. For details, see 'Options for starting a new repeat' on page 62. 11. Under Comment, enter a description of the sub-rule reference (optional). 12. Click OK. The reference box is displayed on your Trial Control screen. 13. Insert the reference box in the appropriate place in the Trial Control sequence (this can be either the Start-Stop trial rule, or another sub-rule). See also page 63.
Notes
If you want the sub-rule not to start immediately as its Reference becomes active, select Without delay and click the Delete button. If you accept the default options (Without delay in the Start conditions box and one repeat), the sub-rule starts immediately and is repeated just once. You cannot edit a condition that you have added to the Start conditions box. Delete first the condition (select the condition and click the Delete button), then click Add to add a new condition. The Start conditions are listed in the following order: Without delay, Delay, Clock Time, Trial Control variable. Stop to Start of a repeat. There is always at least 1 sample difference between the time that the Rule End box is evaluated and the time that the Rule Begin box is evaluated for 5 - Sub-rules the start of a new repeat. This means that a new repeat can never start exactly at the same time as the end of a repeat. Reference names. Names of sub-rule references must be unique in your experiment, unless you have re-used an existing reference. You cannot define two sub-rule references with the same Name, even when these are defined in two different Trial Control Settings. This is because analysis of Trial Control data (see page 168) is based on names of elements (sub-rules, references, actions and conditions). Elements with the same name would give ambiguous results. Re-using a sub-rule reference. If you choose to create a copy of a sub-rule reference and then change any property of this copy (Name, Reference options, or Comment), a window appears with a message Define the scope of your changes. The program asks you whether you want to apply the properties only to the newly-created reference, or to the references with the same name in all Trial Control Settings. Choose the option you require and click OK. If you re-use a Reference that is stored in another Trial Control profile, and this profile is locked after data acquisition, changing any of the Reference settings will not affect the Reference in the locked profile. Modifying a sub-rule reference. To modify a sub-rule reference, click Settings button in the reference box. Multiple references to one sub-rule. You can define multiple references to the same sub- rule, and place the corresponding Reference boxes in the same Trial Control sequence. In the case they are activated at the same time, the program executes the sub-rule in two parallel instances. Such instances are independent, however they can interfere with each other if they both contain actions on a Trial Control variable (see an example on page 30) or on hardware devices. Endless loop - EthoVision XT prevents the occurrence of an endless loop in the Trial Control, which would make EthoVision XT unresponsive. When in a Sub-rule Reference box the number of repeats is not set to a fixed value and the Sub-rule has a 0-second duration, this Sub-rule is evaluated endlessly from the Sub-rule Reference box. To prevent this, in EthoVision XT a Sub-rule is evaluated only once per sample from the Reference box. Sub-rules that are empty, only contain a Trial control variable Action box or Hardware Action boxes, are 0-second Sub-rules. With a 0-second Sub-rule, the Sub- rule Reference box never becomes inactive and, therefore, the Stop track Action box and Rule End box are never reached. In this case, the trial is stopped when you click the Stop trial button (for Live and offline tracking) or when the end of the video file is reached (for offline tracking). 5 - Sub-rules
sub-rule start conditions
To access those options, click Add in the sub-rule's Reference window.
Without delay
Choose this option to start the sub-rule as soon as the sub-rule reference becomes active.
Clock Time
Choose this option to start the sub-rule at specific times of the day. Select trial day. Select the day from the start of the trial that the sub-rule should start. 1st trial day= the same day that the trial starts. Set time (hh:mm:ss). Enter the time of the day that the sub-rule should start. example If you want to start the sub-rule at 12:00 h of the fifth day of the trial, select 5th day and enter 12:00:00.
Delay
Choose this option to start the sub-rule with a specific delay from the moment that the Reference box becomes active. example if you want to start the sub-rule one hour after the start of tracking, enter 01:00:00. Place the Reference box immediately to the right of the Start track box. The time that the Reference becomes active is essentially the time that the previous box in the sequence becomes inactive (a condition being met, or an action being taken). See page 10 for more information on how Trial Control instructions are executed.
Trial Control variable
Choose this option to start the sub-rule when a Trial Control variable gets a certain value for the first time since the Reference becomes active. 1. Click the Edit TC-variable button. The TC-variable condition window appears. 5 - Sub-rules 2. From the first list, select the Trial Control variable. If you need to create a new variable, click TC Variables (see page 28). 3. Select the comparison operator (=, >, etc.) from the second list. 4. Do one of the following: If you want to compare the Trial Control Variable with another variable, select that variable from the third list. If you want to compare the Trial Control variable with a numerical value, enter this value in the third list. If you want to compare a Trial Control variable with a formula, click the double-arrow button and select the operator, then the variable and/or values to complete the formula. example You have defined the variable Phase which can have one of three values 1, 2 and 3 during the trial. You want to start a sub-rule when the current value of Phase is 2. Select Phase = 2. If your variable is of the type true/false, and switches between true and false several times, the sub-rule starts only the first time that the variable gets the value required since the activation of the Reference. For more information on Trial Control variables, see page 28.
sub-rule stop conditions
Execute sub-rule once per start condition (default)
The sub-rule is executed once when one of the Start conditions is met.
Repeat indefinitely (no scheduled stop)
The sub-rule is repeated until trial the trial stops (see page 63 for how this can happen).
Repeat per start condition
The sub-rule is repeated a number of times, or until a condition is met. 5 - Sub-rules For a number of times. To have the sub-rule repeated a fixed number of times for that start condition. Enter this number in the box (default= 2). For a duration of (hh:mm:ss). To have the sub-rule repeated for a specific time period beginning from the corresponding start condition. Enter this time in the box. The maximum time allowed is 99 h 59 min 59 sec. Choose this option if you want that a task is repeated for some time, mo matter how many times in that period. If you choose this option, when the time elapsed since the start condition exceeds the time set here, the ongoing repeat will continue till its end, but no new repeat will start. Until Trial Control variable. To have the sub-rule repeated until a Trial Control variable (see page 28) gets a certain value. Click Edit, specify the variable, its value and click OK. For example, repeat the sub-rule until the variable Count reaches 100. Specify Count <= 100. If you select two or more Repeat per start condition options, no more new repeats are started as soon as any of the conditions is fulfilled. A sub-rule is completed when the last repeat for the planned Start condition is ended. See also the note on Endless loops page 59.
Options for starting a new repeat
Do not start new repeat when there is still a repeat ongoing. A new repeat is not started. A new repeat will start at the planned time, after the ongoing repeat has been completed. Delay new repeat till ongoing repeat finishes. The repeat starts as soon as the ongoing repeat finishes. Terminate ongoing repeat and start new one. The ongoing repeat is ended no matter at which point it is, and a new repeat is started. example A sub-rule is planned to start every 10 minutes. The first Start condition is set to 12:00 h, the second to 12:20 h etc. Suppose that at 12:10, a repeat has not been completed yet, and it will be completed at 12:15. When selecting the first option above, the repeat planned at 12:10 is not started. The program will start the next planned repeat, at 12:20, provided that the first repeat has been completed. When selecting the second option, the repeat of 12:10 starts at 12:15 when the first repeat has been completed. 5 - Sub-rules When selecting the third option, the repeat of 12:10 starts at the planned time. The repeat of 12:00 is forcibly terminated. If Trial Control switches on a light or sound device at the time the repeat is aborted, that device stays on until a switch off command is encountered in the next repeat (or another ongoing sub-rule).
place the sub-rule reference in the trial control sequence
The position of sub-rule's Reference box influences progress in the Trial Control sequence. Consider the difference between the following two cases: Reference box in the linear sequence. Control can only progress when the Reference box becomes inactive. This occurs when the last repeat of the sub-rule has been completed. Reference box -n a dead branch of the sequence. When the sub-rule's Reference box becomes active, the box placed in parallel becomes active too. Thus, control moves forward independent of whether the sub-rule has been completed. For more information on activation of Trial Control boxes, see page 10.
end a sub-rule
A sub-rule is normally ended when the last repeat (see page 57) is completed. However, it can also be forcibly interrupted in the following cases: When the maximum trial duration has been reached. When you stop the trial manually. 5 - Sub-rules When a condition passes control to the next box in the sequence. Consider the following case, where the Reference box is combined with a Condition box through an operator of the Any type. When the Condition is met, the Any operator applies the OR logic, and passes control to the next box. The sub-rule is interrupted. When the Reference box is placed on a dead end of Trial Control sequence. Consider the following example: The right-hand side of the Reference box is not connected to any box of the Start-Stop trial rule. Therefore, the Reference box poses no limit to control that passes through the boxes in the Start-Stop Trial rule up to the Stop box. Depending on the instructions specified in the Start-Stop Trial rule, the trial may stop before the last repeat of the sub- rule is completed.
Figure 19 Example of a sub-rule that is
forcibly interrupted when a condition is met.
Figure 20 Example of a sub-rule
that does not interrupt the Start- Stop Trial rule. 5 - Sub-rules When the last repeat of the sub-rule is ended, the corresponding Reference box becomes inactive. See also the note about Endless loops on page 59.
call a sub-rule from another sub-rule
Within a sub-rule, you can define a reference that calls another sub-rule. Why insert a sub-rule within another sub-rule?. Suppose that your Trial Control is made of four sub-rules that have at least some instructions in common. For example, sub-rules that start at different times, but include the instructions to have the program make a light flash. In such a case, you can define the instructions for the light flash in a separate sub-rule, and then in each of the four sub-rules insert a reference to this sub-rule. 1. Define the sub-rule that should contain the reference to another sub-rule (see page 55). 2. Define the sub-rule that should be called by the first one, and its own reference (see page 57). 3. Insert the Reference box of the second sub-rule in the sequence of the first sub-rule.
Example of calling a sub-rule from another sub-rule
Sub-rule 1 counts the number of times the animal enters the shelter via a particular route. When the animal does so (Condition A in Figure 21), a Reference box (B) calls Sub-rule 2. Figure 21 An example of sub-rule called from another sub-rule. Sub-rule 1 (top) calls Sub-rule 2 (bottom) when the mouse enters the shelter via a particular entry. A - Zone transition condition "Mouse enters the shelter via Entry zone 1" is met (A). B - Reference to Sub-rule 2. C - Action "Light on", followed by a Time condition "0.5 s" and an action "Light off". 5 - Sub-rules Sub-rule 2 is a sub-rule defined to switch a light on for 0.5 seconds (see C for details). As soon as Sub-rule 2 is completed, control is taken back to Sub-rule 1 where the remaining instructions are executed.
Notes
You can call sub-rules in up to 4 levels of existing sub-rules: for example, you can define the Start-Stop trial rule calling Sub-rule 1, which on its turn calls Sub-rule 2, which on its turn calls Sub-rule 3 etc, but you cannot have Sub-rule 4 calling Sub-rule 5. EthoVision XT informs you when you try to create more than 4 levels of sub-rules. If a sub-rule includes the reference to another sub-rule, it cannot be completed until the sub-rule that is called within it has been completed. You cannot create circular references amongst sub-rules. For example: Insert a reference in the sub-rule that this reference calls. In Sub-rule 1, insert a reference to Sub-rule 2, which on its turn contains a reference to Sub-rule 1. EthoVision XT informs you when you try to create a circular reference.
Source: EthoVision XT 17 - Trial and Hardware Control Reference Manual