Many explanatory comments to add to `SynthSeg/dcan/paper/*.py` scripts (from code review)

[GregConan]

Explanatory comments suggested to add to the Python scripts located in the SynthSeg/dcan/paper/ directory, all suggested during the code review on 2022-02-09:

In General

• Add comments explaining each function, what the variables are, what the code is doing, etc.
  • Add pydoc?

Add explanatory comments to specific Python scripts

(Scripts in the SynthSeg/dcan/paper/ directory)

generate_metrics.py

• Add comments explaining each function
• Add comment (header?) explaining that this script is the top-level script that runs the rest of them

evaluate_results.py

• Add comment on line 8 explaining what the evaluate_results function does
  • Especially its inputs and that it outputs numpy files
  • Explain what the rows and columns are in the output numpy files
• Explain that gt_dir is ground truth directory
• Explain that seg_dir is the dir for the segmentations done by the deep learning model
• Explain that path_dice checks overlap between segmentations
• Explain that hausdorff is a topological measure
• Explain that range(10) on line 12 comes from 10-fold validation
• Explain that labels_file_path is a path to FreeSurfer labels

generate_metrics_csv_files.py

• Explain that if os.path.exists(labels_file_path) verifies that the script has been run
• Explain the numpy rows and columns at line 19
  • Explain that (after transposition) rows are names of the .nii.gz files and columns are FreeSurfer segment file names
• Explain that all of the labels variables are FreeSurfer labels

create_plots.py

• Explain that this function creates a plot for each of the 5 measures
• Explain what the function does, and its inputs and outputs