README

# brainCOLOR project

The brainCOLOR project ("Collaborative Open Labeling Online Resource")
started as a group of people interested in manual anatomical labeling of 
human brain MRI data, and the visual presentation of labeled brain images.

The brain labeling protocols and optimal colormaps can be seen on the web page:
https://mindboggle.info/braincolor/

Extra files related to protocol development are here: 
https://www.synapse.org/#!Synapse:syn3268020

# Software

braincolors.py takes in an Excel file with an adjacency matrix, 
where each value signifies adjacency between regions, and outputs the 
optimal assignment of colors to each group of regions on the command line, 
where optimal means maximally distinguishable colors within a neighborhood 
of similar colors in a color space:
 
1. Read in an Excel file with a binary (or weighted) adjacency matrix,
   where each row or column represents a region, and each value signifies 
   whether (or the degree to which) a given pair of regions are adjacent.
   Example: (a) column 0 = region abbreviation
            (b) column 1 & row 0 = full region name
            (c) column 2 = group number (each region is assigned to a group)
2. Create a colormap for the number of regions, with hues that are sampled
   from the (approx. perceptually uniform) CIELch cylindrical color space.
3. Convert the matrix from #1 to a graph, where each node represents a region
   and each edge represents the adjacency value between its connected nodes.
4. Break up the graph in #3 into subgraphs, where each subgraph represents
   a group of adjacent regions (assigned the same group number in #1c).
5. Compute every permutation of colors for the nodes of each subgraph in #4,
   with adjacent colors in the color space.
6. Assign each edge in each subgraph the value of the color difference 
   between the colors assigned to its pair of connected nodes in #5.
   (Multiply the connection matrix for each subgraph by
    the color difference matrix for each permutation.)
7. Find the optimal colors for the subgraph nodes that maximizes the sum 
   of the edge values from #6.
8. Plot the colormap, the whole graph, or individual colored subgraphs.
9. Optional: Replace RGB colors in an XML file.  
   The program recolor_eps.[csh,py] takes the output XML to recolor EPS files.
10. Optional: Use make_regiona_adjacency_matrix.py to help make input file.

(c) Copyright 2010 . arno klein . arno@binarybottle.com . MIT license