Documentation fixes

CONTRIBUTING.md

@@ -1,74 +1,70 @@
 # How to contribute to NARPS Open Pipelines ? 
 
 For the reproductions, we are especially looking for contributors with the following profiles:
- - 👩‍🎤 SPM, FSL, AFNI or nistats has no secrets for you? You know this fMRI analysis software by heart 💓. Please help us by reproducing the corresponding NARPS pipelines. 👣 after step 1, follow the fMRI expert trail.
- - 🧑‍🎤 You are a nipype guru? 👣 after step 1, follow the nipype expert trail.
+ - `🧠 fMRI soft` SPM, FSL, AFNI or nistats has no secrets for you ; you know one of these fMRI analysis tools by :heart:.
+ - `🐍 Python` You are a Python guru, willing to use [Nipype](https://nipype.readthedocs.io/en/latest/).
 
-# Step 1: Choose a pipeline to reproduce :keyboard:
-:thinking: Not sure which pipeline to start with ? 🚦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 in red (not started).
+In the following, read the instruction sections where the badge corresponding to your profile appears.
 
-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.
+## 1 - Choose a pipeline
+`🧠 fMRI soft` `🐍 Python`
 
-When you are ready, [start an issue](https://github.com/Inria-Empenn/narps_open_pipelines/issues/new/choose) and choose **Pipeline reproduction**!
+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: .
 
-# Step 2: Reproduction 
+> [!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.
 
-## 🧑‍🎤 NiPype trail
+## 2 - Interact using issues
+`🧠 fMRI soft` `🐍 Python`
 
-We created templates with modifications to make and holes to fill to create a pipeline. You can find them in [`narps_open/pipelines/templates`](/narps_open/pipelines/templates).
+Browse [issues](https://github.com/Inria-Empenn/narps_open_pipelines/issues/) before starting a new one. If the pipeline is :orange_circle:, the associated issues are listed on the [pipeline dashboard](https://github.com/Inria-Empenn/narps_open_pipelines/wiki/pipeline_status).
 
-If you feel it could be better explained, do not hesitate to suggest modifications for the templates.
+You can either:
+* comment on an existing issue with details or your findings about the pipeline;
+* [start an issue](https://github.com/Inria-Empenn/narps_open_pipelines/issues/new/choose) and choose **Pipeline reproduction**.
 
-Feel free to have a look to the following pipelines, these are examples :
-| team_id | softwares | fmriprep used ? | pipeline file |
-| --- | --- | --- | --- |
-| 2T6S | SPM | Yes | [/narps_open/pipelines/team_2T6S.py](/narps_open/pipelines/team_2T6S.py) |
-| X19V | FSL | Yes | [/narps_open/pipelines/team_X19V.py](/narps_open/pipelines/team_2T6S.py) |
+> [!WARNING]
+> As soon as the issue is marked as `🏁 status: ready for dev` you can proceed to the next step.
 
-## 👩‍🎤 fMRI software trail
+## 3 - Use pull requests
+`🐍 Python`
 
-...
+1. [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository;
+2. create a separate branch for the issue you're working on (do not make changes to the default branch of your fork).
+3. push your work to the branch as soon as possible;
+4. visit [this page](https://github.com/Inria-Empenn/narps_open_pipelines/pulls) to start a draft pull request.
 
-## Find or propose an issue :clipboard:
-Issues are very important for this project. If you want to contribute, you can either **comment an existing issue** or **proposing a new issue**. 
+> [!WARNING]
+> Make sure you create a **Draft Pull Request** as described [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork), and please stick to the description of the pull request template as much as possible.
 
-### Answering an existing issue :label:
-To answer an existing issue, make a new comment with the following information: 
-  - Your name and/or github username
-  - The step you want to contribute to 
-  - The approximate time needed 
+## 4 - Reproduce pipeline
 
-### Proposing a new issue :bulb:
-In order to start a new issue, click [here](https://github.com/Inria-Empenn/narps_open_pipelines/issues/new/choose) and choose the type of issue you want:
-  - **Feature request** if you aim at improving the project with your ideas ;
-  - **Bug report** if you encounter a problem or identified a bug ;
-  - **Classic issue** to ask question, give feedbacks...
+### Translate the pipeline description into code
+`🐍 Python`
 
-Some issues are (probably) already open, please browse them before starting a new one. If your issue was already reported, you may want complete it with details or other circumstances in which a problem appear. 
+Write your code and push it to the branch. Make sure you perform all the items of the pull request checklist.
 
-## Pull Requests :inbox_tray:
-Pull requests are the best way to get your ideas into this repository and to solve the problems as fast as possible.
+From the description provided by the team you chose, write Nipype workflows that match the steps performed by the teams (preprocessing, run level analysis, subject level analysis, group level analysis).
 
-### Make A Branch :deciduous_tree:
-Create a separate branch for each issue you're working on. Do not make changes to the default branch (e.g. master, develop) of your fork.
+We created templates with modifications to make and holes to fill to help you with that. Find them in [`narps_open/pipelines/templates`](/narps_open/pipelines/templates).
 
-### Push Your Code :outbox_tray:
-Push your code as soon as possible.
+> [!TIP]
+> Have a look to the already reproduced pipelines, as examples :
+> | team_id | softwares | fmriprep used ? | pipeline file |
+> | --- | --- | --- | --- |
+> | Q6O0 | SPM | Yes | [/narps_open/pipelines/team_Q6O0.py](/narps_open/pipelines/team_Q6O0.py) |
 
-### Create the Pull Request (PR) :inbox_tray:
-Once you pushed your first lines of code to the branch in your fork, visit [this page](https://github.com/Inria-Empenn/narps_open_pipelines/pulls) to start creating a PR for the NARPS Open Pipelines project.
+Once your work is ready, you may ask a reviewer to your pull request, as described [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review). Please turn your draft pull request into a *regular* pull request, by clicking **Ready for review** in the pull request page.
 
-:warning: Please create a **Draft Pull Request** as described [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork), and please stick to the PR description template as much as possible.
+### Run the pipeline and produce evidences
+`🧠 fMRI soft`
 
-Continue writing your code and push to the same branch. Make sure you perform all the items of the PR checklist.
+From the description provided by the team you chose, perform the analysis on the associated software to get as many metadata (log, configuration files, and other relevant files for reproducibility) as possible from the execution. Complementary hints and comments on the process would definitely be welcome, to enrich the description (e.g.: relevant parameters not written in the description, etc.).
 
-### Request Review :disguised_face:
-Once your PR is ready, you may add a reviewer to your PR, as described [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/requesting-a-pull-request-review) in the GitHub documentation.
+Especially these files contain valuable information about model design:
+* for FSL pipelines, `design.fsf` setup files coming from FEAT ;
+* for SPM pipelines, `matlabbatch` files.
 
-Please turn your Draft Pull Request into a "regular" Pull Request, by clicking **Ready for review** in the Pull Request page.
+You can attach these files as comments on the pipeline reproduction issue.
 
-**:wave: Thank you in advance for contributing to the project!**
-
-## Additional resources
-
- - git and Gitub: general guidelines can be found [here](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) in the GitHub documentation. 
+**:wave: Thank you for contributing to the project!**

README.md

@@ -1,4 +1,4 @@
-# The NARPS Open Pipelines project
+# NARPS Open Pipelines
 
 <p align="center">
 	<img src="assets/images/project_illustration.png"/> 
@@ -15,8 +15,6 @@
         <img src="https://img.shields.io/github/commit-activity/m/Inria-Empenn/narps_open_pipelines" /></a>
 </p>
 
-## Project presentation
-
 **The goal of the NARPS Open Pipelines project is to create a codebase reproducing the 70 pipelines of the NARPS study (Botvinik-Nezer et al., 2020) and share this as an open resource for the community**. 
 
 We base our reproductions on the [original descriptions provided by the teams](https://github.com/poldrack/narps/blob/1.0.1/ImageAnalyses/metadata_files/analysis_pipelines_for_analysis.xlsx) and test the quality of the reproductions by comparing our results with the original results published on NeuroVault.
@@ -25,16 +23,17 @@ We base our reproductions on the [original descriptions provided by the teams](h
 
 ## Contributing
 
-NARPS open pipelines uses [nipype](https://nipype.readthedocs.io/en/latest/index.html) as a workflow manager and provides a series of templates and examples to help reproduce the different teams’ analysis. 
+There are many ways you can contribute 🤗 :wave: Any help is welcome ! 
+
+NARPS Open Pipelines uses [nipype](https://nipype.readthedocs.io/en/latest/index.html) as a workflow manager and provides a series of templates and examples to help reproducing the different teams’ analyses. Nevertheless knowing Python or Nipype is not required to take part in the project.
 
-There are many ways you can contribute 🤗 :wave: Any help is welcome ! Follow the guidelines in [CONTRIBUTING.md](/CONTRIBUTING.md) if you wish to get involved !
+Follow the guidelines in [CONTRIBUTING.md](/CONTRIBUTING.md) if you wish to get involved !
 
-### Installation
+## Using the codebase
 
-To get the pipelines running, please follow the installation steps in [INSTALL.md](/INSTALL.md)
+To get the pipelines running, please follow the installation steps in [INSTALL.md](/INSTALL.md).
 
-## Getting started
-If you are interested in using the codebase to run the pipelines, see the [user documentation (work-in-progress)].
+If you are interested in using the codebase, see the user documentation in [docs](/docs/) (work-in-progress).
 
 ## References
 
@@ -52,7 +51,8 @@ This project is supported by Région Bretagne (Boost MIND) and by Inria (Explora
 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.
 
 In addition, this project was presented and received contributions during the following events:
- - OHBM Brainhack 2022 (June 2022): Elodie Germani, Arshitha Basavaraj, Trang Cao, Rémi Gau, Anna Menacher, Camille Maumet.
- - e-ReproNim FENS NENS Cluster Brainhack (June 2023) : Liz Bushby, Boris Clénet, Michael Dayan, Aimee Westbrook.
- - OHBM Brainhack 2023 (July 2023): Arshitha Basavaraj, Boris Clénet, Rémi Gau, Élodie Germani, Yaroslav Halchenko, Camille Maumet, Paul Taylor.
- - ORIGAMI lab hackathon (Sept 2023): 
+ - [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): 

docs/README.md

@@ -2,14 +2,17 @@
 
 :mega: This is the starting point for the documentation of the NARPS open pipelines project.
 
-Here are the available topics :
-
-* :runner: [running](/docs/running.md) tells you how to run pipelines in NARPS open pipelines
-* :brain: [data](/docs/data.md) contains instructions to handle the data needed by the project
-* :hammer_and_wrench: [environment](/docs/environment.md) contains instructions to handle the software environment needed by the project
-* :goggles: [description](/docs/description.md) tells you how to get convenient descriptions of the pipelines, as written by the teams involved in NARPS.
-* :microscope: [testing](/docs/testing.md) details the testing features of the project, i.e.: how is the code tested ?
-* :package: [ci-cd](/docs/ci-cd.md) contains the information on how continuous integration and delivery (knowned as CI/CD) is set up.
-* :writing_hand: [pipeline](/docs/pipelines.md) tells you all you need to know in order to write pipelines
-* :compass: [core](/docs/core.md) a list of helpful functions when writing pipelines
-* :vertical_traffic_light: [status](/docs/status.md) contains the information on how to get the work progress status for a pipeline.
+## Use the project
+* :brain: [data](/docs/data.md) - Handle the needed data.
+* :hammer_and_wrench: [environment](/docs/environment.md) - Handle the software environment.
+* :rocket: [running](/docs/running.md) - Launch pipelines !
+
+## Contribute to the code
+* :goggles: [description](/docs/description.md) - Conveniently access descriptions of the pipelines, as written by the teams involved in NARPS.
+* :writing_hand: [pipelines](/docs/pipelines.md) - How to write pipelines.
+* :compass: [core](/docs/core.md) - Helpful functions for writing pipelines.
+* :microscope: [testing](/docs/testing.md) - How to test the code.
+
+## For maintainers
+* :vertical_traffic_light: [status](/docs/status.md) - Work progress status for pipelines.
+* :package: [ci-cd](/docs/ci-cd.md) - Continuous Integration and Delivery (a.k.a. CI/CD).

docs/ci-cd.md

@@ -35,10 +35,10 @@ For now, the following workflows are set up:
 | Name / File | What does it do ? | When is it launched ? | Where does it run ? | How can I see the results ? |
 | ----------- | ----------- | ----------- | ----------- | ----------- |
 | [code_quality](/.github/workflows/code_quality.yml) | A static analysis of the python code (see the [testing](/docs/testing.md) topic of the documentation for more information). | For every push or pull_request if there are changes on `.py` files. | On GitHub servers. | Outputs (logs of pylint) are stored as [downloadable artifacts](https://docs.github.com/en/actions/managing-workflow-runs/downloading-workflow-artifacts) during 15 days after the push. |
-| [codespell](/.github/workflows/codespell.yml) | A static analysis of the text files for commonly made typos using [codespell](codespell-project/codespell: check code for common misspellings). | For every push or pull_request to the `maint` branch. | On GitHub servers. | Outputs (logs of codespell) are stored as [downloadable artifacts](https://docs.github.com/en/actions/managing-workflow-runs/downloading-workflow-artifacts) during 15 days after the push. |
+| [codespell](/.github/workflows/codespell.yml) | A static analysis of the text files for commonly made typos using [codespell](https://github.com/codespell-project/codespell). | For every push or pull_request to the `main` branch. | On GitHub servers. | Typos are displayed in the workflow summary. |
 | [pipeline_tests](/.github/workflows/pipelines.yml) | Runs all the tests for changed pipelines. | For every push or pull_request, if a pipeline file changed. | On Empenn runners. | Outputs (logs of pytest) are stored as downloadable artifacts during 15 days after the push. |
 | [test_changes](/.github/workflows/test_changes.yml) | It runs all the changed tests for the project. | For every push or pull_request, if a test file changed. | On Empenn runners. | Outputs (logs of pytest) are stored as downloadable artifacts during 15 days after the push. |
-| [unit_testing](/.github/workflows/unit_testing.yml) | It runs all the unit tests for the project (see the [testing](/docs/testing.md) topic of the documentation for more information). | For every push or pull_request, if a file changed inside `narps_open/`, or a file related to test execution. | On GitHub servers. | Outputs (logs of pytest) are stored as downloadable artifacts during 15 days after the push. |
+| [unit_testing](/.github/workflows/unit_testing.yml) | It runs all the unit tests for the project (see the [testing](/docs/testing.md) topic of the documentation for more information). | For every push or pull_request, if a file changed inside `narps_open/`, or a file related to test execution. | On Empenn runners. | Outputs (logs of pytest) are stored as downloadable artifacts during 15 days after the push. |
 
 ### Cache
 

docs/data.md

@@ -2,7 +2,7 @@
 
 The datasets used for the project can be downloaded using one of the two options below.
 
-The path to these datasets must conform with the information located in the configuration file you plan to use (cf. [documentation about configuration](docs/configuration.md)). By default, these paths are in the repository:
+The path to these datasets must conform with the information located in the configuration file you plan to use (cf. [documentation about configuration](/docs/configuration.md)). By default, these paths are in the repository:
    * `data/original/`: original data from NARPS
    * `data/results/`: results from NARPS teams