Customizing Stimuli with Mathematical Functions and Expressions

Introduction

This project template demonstrates how you can use Functions and Expressions to customize the appearance and behaviour of stimuli in various practical contexts. In this tutorial, we show four examples:

Example 1 - Using a Trigonometric Function to Animate a Stimulus
Example 2 - Displaying Real-Time Values of Expressions on the Screen
Example 3 - Creating a custom timer and limiting an expression-driven property to a maximum value
Example 4 - Animating the position of a stimulus with projectile-like motion

This template project was developed for the features available in LabMaestro 1.7.1 and does not require VPixx hardware devices. Examples are implemented within a single Timeline, in consecutive Epochs. Stimuli are displayed until Wait for Inputs detects any keyboard key press.

Note that values that depend on Time, such as those used in customized time-based animations, will only reflect elapsed time when clicking Launch Experiment or Play Timeline. Otherwise, the value of Time is 0.

Prerequisites

LabMaestro is installed and activated.

Project File

MathematicalExpressionsDemo_V1.lm

Example 1 - Using a Trigonometric Function to Animate a Stimulus

The first example presents a grating which oscillates with a motion pattern characterized by the equation cos(360fT)*theta.

To make the Grating Pattern (but not its parent region) oscillate between -30 and + 30 degrees at a frequency of one oscillation per second, insert the following expression into the grating's Orientation field:

=cos(360*1*Time)*30

*Changing the Grating pattern orientation (Version 1.7.1)*

Example 2 - Displaying Real-Time Values of Expressions on the Screen

When developing stimuli that include expressions, it is often helpful to display their results on the screen.

In this example, we show two different ways to display the result of the expressions. The simplest way, Method 1, involves writing the equation directly in a text region. In contrast, in Method 2, expressions are written directly in the component property where they are used, and referenced in the text region:

*Including expressions within a text region 1.7.1*

Method 1 - Writing the expression directly within a Text Region.

We use a Text Region (DescriptionExample2) to display the result of an expression directly on the screen. Click on the text region, and enter the expression you want to evaluate between closed brackets:

{ }

Here, we use the floor() function to illustrate the method and inserted the following text in DescriptionExample2.Text field to construct our feedback information:

Rounding up or down with floor() within a text region.
Round down from 1.5: {floor(1.5)}
Round up from 1.5 : {floor(1.5)+1}

Method 2 - Referencing a specific component property.

We first created a simple rectangular stimulus, Rectangle2, and used expressions in two fields:

Rectangle2.Geometry.Width:

 =floor(1.5)

Rectangle2.Geometry.Height:

 =floor(1.5+1)

We then entered the following text in the DescriptionExample2.Text field to construct our feedback screen:

Rounding up or down with floor() directly in a component's property
{Rectangle2.Geometry.Width} x {Rectangle2.Geometry.Height} {Rectangle2.Geometry.Units}

Example 3 - Creating a custom timer and limiting an expression-driven property to a maximum value

In Example 1, we showed how to use Time in expressions to create a time-based animation. Time reflects the time elapsed since the start of the Timeline. However, often, expressions should reflect the time elapsed since a more recent reference point. Here, we will demonstrate one method for creating a custom timer that reports the time elapsed since the start of a specific epoch.

Creating a custom timer with Timeline Custom Variables

First, we need to create a custom variable to store our reference time.

From the Project Panel, click on the Timeline to display its properties.
All timelines can define new custom variables that are used only within their own local scope. Click on […] to open the CustomVariables dialogue box.
We created a custom variable, CurrentTime, using the + icon and set it to a float. Every time you run the Timeline through the PlayTimeline or the Launch Experiment buttons, the CurrentTime value will change to 0.0 upon entering the Timeline.

Since we want to use CurrentTime to store the time at which we began Example3, we inserted a Set Variables command at the beginning of the Example3 epoch and renamed it SetVariableExample3.
We navigated to the list of Variables,
and used the + icon to select CurrentTime from the list of available variables. By using the expression:
```
=Time
```
The SetVariable command replaces the default CurrentTime value with the Time at which the software executes the command.

Alternatively, you can use the Reset Timer command component to reset the value of the Time global variable at the beginning of the epoch.

Limiting an expression-driven property to a maximum value

In this example, we present a simple drifting-dot stimulus whose dot population is a function of time. We use an expression that increases the number of displayed dots by 1 per second, up to a maximum of 8.

You can do so with the following expression:

=floor(min(Time-CurrentTime,8))

By subtracting CurrentTime from Time, we ensured that the number of dots depends on the elapsed time since the start of this example, not on the start of the entire Timeline. Then, the min function returns the smaller of 8 and the computed difference.

*Dynamically adapting dot population using component properties (LabMaestro Version 1.7.1)*

Example 4 - Animating the position of a stimulus with projectile-like motion

You can animate the position of a stimulus using mathematical functions. As a toy example, you could show projectile-like motion on a screen by implementing the following equations on the region’s center coordinates.

First, as in Example 3, we use SetVariablesExample4 to store the CurrentTime when Example 4 began.

Using the expression below in the Center.x coordinate, your projectile would originate from the left-most side of a 1920 pixel-wide screen, and cross to the right side in 4 s, i.e., at a constant speed of 480 pixels per second.

=-1920/2 + 1920/4*(Time-CurrentTime)

Whereas, for the Center.y coordinate, the expression below will make the projectile drop from the bottom of a 1080 pixel high screen, accelerating towards the bottom of the screen at a rate of 490 pixels per second :