PyTES Documentation

PyTES is a Python-based, 3-clause BSD licensed toolbox to facilitate the remote control of transcranial electric stimulation and ease deploying a closed-loop TES system. PyTES supports two communication protocols to control the hardware: VISA and USBTMC.

---

Contents

• Installation
• Features
  • Plug-and-play
  • Closed-loop application
  • TES with arbitrary signal
  • Timer for stimulation and fade in/out duration (GUI version)
• Usage
  • Command line
  • GUI
  • In Psychopy
  • In OpenVibe
  • Live Demo
• Known Issues

Installation

---

Prerequiste

Different operating system and communication protocol has diverse prerequisites for installing and using the PyTES package. A brief summary is listed below:

	USBTMC	VISA
Linux	None	pyvisa
Windows	N/A	pyvisa + driver

Pyvisa

More details about the installation of pyvisa can be found here

Driver

Driver installation depends on the chosen hardware(s). For example, the Rigol arbitrary waveform generator requires the type-specific IVI driver, as listed here. Users of PyTES are suggested to install the driver according to the official documentation of their own device(s).

PyTES

You can either clone this repo or install pytes via pip:

pip install git+https://github.com/TateXu/pytes.git

Features

---

Plug-and-play

This feature leverages the default USBTMC driver of the Linux system such that the USBTMC interface can be opened as a file node. Please note that this feature is only available for Linux users using the USBTMC protocol.

Closed-loop application

PyTES can be seamlessly combined with other online experiment frameworks to constitute a closed-loop TES system, e.g., OpenVibe and Psychopy. More details for the usage can be referred to OpenVibe and Psychopy

PyTES with arbitrary signal

Some advanced TES require a non-regular shape of the stimulation signal, e.g., AM-tACS, etc. To better support such studies, PyTES provides such function to output a user-defined signal.

• In the GUI version, the signal should be first used to create a dictionary, as shown below. Next, this dictionary should be saved as a pickle file. Finally, input the path of the pickle file into the corresponding entry.

data_to_save = {'sps': sampling_rate_in_Hz,
                'data': a_list_of_all_data_points}

• In the command line version, you can use the function SignalGenerator().arb_func() to output the arbitrary signal.

Timer for stimulation and fade in/out duration (GUI version only)

For the GUI version of PyTES, the timers for stimulation and fade in/out can be set separately for different output channels. No input for these entries will indicate either indefinite stimulation or no fade in/out for the corresponding channel.

Usage

---

Command Line

The usage via the command-line version is just as same as the other Python packages. One example of outputing a tACS signal with 1V ampltiude, 25Hz frequency and 45 degree phase shift is as shown below:

from pytes.signal_generator import SignalGenerator as SG
control = SG()
control.amp(value=1, chn=1, stim_mode='tACS')  # Adjust the tACS amplitude of channel 1 to 1V
control.freq(value=25, chn=1, stim_mode='tACS')  # Adjust the tACS freuqency of channel 1 to 25Hz
control.phase(value=45, chn=1, stim_mode='tACS')  # Adjust the tACS phase shift of channel 1 to 45 degree
control.on(chn=1)  # Turn on the output of channel 1

PyTES also provides many other functions to adjust the stimulation parameters conveniently, e.g., frequency, offset, phase, etc. More functions can be found at here.

In addition to the provided functions, it is also possible and convenient to directly send SCPI command via PyTES to communicate with the hardware with the function SG().set_cmd().

GUI

• Step 1: You can eithe directly run the GUI python script from command line - path_to_pytes_pkg/pytes_gui.py or call the GUI function from the package

from pytes.pytes_gui import PyTESWindow

• Step 2: Driver selection, USBTMC or VISA (Note: USBTMC is not applicable for Windows; For USBTMC protocol, the root access is required)
• Step 3: Device selection from the option menu
• Step 4: Connection test via clicking "Connect" button
• Step 5: Parameter setup
  • tDCS/tACS/tRNS - Fill in the value in the allowable entry
  • Arbitraty signal stimulation - Input the absolute path to the data file (in .pkl format, more details refer to Features )
• Step 6: Stimulation signal check via clicking "Update Parameters" button
• Step 7: Timer setup for stimulation duration and fade in/out duration.
  • None value for stimulation duration means a indefinite stimulation
  • None value for fade duration means no fade in/out will be applied
• Step 8: Output stimulation signal via clicking "Output" of target channel

Step 1 - 6:

toolbox_parameters_setup.mp4

Step 7 - 8:

toolbox_timer_output.mp4

Psychopy

To integrate the real-time stimulation signal control code into the experimental paradigm written by PsychoPy, you can leverage the Code Component function of PsychoPy, in which the snippets of PyTES control commands can be inserted into the experimental paradigm code.

OpenVibe

For OpenVibe users, you can use The Python Scripting box to integrate the PyTES command to control the stimulation signal based on the online decoding results.

Demos

1. Demo for controlling the stimulation signal on Windows:

demo.mp4

2. Demo for controlling the stimulation signal via USBTMC driver on Linux:

USBTMC.MOV

3. Demo for controlling the stimulation signal via VISA driver on Linux:

VISA.MOV

Issues

---

1. Font issues of the GUI version: The PyTES GUI is based on the package Tkinter. It is known that the Tkinter font cannot be correctly rendered under Anaconda Python on the Ubuntu system. For better visualization, it is suggested to switch to a non-conda Python installation. More discussion about this issue can be found here

2. USBTMC driver cannot be selected after using the VISA driver: Devices that are already opened by the VISA protocol cannot be opened by USBTMC drivers. Restarting the hardware devices can fix the issue.

3. Long initialization on Windows: Please be aware that a longer initialization duration is expected on Windows system due to the file scanning via pyvisa.

---