Generating the XML plugin file¶

Installing the package will bring you a script generate_brain_connectivity_plugin that will be used for generating a plugin file in the .xml format. This little tool converts the entry point of the plugin into an XML file that can be installed/registered into Paraview.

To call the tool, run the following from the command line terminal:

generate_brain_connectivity_plugin mpi_brain_plugin.xml

Registering the XML plugin file¶

This plugin should then be imported into Paraview

1. Open the menu from Tools > Manage Plugins:

   

2. On the custom filter window, click on Load New:

   

3. Select the .xml file that you generated earlier, make sure that the file filter of the selection dialog shows .xml:

   

4. You should then see the plugin on the list of plugins, make sure the plugin is loaded. You may check the autoload option for loading the plugin the next time you start Paraview.

   

Platform specific installation details¶

cd <vtk-source-folder>
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=~/usr/local -DVTK_WRAP_PYTHON=ON ..
make -j 4
make install

virtualenv venv_paraview
. venv_paraview/bin/activate
pip install -r requirements.txt
pip install .
pip install ipython

# adding VTK to the list of paths of the virtualenv
USER_SITE=$(python -c "import os; print os.environ['VIRTUAL_ENV']")
echo "/Users/<myself>/usr/local/lib/python2.7/site-packages/" >> $USER_SITE/lib/python2.7/site-packages/vtk.pth

export DYLD_LIBRARY_PATH=/Users/<myself>/usr/local/lib/:$DYLD_LIBRARY_PATH
python -c "import vtk; print 'success!'"
ipython
> import vtk

export DYLD_LIBRARY_PATH=/Users/<myself>/usr/local/lib/:$DYLD_LIBRARY_PATH
export PYTHONPATH=/Users/<myself>/usr/local/lib/python2.7/site-packages/:$PYTHONPATH

generate_brain_connectivity_volume_file id1090_timestep.nii nii-volume-2

Clustering with kMeans¶

The clustering of edges is performed with the kmeans algorithm.

The version of this algorithm currently being in use within the plugin is implemented in a naive way in Python, using a distance function that is specific to the needs of the visualization. Accelerated algorithms exist such as the [Elkan] and that involves a lower number of computations and distance evaluations.

The hierarchical version of the kMeans runs the kMeans at each level of the hierarchy, and has also a complexity similar to the kMeans multiplied by the number of hierarchy levels.

Since the clustering may take some time to converge, a script accessible after the installation of the package in a virtual environment is provided.

mpi_is_sw.brain_connectivity.naive_k_means¶

This module defines the k-means clustering used for creating clusters of edges and summarized information for the set of edges. The implementation is pure python and is slow, hence the name naive.

convergent(old_means, new_means)¶

Returns True if the two sets of edges are close enough.

This would indicate that the convergence of the k-means clustering has been reached.

create_flip_map(distances)¶

Compares two arrays column-wise and returns an array of integer indices denoting whether the first or second array contains the smaller value.

Parameters:	distances – a matrix of shape (2, k, n) where k is the number of means and n is the number of edges each mean is compared to
Returns:	an array of integer values of 0, 1

distances(edges, means)¶

Computes the distance between two set of edges.

The distance is summing the distance between the end points of two edges, irrespective of the orientation of those edges.

The fixed set is called means. For each edge returns the index of the closest mean edge, as well as a boolean value marking whether or not edge_i has been closer to the flipped or original version of the mean in question.

fetch_edges(mean_index, edges, means)¶

Returns a matrix containing all edges assigned to a mean_index.

init_centroids(k, edges)¶

Returns k centroids by randomly sampling data points out of a given set of edges, as a matrix of shape (k, n).

Parameters:	k – an integer value denoting the number of means/clusters. edges – a matrix of edges to sample the initial means from
Returns:	a matrix of k data points from the original edges matrix
Raises:	AssertError if k > edges.shape[0]

kmeans(k, edges, max_iterations=100, verbose=False, callback=None)¶

Returns k-means clustering of a set of edges.

This algorithm clusters the set of edges in k clusters, using the metric given by the distance() function.

