Merge pull request #53 from CSDLLab/2021_0607_add_config_help

add config documentation

Author: HanZhaang

config/.config_documentation.md

@@ -0,0 +1,49 @@
+## How to set configs
+### 1. SSD metric
+|parameter|type|description|
+|---|:---:|---|
+|threshold_mode|int|mode(1 or 2):<br />1 means static threshold, final threshold equal to ssd_threshold.<br />2 means dynamic threshold, final threshold equal to ssd_threshold * src_node.radius|
+|ssd_threshold|float| For each node in gold standard tree, ssd find its closest node in test tree. If the distance of these two nodes is less than ssd_threshold, this node is successfully reconstructed and it will contribute to recall or precision, otherwise the distance will be contribute to ssd score. |
+|up_sample_threshold|float|up sample rate of gold standard and test test tree. Smaller sample rate threshold means higher sample rate, denser upsampled tree. 
+|scale|tuple(1*3)| scaling of gold and test tree in x,y,z coordinates. 
+|debug|boolean|show debug information or not|
+
+### 2. length metric
+|parameter|type|description|
+|---|:---:|---|
+|rad_mode|int|mode(1 or 2):<br />1 means static threshold, final threshold equal to rad_threshold.<br />2 means dynamic threshold, final threshold equal to rad_threshold * src_node.radius|
+|rad_threshold|float|This threshold measures the distance between nodes on gold standard tree and the closest edge on test tree. 
+|len_threshold|float|This threshold measures the difference between edges on gold standard tree and their corresponding trace on test tree.  
+|scale|tuple(1*3)|scaling of gold and test tree in x,y,z coordinates. |
+|debug|boolean|show debug information or not|
+
+### 3. branch metric
+|parameter|type|description|
+|---|:---:|---|
+|threshold_dis|float| If the distance of two nodes on two trees is less than this threshold, they are probably matched. 
+|scale|tuple(1*3)| scaling of gold and test tree in x,y,z coordinates.|
+|true_positive_type|int| Identify the type of true positive nodes in swc. (This and following two parameters may affect the color of nodes in visualization program) | 
+|false_negative_type|int| Identify the type of false negative nodes in swc. |
+|false_positive_type|int| Identify the type of false positive nodes in swc. |
+
+### 4. diadem metric
+|parameter|type|description|
+|---|:---:|---|
+|weight_mode|int|Choose different map between degree and weight.<br/>(a). WEIGHT_DEGREE = 1<br/>weight is the degree of node <br/>(b). WEIGHT_SQRT_DEGREE = 2<br/>weight is the sqrt of degree <br/>(c). WEIGHT_DEGREE_HARMONIC_MEAN = 3<br/>weight is the harmonic mean of degree of left and right son. <br/>(d). WEIGHT_PATH_LENGTH = 4<br/>weight is the length of path from node to its root<br/>|
+|remove_spur|boolean| remove spur or not |
+|count_excess_nodes|boolean| count excess nodes in test tree or not | 
+|list_miss|boolean| list missed nodes(reconstruct failed nodes) or not|
+|list_distant_matches|boolean| distant match means the parent of a branch is not a matched node, but ancestor is. If this branch is matched, they are distant matched| 
+|list_continuations|boolean| Continuation refer to nodes with only one one. List this kind of nodes or not. |
+|find_proper_root|boolean| find a pair of matched node as roots of two trees or not |
+|scale|tuple(1*3)|scaling of gold and test tree in x,y,z coordinates.|
+|xy_threshold|float| node distance threshold in xy surface.|
+|z_threshold|float| node distance threshold in z axis. |
+|default_xy_path_error_threshold|float| path length difference threshold in xy surface. 
+|default_z_path_error_threshold|float| path length difference threshold in z axis. |
+|debug|boolean| show debug information or not |
+
+### 5. link metric
+|parameter|type|description|
+|---|:---:|---|
+|scale|tuple(1*3)|scaling of gold and test tree in x,y,z coordinates.|

config/fake_reconstruction_configs/skeletonize.schema.json

@@ -1,2 +0,0 @@
-This folder is used to place the temporary reconstruct configs.
-Dont' delete this folder.

config/fake_reconstruction_configs/test1best.json

@@ -107,38 +107,39 @@ def read_parameters():
     parser.add_argument(
         "--gold",
         "-G",
-        help="path to the gold-standard SWC file",
-        required=True
+        help="path of the gold standard SWC file",
+        required=False
     )
     parser.add_argument(
         "--test",
         "-T",
-        help="a list of SWC files for evaluation",
-        required=True,
+        help="a list of reconstructed SWC files or folders for evaluation",
+        required=False,
         nargs='*',
     )
     parser.add_argument(
         "--metric",
         "-M",
         help="metric choice: " + get_metric_summary(False) + ".",
-        required=True
+        required=False
     )
     parser.add_argument(
         "--output",
         "-O",
-        help="metric output path, including different scores of the metric",
+        help="output path of metric results, output file is in json format with different scores of the metric",
         required=False
     )
     parser.add_argument(
         "--detail",
         "-D",
-        help="detail \"type\" marked for gold/test SWC file, including marked swc trees",
+        help="output path of detail metric result, swc format presented.\n"
+             "identify different type according to metric result for each node",
         required=False
     )
     parser.add_argument(
         "--config",
         "-C",
-        help="custom configuration file for the specified metric",
+        help="path of custom configuration file for the specified metric",
         required=False
     )
     parser.add_argument(
@@ -166,10 +167,9 @@ def set_configs(abs_dir, args):
     # argument: metric
     metric = get_root_metric(args.metric)
     if not metric:
-        print("\nERROR: The metric '{}' is not supported.".format(args.metric))
-        print("\nValid options for --metric:\n")
-        print(get_metric_summary(True))
-        return 1
+        raise Exception("\nERROR: The metric '{}' is not supported.".format(args.metric) +
+                        "\nValid options for --metric:\n" +
+                        get_metric_summary(True))
 
     # argument: test
     test_swc_paths = [os.path.join(abs_dir, path) for path in args.test]
@@ -245,10 +245,7 @@ def run():
     abs_dir = os.path.abspath("")
     init(abs_dir)
 
-    try:
-        args = read_parameters()
-    except:
-        raise Exception("[Error: ] Error in reading parameters")
+    args = read_parameters()
     gold_swc_tree, test_swc_trees, metric, output_dir, detail_dir, config, is_debug = set_configs(abs_dir, args)
 
     for test_swc_tree in test_swc_trees:

config/fake_reconstruction_configs/test3best.json

@@ -17,7 +17,7 @@ def read_swc_trees(swc_file_paths, tree_name_dict=None):
     swc_tree_list = []
     if os.path.isfile(swc_file_paths):
         if not (swc_file_paths[-4:] == ".swc" or swc_file_paths[-4:] == ".SWC"):
-            print(swc_file_paths + "is not a tif file")
+            print(swc_file_paths + "is not a swc file")
             return None
         swc_tree = SwcTree()
         swc_tree.load(swc_file_paths)