From 1f925f0a2c8993c677c312cd3f8fd7d2a361b13f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Boris=20Cl=C3=A9net?= <117362283+bclenet@users.noreply.github.com> Date: Wed, 24 Jan 2024 10:31:04 +0100 Subject: [PATCH] Documentation updates (#141) * [BUG] inside unit_tests workflow * [DOC] fix some broken links * [DOC] adding template for pipeline testing * [DOC] adding template for pipeline testing * About implemented_pipelines * Deal with test template * [DOC] new readme for the doc * Changes in README.md * [DOC] slight changes to docs/README.md * Add links to past events * Changes in readme.md * fMRI trail * Adding trail description in contribution guide * Separate trails in contribution guide * [TEST] Solving pytest issues with template test * Changing docker image in use * FSL template correction * [DOC] writing test files * Codespell * First step in writing documentation about NARPS * [DOC] completing doc about narps * [DOC] completing doc about narps * [DOC] completing doc about narps * [DATALAD] change results url * [DOC] reference to the github project for reproduction mgmt * [DOC] adding team id choices for narps open runner * [DOC] list of available team ids in command tools documentation * [DOC] configuration info inside INSTALL.md * [DOC] configuration info inside INSTALL.md * NARPS Exclusion comments --- CONTRIBUTING.md | 2 +- INSTALL.md | 16 ++++++++++ README.md | 10 +++---- narps_open/data/description/__main__.py | 3 +- .../analysis_pipelines_comments.tsv | 26 ++++++++-------- narps_open/data/results/__main__.py | 3 +- narps_open/pipelines/__main__.py | 30 +++++++++++++++++++ narps_open/runner.py | 3 +- narps_open/tester.py | 4 ++- 9 files changed, 73 insertions(+), 24 deletions(-) create mode 100644 narps_open/pipelines/__main__.py diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 98b31c06..dcc8bd6f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ In the following, read the instruction sections where the badge corresponding to ## 1 - Choose a pipeline `🧠 fMRI soft` `🐍 Python` -Not sure which pipeline to start with :thinking:? The [pipeline dashboard](https://github.com/Inria-Empenn/narps_open_pipelines/wiki/pipeline_status) provides the progress status for each pipeline. You can pick any pipeline that is not fully reproduced, i.e.: not started :red_circle: or in progress :orange_circle: . +Not sure which pipeline to start with :thinking:? The [pipeline dashboard](https://github.com/Inria-Empenn/narps_open_pipelines/wiki/pipeline_status) provides the progress status for each pipeline. You can pick a pipeline that is not fully reproduced, i.e.: not started :red_circle: or in progress :orange_circle: . Also have a look to the [pipeline reproduction management page](https://github.com/orgs/Inria-Empenn/projects/1/views/1) in order to get in touch with contributors working on the same pipeline. > [!NOTE] > Need more information to make a decision? The `narps_open.utils.description` module of the project, as described [in the documentation](/docs/description.md) provides easy access to all the info we have on each pipeline. diff --git a/INSTALL.md b/INSTALL.md index 9a429f00..630f96e6 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -66,6 +66,22 @@ Start a Docker container from the Docker image : docker run -it -v PATH_TO_THE_REPOSITORY:/home/neuro/code/ nipype/nipype ``` +Optionally edit the configuration file `narps_open/utils/default_config.toml` so that the referred paths match the ones inside the container. E.g.: if using the previous command line, the `directories` part of the configuration file should be : +```toml +# default_config.toml +# ... + +[directories] +dataset = "/home/neuro/code/data/original/ds001734/" +reproduced_results = "/home/neuro/code/data/reproduced/" +narps_results = "/home/neuro/code/data/results/" + +# ... +``` + +> [!NOTE] +> Further information about configuration files can be found on the page [docs/configuration.md](docs/configuration.md). + Install NARPS Open Pipelines inside the container : ```bash diff --git a/README.md b/README.md index b18c8ff3..a1eee7a6 100644 --- a/README.md +++ b/README.md @@ -50,11 +50,11 @@ This project is supported by RĂ©gion Bretagne (Boost MIND) and by Inria (Explora ## Credits -This project is developed in the Empenn team by Boris Clenet, Elodie Germani, Jeremy Lefort-Besnard and Camille Maumet with contributions by RĂ©mi Gau. +This project is developed in the Empenn team by Boris ClĂ©net, Elodie Germani, Jeremy Lefort-Besnard and Camille Maumet with contributions by RĂ©mi Gau. In addition, this project was presented and received contributions during the following events: - - [OHBM Brainhack 2022](https://ohbm.github.io/hackathon2022/) (June 2022): Elodie Germani, Arshitha Basavaraj, Trang Cao, RĂ©mi Gau, Anna Menacher, Camille Maumet. - - [e-ReproNim FENS NENS Cluster Brainhack](https://repro.school/2023-e-repronim-brainhack/) (June 2023) : Liz Bushby, Boris ClĂ©net, Michael Dayan, Aimee Westbrook. - - [OHBM Brainhack 2023](https://ohbm.github.io/hackathon2023/) (July 2023): Arshitha Basavaraj, Boris ClĂ©net, RĂ©mi Gau, Élodie Germani, Yaroslav Halchenko, Camille Maumet, Paul Taylor. - - [ORIGAMI lab](https://neurodatascience.github.io/) hackathon (September 2023): - [Brainhack Marseille 2023](https://brainhack-marseille.github.io/) (December 2023): + - [ORIGAMI lab](https://neurodatascience.github.io/) hackathon (September 2023): + - [OHBM Brainhack 2023](https://ohbm.github.io/hackathon2023/) (July 2023): Arshitha Basavaraj, Boris ClĂ©net, RĂ©mi Gau, Élodie Germani, Yaroslav Halchenko, Camille Maumet, Paul Taylor. + - [e-ReproNim FENS NENS Cluster Brainhack](https://repro.school/2023-e-repronim-brainhack/) (June 2023) : Liz Bushby, Boris ClĂ©net, Michael Dayan, Aimee Westbrook. + - [OHBM Brainhack 2022](https://ohbm.github.io/hackathon2022/) (June 2022): Elodie Germani, Arshitha Basavaraj, Trang Cao, RĂ©mi Gau, Anna Menacher, Camille Maumet. diff --git a/narps_open/data/description/__main__.py b/narps_open/data/description/__main__.py index b6c9ead3..a7eaa84b 100644 --- a/narps_open/data/description/__main__.py +++ b/narps_open/data/description/__main__.py @@ -7,6 +7,7 @@ from json import dumps from narps_open.data.description import TeamDescription +from narps_open.pipelines import implemented_pipelines def main(): """ Entry-point for the command line tool narps_description """ @@ -14,7 +15,7 @@ def main(): # Parse arguments parser = ArgumentParser(description='Get description of a NARPS pipeline.') parser.add_argument('-t', '--team', type=str, required=True, - help='the team ID') + help='the team ID', choices=implemented_pipelines.keys()) parser.add_argument('-d', '--dictionary', type=str, required=False, choices=[ 'general', diff --git a/narps_open/data/description/analysis_pipelines_comments.tsv b/narps_open/data/description/analysis_pipelines_comments.tsv index 5ebf2405..fd858ebc 100644 --- a/narps_open/data/description/analysis_pipelines_comments.tsv +++ b/narps_open/data/description/analysis_pipelines_comments.tsv @@ -5,7 +5,7 @@ O21U No N/A 3 U26C No N/A 4 Link to shared analysis code : https://github.com/gladomat/narps 43FJ No N/A 2 C88N No N/A 3 -4TQ6 Yes Resampled image offset and too large compared to template. 3 +4TQ6 No Resampled image offset and too large compared to template. 3 T54A No N/A 3 2T6S No N/A 3 L7J7 No N/A 3 @@ -17,17 +17,17 @@ O6R6 No N/A 3 C22U No N/A 1 Custom Matlab script for white matter PCA confounds 3PQ2 No N/A 2 UK24 No N/A 2 -4SZ2 Yes Resampled image offset from template brain. 3 +4SZ2 No Resampled image offset from template brain. 3 9T8E No N/A 3 94GU No N/A 1 Multiple software dependencies : SPM + ART + TAPAS + Matlab. I52Y No N/A 2 5G9K Yes Values in the unthresholded images are not z / t stats 3 -2T7P Yes Missing thresholded images. 2 Link to shared analysis code : https://osf.io/3b57r +2T7P No Missing thresholded images. 2 Link to shared analysis code : https://osf.io/3b57r UI76 No N/A 3 B5I6 No N/A 3 -V55J Yes Bad histogram : very small values. 2 +V55J No Bad histogram : very small values. 2 X19V No N/A 3 -0C7Q Yes Appears to be a p-value distribution, with slight excursions below and above zero. 2 +0C7Q No Appears to be a p-value distribution, with slight excursions below and above zero. 2 R5K7 No N/A 2 0I4U No N/A 2 3C6G No N/A 2 @@ -37,20 +37,20 @@ O03M No N/A 3 80GC No N/A 3 J7F9 No N/A 3 R7D1 No N/A 3 Link to shared analysis code : https://github.com/IMTAltiStudiLucca/NARPS_R7D1 -Q58J Yes Bad histogram : bimodal, zero-inflated with a second distribution centered around 5. 3 Link to shared analysis code : https://github.com/amrka/NARPS_Q58J -L3V8 Yes Rejected due to large amount of missing brain in center. 2 +Q58J No Bad histogram : bimodal, zero-inflated with a second distribution centered around 5. 3 Link to shared analysis code : https://github.com/amrka/NARPS_Q58J +L3V8 No Rejected due to large amount of missing brain in center. 2 SM54 No N/A 3 1KB2 No N/A 2 -0H5E Yes Rejected due to large amount of missing brain in center. 2 -P5F3 Yes Rejected due to large amounts of missing data across brain. 2 +0H5E No Rejected due to large amount of missing brain in center. 2 +P5F3 No Rejected due to large amounts of missing data across brain. 2 Q6O0 No N/A 3 R42Q No N/A 2 Uses fMRIflows, a custom software based on NiPype. Code available here : https://github.com/ilkayisik/narps_R42Q L9G5 No N/A 2 DC61 No N/A 3 -E3B6 Yes Bad histogram : very long tail, with substantial inflation at a value just below zero. 4 Link to shared analysis code : doi.org/10.5281/zenodo.3518407 +E3B6 No Bad histogram : very long tail, with substantial inflation at a value just below zero. 4 Link to shared analysis code : doi.org/10.5281/zenodo.3518407 16IN Yes Values in the unthresholded images are not z / t stats 2 Multiple software dependencies : matlab + SPM + FSL + R + TExPosition + neuroim. Link to shared analysis code : https://github.com/jennyrieck/NARPS 46CD No N/A 1 -6FH5 Yes Missing much of the central brain. 2 +6FH5 No Missing much of the central brain. 2 K9P0 No N/A 3 9U7M No N/A 2 VG39 Yes Performed small volume corrected instead of whole-brain analysis 3 @@ -64,8 +64,8 @@ AO86 No N/A 2 L1A8 Yes Not in MNI standard space. 2 IZ20 No N/A 1 3TR7 No N/A 3 -98BT Yes Rejected due to very bad normalization. 2 +98BT No Rejected due to very bad normalization. 2 XU70 No N/A 1 Uses custom software : FSL + 4drealign 0ED6 No N/A 2 -I07H Yes Bad histogram : bimodal, with second distribution centered around 2.5. 2 +I07H No Bad histogram : bimodal, with second distribution centered around 2.5. 2 1P0Y No N/A 2 diff --git a/narps_open/data/results/__main__.py b/narps_open/data/results/__main__.py index 88111b87..64bbd34f 100644 --- a/narps_open/data/results/__main__.py +++ b/narps_open/data/results/__main__.py @@ -8,7 +8,6 @@ from narps_open.data.results import ResultsCollectionFactory from narps_open.pipelines import implemented_pipelines - def main(): """ Entry-point for the command line tool narps_results """ @@ -16,7 +15,7 @@ def main(): parser = ArgumentParser(description='Get Neurovault collection of results from NARPS teams.') group = parser.add_mutually_exclusive_group(required = True) group.add_argument('-t', '--teams', nargs='+', type=str, action='extend', - help='a list of team IDs') + help='a list of team IDs', choices=implemented_pipelines.keys()) group.add_argument('-a', '--all', action='store_true', help='download results from all teams') parser.add_argument('-r', '--rectify', action='store_true', default = False, required = False, help='rectify the results') diff --git a/narps_open/pipelines/__main__.py b/narps_open/pipelines/__main__.py new file mode 100644 index 00000000..60fd5c76 --- /dev/null +++ b/narps_open/pipelines/__main__.py @@ -0,0 +1,30 @@ +#!/usr/bin/python +# coding: utf-8 + +""" Provide a command-line interface for the package narps_open.pipelines """ + +from argparse import ArgumentParser + +from narps_open.pipelines import get_implemented_pipelines + +def main(): + """ Entry-point for the command line tool narps_open_pipeline """ + + # Parse arguments + parser = ArgumentParser(description='Get description of a NARPS pipeline.') + parser.add_argument('-v', '--verbose', action='store_true', + help='verbose mode') + arguments = parser.parse_args() + + # Print header + print('NARPS Open Pipelines') + + # Print general information about NARS Open Pipelines + print('A codebase reproducing the 70 pipelines of the NARPS study (Botvinik-Nezer et al., 2020) shared as an open resource for the community.') + + # Print pipelines + implemented_pipelines = get_implemented_pipelines() + print(f'There are currently {len(implemented_pipelines)} implemented pipelines: {implemented_pipelines}') + +if __name__ == '__main__': + main() diff --git a/narps_open/runner.py b/narps_open/runner.py index 32c80180..16eab000 100644 --- a/narps_open/runner.py +++ b/narps_open/runner.py @@ -17,6 +17,7 @@ get_participants_subset ) from narps_open.utils.configuration import Configuration +from narps_open.pipelines import get_implemented_pipelines class PipelineRunner(): """ A class that allows to run a NARPS pipeline. """ @@ -158,7 +159,7 @@ def main(): # Parse arguments parser = ArgumentParser(description='Run the pipelines from NARPS.') parser.add_argument('-t', '--team', type=str, required=True, - help='the team ID') + help='the team ID', choices=get_implemented_pipelines()) subjects = parser.add_mutually_exclusive_group(required=True) subjects.add_argument('-s', '--subjects', nargs='+', type=str, action='extend', help='a list of subjects to be selected') diff --git a/narps_open/tester.py b/narps_open/tester.py index 1a2cf284..c3b48ecd 100644 --- a/narps_open/tester.py +++ b/narps_open/tester.py @@ -8,13 +8,15 @@ import pytest +from narps_open.pipelines import get_implemented_pipelines + def main(): """ Entry-point for the command line tool narps_open_tester """ # Parse arguments parser = ArgumentParser(description='Test the pipelines from NARPS.') parser.add_argument('-t', '--team', type=str, required=True, - help='the team ID') + help='the team ID', choices=get_implemented_pipelines()) arguments = parser.parse_args() sys.exit(pytest.main([