Parameters:	k – an integer value denoting the number of means/clusters edges – a matrix of n-dimensional datapoints max_iterations – an integer value that defines the maximum number of iterations should convergence not be reached callback – a callable object taking two arguments: the centroids and the labels. The callback is called every 100 iterations and may be used for checkpointing.
Returns:	a 2-uples where the first element is a matrix of shape (k, n) containing the centroids/means of the clustered dataset, and the second element of the tuple being the assignments/labels of the edges given as argument to the indexed centroids.

label_elements(distances)¶

reorder_edges(edges, flip_map)¶

Combines an array edges of datapoints and its flipped copy into a single array with length equal to the length of the original edges. Datapoints are chosen based on a boolean array flip_map.

Parameters:	edges – a matrix of shape (n, 6) flip_map – an integer/boolean array of length n
Returns:	a matrix of shape (n, 6)

update_centroids(edges, labels, means, flip_map)¶

Returns an updated matrix of means. For each mean, sets it to the mean of all points assigned to it.

Parameters:	edges – a matrix of n-dimensional edges to compute clusters of labels – a matrix of shape edges.shape with integer values in the half-open interval [0, k) means – a matrix of shape (k, 1, n) where k is the number of datapoints and n is the length of a single datapoint
Returns:	a matrix of shape (k, 1, n), containing the updated means

utils.generate_from_nifty¶

Provides tools for constructing intermediate files needed for the visualization.

The functions provided here are:

• the transformation of a Nifti indicator file to a set of edge coordinates. Those edges will be used by the visualization algorithm
• the transformation of the Nifti volumetric data to a VTK image that can be rendered inside Paraview.

The edge file requires:

• a Nifti volume that indicates the end points on a grid, and
• a CSV file that contains the topology that connects the previous end points. This CSV file should have two columns and a number of rows identical to the number of edges. Each column entry is an index to a coordinate that is extracted from the previous Nifti file. The other columns are ignored.

generate_cluster_file(mesh_file, edge_file, number_of_clusters, output_file, max_iterations=100)¶

Convenience function for running the clustering on a set of edges

Parameters:	mesh_file – the mesh that will be used for centering the data and making it isotropic edge_file – the file containing the edges as computed from generate_edge_file() number_of_cluster – the number of desired clusters output_file – the file in which the results of the clutering will be done max_steps – maximum number of iterations for the kmeans

Note

The plugin will not know if the files and parameters are consistent. If you provide a file name that contains the computation of the centroids for a specific edge file, and the edge file is incorrectly given to the plugin, the plugin will be unable to check.

generate_edge_file(csv_file_path, nifti_edge_file_path, output_file)¶

Convenience script for creating an edge file

Parameters:	nifti_edge_file_path – the path containing the nifti volume indicating the locations of the edge end points csv_file_path – the file containing the topology output_file – the output file in a numpy array format

See also

file_ops.assemble_edges()

generate_edge_volume_file(nifti_edge_file_path, output_file)¶

Convenience script for creating a volume locating all edges end-points

Parameters:	nifti_edge_file_path – the path containing the nifti volume indicating the locations of the edge end points csv_file_path – the file containing the topology output_file – the output file in a VTK file format

See also

file_ops.assemble_edges()

See also

file_ops.save_points_to_vtk_array()

generate_volume_file(nifti_volumetric_file_path, output_file)¶

Convenience script for creating a VTK compatible volume image file.

utils.generate_plugin_xml¶

Provides tools for generating the XML Paraview plugins.

generatePythonFilterFromFiles(script_file, output_file, function_name=None)¶

Generates an XML plugin file for Paraview from Python source file

Parameters:	function_name – the name of the function containing the plugin entry point. Defaults to RequestData

generate_plugin_after_install(output_file)¶

Utility for generating the plugin XML file after the package has been successfully installed

This utility uses the plugin.py file as an entry point. This is suitable for running in Paraview in an environment that is not a virtual environment. It requires a Paraview installation of the plugin using pvpython. See the documentation for more details.

generate_plugin_in_virtualenv_after_install(output_file)¶

Utility for generating the plugin XML file after the package has been successfully installed

This utility uses the plugin.py file as an entry point. This is suitable for running in Paraview in an environment that is not a virtual environment. It requires a Paraview installation of the plugin using pvpython. See the documentation for more details.