File Import, Export, and Advanced Venus Scripting: Connecting Your Method to the Outside World

Beyond the deck

The previous articles in this series cover the closed loop: worktable, teaching, sequences, step selection, variables and loops. Together, these give you complete control over what happens on the deck during a run.

This article opens that loop. Real-world lab methods don't exist in isolation. They read sample worklists from a LIMS. They write results to shared network folders. They trigger downstream instruments. They run heating and pipetting in parallel. They pass data between the robot and the people running it.

The General Steps covered here, file operations, the Shell step, parallel execution, timers, and error handling, are what make a Venus method part of a larger workflow rather than a standalone robot action.

File operations: reading from and writing to external files

Venus provides five file steps that allow methods to read and write text files, CSV files, and Excel files (.xls).

Opening a file

File: Open (filePath, mode)

filePath is the full path to the file, typically as a string variable. mode is either Read or Write (append or overwrite). The file must be opened before any Read or Write steps can access it.

Store file paths as variables at the top of the method, not hard-coded within individual steps. This makes it easy to update the file location without hunting through the method for every File step.

inputFilePath = "C:\Methods\Worklists\SampleWorklist_2026.csv"
outputFilePath = "C:\Methods\Results\Run_[timestamp].csv"

Reading from a file

File: Read (fileHandle, delimiter, variables...)

The Read step reads one line from the currently open file. The line is split by a specified delimiter (typically comma for CSV) and each field is assigned to a variable in order.

Reading a CSV worklist:

File: Open (inputFilePath, Read)
Loop until end of file:
    File: Read (file, ",", sampleID, sampleVolume, destinationWell)
    // use sampleID, sampleVolume, destinationWell in subsequent steps
End Loop
File: Close (file)

Each loop iteration reads one row of the CSV. The fields split into variables, which are then used to drive the pipetting steps for that sample, using the same loop and variable mechanics covered earlier in this series.

SQL queries on .xls files

One of Venus's more useful file features: the File: Read step supports SQL-style queries when reading from an Excel (.xls) file. This allows you to filter and sort rows before reading them into the method, without pre-processing the file externally.

Reading only rows where the sample status column equals "Ready":

File: Open (worklist.xls, Read)
File: Read SQL: SELECT SampleID, Volume, DestWell FROM Sheet1 WHERE Status = 'Ready' ORDER BY DestWell

The result is a filtered, ordered set of rows that the method can iterate through with a loop. This is particularly useful when your worklist comes from a LIMS and includes samples at various stages. You only want to process those flagged as ready for this run.

The SQL query syntax is limited compared to a full database (no joins between sheets, limited function support), but for filtering and sorting a single worklist table it's practical and eliminates the need for external preprocessing.

Writing to a file

File: Write (fileHandle, delimiter, variables...)

The Write step writes one line to the currently open output file. Specify the delimiter and the variables to include.

Writing a results log:

File: Open (outputFilePath, Write, Append)
Loop [sample iterations]:
    // [pipetting steps]
    File: Write (outputFile, ",", sampleID, transferredVolume, timestamp, tadmStatus)
End Loop
File: Close (outputFile)

This produces a CSV with one row per sample, recording what was transferred and whether TADM monitoring passed. The output file can be picked up by a LIMS, a shared folder watcher, or manual review.

File: Set Position

File: Set Position moves the read pointer to a specific line in the file. Use this to re-read a file from the beginning on a second pass, or to skip a header row at position 1 before beginning to read data rows.

The Shell step: running external scripts and applications

The Shell step executes an external command or script from within the Venus method: a Windows command, a Python script, a batch file, or any executable.

Shell: "python.exe C:\Scripts\ProcessResults.py [outputFilePath]"
Shell: "xcopy [outputFilePath] \\SharedServer\Results\ /Y"
Shell: "C:\ExternalApp\DataProcessor.exe [args]"

The Shell step runs synchronously by default; the method waits for the external process to complete before continuing. This means you can chain: write a results file, call a Python script that processes it, then read the output back into the method.

Common use cases:

• Calling a Python script to process TADM output from the database and flag any anomalous wells before the next step
• Copying result files to a network location at the end of each run
• Triggering a downstream instrument (if it accepts command-line arguments)
• Sending a notification to an operator via a command-line email utility

One caution: Shell steps introduce dependencies on the computer's external environment. The external script must exist at the specified path, the runtime (Python, batch interpreter, etc.) must be available, and the Venus computer's network access must be configured correctly. Document these external dependencies as part of the method validation. A Shell step that silently fails because a network drive is unmounted won't produce an error visible in the Venus trace unless you explicitly check the Shell return code.

Parallel execution: Begin Parallel and End Parallel

The Begin Parallel and End Parallel steps mark a block of steps that can execute simultaneously. Within a parallel block, the robot executes multiple operations concurrently. The most common application is pipetting while a heater shaker is running, or moving the iSWAP while channels are processing.

Standard pattern for incubation with concurrent pipetting:

Begin Parallel:
    [Start heater shaker on plate 1]
    [Start timer: incubationTimer]
Parallel:
    [Pipette samples from plate 2 while plate 1 incubates]
End Parallel
[Wait for incubationTimer: 600 seconds]
[Transfer plate 1 to next position]

Parallel execution requires careful planning. Not all step combinations can run in parallel; the pipetting arm can't be in two places at once. Specifically:

