[DOC] Address feedback

docs/source/_includes/working_directory.md

@@ -0,0 +1,5 @@
+<!-- markdownlint-disable-file MD041 -->
+```{note}
+All commands assume that the working directory is the root of the `brainflex-node` repository.
+They will need to be modified if that is not the case.
+```

docs/source/conf.py

@@ -22,7 +22,7 @@
     "sphinx_togglebutton",
 ]
 
-exclude_patterns = []
+exclude_patterns = ["_includes"]
 
 nitpicky = True
 

docs/source/fedbiomed_node_part_1.md

@@ -4,6 +4,13 @@ We will be using [Fed-BioMed](https://fedbiomed.org/) to conduct the federated l
 See [this page](https://fedbiomed.org/federated-network/) of the Fed-BioMed website for more information about how it works.
 Essentially, each site participating in the federated experiment needs to deploy a **node**, and the person responsible for running the experiment (i.e. training the models) deploys a server (**researcher** in Fed-BioMed vocabulary) to which all nodes connect to.
 
+During training, the researcher sends experiment-specific code (a *training plan*) to all nodes.
+Nodes use this code to train a local model, then send model weights to the researcher (subject-level data never leave the node).
+The researcher aggregates the set of all weights to produce a global model, which can be sent back to the nodes for further training.
+
+```{include} _includes/working_directory.md
+```
+
 ## Record start time
 
 ```bash
@@ -12,7 +19,7 @@ brainflex record fedbiomed_node_part_1 start
 
 ## Deploy the node
 
-Run this to download the images (if needed) and start them:
+Run this to download the images (about 18 GB in total) and start them:
 
 ```bash
 docker compose up -d
@@ -26,19 +33,61 @@ docker compose up -d
  ✔ Container brainflex-node-default  Started
 ```
 
+The download can take a couple of (maybe 5–10) minutes, depending on your Internet connection.
+
 The two services are:
 
 - `vpn`: a WireGuard VPN client that connects to the central VPN server
 - `node`: the [node image](https://hub.docker.com/r/fedbiomed/node) distributed by Fed-BioMed
 
-### Troubleshooting
+### Troubleshooting: disk quota error
+
+If you run out of disk space and have already tried changing the Docker data directories [as previously described](idp_extraction.md#troubleshooting-disk-quota-error), you can remove the FreeSurfer image downloaded in the [IDP extraction step](idp_extraction), as it is not needed anymore.
+
+1. List your images:
+
+    ```bash
+    docker image ls --filter reference=freesurfer/freesurfer:7.3.2
+    ```
+
+    ```{code-block}
+    :caption: Example output
+    IMAGE                         ID             DISK USAGE   CONTENT SIZE   EXTRA
+    freesurfer/freesurfer:7.3.2   e04a8cf308a8       22.5GB         6.88GB
+    ```
+
+    Note the `ID` that corresponds to the `freesurfer/freesurfer:7.3.2` image.
 
-By default, Docker images are stored on the root disk.
-If you encounter issues with disk storage quota being exceeded, you can configure Docker to use a different directory for storing data.
-This can be done by following e.g. [this guide](https://www.simplified.guide/_export/xhtml/docker/change-data-directory).
+2. Remove the image
+
+    ```bash
+    docker image rm <IMAGE_ID>
+    ```
+
+3. If you get an error about a container (running or stopped) still using the image, find it:
+
+    ```bash
+    docker container ls --all --filter ancestor=freesurfer/freesurfer:7.3.2
+    ```
+
+    Note its `ID`.
+    Stop it if it's running, then remove it:
+
+    ```bash
+    docker container stop <CONTAINER ID>
+    docker container rm <CONTAINER ID>
+    ```
+
+    Then remove the image:
+
+    ```bash
+    docker image rm <IMAGE_ID>
+    ```
 
 ## Check Fed-BioMed node status
 
+Run this to confirm that the node is running:
+
 ```bash
 docker compose exec -u fedbiomed node fedbiomed node -p /fbm-node status
 ```
@@ -51,6 +100,21 @@ docker compose exec -u fedbiomed node fedbiomed node -p /fbm-node status
 Node status: NodeState.RUNNING
 ```
 
+### Troubleshooting: permission error
+
+If the command fails with a permission error like this:
+
+```{code-block}
+PermissionError: [Errno 13] Permission denied: '/fbm-node/log'
+```
+
+check that `CONTAINER_UID` and `CONTAINER_GID` in your `.env` file match the output of `id -u` and `id -g` (see [Initial setup](initial_setup.md#env-file)), then restart the containers:
+
+```bash
+docker compose down
+docker compose up -d
+```
+
 ## Add datasets to the node
 
 Run the two commands below to register the datasets [created by `nipoppy2fedbiomed`](fl_ready_dataset.md):
@@ -66,6 +130,17 @@ Confirm that they have been added:
 docker compose exec -u fedbiomed node fedbiomed node -p /fbm-node dataset list
 ```
 
+You should see a table like this:
+
+```{code-block}
+:caption: Example output
+Listing your data available
+name    data_type    tags                  description                                                                                                                                                                              path                                                                       shape               dataset_id                                    dataset_parameters
+------  -----------  --------------------  ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------  -------------------------------------------------------------------------  ------------------  --------------------------------------------  --------------------
+age     csv          ['brainflex', 'age']  Generated by nipoppy2fedbiomed (sources: nb:Age, nb:Sex, freesurfer 7.3.2 idp/fs_stats-*/fs7.3.2-aparc.DKTatlas-thickness.tsv, freesurfer 7.3.2 idp/fs_stats-*/fs7.3.2-aseg-volume.tsv)  /nipoppy_study/derivatives/nipoppy2fedbiomed/0.1.0/output/age/dataset.csv  {'csv': [80, 131]}  dataset_f555e76c-e98c-46f4-81f8-6936edc5a004  {}
+sex     csv          ['brainflex', 'sex']  Generated by nipoppy2fedbiomed (sources: nb:Age, nb:Sex, freesurfer 7.3.2 idp/fs_stats-*/fs7.3.2-aparc.DKTatlas-thickness.tsv, freesurfer 7.3.2 idp/fs_stats-*/fs7.3.2-aseg-volume.tsv)  /nipoppy_study/derivatives/nipoppy2fedbiomed/0.1.0/output/sex/dataset.csv  {'csv': [80, 131]}  dataset_4b7addc7-37c4-404c-a530-279554e3237d  {}
+```
+
 ## Share the public key with the server
 
 Run this to get the node's public key:
@@ -82,6 +157,11 @@ brainflex-vpn-default  | info: wireguard public key for this peer: <PUBLIC_KEY>
 ```
 
 Copy the public key (or the entire output of the previous command) and send it to us via email.
+We will register it on the central VPN server so that your node can join the federated network.
+
+```{note}
+Sharing the public key is safe and necessary for establishing a connection with the VPN server.
+```
 
 ## Record end time
 

docs/source/fedbiomed_node_part_2.md

@@ -1,5 +1,14 @@
 # Fed-BioMed node: Part 2
 
+```{attention}
+Only start this part after the FL experiment coordinator has told you that your public key has been registered and that the training plans have been sent to your node.
+```
+
+In this step, you will check that your node can reach the researcher, then review and approve the code that will be run on your machine.
+
+```{include} _includes/working_directory.md
+```
+
 ## Record start time
 
 ```bash
@@ -25,15 +34,19 @@ scripts/vpn_status
 
 ## View and approve the training plans
 
-At this point, the Fed-BioMed researcher should have sent 2 training plans to your node.
-This is the custom Python code needed for e.g. data loading and preprocessing.
+A Fed-BioMed *training plan* is the custom Python code that will be run on your node, e.g. for data loading, preprocessing and model definition.
+
+At this point, the Fed-BioMed researcher process should have sent 2 training plans to your node (via the VPN connection), one for each prediction task (brain age regression and biological sex classification).
+Your node is configured to only run approved code, so you will need to review and approve them before training can start.
 
 Run this to view the training plans (need to run once for each training plan):
 
 ```bash
 docker compose exec -u fedbiomed node fedbiomed node -p /fbm-node training-plan view
 ```
 
+This prints the code of the training plan to the terminal.
+
 Once you are satisfied, run this to approve them (also need to run twice):
 
 ```bash
@@ -47,3 +60,39 @@ Once both training plans are approved, the node is ready for training!
 ```bash
 brainflex record fedbiomed_node_part_2 end
 ```
+
+## Share data about setup timing
+
+Timing information and your answers to the initial survey and step-specific questions have been saved to TSV files under the `.brainflex` directory:
+
+```bash
+tree .brainflex
+```
+
+```{code-block}
+:caption: Output
+.brainflex/
+├── initial_survey.tsv
+├── step_survey.tsv
+└── timestamps.tsv
+```
+
+Take a look at them, make edits as needed, and send them to us via email.
+
+## Next
+
+Once all nodes are set up and have approved the training plans, the researcher will launch the federated learning experiment through the network.
+There is nothing else to do on your side for the moment.
+Just make sure to:
+
+- Leave the containers running
+- Keep the machine turned on and connected to the internet until the end of the experiment (estimated to be 1-2 months)
+
+You can check that the containers are still running with:
+
+```bash
+docker compose ps
+```
+
+We will keep you updated on the progress of the experiment and manuscript.
+Thank you for participating!

docs/source/fl_ready_dataset.md

@@ -1,14 +1,20 @@
 # FL-ready dataset
 
+In this step, you will combine the standardized IDPs and the harmonized phenotypic data into one table per prediction task, **in the format expected by Fed-BioMed and the machine learning models we will train**.
+
+```{include} _includes/working_directory.md
+```
+
 ## Record start time
 
 ```bash
-brainflex record fl_ready_data start
+brainflex record fl_ready_dataset start
 ```
 
 ## Pipeline installation
 
-Install the Nipoppy-to-Fed-BioMed conversion pipeline:
+Install the [Nipoppy-to-Fed-BioMed](https://zenodo.org/records/23753437) conversion pipeline.
+This pipeline was written for this FL experiment specifically.
 
 ```bash
 nipoppy pipeline install 23753437 --study nipoppy_study
@@ -39,7 +45,7 @@ nipoppy process --pipeline nipoppy2fedbiomed --pipeline-step age --study nipoppy
 nipoppy process --pipeline nipoppy2fedbiomed --pipeline-step sex --study nipoppy_study
 ```
 
-For each of the prediction tasks (brain age regression and biological sex classification), this will write a CSV file (the Fed-BioMed dataset) and a JSON file used to register it on the [Fed-BioMed node](fedbiomed_node_part_1.md).
+For each of the prediction tasks (brain age regression and biological sex classification), this will write a CSV file (the Fed-BioMed dataset) and a JSON file that can be used to register it on the Fed-BioMed node in the next step.
 
 ```bash
 tree nipoppy_study/derivatives/nipoppy2fedbiomed
@@ -61,5 +67,5 @@ nipoppy_study/derivatives/nipoppy2fedbiomed
 ## Record end time and answer questions
 
 ```bash
-brainflex record fl_ready_data end
+brainflex record fl_ready_dataset end
 ```

docs/source/freesurfer_idps.md → docs/source/idp_extraction.md

@@ -1,27 +1,43 @@
-# FreeSurfer IDPs
+# IDP extraction
+
+In this step, you will use a Nipoppy pipeline to extract imaging-derived phenotypes (IDPs), such as cortical thickness and subcortical volumes, from the FreeSurfer outputs that came with your dataset.
+Because every site runs the same containerized pipelines with the same configuration, **the resulting IDPs are standardized across the federation**.
+
+```{include} _includes/working_directory.md
+```
 
 ## Record start time
 
 ```bash
 brainflex record idp_extraction start
 ```
 
+```{important}
+Starting from this step, make sure to run `brainflex record` at the beginning and end of each step, as instructed.
+```
+
 ## Install pipelines
 
-Install the FreeSurfer and FreeSurfer stats extraction pipelines:
+Install (i.e., download the JSON configuration files for) the FreeSurfer and FreeSurfer stats extraction pipelines:
+
+- [`freesurfer` 7.3.2](https://zenodo.org/records/21929473): FreeSurfer has already been run on your dataset, but the configuration files still need to be installed due to a quirk in how the `fs_stats` pipeline currently works in Nipoppy.
+- [`fs_stats` 0.3.0](https://zenodo.org/records/23752946): an extraction pipeline that compiles FreeSurfer outputs spread across subject directories into feature tables using [`asegstats2table`](https://surfer.nmr.mgh.harvard.edu/fswiki/asegstats2table) and [`aparcstats2table`](https://surfer.nmr.mgh.harvard.edu/fswiki/aparcstats2table).
 
 ```bash
-# FreeSurfer
+# FreeSurfer 7.3.2
 nipoppy pipeline install 21929473 --study nipoppy_study
 
-# fs_stats
+# fs_stats 0.3.0
 nipoppy pipeline install 23752946 --study nipoppy_study
 ```
 
 ```{note}
 The `--study` option is not needed if your working directory is somewhere inside `nipoppy_study`.
 ```
 
+If the [FreeSurfer 7.3.2 container image](https://hub.docker.com/r/freesurfer/freesurfer/tags?name=7.3.2) is not already on your machine, you will be prompted to download it.
+Enter 'y' to accept; this can take a few (maybe 5-10) minutes and will use around 23 GB of storage.
+
 Confirm that the pipeline have been installed correctly:
 
 ```bash
@@ -37,11 +53,20 @@ INFO     Available extraction pipelines and versions
 INFO             - fs_stats (0.3.0)
 ```
 
-## Configure the fs_stats pipeline with your FreeSurfer license
+### Troubleshooting: disk quota error
+
+By default, Docker images are stored on the root disk.
+If you encounter issues with disk storage quota being exceeded, you can configure Docker to use a different directory for storing data.
+This can be done by following e.g. [this guide](https://www.simplified.guide/_export/xhtml/docker/change-data-directory).
+
+## Configure the `fs_stats` pipeline with your FreeSurfer license
 
-The `fs_stats` pipeline requires a FreeSurfer license because it runs lightweight tools that are packaged with FreeSurfer.
+The `fs_stats` pipeline requires a FreeSurfer license because it runs lightweight tools that are packaged with FreeSurfer ([`asegstats2table`](https://surfer.nmr.mgh.harvard.edu/fswiki/asegstats2table) and [`aparcstats2table`](https://surfer.nmr.mgh.harvard.edu/fswiki/aparcstats2table)).
 Open the study configuration file at `nipoppy_study/global_config.json` and set `FREESURFER_LICENSE_FILE` to the absolute path to your FreeSurfer license.
-FreeSurfer licenses can be obtained by filling out [this form](https://surfer.nmr.mgh.harvard.edu/registration.html).
+
+```{note}
+If you do not already have a FreeSurfer license, fill out [this form](https://surfer.nmr.mgh.harvard.edu/registration.html) to get one.
+```
 
 ```{code-block} json
 :emphasize-lines: 7

docs/source/index.md

@@ -2,13 +2,19 @@
 
 Real-world neuroimaging federated learning (FL) experiment using the open neuroinformatics ecosystem described in [this preprint](https://doi.org/10.64898/2026.04.30.721944).
 
-Each site involved in the federation will:
+```{admonition} What is federated learning?
+[Federated learning (FL)](https://en.wikipedia.org/wiki/Federated_learning) enables the training of machine learning models on multiple datasets without direct sharing of participant-level data.
+It has use-cases in neuroimaging research (and other domains) when data-sharing is not possible due to e.g. privacy or governance concerns.
+```
+
+This website contains instructions for sites (nodes) participating in this FL experiment.
+We will help you:
 
 1. Download an [OpenNeuro](https://openneuro.org/) dataset of ~50-100 participants that has been pre-formatted into a [Nipoppy study](https://nipoppy.readthedocs.io/en/latest/) with (already processed) FreeSurfer derivatives and demographics (age and sex)
-2. Run some fast (no HPC required), user-friendly [Nipoppy](https://nipoppy.readthedocs.io/en/latest/) and [Neurobagel](https://neurobagel.org/) tools to obtain FL-ready data
-3. Deploy a [Fed-BioMed](https://fedbiomed.org/) client node and participate in the training of simple machine learning models for brain age regression and biological sex classification from FreeSurfer cortical thickness/subcortical volume data
+2. Use some fast (no HPC required), user-friendly [Nipoppy](https://nipoppy.readthedocs.io/en/latest/) and [Neurobagel](https://neurobagel.org/) tools to obtain **FL-ready data**
+3. Deploy a [Fed-BioMed](https://fedbiomed.org/) client node and participate in the training of simple machine learning models for **brain age regression** and **biological sex classification** from FreeSurfer cortical thickness/subcortical volume data
 
-The time required to do each step will be recorded and included in the manuscript along with the model results.
+Information about the perceived usefulness of the tools and the time required to do each step will be recorded and included in the manuscript along with the model results.
 
 ```{toctree}
 ---
@@ -19,8 +25,8 @@ caption: Instructions
 ---
 prerequisites
 initial_setup
-freesurfer_idps
-phenotypic_files
+idp_extraction
+semantic_harmonization
 fl_ready_dataset
 fedbiomed_node_part_1
 fedbiomed_node_part_2