Use cases of Axon python API¶
Load Brainvisa¶
The following lines enable to load Brainvisa without the graphical user interface through a python script:
>>> import brainvisa.axon
>>> brainvisa.axon.initializeProcesses()
Loading toolbox ...
Call a process¶
The module brainvisa.processes
manages the processes, pipelines and their execution.
The object brainvisa.processes.ExecutionContext
enables to start a Brainvisa process using the method brainvisa.processes.ExecutionContext.runProcess()
.
When Brainvisa is loaded, a default execution context exists and is returned by the function brainvisa.processes.defaultContext()
The following example will run the process Threshold on an image:
>>> import brainvisa.processes
>>> context = brainvisa.processes.defaultContext()
>>> # Just to get an example data for running the process
>>> from brainvisa.configuration.neuroConfig import getSharePath, bvShareDirectory
>>> import os
>>> example_data = os.path.join(getSharePath(), bvShareDirectory, "anatomical_templates", "MNI152_T1_1mm_brain_mask.nii")
>>> # creating a temporary file for the output
>>> output_data = context.temporary("NIFTI-1 image")
>>> context.runProcess("threshold", image_input=example_data, image_output=output_data, threshold1=100)
Process Threshold started ...
Select a step in a pipeline¶
In a pipeline, some steps may be optional and can be selected or unselected for execution.
It is possible to select or unselect a step of a pipeline before running it through a python script.
A pipeline is a process that have execution nodes. The method brainvisa.processes.Process.executionNode()
returns an brainvisa.processes.ExecutionNode
.
The execution node of the pipeline contains child nodes, the name of these nodes can be obtained with the method brainvisa.processes.ExecutionNode.childrenNames()
.
To get a specific child node, the method brainvisa.processes.ExecutionNode.child()
can be used.
The following examples gets an instance of the convertOldDatabase pipeline and unselects all its steps:
>>> pipeline=brainvisa.processes.getProcessInstance("convertOldDatabase")
>>> nodes=pipeline.executionNode()
>>> nodes.childrenNames()
['ConvertDatabase', 'CheckDatabase', 'CleanDatabase']
>>> nodes.child("ConvertDatabase").setSelected(0)
>>> nodes.child("ConvertDatabase").isSelected()
0
>>> nodes.child("CheckDatabase").setSelected(0)
>>> nodes.child("CleanDatabase").setSelected(0)
The process instance can be given as a parameter for the brainvisa.processes.ExecutionContext.runProcess()
method instead of the process id.
Query a database¶
At Brainvisa startup, an internal database and the database selected in the user’s preferences are loaded.
The list of databases (brainvisa.data.sqlFSODatabase.SQLDatabases
) is stored in the global variable brainvisa.data.neuroHierarchy.databases
.
Each database is an instance of the class brainvisa.data.sqlFSODatabase.SQLDatabase
.
Several methods enable to query a database or a list of databases. The results of queries are generally brainvisa.data.neuroDiskItems.DiskItem
objects. A DiskItem represents data stored in files and indexed in a database with additionnal information.
In the following example, a DiskItem is searched in the databases by filename:
>>> from brainvisa.data.neuroHierarchy import databases
>>> from brainvisa.data.neuroDiskItems import DiskItem
>>> item = databases.getDiskItemFromFileName(example_data)
>>> isinstance(item, DiskItem)
True
>>> item.type
<anatomical Mask Template>
>>> item.format
'NIFTI-1 image'
Here is a request for all DiskItems of type “Model graph” with the value of side attribute is “left”:
>>> items = databases.findDiskItems({"_type" : "Model graph", "side": "left"})
>>> items
<generator object ...>
>>> model_filename = os.path.normcase(items.next().fileName())
>>> model_filename.startswith(os.path.normcase(os.path.join(getSharePath(), bvShareDirectory, "models")))
True
The object brainvisa.data.readdiskitem.ReadDiskItem
enables to search for an existing DiskItem in the databases using the method ReadDiskItem.findValue()
. If the request is not precise enought and several DiskItems match, the method returns nothing.
>>> from brainvisa.data.readdiskitem import ReadDiskItem
>>> rd=ReadDiskItem("Model graph", "Graph and Data")
>>> rd.findValue({"side" : "left"})
>>> model = rd.findValue({"side" : "left", "sulci_database" : "2001"})
>>> os.path.normcase(model.fileName()).startswith(os.path.normcase(os.path.join(getSharePath(), bvShareDirectory, "models")))
True
The object brainvisa.data.writediskitem.WriteDiskItem
enables to create new DiskItems to write output data according to Brainvisa hierarchy of directories.
>>> from brainvisa.data.writediskitem import WriteDiskItem
>>> wd=WriteDiskItem("Raw T1 MRI", "NIFTI-1 image")
>>> item=wd.findValue({"protocol" : 'test', "subject" : "mysubject"})
Quit Brainvisa¶
The function brainvisa.axon.processes.cleanup()
should be called at the end of the script to quit properly Brainvisa.
>>> brainvisa.axon.cleanup()