Docstrings and readme

README.rst

@@ -65,8 +65,16 @@ Usage
 -----
 
 First, you need to have the output stats table from Freesurfer outputs. A collection of commands can be executed
-from fs_utils/stats2table.sh file. In later versions, we will provide Python utilities to extract these stats tables
-as well.
+from fs_utils/stats2table.sh file. We now provide Python utilities to extract these stats tables
+as well. You can use our Freesurfer StatsCollector class:
+
+>>> from avicortex.freesurfer.reader import StatsCollector
+>>> collector = StatsCollector(subjects_path="/freesurfer/execution/outputs/subjects/dir")
+>>> table = collector.collect_all()
+
+StatsCollector's collect_all function will collect all subjects, hemispheres, measurements of specified atlas into a
+pandas dataframe. Then you can save your table to a csv for later use. In later versions, we will provide a better
+maintained CLI.
 
 One class is provided for HCP Young Adult dataset but the you need to access data from:
 https://www.humanconnectome.org/study/hcp-young-adult
@@ -86,7 +94,7 @@ Moreover, you can select a feature set for the source and target graphs that wil
 Data(x=[batch_size, n_nodes, n_features], edge_attr=[batch_size, n_edges, n_features]). After the selection, you will have:
 Data(x=[batch_size, n_nodes, selection_idx], edge_attr=[batch_size, n_edges, selection_idx]). You can specify this while initializing:
 
->>> hcp_dataset_tr = HCPYoungAdultDataset(hemisphere="left", mode="train", freesurfer_out_path=freesurfer_stat_path, in_view_idx=0, out_view_idx=3)
+>>> hcp_dataset_tr = HCPYoungAdultDataset(hemisphere="left", mode="train", freesurfer_out_path=freesurfer_stat_path, src_view_idx=0, tgt_view_idx=3)
 
 Now you can put into a torch_geometric dataloader:
 
@@ -104,6 +112,26 @@ Output input_graph and target_graph will belong to the same patient. And you can
 This class might represent different conditions, such as different diseases, age groups, or gender. For example, in HCP Young Adult dataset, label
 represents patient gender.
 
+You can access the subject id of each graph to easily keep track of.
+
+>>> cls_label = target_graph.subject_id
+
+Another use case we cover is to atlas selections for both source and target. You can select different atlases for atlas-to-atlas mapping tasks.
+
+>>> hcp_dataset_tr = HCPYoungAdultDataset(
+>>>     hemisphere="left",
+>>>     mode="train",
+>>>     src_atlas="dktatlas",
+>>>     tgt_atlas="destrieux",
+>>>     src_atlas_path="/path/to/dktatlas/freesurfer/table.csv",
+>>>     tgt_atlas_path="/path/to/destrieux/freesurfer/table.csv"
+>>> )
+
+You can further select a device and specify a random seed for reproducibility.
+
+>>> hcp_dataset_tr = HCPYoungAdultDataset(hemisphere="left", mode="train", device="cpu", random_seed=9832)
+
+
 Contributing
 ------------
 

avicortex/builders.py

@@ -36,7 +36,7 @@ def __init__(self) -> None:
     def load_atlas(
         self, fs_stats_atlas_path: str, atlas: str = "dktatlas"
     ) -> pd.Series:
-        """Get a list of cortical regions."""
+        """Get a list of cortical regions of specified atlas and read the stats file."""
         # Read freesurfer output table.
         self.fs_stats_atlas_path = fs_stats_atlas_path
         self.freesurfer_df = pd.read_csv(fs_stats_atlas_path)

avicortex/datasets.py

@@ -270,6 +270,8 @@ def get_view_graph_for_subject(self, subj_idx: int, tgt: bool = False) -> PygDat
         ----------
         subj_idx: int
             Index of the desired subject to construct its multigraph.
+        tgt: boolean
+            Whether the requested graph is a target or not.
 
         Returns
         -------
@@ -306,6 +308,8 @@ def get_fold_indices(
             Size of all data.
         fold_id: int
             Which cross validation fold to get the indices for.
+        random_seed: int
+            Random seed to be used for randomization.
 
         Returns
         -------
@@ -342,6 +346,10 @@ def create_graph_obj(
             Node feature matrix for the graph. Shaped (n_nodes, n_views)
         labels: numpy ndarray
             Subject-level labels. Only one label if batch size is 1.
+        subject_id: string
+            Subject ID attached to the graph.
+        tgt: boolean
+            Whether the requested graph is a target or not.
 
         Returns
         -------