brainvoyagertools

BrainVoyager Tools

An object-oriented approach to create, read and write common plain-text BrainVoyager input formats with Python.

Currently supported:

• .ctr
• .mdm
• .prt
• .sdm
• .voi

Installation

BrainVoyager Tools can be easily installed with pip:

pip install brainvoyagertools

Usage

ctr

Build a contrast definition from scratch:

from brainvoyagertools import ctr

contrasts = ctr.ContrastsDefinition()
contrasts.add_contrast(ctr.Contrast("All vs. Baseline", [1, 1, 0]))
contrasts.add_contrast(ctr.Contrast("House vs. Faces", [1, -1, 0]))
contrasts.save("contrasts.ctr")

Add contrasts to contrast definition file:

from brainvoyagertools import ctr

contrasts = ctr.ContrastsDefinition(load="contrasts.ctr")
contrasts.add_contrast(ctr.Contrast("Faces vs. Houses", [-1, 1, 0]))
contrasts.save("contrasts2.ctr")

mdm

Build a design matrix from scratch:

from brainvoyagertools import mdm

design = mdm.DesignMatrix()
design.add_study(mdm.Study("path/to/MyStudy1.vtc", "path/to/MyStudy1.sdm")
design.add_study(mdm.Study("path/to/MyStudy2.vtc", "path/to/MyStudy2.sdm")
design.add_study(mdm.Study("path/to/MyStudy3.vtc", "path/to/MyStudy3.sdm")
design.add_study(mdm.Study("path/to/MyStudy4.vtc", "path/to/MyStudy4.sdm")
design.add_study(mdm.Study("path/to/MyStudy5.vtc", "path/to/MyStudy5.sdm")
design.add_study(mdm.Study("path/to/MyStudy6.vtc", "path/to/MyStudy6.sdm")
design.add_study(mdm.Study("path/to/MyStudy7.vtc", "path/to/MyStudy7.sdm")
design.add_study(mdm.Study("path/to/MyStudy8.vtc", "path/to/MyStudy8.sdm")
design.add_study(mdm.Study("path/to/MyStudy9.vtc", "path/to/MyStudy9.sdm")
design.add_study(mdm.Study("path/to/MyStudy10.vtc", "path/to/MyStudy10.sdm")
design.rfx_glm = True
design.transformation = 'z'
design.separate_predictors = True
design.save("design.mdm")

Also works for MTC data:

from brainvoyagertools import mdm

design = mdm.DesignMatrix()
design.add_study(mdm.Study(["path/to/MyStudy1.ssm", "path/to/MyStudy1.mtc"], "path/to/MyStudy1.sdm")
design.add_study(mdm.Study(["path/to/MyStudy2.ssm", "path/to/MyStudy2.mtc"], "path/to/MyStudy2.sdm")
design.add_study(mdm.Study(["path/to/MyStudy3.ssm", "path/to/MyStudy3.mtc"], "path/to/MyStudy3.sdm")
design.save("design2.mdm")

prt

Build a stimulation protocol from scratch:

from brainvoyagertools import prt

protocol = prt.StimulationProtocol(experiment_name="MyExperiment")
protocol.add_condition(prt.Condition("Rest", [[x+1,x+8] for x in range(1,80,16], colour=[255,0,0]))
protocol.add_condition(prt.Condition("Task", [[x+1,x+8] for x in range(8,80,16], colour=[0,255,0]))
protocol.save("MyExperiment.prt")

Change time units to milliseconds and add condition to other protocol:

from brainvoyagertools import prt

protocol = prt.StimulationProtocol(load="MyExperiment.prt")
protocol.convert_to_msec(tr=2000)
protocol2 = prt.StimulationProtocol(experiment_name="MyExperiment2", time_units="msec")
protocol2.add_condition(prt.conditions[-1])
protocol2.save("MyExperiment2.prt")

Add combination of conditions into new protocol:

from brainvoyagertools import prt

protocol = prt.StimulationProtocol(load="MyExperiment.prt")
protocol2 = prt.StimulationProtocol(experiment_name="MyExperiment3"
protocol2.add_condition(protocol.condition[0] + protocol.conditions[1])
protocol2.save("MyExperiment3.prt")

sdm

Build a design matrix from scratch:

from brainvoyagertools import sdm

design = sdm.DesignMatrix()
design.add_predictor(sdm.Predictor("FirstHalf", 100*[1] + 100*[0], colour=[255,0,0]))
design.add_predictor(sdm.Predictor("SecondHalf", 100*[0] + 100*[1], colour=[0,255,0]))
for p in design.predictors:
    p.convolve_with_hrf(tr=2000)
design.save("design.sdm")

Add z-transformed motion regressors, their first and second derivatives, and a constant:

from brainvoyagertools import sdm

design = sdm.DesignMatrix(load="design.sdm")
motion = sdm.DesignMatrix(load="3DMC.sdm")
for p in motion.predictors:
    p.ztransform()
    design.add_confound_predictor(p)
    design.add_confound_predictor(p.get_derivative(1))
    design.add_confound_predictor(p.get_derivative(2))
design.add_constant()
design.save("design_and_motion.sdm")

Define predictors from a prt file:

from brainvoyagertools import prt, sdm

protocol = prt.StimulationProtocol(load="protocol.prt")
design = sdm.DesignMatrix()
design.define_predictors(protocol, data_points=400, tr=2000)
design.add_constant()
design.save("design.sdm")

voi

Save a single a VOI with three coordinates :

from brainvoyagertools import voi

vois = voi.VOIsDefinition(reference_space="MNI")
vois.add_voi(voi.VOI("VOI_1", [[15, 30, 40], [16, 30, 40]]
vois.save("my_voi.voi")