ROOTS: Ruled-Optimum Ordered Tree System

ROOTS is a package designed to take experimentally determined morphometric data and return an artificial neuronal arbor which satisfies the user-defined parameters.

Originally this package was written to aid the construction of biologically realistic neural models for use in computational studies of extracellular electrical stimulation but it can be used for diverse neural modeling problems.

Installation (Recommended) Download the package and while in root directory call:

python setup.py install

or

pip install Roots

The latest version of Roots will always be available through Github rather than PyPI.

Usage

#import roots modules
from roots.core import Roots,Roots_math
from roots.kmd import KMDD
from roots.graphmethods import GraphMethods
from roots.swcToolkit import swcToolkit

#import a few helper libraries
import numpy as np
import random
import os

#generate some random parameters for roots to use
def return_random_params():
	a = random.choice(np.arange(1,3.0,0.25))
	b = random.choice(np.arange(300,475,25))
	c = random.choice(np.arange(1.5,3.0,0.25))
	d = random.choice(np.arange(300,425,25))
	return(a,b,c,d)


#create source point, target points, and pass them to Roots.
#call .grow() method and specify output .swc file to write results to
def make_axon(kmdd=True,outputdir=os.getcwd()):
	targets = np.random.rand(300,3)*100.0
	source_point = list(targets[0])
	targets = [list(item) for item in targets[1:]]
	a,b,c,d = return_random_params()
	if kmdd:
		root = Roots(source_point, targets,np.inf, np.pi/a, b, np.pi/c, d, bnum_limit=np.inf, KMDDproperties=dict(zip(['cluster_reduce','tri_edge_length_max','source','open_points'],[1.0,100,source_point,targets])))
	
	else:
		root = Roots(source_point, targets,np.inf, np.pi/a, b, np.pi/c, d, bnum_limit=np.inf,rel_source_dist=7)
	
	newpnts = root.grow()
	swcname = outputdir+'/root_KMDD.swc'
	swcTool = swcToolkit()
	swcTool.to_swc(root.arbor,swcname) #save axon to swc

Roots() arguments include the following:

source - point from which the tree begins (not a member of open 'points' which is a separate argument)

points - open points through which the tree must grow (does not include 'source')

s_ang - branch extension angle threshold

s_dist - branch extension distance threshold

b_ang - bifurcation angle threshold

b_dist - bifurcation distance threshold

rel_source_dist - (disabled for KMDD mode growing) minimum distance down the active branch on which to find a bifurcation point

KMDDproperties - properties of k-means, delaunay triangulation for 'likely path' sorting for dynamic source updating fibers provided as a dictionary

KMDDproperties:

cluster_reduce - proportion of reduction for k-means clustering (i.e. if cluster_reduce == 0.25 then the number of clusters will equal 25% of the number of open points)

tri_edge_length_max - the meshing distance threshold below which delaunay triangulated edges will be returned (i.e. triangulated edges longer than tri_edge_length_max will be removed from the triangulation)

openpoints - open points to be clustered and meshed (same as ROOTS argument 'points')

source - source point from which a tree will be grown (same as ROOTS argument 'source')

#finally run the make_axon function.
if __name__ == "__main__":
	root = make_axon()

If you use Roots or any part of Roots for your own work, kindly cite:

-Bingham, C. S., Mergenthal, A., Bouteiller, J.-M. C., Song, D., Lazzi, G., & Berger, T. W. (2020). ROOTS: An algorithm to generate biologically realistic cortical axons and an application to electroceutical modeling. Frontiers in Computational Neuroscience. In print.

-Bingham, C. S., Bouteiller, J. M. C., Song, D., & Berger, T. W. (2018, July). Graph-Based Models of Cortical Axons for the Prediction of Neuronal Response to Extracellular Electrical Stimulation. In 2018 40th Annual International Conference of the IEEE Engineering in Medicine and Biology Society (EMBC) (pp. 1380-1383). IEEE.