diff --git a/.github/ISSUE_TEMPLATE/bids_apps_submission.yml b/.github/ISSUE_TEMPLATE/bids_apps_submission.yml index 0d9dc308..76809328 100644 --- a/.github/ISSUE_TEMPLATE/bids_apps_submission.yml +++ b/.github/ISSUE_TEMPLATE/bids_apps_submission.yml @@ -11,10 +11,10 @@ body: - type: markdown attributes: value: | - - Have you checked our [contributing guide](https://github.com/bids-apps/bids-apps.github.io/blob/master/CONTRIBUTING.md)? + - Have you checked our [contributing guide](https://bids-website.readthedocs.io/en/latest/collaboration/bids_github/CONTRIBUTING.html)? It's a helpful resource. - - Have you checked our [FAQ](https://bids-apps.neuroimaging.io/dev_faq/)? + - Have you checked our [FAQ](https://bids-website.readthedocs.io/en/latest/faq/bids-apps.html)? - type: textarea attributes: @@ -30,7 +30,7 @@ body: More details here: - https://github.com/bids-apps/bids-apps.github.io/blob/761bcd927ddce83e80e9f898dce1864d9bcb9b04/_config.yml#L64 + https://github.com/bids-standard/bids-website/blob/81c642691150e00c08ad4450dbdb05eb794f8f9a/data/tools/apps.yml#L3 For example: diff --git a/docs/collaboration/governance.md b/docs/collaboration/governance.md index c634f699..f627fb66 100644 --- a/docs/collaboration/governance.md +++ b/docs/collaboration/governance.md @@ -60,7 +60,7 @@ users to confirm that a given dataset complies with the current edition of the standard, the [PyBIDS](https://github.com/bids-standard/pybids) Python and [bids-matlab](https://github.com/bids-standard/bids-matlab) libraries allow querying and manipulating BIDS-compliant datasets, -[BIDS-Apps](https://bids-apps.neuroimaging.io/) for running portable +[BIDS-Apps](https://bids-website.readthedocs.io/en/latest/tools/bids-apps.html) for running portable pipelines on validated BIDS datasets, and platforms like [OpenNeuro](https://openneuro.org/) store and serve BIDS datasets. Note that the associated software does not fall under the same governance diff --git a/docs/collaboration/index.md b/docs/collaboration/index.md index 9ed1c1de..537271d5 100644 --- a/docs/collaboration/index.md +++ b/docs/collaboration/index.md @@ -39,7 +39,7 @@ Below is a list of common resources where users can get involved in making the B There are so many ways to help us build this community. - You could help someone else learn the benefits of BIDS by giving a talk in your local organization -- Or you could work on [building a BIDS App](https://bids-apps.neuroimaging.io/){:target="_blank"}! +- Or you could work on [building a BIDS App](https://bids-website.readthedocs.io/en/latest/tools/bids-apps.html){:target="_blank"}! The only requirement is that everyone who contributes adheres to our [BIDS Code of Conduct](https://github.com/bids-standard/bids-specification/blob/master/CODE_OF_CONDUCT.md). diff --git a/docs/faq/bids-apps.md b/docs/faq/bids-apps.md index bc92278f..50542343 100644 --- a/docs/faq/bids-apps.md +++ b/docs/faq/bids-apps.md @@ -1,96 +1,68 @@ -## Can I add more arguments to the API of my App? +# BIDS apps -Every BIDS App must use the mandatory arguments mentioned above, but you are -free to add more that are specific to the task your App will perform. +!!! note -We recommend you follow the guidelines mentioned in the -[BIDS extension proposal 027](https://bids.neuroimaging.io/bep027) -for more information on specifying the API of your App. + Make sure to check out the [nipreps wesbite](https://www.nipreps.org/) + for more information on using and creating BIDS apps. -## How can I check a version of a container I have available locally? +!!! warning -Inside each BIDS App there is a /version file with the version number. + If you are developing a BIDS app, + make sure to check the [BIDS apps specification](https://bids-standard.github.io/execution-spec/). -This file is automatically populated with tag used to trigger the build on the CI server. +## For users -## How can I download a particular version of a BIDS App? +### How can I check a version of a container I have available locally? -All versions of BIDS Apps are archived on Docker Hub. To access a particular -version you should refer to a specific Docker Hub tag. For example: +For many bids-app you should be able to run something like: ```bash -docker pull bids/example:v0.0.5 +docker run bids/example --version ``` -## How do I upload my BIDS App to the BIDS App Github org? - -You can release BIDS Apps using your own or your lab's account. -However, if you want to be added to the BIDS docker hub, -please message the [BIDS maintainers](mailto:bids.maintenance+apps@gmail.com) -to have a repo created for you. - -If you base your code on deployment on -docker hub will happen automatically via Circle-ci. - -If you want your App to show on the BIDS App website -[here](https://bids-apps.neuroimaging.io/apps/), you will in any case have to -update the `_config.yml` in the -[BIDS App website repository](https://github.com/bids-apps/bids-apps.github.io.git). +Inside each BIDS App there is a `/version` file with the version number. -## How should I version my BIDS App? - -Since most BIDS Apps are just thin wrappers around existing pipelines it would -be most sensible to use the same version as the software they are wrapping. +This file is automatically populated with tag used to trigger the build on the CI server. -For example in case of HCP Pipelines this would be `v3.17.0`. +## How can I download a particular version of a BIDS App? -## How to tag a new release? +All versions of BIDS Apps are archived on Docker Hub. To access a particular +version you should refer to a specific Docker Hub tag. For example: ```bash -git tag v0.0.1 -git push +docker pull bids/example:v0.0.5 ``` -## I want to release a new version of a BIDS App, but the pipeline version is the same? - -This can happen when only the runscript or the Dockerfile changed? -According to semantic versioning we should use the `+` signed followed by the build number. -Unfortunately Docker Hub does not support semantic versioning. -The best option is to use the `-` sign followed by the build number. -For example `v3.17.0-3`. +## What do the analysis levels (`participant` and `group`) mean? -## Is it mandatory to first check the dataset validity using the BIDS-validator? +Generally, `participant` means individual level analysis (for instance: single subject). +The `group` level analysis can be thought of as the second step, +where the input becomes the output of the `participant` level analysis. -It is an extremely helpful feature to have validation of the dataset as part of your tool. -However, it's not considered mandatory. -For instance: many Apps will -simply fail with an error message if the dataset is not BIDS compliant. +For example, generating statistic maps of each subject's brain could be considered `participant`, +while generating the average of these maps across the dataset could be considered `group`. -## Is there a BIDS App template? +## For developers -Have a look at the -[example BIDS App repository](https://github.com/bids-apps/example). A -minimalist example of a BIDS App consisting of a Dockerfile and a simple entry -point script (written in this case in Python) accepting the standard BIDS Apps -command line arguments. +### Getting started -## What do the analysis levels (`participant` and `group`) mean? +#### Is there a BIDS App template? -Generally, `participant` means individual level analysis (for instance: single -subject) The group level analysis can be thought of as the second step, where -the input becomes the output of the `participant` level analysis. +Have a look at the +[example BIDS App repository](https://github.com/bids-apps/example). +A minimalist example of a BIDS App consisting of a Dockerfile +and a simple entry point script (written in this case in Python) +accepting the standard BIDS Apps command line arguments. -For example, generating statistic maps of each subject's brain could be -considered `participant`, while generating the average of these maps across the -dataset could be considered `group`. +#### Which container should I use to start building my app? -## What do we do if our application does not have any use for the group level analysis? +The only minimum requirements of a BIDS App's container is its ability to run your pipeline. +So for example, if your App is mostly Python based it should be sufficient +to start with any image that has Python and include your environment dependencies. -If your pipeline has no need for group level analysis, it is fine if it is only -valid for the analysis_level argument (see -[fmriprep](https://fmriprep.readthedocs.io/en/latest/usage.html)) +### API -## What should the API of my BIDS App look like? +#### What should the API of my BIDS App look like? The obligatory arguments of the API of any BIDS App are: @@ -104,20 +76,59 @@ with an API call that would look like this: app_name bids_dir output_dir analysis_level ``` -## When is a new image deposited to Docker Hub? +#### What do we do if my application does not have any use for the group level analysis? -Even though Docker image is being build on the CI server each time -you push a commit to the repository it is not automatically being pushed to Docker Hub. -Only if you tag a commit, push the tag to GitHub, -and the tests you configured pass a new image will be deposited in Docker Hub. +If your pipeline has no need for group level analysis, +it is fine if it is only valid for the analysis_level argument +(see [fmriprep](https://fmriprep.readthedocs.io/en/latest/usage.html)). -## Where can I can data to test my app +#### Can I add more arguments to the API of my App? + +Every BIDS App must use the mandatory arguments mentioned above, +but you are free to add more that are specific to the task your App will perform. + +We recommend you follow the guidelines mentioned in the [BIDS apps specification](https://bids-standard.github.io/execution-spec/) +for more information on specifying the API of your App. + +### Testing + +#### Where can I can get data to test my app? For both lightweight and full datasets to test your BIDS App, you can choose from one of these [example datasets](https://bids-standard.github.io/bids-starter-kit/dataset_examples.html) -## Where should I describe changes between versions? +#### Is it mandatory to first check the dataset validity using the BIDS-validator? + +It is an extremely helpful feature to have validation of the dataset as part of your tool. +However, it's not considered mandatory. +For instance: many Apps will simply fail with an error message if the dataset is not BIDS compliant. + +### Version + +#### How should I version my BIDS App? + +Since most BIDS Apps are just thin wrappers around existing pipelines it would +be most sensible to use the same version as the software they are wrapping. + +For example in case of HCP Pipelines this would be `v3.17.0`. + +#### How to tag a new release? + +```bash +git tag v0.0.1 +git push +``` + +#### I want to release a new version of a BIDS App, but the pipeline version is the same? + +This can happen when only the runscript or the Dockerfile changed? +According to semantic versioning we should use the `+` signed followed by the build number. +Unfortunately Docker Hub does not support semantic versioning. +The best option is to use the `-` sign followed by the build number. +For example `v3.17.0-3`. + +#### Where should I describe changes between versions? After tagging a new release it is important to provide a list of changes on the GitHub Releases page. @@ -126,13 +137,25 @@ It accepts markdown syntax and allows you to explain in detail what has changed. Here's an [example](https://github.com/bids-apps/example/releases). -## Which container should I use to start building my app? +### Deplopying + +#### How do I upload my BIDS App to the BIDS App Github org? -The only minimum requirements of a BIDS App's container is its ability to run -your pipeline. So for example, if your App is mostly Python based it should be -sufficient to start with any image that has Python and include your environment -dependencies. +You can release BIDS Apps using your own or your lab's account. +However, if you want to be added to the BIDS docker hub, +please message the [BIDS maintainers](mailto:bids.maintenance+apps@gmail.com) +to have a repo created for you. + +If you base your code on deployment +on docker hub will happen automatically via Circle-ci. -
+If you want your App to show on the [BIDS website](https://bids-website.readthedocs.io/en/latest/tools/bids-apps.html), +you will have to update the `data/tools/apps.yml` in the +[BIDS website repository](https://github.com/bids-standard/bids-website/tree/main). -Generated by [FAQtory](https://github.com/willmcgugan/faqtory) +#### When is a new image deposited to Docker Hub? + +Even though Docker image is being build on the CI server each time +you push a commit to the repository it is not automatically being pushed to Docker Hub. +Only if you tag a commit, push the tag to GitHub, +and the tests you configured pass a new image will be deposited in Docker Hub. diff --git a/docs/faq/bids-extensions.md b/docs/faq/bids-extensions.md index b5f5b2d3..3bc34d1d 100644 --- a/docs/faq/bids-extensions.md +++ b/docs/faq/bids-extensions.md @@ -17,7 +17,3 @@ See [bids-specification issue #1177](https://github.com/bids-standard/bids-specification/issues/1177) for an example of the reasoning that led to the application of an entity previously used for functional data to anatomical MRI. - -
- -Generated by [FAQtory](https://github.com/willmcgugan/faqtory) diff --git a/docs/faq/eeg.md b/docs/faq/eeg.md index e1c29929..58abe808 100644 --- a/docs/faq/eeg.md +++ b/docs/faq/eeg.md @@ -36,7 +36,3 @@ This is the case for Biosemi, as further documented on For a formatted example on how to deal with this in the BIDS context, please see this [template](https://github.com/bids-standard/bids-starter-kit/blob/main/templates/sub-01/ses-01/eeg/sub-01_ses-01_task-ReferenceExample_eeg.json). - -
- -Generated by [FAQtory](https://github.com/willmcgugan/faqtory) diff --git a/docs/faq/general.md b/docs/faq/general.md index a056ac87..349ca1bd 100644 --- a/docs/faq/general.md +++ b/docs/faq/general.md @@ -182,7 +182,3 @@ page dedicated to this topic. If you plan to put your dataset on [openneuro](https://openneuro.org/), you should use a CC0 or a PDDL license as explained in their [FAQ](https://openneuro.org/faq). - -
- -Generated by [FAQtory](https://github.com/willmcgugan/faqtory) diff --git a/docs/faq/mri.md b/docs/faq/mri.md index 7d3b4a20..2638f5eb 100644 --- a/docs/faq/mri.md +++ b/docs/faq/mri.md @@ -89,7 +89,3 @@ Otherwise you can also use: - [Fieldtrip](http://www.fieldtriptoolbox.org/faq/how_can_i_anonymize_an_anatomical_mri/) under matlab can do it. - SPM8 and SPM12: when in the batch editor go to: `SPM menu --> Util --> Deface` - -
- -Generated by [FAQtory](https://github.com/willmcgugan/faqtory) diff --git a/docs/faq/phenotype.md b/docs/faq/phenotype.md index 4a3eaccc..4f3b0d34 100644 --- a/docs/faq/phenotype.md +++ b/docs/faq/phenotype.md @@ -17,7 +17,3 @@ Yes, open this [epilepsyClassification2017](https://github.com/bids-standard/bids-starter-kit/blob/main/interactiveTreeVisualization/epilepsyClassification2017/tree.html) and follow the examples in the [phenotype templates](https://github.com/bids-standard/bids-starter-kit/tree/main/templates/phenotype). - -
- -Generated by [FAQtory](https://github.com/willmcgugan/faqtory) diff --git a/docs/impact/index.md b/docs/impact/index.md index c5971668..f7a9e940 100644 --- a/docs/impact/index.md +++ b/docs/impact/index.md @@ -77,7 +77,7 @@ You can also find them [in the specification](https://bids-specification.readthe | statistical model | ![PyPI - Downloads](https://img.shields.io/pypi/dm/bsmschema) | For the number of docker pulls of the BIDS apps, please check the -[BIDS app dashboard](https://bids-apps.neuroimaging.io/apps/). +[BIDS app dashboard](https://bids-website.readthedocs.io/en/latest/tools/bids-apps.html). ### Contributors