Analytic Tools

We regularly use a number of analytic tools for computational neurosciences in our research. The codes for these analytic tools were developed and written by Stefan Fuertinger, PhD, and Joel Zinn, BA. The codes are open source software tools in Python. We are offering them as a free resource for the neuroscience community. All routines require NumPy, SciPy, and Matplotlib to be installed—some functions optionally use Weave for embedded C++ code. 

Brain network analysis
Routines to construct and analyze brain networks can be found under Network Tools. The Python module nws_tools.py comprises all routines presented in this section. 

Neural simulations
All codes necessary to run simulations using the neural population model are listed in Neural Population Model. Due to the significant computational load for large-scale neural population simulations using a multi-compartment stochastic model, the module requires the installation of Cython.

Applications Routines Brief Description 
Network Tools Network Metrics Compute simple graph metrics
  Correlation Matrix Construction      Correlate time-series
  Network Processing Perform thresholding, calculate group-averaged networks, and construct random graphs
  Visualization Plot networks in three dimensional space
  Miscellaneous Some handy tools for dealing with graphs
Neural Population Model      Simulation Collection of Python routines/Cython extensions to run a simulation
  Tools Routines to incorporate coupling matrices and brain parcellations into the model


License and Contact

All codes are free software. You may redistribute and/or modify them under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 and higher. The codes are distributed 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 receive a copy of the GNU General Public License along with each module. Alternatively, you may write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA, or visit their website gnu.org/licenses

If you have questions or comments, please email Stefan Fuertinger, PhD



Network Tools

This Python module provides tools for the creation, processing, analysis, and visualization of functional brain networks (i.e. weighted, undirected networks). To use the module in Python: 
  • Download nws_tools.py 
  • Navigate to the directory you downloaded the file to
  • Open Python (we recommend using an iPython shell)
  • Type "import nws_tools as nwt" to import the network tools module
  • Then type "nwt.get_corr?" in iPython to display help for the function get_corr


Network Metrics

Three basic routines are provided to compute nodal strength, degree, and connection density of an undirected graph. Note that similar functions are part of the Brain Connectivity Toolbox for Python (bctpy).


Functions

For convenience, the routines are included in nws_tools.py in case the user does not want to install bctpy.

 Resources1  

strengths_und(CIJ): Compute nodal strengths in an undirected graph

Nodal strength is the sum of connected edge-weights
 
 Resources2

degrees_und(CIJ): Compute nodal degrees in an undirected graph

Nodal degree is the number of connected edges
 
 Resources3

density_und(CIJ): Compute the connection density of an undirected graph

Connection density is the ratio of actual to possible edges
 


Correlation Matrix Construction

These routines may be used to generate, process, and visually inspect correlation matrices based on different notions of statistical dependence. 


Functions

  • get_corr(txtpath[, corrtype, sublist]): Compute pair-wise statistical dependence of time-series 
  • mutual_info(tsdata[, n_bins, normalized, fast, norm_ts]): Calculate the (normalized) mutual information matrix at zero lag 
  • corrcheck(*args, **kwargs): Sanity checks for statistical dependence matrices (Pearson or NMI) 
  • rm_negatives(corrs): Remove negative entries from correlation matrices 
  • rm_selfies(conns): Remove self-connections from connection matrices 
  • issym(A[, tol]): Check for symmetry of a NumPy 2d array A

Resources4

Exemplary output of the routine corrcheck showing two correlation matrices.



Network Processing 

This module provide means average and threshold networks and generate a number of null model graphs. 


Functions

  • get_meannw(nws[, percval]): Helper function to compute group-averaged networks 
  • thresh_nws(nws[, userdens, percval, force_den, span_tree]): Threshold networks based on connection density 
  • generate_randnws(nw[, M, method, rwr, rwr_max]): Generate random networks given a(n) (un)signed (un)weighted (un)directed input network 


Visualization

These routines may be useful for plotting 3-D networks using either Mayavi or Matplotlib.


Functions


 Two functional brain networks
shownet(A, coords[, colorvec, sizevec, …]): Plots a 3D network using Mayavi 
Two functional brain networks generated using shownet
 
 Cortical subnetwork
show_nw(A, coords[, colorvec, sizevec, …]): Matplotlib-based plotting routine for 3d networks 
Cortical subnetwork visualized using show_nw
 
csv2dict(csvfile): Reads 3D nodal coordinates of from a csv file into a Python dictionary



Miscellaneous 

These are functions that may come in handy when working with networks and large data files. 


Functions

  • normalize(arr[, vmin, vmax]): Re-scales a NumPy 
  • ndarray hdfburp(f): Pump out everything stored in a HDF5 file
  • printdata(data, leadrow, leadcol[, fname]): Pretty-print/-save array-like data 
  • myglob(flpath, spattern): Return a glob-like list of paths matching a path-name pattern BUT support fancy shell syntax 
  • img2vid(imgpth, imgfmt, outfile, fps[, …]): Convert a sequence of image files to a video using ffmpeg 



Neural Population Model

Based on model proposed by Breakspear et al. (2003), we have developed a neural population model, which incorporates dopmainergic neurotransmission during complex voluntary behaviors, such as speech production.

The Python modules below may be used to simulate neural population dynamics. In order to run the population model:

  • Download model_codes.zip 
  • Unzip the archive and navigate to the location of the extracted files 
  • Open a terminal and type make in this directory
This will build a library called the_model. To run the model, a list of brain areas as well as a coupling weight matrix defining inter-regional connectivity is needed. 

Note: Currently, only symmetric coupling matrices are supported. Functionality to handle non-symmetric matrices will be added in a future release of the software. 

To run the model:

  • Open iPython and type import sim_tools as smt to import the simulation module
  • Use smt.run_model(V0,Z0,DA0,'rest','sim_rest.h5') to start a simulation
For more information, refer to the documentation of run_model the Simulation section below.


 

Simulation 

All routines below are part of the module sim_tools.py. The following functions may be helpful to run the compiled neural population model. 

  • Download model_codes.zip

Functions

  • run_model(V0, Z0, DA0, task, outfile[, C, …]): Run a simulation using the neural population model 
  • make_bold(fname[, stim_onset]): Convert raw model output to BOLD signal 
  • plot_sim(fname[, names, raw, bold, figname]): Plot a simulation generated by run_model

Resources7

Exemplary output of the neural population model compared to real BOLD signal.


Tools 

All routines below are part of the module sim_tools.py. These functions proved to be very useful when working with different coupling matrices and brain parcellations. 

  • Download model_codes.zip

Functions

  • show_params(fname): Pretty-print all parameters used in a simulation 
  • make_D(target, source, names[, values]): Create matrix of afferent/efferent dopamine regions in the model 
  • regexfind(arr, expr): Find regular expression in a NumPy array