ClarityViz Tutorial

Overview

claritybase: module loads all the initial img files, applies local histogram equilization, and generates a csv file for the points and enables plot generation and graphml generation
densitygraph: module does takes the graphml file generated from clarityviz and performs all the necessary caluclations and generates a graph with a color scheme representative of node density
atlasregiongraph: module takes a csv and generates a graph color coded by region according to the atlas
- NOTE: the atlasregiongraph module is still currently in development and is not currently functional

I) Using claritybase

claritybase is used to produce the essential files. After you perform these operations, you can choose to choose to do the calculations and or display which ever graphs you want.

1) First you import the claritybase module and then you specify the token of the img file you're working with and the optional source directory.

If you're in the same directory as the img file you're working with, you only need to pass in the token.
This creates a directory with the same name as the given token in which all the intermediate and final result files will be output to.



In [ ]:

    
from clarityviz import claritybase

token = 'Fear199'
source_directory = '/cis/home/alee/claritycontrol/code/data/raw'

# Initialize the claritybase object, the initial basis for all operations.
# After you initialize with a token and source directory, a folder will be created in your current directory
# with the token name, and all the output files will be stored there.
cb = claritybase(token, source_directory)

2) local histogram equilization

local histogram equilization is the process of enhancing low contrast images, and makes the pixel values easier to process
after you apply localeq, load the nii file generated from it



In [ ]:

    
cb.applyLocalEq()

cb.loadGeneratedNii()

3) Filter out the noise in the image to get only the points we actually want

for .calculatePoints:
- threshold is the threshold of samples to filter out based on fraction of the maximum intensity.
  - e.g. let threshold = 0.9, if the sample's intensity is less than 0.9 * (maximum intensity) then it will be filtered out
- sample is the fraction of the total number of samples to include in the graph.



In [ ]:

    
cb.calculatePoints(threshold = 0.9, sample = 0.1)

4) Now that you've calculated the points, you have options.

generate_plotly_html() lets you generate your first graph, a basic plotting of the points using plotly. Fancier graphs come later, after edges are calculated and some other operations are performed.
savePoints() saves the points to a csv file
plot3d() calculates the edges between the nodes in the graph
graphmlconvert() uses the nodes and edges files generated in plot3d() to create a graphml file that can later be used for more advanced graphs



In [ ]:

    
cb.generate_plotly_html()

# savePoints generates the csv file of all the points in the graph.
cb.savePoints() 

# plot3d calculates all the edges between the nodes.
cb.plot3d()

# graphmlconvert() creates a graphml file based on the nodes and edges file generated in plo3d.
cb.graphmlconvert()

Sample output from generate_plotly_html():

Fear199: https://neurodatadesign.github.io/seelviz/reveal/html/clarityvizhtmls/Fear199plotly.html

Cocaine174: https://neurodatadesign.github.io/seelviz/reveal/html/Cocaine174localeq.html

Control181: https://neurodatadesign.github.io/seelviz/reveal/html/Control181localeq.html

After you finish generating all the files from claritybase, you have two options for more advanced analysis: the densitygraph module and the atlasregiongraph module

II) Using densitygraph

Once the graphml file is generated with graphmlconvert(), you can use the densitygraph module. The density graph module is used to visualize the density of nodes in the graph, i.e. the density of neurons, in a colored fashion.



In [ ]:

    
from clarityviz import densitygraph

# Uses the same token before, must be in the same directory as before.
dg = densitygraph(token)

# generates a 3d plotly with color representations of density
dg.generate_density_graph()

# generates a heat map, essentially a legend, telling how many edges a certain color represents,
# with number of edges representing how dense a certain node clustering may be.
dg.generate_heat_map()

Sample output from generate_density_graph():

Fear199: https://neurodatadesign.github.io/seelviz/reveal/html/clarityvizhtmls/Fear199_density.html

Cocaine174: https://neurodatadesign.github.io/seelviz/reveal/html/graphmlhtmls/Cocaine174localeq.5000.graphml.html

Sample output from generate_heat_map():

Fear199: https://neurodatadesign.github.io/seelviz/reveal/html/clarityvizhtmls/Fear199heatmap.html

Cocaine174: https://neurodatadesign.github.io/seelviz/reveal/html/graphmlhtmls/Cocaine174localeq.5000.graphmlheatmap.html

III) Using atlasregiongraph

Once the csv file is generated with savePoints(), we can use the atlasregiongraph module. This module creates a graph color coded to the different regions of the brain according to the atlas.



In [ ]:

    
from clarityviz import atlasregiongraph

regiongraph = atlasregiongraph(token)

regiongraph.generate_atlas_region_graph()