• iSWAP operations and channel pipetting operations cannot run in parallel on the same arm
• Two channel aspirate steps cannot run in parallel
• A channel pipetting step and a non-arm operation (starting a heater shaker, starting a timer, writing to a file) can run in parallel

The Set Event and Wait for Event steps provide a mechanism for coordinating parallel blocks. One block signals an event when it reaches a specific point, and another block pauses at Wait for Event until that signal arrives. This is used in more complex multistep parallel workflows where the two parallel streams have different durations and must synchronise at defined points.

Error handling

Errors in Venus methods fall into two categories: recoverable errors the method can handle automatically, and unrecoverable errors that require operator intervention or abort.

Error settings in step dialogs

Every hardware step (Aspirate, Dispense, Tip Pick Up, Tip Eject, iSWAP steps) includes an Error settings dialog. Here you define automatic responses to specific error codes:

• No tip detected during Tip Pick Up: automatically re-attempt, or advance to the next tip position and retry
• LLD not detected during Aspirate: alert operator, or abort
• TADM error during Aspirate: flag the channel, eject tip, continue with remaining channels
• iSWAP grip failure: retry N times, then abort

These automatic error responses are specific to the step that generated them. They execute without pausing the method unless configured to prompt the operator.

Error Handling by the User

The Error Handling by the User General Step captures errors not handled by the step-level error settings and routes them to custom logic. This is the method-level catch mechanism.

A common pattern: any unhandled error triggers Error Handling by the User, which logs the error to the output file, displays a User Output message, and optionally allows the operator to choose Retry, Continue, or Abort via a dialog.

Abort

The Abort step terminates the method immediately with an error state. Include Abort in any branch where continuing the method would be unsafe or produce invalid results, for example after detecting a sample count outside valid range, or after a second consecutive TADM failure on the same channel.

TADM: the quality control layer you should not skip

TADM (Total Aspiration and Dispense Monitoring) records pressure traces for every aspiration and dispense at 10 ms intervals. Each trace is checked in real time against a tolerance band specific to the liquid class and volume. Deviations flag potential issues: a blocked tip, an empty vessel, partial air aspiration, a clot, or a burst bubble.

TADM data is written to a Microsoft Access database and is available for post-run review and, with the Wait for TADM Upload step, for in-method branching logic.

Enabling TADM doesn't slow the method meaningfully. It adds a layer of run-time QC that distinguishes a monitored, defensible result from an unmonitored one. For any method where pipetting failures would compromise assay validity, TADM should be enabled. This is the same monitoring layer referenced when choosing step types for aspirate and dispense.

The Wait for TADM Upload Single Step ensures the TADM database has received data from the most recent monitored step before any downstream logic reads from that database. Without this step, a Shell call to a TADM-reading script may execute before the data is available.

Structuring a complete production method

A production-ready Venus method typically has this structure:

// 1. Initialise
Initialize (Always)
Calibrate Carrier (critical carriers)

// 2. Load and verify
Advanced Load Settings
Load (all carriers with Autoload)
[Load and Match if barcode verification required]

// 3. Accept runtime parameters
User Input: sample count, operator ID, any variable parameters
[Validate inputs]
[Calculate derived values: reagent volume required, iteration counts]
User Output: confirm run parameters before proceeding

// 4. Pre-run checks
[Read worklist from file if applicable]
[Display reagent requirements]
[Prompt operator to confirm deck is loaded correctly]

// 5. Execute workflow
[Nested loops, conditional branching, sequence manipulation]
[File: Write run log with timestamps]
[Timers for incubation steps]
[Parallel blocks where appropriate]

// 6. Post-run
[Write final results to output file]
[Shell: copy results to network location or trigger downstream processing]
User Output: "Run complete. [N] samples processed. Output: [filepath]"

// 7. Unload
Unload (all carriers)

Every section has a clear purpose that's evident from the structure without needing to read every step individually.

Version control and method files

Venus methods are stored as .med files and worktables as .lay files. Treating them as code, with version control, meaningful file names, and change logs, is the practice that separates a well-run lab's automation from one that runs on a single critical operator's memory.

Minimum recommended practice:

• Name method files with instrument, assay, and version: STAR01_NGSLibraryPrep_v2.3.med
• Store method and worktable files together in a shared, backed-up location
• Record the Venus version and instrument firmware version alongside each method file
• Log every change with a description in a change log file adjacent to the method

If your lab uses a formal LIMS or document management system, method files should be registered as controlled documents with change approval workflows.

The Venus scripting stack

This series has covered the complete Venus scripting stack from the ground up:

1. Worktable -- the software model of the physical deck; must be correct before anything else works
2. Teaching -- the calibration layer that validates the model against reality
3. Sequences -- the ordered position lists that all pipetting steps reference; the logic of how the robot traverses labware
4. Step tiers -- Single Steps for full control, Power Steps for composite operations, Smart Steps for standard workflows; liquid classes as the physical pipetting layer
5. Variables and loops -- the general programming layer that makes methods flexible, parameterised, and reusable
6. File I/O, Shell, parallel execution, error handling -- the integration layer that connects the method to external data, downstream processes, and runtime QC

None of these layers works without the ones below it. A sophisticated file-driven variable-volume transfer method fails at the first step if the worktable carrier positions are wrong. A carefully taught deck produces the wrong results if the sequences are ordered incorrectly. Understanding the stack from bottom to top, and building each layer deliberately, is what Venus scripting for production actually requires.