.. _scil_viz_connectivity:

scil_viz_connectivity
=====================

::

	usage: __main__.py [-h] [--labels_list LABELS_LIST]
	                   [--reorder_txt REORDER_TXT] [--lookup_table LOOKUP_TABLE]
	                   [--name_axis] [--axis_text_size X_SIZE Y_SIZE]
	                   [--axis_text_angle X_ANGLE Y_ANGLE] [--colormap COLORMAP]
	                   [--display_legend] [--legend_min_max MIN MAX]
	                   [--write_values FONT_SIZE DECIMAL] [--histogram FILENAME]
	                   [--nb_bins NB_BINS] [--exclude_zeros]
	                   [--chord_chart FILENAME]
	                   [--percentile_threshold PERCENTILE_THRESHOLD]
	                   [--angle_threshold ANGLE_THRESHOLD] [--alpha ALPHA]
	                   [--text_size TEXT_SIZE] [--text_distance TEXT_DISTANCE]
	                   [--log] [--show_only] [-v [{DEBUG,INFO,WARNING,ERROR}]]
	                   [-f]
	                   in_matrix out_png
	
	Script to display a connectivity matrix and adjust the desired visualization.
	Made to work with scil_tractogram_segment_connections_from_labels and
	scil_connectivity_reorder_rois.
	
	This script can either display the axis labels as:
	- Coordinates (0..N)
	- Labels (using --labels_list)
	- Names (using --labels_list and --lookup_table)
	Examples of labels_list.txt and lookup_table.json can be found in the
	freesurfer_flow output (https://github.com/scilus/freesurfer_flow)
	
	If the matrix was made from a bigger matrix using
	scil_connectivity_reorder_rois, provide the text file(s), using
	--labels_list and/or --reorder_txt.
	
	The chord chart is always displaying parting in the order they are defined
	(clockwise), the color is attributed in that order following a colormap. The
	thickness of the line represent the 'size/intensity', the greater the value is
	the thicker the line will be. In order to hide the low values, two options are
	available:
	- Angle threshold + alpha, any connections with a small angle on the chord
	    chart will be slightly transparent to increase the focus on bigger
	    connections.
	- Percentile, hide any connections with a value below that percentile
	
	positional arguments:
	  in_matrix             Connectivity matrix in numpy (.npy) format.
	  out_png               Output filename for the connectivity matrix figure.
	
	options:
	  -h, --help            show this help message and exit
	  --log                 Apply a base 10 logarithm to the matrix.
	  --show_only           Do not save the figure, simply display it.
	  -v [{DEBUG,INFO,WARNING,ERROR}]
	                        Produces verbose output depending on the provided level. 
	                        Default level is warning, default when using -v is info.
	  -f                    Force overwriting of the output files.
	
	Naming options:
	  --labels_list LABELS_LIST
	                        List saved by the decomposition script,
	                        must contain labels rather than coordinates (.txt).
	  --reorder_txt REORDER_TXT
	                        File with two rows (x/y) listing the ordering (.txt).
	  --lookup_table LOOKUP_TABLE
	                        Lookup table with the label number as keys and the name as values (.json).
	
	Matplotlib options:
	  --name_axis           Use the provided info/files to name axis.
	  --axis_text_size X_SIZE Y_SIZE
	                        Font size of the X and Y axis labels. [(10, 10)]
	  --axis_text_angle X_ANGLE Y_ANGLE
	                        Text angle of the X and Y axis labels. [(90, 0)]
	  --colormap COLORMAP   Colormap to use for the matrix. [viridis]
	  --display_legend      Display the colorbar next to the matrix.
	  --legend_min_max MIN MAX
	                        Manually define the min/max of the legend.
	  --write_values FONT_SIZE DECIMAL
	                        Write the values at the center of each node.
	                        The font size and the rouding parameters can be adjusted.
	
	Histogram options:
	  --histogram FILENAME  Compute and display/save an histogram of weights.
	  --nb_bins NB_BINS     Number of bins to use for the histogram.
	  --exclude_zeros       Exclude the zeros from the histogram.
	
	Chord chart options:
	  --chord_chart FILENAME
	                        Compute and display/save a chord chart of weigth.
	  --percentile_threshold PERCENTILE_THRESHOLD
	                        Discard connections below that percentile.[0]
	  --angle_threshold ANGLE_THRESHOLD
	                        Angle below that theshold will be transparent.
	                        Use --alpha to set opacity. Value typicallybetween 0.1 and 5 degrees. [1]
	  --alpha ALPHA         Opacity for the smaller angle on the chord (0-1). [0.9]
	  --text_size TEXT_SIZE
	                        Size of the font for the parcels name/number [10].
	  --text_distance TEXT_DISTANCE
	                        Distance from the center so the parcels name/number do not overlap 
	                        with the diagram [1.1].
	
	2.2.2