SciScript is a scripting feature available as an add-on module with the SciScan software. It provides a macro like functionality, letting the user automate repetitive tasks normally carried out using the SciScan UI. Hence, you may notice the terms ‘SciScript’ and ‘Macro’ being used interchangeably.
To ensure that SciScript is included in your version of SciScan, be sure to list SciScript_coMD.vi in the optional modules section of the .ini file.
The SciScript macro files (.sscr) are stored in a human-readable format and can be edited either through the SciScript module as described below or by using a simple text editor.
Launching the Macro Module
The SciScript Module can be launched from the SciScan menu item Plugins → SciScript Module.
When SciScript launches for the first time, the GUI will appear and present the user with the following message:
Load auto-saved macro (from the temp file)
Any changes to your macro are auto-saved to a temporary file; If you choose the load auto-saved macro option, the Macro UI would start with the macro you were last working on. This again gives you 2 options as shown:
This dialogue is a safety feature designed to protect against scenarios where the relative position of your sample has changed from the time the macro was created. This could be caused by the sample being remounted differently, absolute XYZ stage positions being reset manually, or the microscope hardware being re-arranged between uses. The pop-up gives you the option (recommended) to clear all position related information from the macro, or if you are sure of the position calibration, to keep the positions. The commands that are affected include Move.To.Position, Z-Stack and Fast-Z
Start with an empty macro
Choose this option if you want to create a new macro. The UI initializes with a blank macro, allowing you to use the UI to build a new one from scratch.
SciScript User Interface
The figure and table below outline the key parts of the SciScript UI.
|A||Available Actions||The Available Actions Tree contains a list of actions that can be performed by the user. Note that 2D.Line.Scan is only available with a Galvo system and Fast.Z is available only if you have piezoelectric z motion for your objective.|
|B||Info Table||The Info Table contains entries to alert the user about specific events and macro status, such as colours to indicate warnings (orange) or errors (red), no of loop iterations completed, etc.|
|C||Macro Tree||The Macro Tree is the created macro listing the actions that will be executed and the parameters for each macro.|
|D||Presets||Pre-set actions help configure more complicated sequences, such as Slow Z Stack.|
|E||Get Positions||Lets you grab absolute X-Y-Z stage positions from the Position Save Module (if there are valid positions), and inserts Move.To.Position() commands with the selected positions into the macro, starting at the current macro index.|
|F||Edit||The edit button lets you modify the parameters associated with the actions, including modifying scan settings.|
|G||Execution Timing||The Execution Timing cluster gives you approximate timing information in seconds for the macro such as estimated run duration; and during a run, the time remaining and elapsed time.|
|H||Recalculate Execution Timing||Recalculate the Execution Timing, for example after modifying the macro.|
|I||Preview||The Preview lets you step through your macro to verify your settings. It executes Move.To.Position() commands and updates the SciScan UI with the scan settings associated with each command. The user can then Focus at each step to verify if the settings are satisfactory. Please keep in mind that the Preview action executes stage movements and hence you will want to ensure beforehand that the position information specified is safe for both the sample and your equipment. A warning to this effect will be issued when you initiate a preview.|
|J||Run||The Run Button can be used to run a macro as well as to Abort a run that is in progress.|
|K||File I/O Cluster||Lets you carry out actions such as:
|L||Macro File Path||Shows the path of the current file. Unsaved changes are indicated by a * in the indicator name and orange, italicized path text.|
|M||Save As/Make a copy||This lets you make a copy of the current macro and save it to the disk at the location specified in the windows browser.|
Creating/Modifying a Macro
The user has the option to either create a Macro from scratch or edit an existing macro. Available actions refer to software mechanisms that can be automated through SciScript. A new macro is made by ordering these actions and choosing their parameters.
- To Add a new action, <click + drag> from the Available Actions tree and <drop> into the Macro tree.
- To Delete an action in the created Macro, <click + drag> it from the Macro tree and <drop> it in the Available Actions Tree
- To reorder actions within the Macro tree, <drag + drop> actions to different locations within the Macro tree.
Most actions have parameters (specified in the parameters table) or settings (stored in a settings file) associated with them. These parameters/settings can be modified by selecting the command and by clicking on the Edit button.
The Edit button automatically gets triggered during:
- Dropping of a new action into the Macro tree
- Executing the Preview option.
The Edit option works differently in scan commands (2D.Frame.Scan(), Z.Stack() and Fast.Z()), when compared to non-scan commands (LOOP.Start(), Pause() and Move.To.Position()) . These are described below.
The confirmed settings can be altered at any time by selecting the action within the Macro tree and then clicking Edit.
If an error is present in the macro, it will be highlighted in the Info column, click to display the error message.
Non-Scan Actions – commands without settings files
Non-Scan Actions tend to have fewer parameters than Scan Actions and so do not require a settings file. Instead, the parameters are stored as text.
LOOP.Start() and LOOP.End()
The Loop actions allow you to carry out the same procedure multiple times. Loops can be nested within loops for more complicated macros. A completed loop consists of a LOOP.Start() action and a LOOP.End() action with other actions in between.
LOOP.Start() only has one parameter; the number of loop.iterations. This defines the number of times the loop will execute before the macro stops. The LOOP.End() action has no parameters as it just signals to the macro to move back to the start of the loop.
The pause action allows you to insert software-timed delays into the Macro.
Pause() only has a single parameter; wait.seconds. This specifies the number of seconds the software is to wait before moving onto the next action in the Macro.
Move.To.Position() allows the user to pre-program motor movements that will be executed during the macro, allowing you to image multiple areas of interest or perform operations like Z-Stacks or Volume scans through SciScript.
The default recommended setting is to auto-update using the current stage position. With this button ticked, the position values will update as you move around your sample.
With the edit window up, click Focus to bring up a live image and move your stage around to find the required area of interest. Selecting OK will update the parameters for the Move.To.Position() action to the specified position. You can also use the Go To option in the Position Save Module to move to a saved position and then click OK to update the XYZ parameters.
If you know the absolute X,Y,Z position you wish to move to, you can uncheck the Update Current Position options and manually enter the positions (not recommended).
Scan Actions – Actions with a settings file.
Setting up automated image acquisition is much more complicated than the actions described above and as a result, a settings file needs to be generated, saved and associated with any scan actions. The settings file types are unique for the different types of scan actions and store important information about the various scan parameters.
To create a settings file, SciScript asks you to set up the scan using the standard SciScan user interface. SciScript will keep track of any changes you make to the variables that affect the type of scan you are looking to set up and stores the values in the settings file once you confirm everything is set up correctly.
Please note: It is best practice to place a Move.To.Position() action before any scan action to ensure that the system has moved to the area you wish to image, especially if acquiring images within a loop.
2D.Frame.Scan() allows users to automate the acquisition of standard 2D images. Upon adding the action to the macro tree, the popup below will appear, directing you to use the SciScan user interface to set up the scan.
The ‘Advanced View?’ option gives the option to view details of all the variables SciScript will save into the settings file once the settings have been confirmed.
The settings to be modified can be found in the 2D Frame tab on the SciScan main UI and where applicable, in the advanced settings cluster (for arbitrary frames, external.start.trigger.enable, bidirectional scanning, etc.)
Settings can be verified by clicking FOCUS on the SciScan user interface and observing the image. If you are happy with the settings for the image (resolution, speed, number of frames to acquire, start delay, zoom etc…) the settings can be confirmed using the blinking ‘Tick’ button on the SciScript UI. If you don’t want to update the current settings to file, select the ‘X’ button (cancel) instead.
Similar to the 2D.Frame.Scan() the 2D.Line.Scan() action allows you to automate the acquisition of a line scan.
Please note: the 2D.Line.Scan() action is only available in the Galvo version of SciScan.
As with a frame scan, the 2D.Line.Scan() action launches a similar “Settings Update Guide” which offers an advanced view if you wish to verify the variables that will be saved in the associated settings file.
The major difference between the frame scan and line scan settings is the requirement to specify the Region of Interest (ROI) which indicates the path that the galvos will scan.
Upon adding the 2D.Line.Scan() action to the macro, the arbitrary line scan tab will be selected. Select which channel you wish to acquire the line scan from and click FOCUS to bring up a live image.
Use either the freehand draw tool or the polygon tool to specify a closed-loop ROI on your image.
Once you are happy with your drawn ROI, press the OK button to confirm the line. This will add an indicator showing the starting point and direction in which the beam will travel along the line.
All other imaging tabs will get hidden at this stage and the 2D Line Scan tab will become enabled. Specify the number of lines you would like the macro to acquire as well as the number of lines you would like displayed as a single ‘frame’.
Once you are happy with all of the settings click the blinking confirm settings ‘Tick’ button on the SciScan UI, or if you would like to cancel the operation, click the red X.
Similar to the scans above, upon dragging the Z.Stack() action into the macro tree an Update Settings Guide popup is launched, allowing you to view all the variables that will be saved in the settings file.
The main difference between the Z.Stack() action and the 2D.Frame.Scan() action is the requirement to specify the Z-Stack data array which configures the stack planes and the associated laser power. As the default, when the action is added, the Z.Stack and ZStack.data tabs are selected and the Z-Stack can be configured as normal from the SciScan interface.
Use FOCUS to verify that the 2D Frame Scan settings are correct and that the start and end planes of the Z-Stack have been properly specified.
Once you are happy with the settings, press the blinking confirm button on the SciScan UI.
Please note: “Move To Z.Stack Start plane” is automatically carried out at the beginning of a Z.Stack() action to ensure the system starts from the correct position.
The Fast.Z() action can only be carried out if you have a piezoelectric objective positioner configured on your system. As with the other scan actions, a Settings Update Guide popup will appear when the action is added to the macro allowing you to configure the parameters for the volume scan.
Use Focus to set the 2D imaging parameters for the volume scan. The main difference between the Fast.Z() action and the 2D.Frame.Scan() action is the requirement, as with the Z.Stack() action is to populate the Z.Stack.data table with the start and end planes for the piezo scan.
In this scan mode the only the difference in Z position from the table is used to calculate the distance to drive the piezo, because it doesn’t use the X, Y and Z positions from the table, it is important to insert a Move.To.Position() command before the Fast.Z() action.
Once happy with the settings, click the blinking confirm button on the SciScan UI to save the settings file.
The pre-set actions are used to help configure more complicated sequences.
Slow Z Stack
The slow Z Stack action creates a macro representation of the data you have set up in the Z-Stack Table. It converts each plane into a discrete 2D acquisition to ensure accurate objective positioning and improved imaging stability.The macro will step between each plane before adjusting the laser power as specified in the table and executing the 2D scan. Separate 2D images are recorded as raw files into a temporary folder. After completion of the macro, the images are re-combined and saved into the standard root folder with a batch file to open the combined raw image in ImageJ.
This system differs from the standard Z-Stack system by ensuring the objective has moved and is stationary at the point of imaging. In contrast, the standard Z-Stack system records a volume much quicker than the macro, but as a result, there may be some movement artefacts as images are acquired while the objective is still moving.
Using Slow Z Stack
The slow-z stack action is listed under the presets section of the action tree.
Before adding the Slow-Z to your macro, first configure your Z-Stack using the SciScan GUI by populating the Z-Stack Table, setting the imaging parameters. Once set up, add the slow-Z to your macro by dragging and dropping the action into the macro table as you would any other action. When the Slow-Z action is dropped, it will automatically read all of the imaging parameters and populate the macro table based on the information in the Z-Stack table. If you need to edit this information, or make a change to your stack, make the changes in the SciScan GUI and then click the Edit button on the SciScript interface, this will automatically re-read and re-populate the table with the new values.
When ready, click Run to begin acquisition.
Please note: you cannot edit an individual parameter in the slow-z action and actions cannot be dropped into the middle of the pre-set action, other actions can be added before or after the pre-set if required.
The tiling pre-set allows users to automatically collect multiple 2D or 3D acquisitions across a pre-defined region for stitching together afterwards. A macro to automatically stitch together 2D acquisitions is provided with any recorded 2D tile. Stitching for 3D acquisitions needs to be carried out manually.
- Single Plane – obtains a series of 2D XY scans to create a large single plane image.
- Slow Z – obtains a series of Slow Z Stacks across the desired region.
Please note: to use Slow Z tiling you must first have the Z-Stack table set up as you would for initiating a Slow-Z preset.
Using of Image Tiling
Begin by dragging the Tiling preset action into the macro tree. This will launch the tiling setup window.
From this window, you can select the type of tiling to be conducted, either Single Plane (2D) or Slow-Z (3D).
Once the type has been selected, use the movement of the XY stage (either through software or hardware control) to set the bottom right and then top left corners of the region you would like to tile.
Once the corners are specified you can change the number of frames per tile (for group averaging) as well as the desired overlap percentage between each of the tiles for your given stitching application.
When you are happy with the entered information, click OK.
Pressing OK will trigger calculation of the macro and launch a final pop-up for confirmation before finishing.
The pop-up contains information about the overall FOV of your tiled region as well as the overlap percentage and the number of columns and rows of tiles in your final image. If everything appears correct, press OK.
The macro tree in the main SciScript UI should auto-populate with the constructed macro once confirmed.
Press RUN to start the acquisition.
Stitching: a Macro is generated with any single plane tiled acquisition, this can be opened from Fiji to automatically stitch 2D acquisitions.
The generic preset allows the user to change any of the variables of the front panel in a script. One Preset can affect several variables.
Using the generic preset
|A||Data Type||Select the type of data you want to include in the Generic preset (Numeric / Boolean / String / Path)|
|B||CFG Variable name||List the Variables of the selected type. This field is also searchable by typing the name or part of the name of the variable you are seeking|
|C||Current value||Display the current value of the selected variable|
|D||Enter Value||Enter the new value you want to be applied when the Generic Preset will be executed|
|E||Use Current||Tick this box if you wish to use the current value to be applied when the Generic Preset will be executed|
|F||Modify the Generic Preset||
|G||List of Parameters included||List of the GFG variables that will be modified when executing the Generic Preset|
In the example above, running the preset will change the “Shutter” variable from False to True, and therefore open the shutter.
The preview function has been added to SciScan to give you a final opportunity to review all the settings used in your macro before executing it. The Preview functionality steps through each action in the macro as it would during acquisition and launches the Edit option for each.
For each non-scan action the parameters will be applied and for each scan action the settings file will be loaded for confirmation, as it would be in Edit mode.
You can press FOCUS before confirming each of the settings to double check that you are in the location that you expect to be and that the scan settings have loaded properly and are correct.
Please note: preview mode will execute any Move.To.Position() commands so please ensure that movements to the absolute positions specified in the macro do not cause damage to your sample or equipment, if the positions have changed since you specified the location.
File Read/Write operations
Functionalities related to File Read/Write can be found the bottom right side of the SciScript UI (Items K, L, and M in the annotated figure above). All unsaved changes to the macro you are creating are saved in a temporary file (located in <SciScan directory>\Macro Module\SCISCAN Application Data\SciScript\temp.sscr) and an associated settings folder. You should NOT manually make any changes to these files as this can cause the macro to malfunction.
Whenever you run a macro, a copy of the macro file as well as the associated settings files are saved in a date and time stamped zip file in the directory with your imaging data.
Other functions are described below:
New – Creates a new macro. Note that this will clear your temporary file and any unsaved work will be lost. You will get a confirmation window where you may abort the procedure if you so wish:
Load – Lets you load a saved macro from the disk. You can load in files of type *.sscr (SciScript file) or zipped versions of the macro file, which are automatically saved when you run a macro. Opening the zipped version of the macro could come in handy if you want to verify/re-run a macro you used earlier to acquire data. The auto-saved macro can be found in your data folder (<data root path specified in Sciscan>\<date>\)
Save – Save the current macro. If the file has not been saved before, you will get a file explorer window where you can specify the file path. When saved, a copy of the *.sscr file, as well as a folder of the same name (containing the settings files), will be saved into your specified root folder.
Macro File Path – This shows the path of the current macro.
Any unsaved changes to the macro are indicated by a * and a change in text colour as shown below:
Save As/Make a copy – This functionality lets you make a copy of the current macro and save it in the location you specify using the file explorer window.
Please note: it is highly recommended that you use this functionality to make a copy of an existing macro (rather than manually move files using windows explorer), to ensure that the file structures are maintained
Running a Macro/Aborting a run
The Run button starts executing the macro. During a Macro run, some of the controls in SciScan and the SciScript user interface are disabled. This is to ensure that the macro execution is not interrupted due to any undesired button presses. All data acquired during the macro run is saved in the same way as it would be if you were acquiring the image normally.
If you need to abort a macro during its run (and re-enable the controls) you can use the Abort button. The Abort button takes the place of the Run button during a macro run.
Remember that during a macro Run Move.To.Positions, Z-Stack and Fast-Z commands result in stage movements to the absolute positions that have been specified. For Fast-Z and Z-Stack, the Z-stack data table determines the start and end Z-positions. Please ensure that the absolute stage positions specified in the macro do not damage your sample and/or equipment.
Example: Creating a macro for time-lapse imaging
This section describes how to create a simple macro to carry out time-lapse imaging. Multiple scans are carried out from a single position with a specified delay between acquisitions.
- Start with an empty Macro
- Click New from the file operations cluster to open an empty macro
- Add a LOOP.Start() action
- LOOP.Start() specifies the beginning of a loop or ‘iteration’. You are required to specify the number of iterations required using the pop-up window.
- Enter 3 in this example and click ‘OK to confirm. This adds an action, LOOP.Start() in the Macro tree, and a parameter loop.iterations with the argument 3 in the Parameters table.
- Note that LOOP.Start() needs to be terminated with a LOOP.End(); hence the macro will have an error, which we can ignore for now.
- Add a 2D-Frame.Scan action
- 2D.Frame.Scan() instructs SciScan to acquire a frame scan using the scan settings associated with the scan. The scan parameters are stored as a settings file along with the macro.
- Note that configuring scans is different from the LOOP.Start() shown before.
- You get a pop-up window (Settings Update Guide) which directs you to update settings on the SciScan UI
- The pop-up also recommends that you have a Move.To.Position() before a scan. This is to ensure you are in the correct position (which might have been changed manually or by other Move.To.Position() commands in a macro run).
- The ‘Advanced View?’ option gives you the details of all SciScan variables that will be saved.
- You can verify the settings by clicking FOCUS on SciScan and observing the image.
- If you are happy with the settings, you can confirm the settings by clicking the blinking ‘confirm’ button on the Macro GUI. If you don’t want to update the current settings to file, select ‘cancel’.
- On confirming the settings, you will notice an orange highlighted flag next to the row with the 2D.Frame.Scan() action.
- This warning can be clicked on to launch a pop-up containing the warning description. In this case, it is a recommendation to add a Move.To.Position() action before the scan.
- Close the warning message. We will add the suggested action next.
Add a Move.To.Position() action
- The Move.To.Position() command instructs SciScan to move the stage position to the absolute X-Y-Z coordinates specified in the parameters (macro.posx, macro.posy and macro.posz).
- Drop a Move.To.Position() command immediately above the 2d.Frame.Scan() command. In case you dropped the command at a different position, you can move it to the correct location from within the Macro by dragging and dropping.
- Dropping the ‘Move.To.Position()’ pops up a window where you can confirm the XYZ positions. This can be entered by Selecting Update Current Position (default option) and using SciScan on Hardware to move your stage to a position of interest – this updates the position automatically. You may use FOCUS from SciScan main UI to verify you are imaging at the required position (this is recommended).
- Once you are happy with your current position, select OK and 3 arguments and values (for positions X, Y, and Z) get updated in the Macro. If you dropped at the wrong location you can always drag it to a different position within the Macro.
- Alternatively, you can also un-select Update Current Position and enter the positions manually.
- You can also observe that the earlier warning has now disappeared from next to the 2D.Frame.Scan() action.
Add a Pause() action
- The Pause() command suspends macro execution for a certain duration (in seconds) specified in the parameter wait.seconds.
- This can be configured using the pop-up window which opens when the action is dropped into the macro tree or an Edit is selected.
- Select a pause duration of your choice.
Add a LOOP.End() action
- You might have noticed that the Preview and Run option are disabled in the user interface. Also, the LOOP.Start command is coloured red. This is because the macro has an error (in this case, the LOOP.Start() is not terminated with a LOOP.End().
- Dropping a LOOP.End() should clear the error and the Preview and Run options should be enabled. Your macro should look as shown below (with the macro.posx, macro.posy, macro.posz and wait.seconds value you have selected).
- You are now ready to Preview or Run your macro.
Using SciScript with the Position Save Module
The Position Save Module can be a useful tool to configure your Move.To.Position() commands. This may be done in two ways:
Get Positions button in SciScript Module
- The Get Positions button in the SciScript module, lets you grab one or more positions from the Position Save Module. Clicking on the button opens a pop-up window where you can specify the positions to be added.
- The user can select the required positions (selected positions indicated by ‘x’ next to it), and Move.To.Position() commands with the specified absolute XYZ coordinates get added to the macro.
Using Go To button in the Position Save Module
- In the SciScript Module, select the Move.To.Position() command you want to edit. Click on Edit to bring up the ‘Enter Stage Position’ pop-up window.
- Make sure that the Update Current Position option is selected (this is selected by default). This ensures that the current stage position gets updated in the window whenever the stage moves.
- Now, go to the Position Save Module and select a saved position of interest. Click on Go To. This moves the stage to the selected position and updates the absolute XYZ position in the ‘Enter Stage Position’ pop-up window.
- When you are happy with the current position (click on FOCUS from SciScan UI or Position Save Module to verify the position using a live image), click OK on the ‘Enter Stage Position’ pop-up window to save the stage position.