[DOC] doc update

INSTALL.md

@@ -131,7 +131,7 @@ narps_open_status --json
 > For further information about these command line tools, read the corresponding documentation pages.
 > * `narps_open_runner` : [docs/running.md](docs/running.md)
 > * `narps_open_tester` : [docs/testing.md](docs/testing.md#command-line-tool)
-> * `narps_open_correlations` : [docs/correlation.md](docs/correlation.md#command-line-tool)
+> * `narps_open_correlations` : [docs/testing.md](docs/testing.md#command-line-tool)
 > * `narps_description` : [docs/description.md](docs/description.md)
 > * `narps_results` : [docs/data.md](docs/data.md#results-from-narps-teams)
 > * `narps_open_status` : [docs/status.md](docs/status.md)

docs/running.md

@@ -9,23 +9,32 @@ The `narps_open.runner` module allows to run pipelines from the command line.
 
 ```bash
 narps_open_runner -h
-	usage: runner.py [-h] -t TEAM (-r RANDOM | -s SUBJECTS [SUBJECTS ...]) [-g | -f]
+	usage: narps_open_runner [-h] -t
+	                         {08MQ,2T6S,3TR7,4SZ2,4TQ6,51PW,98BT,B23O,C88N,J7F9,L7J7,O21U,O6R6,Q6O0,R9K3,T54A,U26C,UK24,X19V}
+	                         (-s SUBJECTS [SUBJECTS ...] | -n NSUBJECTS | -r RSUBJECTS) [-l {p,r,s,g} [{p,r,s,g} ...]]
+	                         [-c] [-e]
 
 	Run the pipelines from NARPS.
 
 	options:
 	  -h, --help            show this help message and exit
-	  -t TEAM, --team TEAM  the team ID
-	  -r RANDOM, --random RANDOM the number of subjects to be randomly selected
-	  -s SUBJECTS [SUBJECTS ...], --subjects SUBJECTS [SUBJECTS ...] a list of subjects
-	  -g, --group           run the group level only
-	  -f, --first           run the first levels only (preprocessing + subjects + runs)
+	  -t {08MQ,2T6S,3TR7,4SZ2,4TQ6,51PW,98BT,B23O,C88N,J7F9,L7J7,O21U,O6R6,Q6O0,R9K3,T54A,U26C,UK24,X19V}, --team {08MQ,2T6S,3TR7,4SZ2,4TQ6,51PW,98BT,B23O,C88N,J7F9,L7J7,O21U,O6R6,Q6O0,R9K3,T54A,U26C,UK24,X19V}
+	                        the team ID
+	  -s SUBJECTS [SUBJECTS ...], --subjects SUBJECTS [SUBJECTS ...]
+	                        a list of subjects to be selected
+	  -n NSUBJECTS, --nsubjects NSUBJECTS
+	                        the number of subjects to be selected
+	  -r RSUBJECTS, --rsubjects RSUBJECTS
+	                        the number of subjects to be selected randomly
+	  -l {p,r,s,g} [{p,r,s,g} ...], --levels {p,r,s,g} [{p,r,s,g} ...]
+	                        the analysis levels to run (p=preprocessing, r=run, s=subject, g=group)
 	  -c, --check           check pipeline outputs (runner is not launched)
+	  -e, --exclusions      run the analyses without the excluded subjects
 
-narps_open_runner -t 2T6S -s 001 006 020 100
-narps_open_runner -t 2T6S -r 4
-narps_open_runner -t 2T6S -r 4 -f
-narps_open_runner -t 2T6S -r 4 -f -c # Check the output files without launching the runner
+narps_open_runner -t 2T6S -s 001 006 020 100 # Launches the full pipeline on the given subjects
+narps_open_runner -t 2T6S -r 4 # Launches the full pipeline on 4 random subjects
+narps_open_runner -t 2T6S -r 4 -l s # Launches the subject level of the pipeline on 4 random subjects
+narps_open_runner -t 2T6S -r 4 -l p r s -c # Check the output files of the prerprocessing, run level and subject level parts of the pipeline, without launching it.
 ```
 
 > [!NOTE]
@@ -36,7 +45,7 @@ narps_open_runner -t 2T6S -r 4 -f -c # Check the output files without launching
 The class `PipelineRunner` is available from the `narps_open.runner` module. You can use it from inside python code, as follows :
 
 ```python
-from narps_open.runner import PipelineRunner
+from narps_open.runner import PipelineRunner, PipelineRunnerLevel
 
 # Initialize a PipelineRunner by choosing the team ID
 runner = PipelineRunner(team_id = '2T6S')
@@ -53,16 +62,19 @@ runner.subjects = ['001', '006', '020', '100']
 # Alternatively, ask the runner to pick a random number of subjects
 # runner.random_nb_subjects = 4
 
-# Start the runner
+# Start the runner (all available levels)
 runner.start()
 
-# Or start the first level only (preprocessing + run level + subject level)
-runner.start(True, False)
+# Start the subject level only
+runner.start(PipelineRunnerLevel.SUBJECT)
 
-# Or start the second level only (group level)
-runner.start(True, True)
+# Or start the "first level" (preprocessing + run level + subject level)
+runner.start(PipelineRunnerLevel.FIRST)
+
+# Or start the group level only
+runner.start(PipelineRunnerLevel.GROUP)
 
 # Get the list of missing files (if any) after the pipeline finished
-runner.get_missing_first_level_outputs()
-runner.get_missing_group_level_outputs()
+runner.get_missing_outputs() # for all available levels
+runner.get_missing_outputs(PipelineRunnerLevel.PREPROCESSING) # for preprocessing only
 ```

docs/testing.md

@@ -43,7 +43,7 @@ Tests can be launched manually or while using CI (Continuous Integration).
 * To run a tests with a given mark 'mark' : `pytest -m 'mark'`
 * To create code coverage data : `coverage run -m pytest ./tests` then `coverage report` to see the code coverage result or `coverage xml` to output a .xml report file
 
-## Command line tool
+## Command line tools
 
 We created the simple command line tool `narps_open_tester` to help testing the outcome of one pipeline.
 
@@ -58,6 +58,14 @@ This will run the pipeline for the requested team -here 08MQ- on subsets of subj
 
 Once finished, a text file report (`test_pipeline-*.txt`) is created, containing all the computed correlation values.
 
+The command line tool `narps_open_correlations` is also available and can be used as follows:
+
+```bash
+narps_open_correlations -t 2T6S -n 60
+```
+
+to get the correlation values for the results of a previously executed pipeline (here team 2T6S, with 60 subjects).
+
 ## Configuration files for testing
 
 * `pytest.ini` is a global configuration files for using pytest (see reference [here](https://docs.pytest.org/en/7.1.x/reference/customize.html)). It allows to [register markers](https://docs.pytest.org/en/7.1.x/example/markers.html) that help to better identify tests. Note that `pytest.ini` could be replaced by data inside `pyproject.toml` in the next versions.