This repository generates a nonnegative connectome from an unconstrained connectome approximation generated by the lowrank_connectome repository created by kuerschner (See the link at the end of this section). The initial solution can be constructed as a test, top-view, or flatmap connectome and passed to nonnegative_converter.py, which constructs the nonnegative version of this solution.
After nonnegative_converter.py returns a solution, its most prominent factors can be visualized using plot_svectors.py for top-view or flatmap solutions and plot_test_svectors.py for test solutions. The file plot_test_heatmap.py uses the function create_heatmap_from_solution() to display projections for a given test solution.
To find an optimal value of lambda plot_l_curve.py can be used to create a loss and regularization L-curve for various solutions of one type, it also has the option of creating a log-scale L-curve. Also, Relative RMSE curves can be made for multiple solutions of the same type (test, top-view, or flatmap). This begins with using relative_rmse.py to calculate the relative RMSE for each solution, then plot_rmse.py creates figures by using this data.
Additionally, costs for various ranks can be measured using final_cost_by_rank.py, which will take a series of solutions from one type with different ranks and plot their final costs. Note that final_cost_by_rank requires both the nonnegative and related unconstrained solutions. The file init_quality.py constructs a graph comparing refinement iterations with the total runtime.
https://gitlab.mpi-magdeburg.mpg.de/kuerschner/lowrank_connectome.git
The lowrank_connectome repository should be located beside this repository as shown below:
...
├── lowrank_connectome/
└── nonnegative_connectome/
This file provides a wrapper to run matlab code in lowrank_connectome/matlab/. example invocation:
./run_matlab.sh test_allvis_completion
https://github.com/harrispopgen/mushi
Computes nonnegative connectome solution using greedy solution.
Arguments:
- testname: 'test', 'top_view', or 'flatmap'
- solution_name: filename of unconstrained solution
- data_directory: path to folder where output data is stored
- images_directory: path to folder where output images are stored (test heatmaps)
- output_suffix: String added to the output solution's filename
- init_max_outer_iter: Number of alternating iterations in initialization refinement
- init_max_inner_iter: Number of updates on each factor before alternating in initialization refinement
- init_max_line_iter: Maximum number of line-search iterations in initialization refinement
- max_outer_iter: Number of alternating iterations
- max_inner_iter: Number of updates on each factor before alternating
- max_line_iter: Maximum number of line-search iterations
Flags:
- from_lc: look for unconstrained solution in ../lowrank_connectome/data rather than /data
- tol: PGD stopping criteria tolerance
- init_tol: PGD stopping criteria tolerance for initialization refinement
- alt_tol: tolerance for alt_acc_prox_grad
- lamb: value of lambda
- -load_lamb: load lambda value from unconstrained solution in ../lowrank_connectome/matlab/solution
Example invocation:
python3 nonnegative_converter.py top_view top_view_solution data/ images/ nonneg_top_view 1000 50 20 1000 50 20 -init_tol 1e-6 -tol 1e-7 --load_lamb -from_lc
Visualize dominant singular vectors of flatmap or top_view solution. Based on plot_svectors.m in lowrank_connectome/matlab. used by nonnegative_converter.py
Arguments:
- testname: either 'top_view' or 'flatmap'. Used to locate voxel coordinate mapping
- solution_name: name of .mat solution file to plot
- path_to_solution: path to where solution is located.
- n: number of factors to plot
Flags:
- greedy: Look for solution name in the lowrank_connectome/data/ directory rather than nonnegative_connectome/data/.
- raw: Plot the raw solution, rather than scaled QR decompositions.
example invocation:
python3 plot_svectors.py flatmap flatmap_solution path/to/file/ 6 -nneg
Visualize dominant singular vectors of test solution. Based on plot_svectors.m in lowrank_connectome/matlab. used by nonnegative_converter.py
Arguments:
-
solution_name: name of .mat solution file to plot
-
path_to_solution: path to where solution is located.
-
n: number of factors to plot
-
greedy: Look for solution name in the lowrank_connectome/data/ directory rather than nonnegative_connectome/data/.
-
raw: Plot the raw solution, rather than scaled QR decompositions.
example invocation:
python3 plot_svectors.py test_solution path/to/file/ 6 -nneg
Module to plot test solutions on a heatmap. Used by nonnegative_converter.py
Arguments:
- solution_name: Name of solution to plot
- output_file: Name of file to save heatmap
Module to plot regularization vs cost l-curve of both nonnegative and greedy solutions. Corner of L-Curve represents optimal lambda value.
Arguments:
- testname: Can be 'test', 'top_view' or 'flatmap'. Used to determine where figures are saved.
- solution_name: Name of solutions to plot (Ex. 'test_*.mat')
- path_to_solution: path to where solutions are located.
- title: Title of l-curve (note: title cannot contain spaces)
Flags:
- nneg: Plot the nonnegative solution using proper keywords in data retrieval
Example invocation:
python3 plot_l_curve.py test lambda_test*.mat path/to/solutions/ Unconstrained_Test_L-Curve -nneg
NOTE: For plot_l_curve and plot_error, add the following directories to save images:
... ├── plot ├── data │ ├── lambda_tests │ ├── lambda_tv │ └── lambda_fm ...
Module to plot the relative root mean squared error for various values of lambda.
Arguments:
- testname: 'test', 'top_view' or 'flatmap'. Used to locate relative RMSE values for each solution.
- rmse_vals_file : Name of file containing all relative RMSE values for each solution
- path_to_solution: path to where solutions are located.
- title: Title of figure to be plotted.
Flags:
- nneg: Plot the nonnegative relative RMSE solution.
Example invocation:
python3 plot_rmse.py test_rmse*.mat path/to/solutions/ Relative_RMSE_Nonnegative_Test_Problems -nneg
...
├── plot
│ ├── plots
│ ├── plot_svectors.py
│ ├── plot_test_svectors.py
│ ├── plot_test_heatmap.py
│ ├── plot_l_curve.py
│ └── plot_rmse.py
...
Module to load connectome solutions from .mat files. Used by nonnegative_converter.py, plot_svectors.py, plot_test_heatmap.py
...
├── util
├── load_mat.py
├── math_util.py
└── read_hyperparameters.py
Module to plot the total costs for solutions of different ranks.
Arguments:
- testname: either 'top_view' or 'flatmap'.
- directory_path: path to where solutions are located.
Example invocation:
python3 final_cost_by_rank.py top_view /path/to/solutions
Module to plot the average total runtime in comparison to the number of refinement iterations made.
Arguments:
- suffixes: The total number of tests completed (each test contains solutions with refinements 0-160) .
- directory_path: path to where solutions are located.
Example invocation:
python3 final_cost_by_rank.py top_view /path/to/solutions
...
├── visualizations
├── final_cost_by_rank.py
└── init_quality.py