MagVenture class

This is a python translation of the MagVenture part of the MAGIC toolbox (https://github.com/nigelrogasch/MAGIC).

MAGICPy Copyright (C) 2021-2024 Ole Numssen

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.

class magicpy.magicpy.MagVenture(portid, ttl_port=None, flush_before_cmd=True, wait_s=1, wait_l=1)

Class to manage communication with a MagVenture TMS stimulator connected to a serial port.

m = MagVenture('/dev/ttyS4')
m.connect()
m.arm()
m.set_amplitude(50)
m.fire()
m.disarm()
m.disconnect()

Use a direct parallel port connection to fire stimulators via TTL pulse:

m = MagVenture('/dev/ttyS4', ttl_port=0)# use /dev/parport0 for TTL pulse
m.connect()
m.arm()
m.set_amplitude(50)
m.fire()          # fire stimulator via TTL
m.fire(TTL=False) # fire stimulator via control connection. High lag.
m.disarm()
m.disconnect()

Attributes

portserial.Serial()

Information about the serial connection.

arm(get_response=False)

Enables the stimulator.

Example

import magicpy as mp
stim = mp.MagVenture(portid="/dev/ttyUSB1", ttl_port=0)
stim.arm()  # return is always (None, None)

data, errorcode = stim.arm(get_response=True)  # errorcode is 0 (=all good) or 1 (= error)
if errorcode is not 0:
    print("Cannot enable stimulator")
else:
    print(f"Successfully enabled stimulator {data['Model']}")

Parameters

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

static calc_crc(cmd)

Computes CRC code needed for the MagVenture device to accept the command.

Parameters

cmdlist of str

The command that should be sent to the stimulator as bytestring. E.g.: ['01', '02']

Returns

retstr

The CRC in hexs tring.

connect(force=False)

Opens or reopens the desired port.

Example

import magicpy as mp
stim = mp.MagVenture(portid="/dev/ttyUSB1", ttl_port=0)
stim.connect()

Parameters

forcebool, default: False

Reopen if already open.

static dec2bin_padded(val, z=8)

Decimal to binary conversion. Includes zero padding and stripping of the ‘0b’ prefix.

Example

MagVenture.dec2bin_padded(1, z=8) == '00000001'

Parameters

valint

Value to convert to padded binary.

zint, default: 8

Length of string to pad with zeros.

Returns

bin_val : str

static dec2hex_padded(val, z=2)

Decimal to hexadecimal conversion. Includes zero padding and stripping of the ‘0x’ prefix.

Example

MagVenture.dec2hex_padded(1, z=8) -> '00000001'

Parameters

valint

Value to transform to hex.

zint, default: 8

Length of string to pad with zeros.

Returns

hex_val : str

disarm(get_response=False)

Disables the stimulator.

Parameters

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

disconnect()

Closes the port.

fire(use_ttl=True, get_response=False)

Fires a single pulse. If a parallel port is provided while initialization, the stimulator is fired via a TTL # pulse without further checks. Otherwise, the stimulator is fired via serial control connection and thus has a high jitter.

Parameters

use_ttlbool, default: True

Fire stimulator via TTL pulse over parallel port if self.ttl_port is set.

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

get_baratio()

Gets the B/A Ratio.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

get_burst()

Gets burst parameters.

Returns

device_responsedict

The response sent back from the device

errorbool

Non-zero value indicates error code, or zero on success.

get_current_dir()

Gets the current direction.

Returns

device_responsestr

The current direction. One of ['Normal', 'Reversed'].

errorbool

Non-zero value indicates error code, or zero on success.

get_ipi()

Gets interpulse interval in ms.

Returns

interpulse intervalfloat

The interpulse in ms.

errorbool

Non-zero value indicates error code, or zero on success.

get_mode()

Gets stimulator mode information.

Returns

modestr

The stimulator mode. One of ['Standard', 'Power', 'Twin', 'Dual'].

errorbool

Non-zero value indicates error code, or zero on success.

get_raw_info()

Gets all current raw information from device for set commands.

Returns

Informationdict

Raw information from stimulator.

get_status()

Gets the status of the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

get_status2()

Gets the second status (Status2) of the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

get_status_set_get(get_response=False)

# TODO: remove this and use status2() Get info from device in set/get commands.

Parameters

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

get_waveform()

Gets the waveform from stimulator.

Returns

waveformstr

The device’s waveform.

errorbool

Non-zero value indicates error code, or zero on success.

parse_pulses_per_burst(n_pulses_per_burst)

If n_pulses_per_burst is None, it is read from stimulator.

parse_response(read_data, only_last=True)

Parses the stimulator response.

Parameters

read_databytes

Bytestring. The raw response from the stimulator.

only_lastbool, default: True

Return only the last response if multiple responses are in read_data. If not, returns turn into lists of dict.

Returns

infodict or list of dict

The parsed response sent back from the device.

info_rawdict or list of dict

The raw response sent back from the device.

process_command(command_length, command_bytes, resp_len_exp=8, get_response=False)

Prepares the command to be sent to the stimulator. Start and end bytes are added, the crc for the command_bytes are computed, and everything is sent to the stimulator.

Parameters

command_lengthstr

Length of command to be sent to the stimulator, in bytes.

command_byteslist of str or str

Stimulator command as bytestring list.

resp_len_expint, default: 8

Length of stimulator response that one expects.

get_responsebool or int, default: False

Whether to request a response from the stimulator. get_response = 2 or 3 returns raw_response.

Returns

device_responsedict

The response sent back from the device

errorbool

Non-zero value indicates error code, or zero on success.

send_train(get_response=False)

Sends a train of pulses to the specified port.

Parameters

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

set_amplitude(a_amp, b_amp=None, get_response=False)

Sets the amplitude in standard or twin mode. If only one amplitude (a_amp) is given, standard mode is selected. If both amplitudes (a_amp, b_amp) are given, Dual/ Twin Mode is selected.

Parameters

a_ampint

Indicates A amplitude in percentage in Standard Mode.

b_ampint, optional

Indicates B amplitude in percentage in Dual/ Twin Mode (otherwise only A amplitude required).

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

set_baratio(baratio, current_dir=None, n_pulses_per_burst=None, ipi=None, get_response=False)

Sets the B/A Ratio.

If current_dir, n_pulses_per_burst, or ipi is not set it is read from the stimulator. This takes some time, so better set arguments accordingly.

Parameters

baratioint

When working in Twin Mode, the amplitude of the two pulses A and B are controlled in an adjustable ratio between 0.2-5.0. “Pulse B” is now adjusted to a selected percent ratio proportional to “Pulse A”.

current_dirstr, optional

Current direction of the stimulator. One of ['Normal', 'Reverse'].

n_pulses_per_burstint, optional

Biphasic Burst index in the current status of the device. One of [2, 3, 4, 5].

ipifloat, optional

Represents Inter Pulse Interval which defines the duration between the beginning of the first pulse to the beginning of the second pulse.

get_responsebool, default: False

Request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

set_burst(n_pulses_per_burst, current_dir=None, ipi=None, baratio=None, get_response=False)

Sets the number of pulses per burst.

If current_dir, ipi, or baratio is not set it is read from the stimulator. This takes some time, so better set arguments accordingly.

Example

import magicpy as mp
stim = mp.MagVenture(portid="/dev/ttyUSB1", ttl_port=0)
stim.connect()
stim.set_burst(4)  # set burst of 4 pulses per trigger in. Slow, because we need to read other params.
stim.set_burst(4,' Normal', 10, 1)  # faster, because we don't need to reed parameters from stimulator.

Parameters

n_pulses_per_burstint

Biphasic Burst index in the current status of the device. One of [2, 3, 4, 5].

current_dirstr, optional

defines current direction of the device in the current status. One of ['Normal', 'Reverse'].

ipiint, optional

represents Inter Pulse Interval of the current status of the device which defines the duration between the beginning of the first pulse to the beginning of the second pulse.

baratioint, optional

when working in Twin Mode, the amplitude of the two pulses A and B are controlled in an adjustable ratio between 0.2-5.0. “Pulse B” is now adjusted to a selected percent ratio proportional to “Pulse A”.

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device

errorbool

Non-zero value indicates error code, or zero on success.

set_current_dir(current_dir, n_pulses_per_burst=None, ipi=None, baratio=None, get_response=False)

Sets the current direction.

Example

import magicpy as mp
stim = mp.MagVenture(portid="/dev/ttyUSB1", ttl_port=0)
stim.connect()
stim.set_current_dir('Normal')  # set current dir to normal direction. Slow, because other params are read.
stim.set_current_dir('Normal', 2, 10, 1)  # Faster, because we don't read anything from stimulator device.

Parameters

current_dirstr

Current direction of the stimulator. One of ['Normal', 'Reverse'].

n_pulses_per_burstint, optional

Biphasic pulses (= burst) per trigger in. One of [2, 3, 4, 5].

ipiint, optional

The inter pulse interval defines the duration between the beginning of the first pulse to the beginning of the second pulse in a burst.

baratioint, optional

When working in Twin Mode, the amplitude of the two pulses A and B are controlled in an adjustable ratio between 0.2-5.0. “Pulse B” is now adjusted to a selected percent ratio proportional to “Pulse A”.

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

set_ipi(ipi, current_dir=None, n_pulses_per_burst=None, baratio=None, get_response=False)

Sets the interpulse interval.

If current_dir, n_pulses_per_burst, or baratio is not set it is read from the stimulator. This takes some time, so better set arguments accordingly.

Parameters

ipifloat

Inter pulse interval in ms, which defines the duration between the beginning of the first pulse to the beginning of the second pulse.

current_dirstr, optional

Current direction of the stimulator. One of ['Normal', 'Reverse'].

n_pulses_per_burstint, optional

Biphasic Burst index in the current status of the device. One of [2, 3, 4, 5].

baratioint, optional

when working in Twin Mode, the amplitude of the two pulses A and B are controlled in an adjustable ratio between 0.2-5.0. “Pulse B” is now adjusted to a selected percent ratio proportional to “Pulse A”.

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device

errorbool

Non-zero value indicates error code, or zero on success.

set_mode(mode, current_dir, n_pulses_per_burst, ipi, baratio=1, get_response=False)

Sets the stimulation mode. This includes current directions, burst_pulses, and others. Note that you can use burst_pulses to send out multiple single pulses as a burst for each trigger-in.

Example

import magicpy as mp
stim = mp.MagVenture(portid="/dev/ttyUSB1", ttl_port=0)
stim.connect()
stim.set_mode('Standard', 'Normal', 2, 10)  # set to 2 pulses per trigger-in with 10 ms interpulse time.

Parameters

modestr

Working mode. One of ['Standard', 'Power', 'Twin', 'Dual'].

current_dirstr

Current direction of the stimulation. One of ['Normal', 'Reverse'].

n_pulses_per_burstint

Biphasic pulses (= burst) per trigger in. One of [2, 3, 4, 5].

ipiint

The inter pulse interval defines the duration between the beginning of the first pulse to the beginning of the second pulse in a burst.

baratioint, default: 1

When working in Twin Mode, the amplitude of the two pulses A and B are controlled in an adjustable ratio between 0.2-5.0. “Pulse B” is now adjusted to a selected percent ratio proportional to “Pulse A”.

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

set_page(page, get_response=False)

Configures the desired page.

Parameters

pagestr

Which page to configure. One of ['Main', 'Train', 'Trig', 'Config', 'Protocol'].

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

set_train(reprate, n_pulses, n_trains, iti, get_response=False)

Sets train parameters. A train is a sequence of multiple pulses in a specific rate. Multiple trains (of the same type) can be sent successively.

Example

import magicpy as mp
stim = mp.MagVenture(portid="/dev/ttyUSB1", ttl_port=0)
stim.connect()
stim.set_train(10, 5, 1, 1)  # set one 5-pulse 10 Hz train
stim.fire()

Parameters

reprateint

Number of pulses per second.

n_pulsesint

Number of pulses in each train.

n_trains: int

Total amount of trains per sequence.

itiint

Time interval between two trains in seconds. This is the time period between the last pulse in the first train and the first pulse in the next train.

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

set_waveform(waveform, current_dir=None, n_pulses_per_burst=None, ipi=None, baratio=None, get_response=False)

Sets the waveform.

If current_dir, n_pulses_per_burst, ipi, baratios is not set it is read from the stimulator. This takes some time, so better set all arguments accordingly.

Example

import magicpy as mp
stim = mp.MagVenture(portid="/dev/ttyUSB1", ttl_port=0)
stim.connect()
stim.set_waveform('Biphasic')  # set stim to Biphasic and leave all other settings as they are. Slow.
stim.set_waveform('Biphasic', 'Normal', 2, 10, 1)  # set stim to Biphasic without the need to read settings.

Parameters

waveformstr

defines the desired waveform. One of ['Monophasic', 'Biphasic', 'HalfSine', 'BiphasicBurst'].

current_dirstr, optional

defines current direction of the device in the current status. One of ['Normal', 'Reverse'].

n_pulses_per_burstint, optional

Biphasic Burst index in the current status of the device. One of [2, 3, 4, 5].

ipiint, optional

represents Inter Pulse Interval of the current status of the device which defines the duration between the beginning of the first pulse to the beginning of the second pulse.

baratioint, optional

when working in Twin Mode, the amplitude of the two pulses A and B are controlled in an adjustable ratio between 0.2-5.0. “Pulse B” is now adjusted to a selected percent ratio proportional to “Pulse A”.

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.

settrig_chargedelay(trig_in_delay, trig_out_delay, charge_delay, get_response=False)

Sets trigger and charge delay.

Parameters

trig_in_delayint

Trigger-in delay in ms.

trig_out_delayint

Trigger-out delay in ms.

charge_delayint

Time in ms to make the device wait before recharging.

get_responsebool, default: False

Whether to request a response from the stimulator.

Returns

device_responsedict

The response sent back from the device.

errorbool

Non-zero value indicates error code, or zero on success.