diff --git a/INSTALL.md b/INSTALL.md index 6993d320..59e58338 100644 --- a/INSTALL.md +++ b/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) diff --git a/docs/running.md b/docs/running.md index b2f7da77..83d9e4ea 100644 --- a/docs/running.md +++ b/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 ``` diff --git a/docs/testing.md b/docs/testing.md index 1ea3b66c..ed20959f 100644 --- a/docs/testing.md +++ b/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.