Automator Subroutines

Subroutines are basically automations that run within other automations. By thinking ahead and designing subroutines you can use them as building blocks to construct bigger automations. Once they are written you can have access to them to use in many future automations. Subroutines need to be freestanding automations that can run independently. So the example here will run as it is but will also function as a subroutine.

Before we get started on an example subroutine it is important to know about the new variables that a subroutine can use. At the end of the day the subroutine doesn't have to use variables but you might find they come in handy. For instance you might need to pass information in the form of a number or string variable to and from the subroutine and the automation that is using it.

There are three categories of variable;

Private

Input

Output

A private variable is not shared between automations, when a new variable is created it defaults to private. An input variable is a variable that will accept a value from the 'calling' automation. An output variable is a variable that returns a value to the 'calling' automation. The 'calling' automation is the automation that contains the subroutine, when a “Subroutine task” is executed in the automation the Subroutine is 'called'.

It's probably easier if we look at this with a worked example. The most common type of automation is a timelapse experiment in some shape or form.

In a timelapse you will usually need a delay and a number of timepoints. The number of timepoints is usually controlled by the number of iterations of a loop task. However to some users it might be easier to think of the experiment's duration in hours. If you want to use this alternative approach we need to calculate the number of timepoints. This could be derived by dividing the duration of the timelapse by the duration of the delay, thus giving us the number of timepoints. Also you might prefer to have the delay time in minutes. The delay task in the Automator uses a value in seconds, but it is easy enough to convert from minutes to seconds using a variable task. This is all simple, but we can make a subroutine to do this, that will return the number of timepoints and also the delay time in seconds. Then we can keep reusing this subroutine in future automations rather than rewriting this functionality into every timelapse automation.

First let's build the subroutine, we will make it like any other automation.

You will need a 'Start' task to begin with.

Next we will have a 'Multiple Input' task.

We will ask the user to enter the experiment duration in hours and the delay time in minutes. We will put the answer to these in two variables 'duration_hours' and 'delay_minutes'.

Before you ask, these variables will be private to the subroutine. If you need to check a variable's scope look in the variables window for the automation (Windows … automation variables), see below.

Next we need to think about deriving the number of timepoints and the duration in seconds from these inputted values.

Converting the delay time from minutes to seconds is easy enough using a variable task.

I have set up the variable task to multiply 'delay_minutes' by 60, putting the result into a new variable 'delay_seconds'.

The variable 'delay_seconds' will need to be an 'output' variable as we need to return the value to the 'calling' automation. To change the variable scope, go to the automation variable window and double click over the variable, or select the variable and click the 'Change Type' button.

The dialog below will open, this will enable you to change the variable's scope to 'output'.

Next we need to derive the number of timepoints, we can do this using another variable task.

In the setup for this task I have taken 'duration_hours' and multiplied it by 60 to get it into minutes then divided the result of this by 'delay_minutes' putting the value into another new variable 'number_of_timepoints'. Again this new variable needs to be changed to an 'output' variable as it needs to be returned to the 'calling' automation.

That's pretty much it for the subroutine but remember to end it with an “End” task otherwise the automation will get nowhere.

For Openlab to load a subroutine the automation needs to be in the 'Automator Subroutines' folder.

Save the subroutine to this location, I will call this subroutine 'timepoints and delay'

For the subroutine to load you will now need to quit and restart Openlab,  a subroutine will only get loaded if it is in the 'Automator Subroutine' folder when Openlab is started.

Now let's make a very simple timelapse with the subroutine.

Again we will start with a “Start” task, then a “Target Image window” task to target an image document.

Next we will use the subroutine, you will find it under the 'Subroutines' tasks in the Automator.

In the setup task for the Subroutine (double click on the task to see this) you will need to put the output values from the subroutine into two new variables in this 'calling' automation. To keep things simple I will name these variables 'delay' and 'timepoints'. These variables will be private to this automation so no scope change is necessary here.

Let's take a quick look at the rest of the automation.

We will use a “Loop” task to 'Loop' the number of timepoints.

And in the “Delay” task we will 'Wait until' using the variable 'delay'

You can also see I have added in a “Capture Layer” task and an “End” task that will stop the automation after the Loop body has finished executing.

When you run the automation the subroutine is executed and you will be prompted with the multiple input task dialog, see below.

In this example I will use an experiment duration of 5 hours and a delay time of 1 minute.

This should give us a 60 second delay and 300 timepoints in total.

If you check the variables window these values are set for 'delay' and 'timepoints' respectively.

That's pretty much it. It looks like more work but you will reap the benefits later if you invest the time now. See you next time!