[ENH] Update ezBIDS documentation

docs/tutorial/ezBIDS.md

@@ -1,6 +1,6 @@
 # **ezBIDS Tutorial**
 
-The page provides a simple tutorial for using [ezBIDS](https://brainlife.io/ezbids). The goal of this tutorial is to demonstrate how to use ezBIDS in order to convert raw imaging data to BIDS. For more in-depth information regarding the functionality and features of ezBIDS, please refer to the [user documentation](https://brainlife.io/docs/using_ezBIDS/).
+This page provides a simple tutorial for using [ezBIDS](https://brainlife.io/ezbids). The goal of this tutorial is to demonstrate how to use ezBIDS in order to convert imaging data to BIDS. For more in-depth information regarding the functionality and features of ezBIDS, please refer to the [user documentation](https://brainlife.io/docs/using_ezBIDS/).
 
 Before we begin, we'll need some test data, which can be found [here](https://drive.google.com/drive/folders/18Y0SuSAevh2pu7Wuv3BFnbrLZNlVMeJr?usp=sharing). After a few minutes, the data will be downloaded to your Downloads folder, titled "ezBIDS_tutorial_data".
 
@@ -174,7 +174,7 @@ The last item of business is to click on the **Download configuration/template**
 
 ## Feedback
 
-Congratulations, you've successfully used ezBIDS to create a BIDS-compliant dataset! If you have questions or wish to provide feedback you can reach us at the following channels:
-1. [Brainlife.io Slack](https://brainlife.io/slack)
-2. [E-mail: ezbids@brainlife.io](mailto:ezbids@brainlife.io)
-3. [Github Issues](https://github.com/brainlife/ezbids/issues)
+Congratulations, you've successfully used ezBIDS to create a BIDS-compliant dataset! If you have questions or wish to provide feedback you can reach us the following ways:
+
+1. Post on our brainlife.io [Slack channel](https://brainlife.io/slack)
+2. Submit a [GitHub Issue](https://github.com/brainlife/ezbids/issues)

docs/using_ezBIDS.md

@@ -40,19 +40,19 @@ For ezBIDS to access users' imaging data, the data must first be uploaded to ezB
 * **Raw DICOM data** from the scanner or imaging device.
 * **NIfTI/JSON data** converted from DICOMs using [dcm2niix](https://github.com/rordenlab/dcm2niix). If using this option, it is best if the [most recent](https://github.com/rordenlab/dcm2niix/releases) dcm2niix version was used. 
 
-!!! warning
+!!! note Data privacy
     Uploaded data can only be accessed through the unique URL with your session ID. Also, uploaded data are purged from the ezBIDS system after 5 days.
 
 ezBIDS prefers that non-anonymized data are uploaded (e.g. with the `-ba y` flag option in dcm2niix), as this makes it easier to discern the subject (and session, if applicable) mapping of the data and doesn’t require organizing the raw data in any specific manner. When non-anonymized, the data contains important metadata information such as the *AcquisitionDateTime*, *PatientName*, and *PatientID*, which help inform ezBIDS of the subject and session mappings. If however anonymized data are uploaded, which do not contain this metadata information, users will need to organize their data such that data from individual subject (and session) scans are in separate folders. To improve performance, these folder names should explicitly specify the subject (and session, if applicable) IDs desired (e.g., `sub-001`, `sub-001_ses-pre`, etc.). Users are not required to adhere to this naming convention, however, in such cases, ezBIDS will simply use the folder(s) name(s) as a placeholder for the subject (and session) IDs.
 
-!!! note "Non-anonymized Data"
+!!! note Non-anonymized Data
     If non-anonymized data are provided, ezBIDS will anonymize the data (i.e., remove identifying metadata) before converting to BIDS.
 
 Users may upload compressed imaging data using formats such as *.tar.xz*, *.tar*, *.tgz*, *.gz*, *.7z*, *.bz2*, *.zip*, and *.rar*.
 
 Once data are uploaded, ezBIDS performs several backend operations to gather and identify as much relevant BIDS information as possible, as well as general information to help users see what data they’re examining (e.g., image screenshots, metadata, etc.). All this information is then presented to users on the subsequent pages. Users may then edit or modify BIDS-specific information as they so choose. 
 
-!!! info "Upload Speed and Time"
+!!! info Upload Speed and Time
     The amount of time to upload data will depend on the size of the data being uploaded and the speed of the internet connection. 
 
 ezBIDS has been primarily tested on the Chrome and Firefox browsers; it is preferable that one of these browsers be used. 
@@ -65,7 +65,7 @@ This page allows users to provide general information regarding their dataset, s
 
 Users only need to provide information here the first time using ezBIDS with data from a new dataset. When using ezBIDS with newly acquired data from the same dataset as before, this information is already provided and is therefore redundant to specify again.
 
-!!! warning "Progress checks"
+!!! warning Progress checks
     For this and subsequent ezBIDS web pages, certain information is required by BIDS, indicated on each page with a red asterisk or circle. These fields must be entered, otherwise, users will be unable to progress to the next page. This provides users with real-time assistance on what information is required in order to have BIDS-compliant data, rather than going through the entire process only to learn afterward that there is an issue to resolve. 
 
 ### 4. Subjects and Sessions
@@ -80,7 +80,7 @@ ezBIDS organizes all uploaded data into specific series and group IDs (grouping
 
 ![Series Mapping](./img/ezbids/Levitas_etal_figureS5_series_mapping_all.png)
 
-!!! info
+!!! info Grouping procedure
     ezBIDS makes educated guesses about your data using information saved in the DICOM files.
     ezBIDS uses the DICOM fields *Series Description*, *Image Type*, *Echo Time*, and *Repetition Time* to group data together. This means that ezBIDS assumes that data with the matching values in these fields are part of the same series of data. ezBIDS then matches the Series to the corresponding [BIDS entities](https://bids-specification.readthedocs.io/en/stable/appendices/entities.html).
 
@@ -97,12 +97,12 @@ A critical feature of ezBIDS is the ability to support tasks and event files. If
 !!! warning 
     When uploading timing files, it is **crucial** that the following entity labels be explicitly specified: *subject*, (*session*, if applicable), *task*, and *run*. These must match the corresponding `func/bold` sequences. This information can either be provided in the file path or as columns in the timing data themselves. Failure to do so will result in ezBIDS creating a placeholder value for any mismatched entity labels that will later require manual intervention. 
 
-!!! info "ezBIDS assists users in dealing with timing events and units"
+!!! info ezBIDS assists users in dealing with timing events and units
     BIDS requires that timing files be translated into *events.tsv* format, with several required and optional columns. Required columns include the *onset* and *duration*. ezBIDS has the ability to assist users in cases where uploaded timing files do not have a column that specifically pertains to *onset* and *duration*. For example, rather than a column specifying trial durations, a file might contain a column for trial_onset and another column for trial_offset. Users can specify an arithmetic method (Subtract, Add) and choose the two columns that when subtracted or added create the duration value. It should be noted that this arithmetic approach only applies to event columns involving time-based values. Additionally, users can specify for timed-based columns whether the values are in seconds or milliseconds (BIDS requires that these values be reported in seconds).
 
 ![Events Mapping](./img/ezbids/Levitas_etal_figureS7_events_mapping.png)
 
-!!! warning "Timing files for different tasks"
+!!! warning Timing files for different tasks
     Currently, ezBIDS can only handle timing files that have identical column names. In theory, users can upload timing files pertaining to different `func/bold` tasks, but only if all files contain identical column names. 
 
 ### 7. Dataset Review
@@ -113,7 +113,7 @@ Upon reaching this page, all individual imaging sequences are provided in the or
 
 All modifications made on the Series Mapping and Events pages are applied. ezBIDS applies a run entity label to sequences if there were multiple occurrences during the scan. 
 
-!!! warning "Functional data exclusion"
+!!! warning Functional data exclusion
     ezBIDS applies a volume threshold on 4D data (e.g., `func`/`bold`) to check for sequences that might have had to be restarted during the scan. The threshold is calculated based on the expected number of volumes collected during a 60-sec period, given the TR (`60/TR`). If a 4D sequence does not meet this threshold, ezBIDS sets the datatype/suffix pair to `exclude`, unless modified by the user.
 
 ### 8. Deface
@@ -138,16 +138,18 @@ Once complete, two screens are presented. On the left is a Linux tree structure
 
 Once a BIDS-compliant dataset is generated, users can click on the blue "Download BIDS" button to download their zipped data to their local computer/server, and/or send their BIDS data to [OpenNeuro.org](https://openneuro.org/) or [brainlife.io](https://brainlife.io/about/). 
 
-!!! info "Downloading non-BIDS compliant data"
+!!! info Downloading non-BIDS compliant data
     Users may still download their BIDS dataset (or upload it elsewhere) even if the bids-validator returns error(s); however, users should know that their dataset is not fully BIDS-compliant and will need to be corrected at some point. 
 
 Lastly, upon completing the BIDS mapping, ezBIDS automatically generates a configuration template JSON file (`ezBIDS_template.json`) that details all information and changes made during the current ezBIDS session. This template can be uploaded with subsequent data from the same study, which reduces the time spent editing the BIDS structure on subsequent uploads of imaging data. See [here](#additional-information) for additional information. 
 
 ---
 ## Additional Information
+
 ezBIDS provides additional features to assist users in converting their data to BIDS. 
 
 **1. ezBIDS configuration templates**
+
 ezBIDS creates templates for scanning sessions. Any scanning session processed using ezBIDS can become a template for future sessions. ezBIDS Templates can be reused to automatically load the BIDS mapping configuration a user has identified. Templates are helpful in the common situation where the same scanning protocol is used for multiple sessions. Often, researchers set up a scanning protocol and configure a series of scans to be acquired on multiple subjects across the duration of a research project. When the scans from the first subject are uploaded and processed via ezBIDS the researcher is effectively creating an ezBIDS Template, automatically. ezBIDS Templates are JSON files created every time a dataset is processed via ezBIDS. To use the template all the user has to do is download the template and upload the template with any new sessions acquired in the future. ezBIDS Templates can be reused for any number of datasets and reduce users' interaction with the ezBIDS graphical interface. More specifically, after ezBIDS has converted a dataset to BIDS, users have the option to download the file `ezBIDS_template.json`. This file contains all information, to map the DICOMs to BIDS, including user edits and modifications, from the ezBIDS session. This file can be uploaded with new datasets. When done so, the information in the file is applied to the new ezBIDS session, all the graphical interface fields are loaded with the information initially set by the user, reducing time spent on edits. If a dataset is uploaded with the wrong template, or if the template needs to be modified, the user has the option to overwrite the template uploaded and use ezBIDS as usual via the graphical interface. The configuration also enables many-to-one or one-to-many mapping, meaning that the `ezBIDS_template.json` information can pertain to a single subject but be applied to a current upload with multiple subjects or even sessions. The `ezBIDS_template.json` file can be renamed if desired, however, it needs to end in `ezBIDS_template.json` in order for ezBIDS to know what to look for. Uploading an `ezBIDS_template.json` file will not let ezBIDS run automatically from start to finish, the user's review and approval are judicious.
 
 **2. ezBIDS errors and warnings**
@@ -157,22 +159,54 @@ ezBIDS creates templates for scanning sessions. Any scanning session processed u
 ezBIDS alerts users to BIDS validation errors and provides additional guidance to BIDS validation via custom warnings, to ensure BIDS compliance and to provide recommendations for improved curation of datasets. **Errors**. Marked by an “x” symbol (red). Errors identify details that prevent the dataset from being BIDS compliant, identical to BIDS validator errors. These are displayed in red and must be rectified by the user before proceeding. In the example, the task entity label is missing from the func/bold sequence, which is required by BIDS. ezBIDS therefore flags it as an error to alert the user that this must be addressed. **Warnings**. Marked by an “!” symbol (gold). Warnings offer recommended changes to the current BIDS structure that would improve the quality and curation of the dataset, and are displayed in dark yellow. Unlike errors, ezBIDS warnings are different from the BIDS validator warnings; ezBIDS warnings are unique recommendations presented to users as a way to improve the quality of details and metadata that the final BIDS datasets will be stored with. In the example, the user specifies the phase encoding direction (direction) entity label as “PA”, when in reality, ezBIDS knows that the correct label should be “AP”. Such warnings alert users to potential mistakes that might otherwise pass BIDS validation. ezBIDS is agnostic with regard to how users respond to these warnings, meaning that users can ignore warnings and proceed if they so choose, since warnings do not preclude BIDS compliance.
 
 **3. Adding metadata information**
+
 For certain data sequences, specific metadata is required to be specified in the corresponding sidecar JSON file. This information typically pertains to parameters of the data that is relevant to other researchers. ezBIDS provides users the ability to enter this information, guiding them to ensure BIDS compliance. Users can click on the "Edit Metadata" button to open a pop-up window to see the relevant metadata fields.
 
 ![metadata](./img/ezbids/ezBIDS_metadata_fields.png)
 
 ezBIDS groups metadata fields into three separate categories based on their requirement level, per the BIDS specification. Required, Recommended, and Optional. ezBIDS alerts users to metadata fields that are required to ensure ezBIDS compliance.
 
 **4. ezBIDS and dcm2niix**
+
 ezBIDS, like most BIDS converters, uses [dcm2niix](https://github.com/rordenlab/dcm2niix) to convert DICOM files to NIfTI, JSON, .bval, and .bvec files. The set of *dcm2niix* output files is required by BIDS. If dcm2niix generates an error for a specific series of DICOMS during the conversion process, ezBIDS will display the message for users.
 
 ![dcm2niix error](./img/ezbids/ezBIDS_dcm2niix_error.png)
 
 It is recommended that users open an issue on the dcm2niix [issues page](https://github.com/rordenlab/dcm2niix/issues) to resolve any detected dcm2niix-specific errors. However, users may still proceed with ezBIDS, as the error does not pertain to the entire uploaded data but rather a specific DICOM file(s). It should be noted though that the offending file(s) might result in an improper or corrupted NIfTI file that doesn't properly convert to BIDS. 
 
 **5. ezBIDS and data visualization**
+
 ezBIDS uses [NiiVue](https://github.com/niivue/niivue) to visualize data. *NiiVue* is a web-based visualization tool for neuroimaging that can run on any operating system and any web device (phone, tablet, computer). On each image screenshot, users may click on the "NiiVue" button to open NiiVue and view their data.
 
+---
+## Types of data supported
+
+ezBIDS provides BIDS conversion support for the following data modalities:
+1. **MRI**
+   * *Including arterial spin labeling (ASL)*
+   * *Including functional bold task events*
+2. **DWI**
+3. **PET**
+   * *Including blood recording data*
+4. **MEG**
+
+!!! warning PET and MEG
+    Support for these modalities are relatively new and in the beta stage. Improvements will continue as users submit issues pertaining to to bugs and other related requests.
+
+---
+## Installing ezBIDS locally
+
+Although ezBIDS is a web-based service that does not require installation, some users may wish to install it on their local machine or server. The main advantage here is that data is not uploaded to the ezBIDS server (i.e. data remains on-site). Instead, data is copied within one of the ezBIDS containers (handler) at */tmp/ezbids-workdir*. However, with this approach users cannot upload their finalized BIDS-compliant data to brainlife.io via ezBIDS, as this requires authentication that isn't available with a local installation. With that said, installing ezBIDS locally consists of a few simple steps in the terminal/CLI:
+
+1. *git clone https://github.com/brainlife/ezbids*
+2. *cd ezbids && ./dev.sh -d*
+
+!!! warning Software requirements
+    Users must have both [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/) on their machine.
+
+!!! note ezBIDS on HPCs
+    Users wishing to install ezBIDS on their institution's HPC will not have access to Docker or Docker Compose. ezBIDS is currently unsupported by Singularity, and thus users should reach out to system administrators to see if installation of ezBIDS can be supported.
+
 ---
 ## FAQ
 
@@ -188,3 +222,8 @@ Dozens of users at multiple institutions have used ezBIDS for research and educa
 | _Are there any differences in how ezBIDS stores users data for example when downloading the BIDS data or pushing the data to OpenNeuro.org, brainlife.io?_ | No, all data sets are treated the same, software services process the data without human intervention and regardless of user selections. |
 | _If users’ data were collected under an IRB that states that the data will only be stored on university servers; will I be non-compliant if I use ezBIDS on these data?_ | The answer is “possibly, yes,” and it is such only if the IRB does not specify what it is meant by the phrase “to store data,” i.e., long term preservation. ezBIDS is not a long-term preservation system nor a data archive. ezBIDS stores users data, in most cases, outside of the users’ University servers for up to 5 days for the sole purpose to provide a service to the user and without human intervention or actions on the data. |
 | _Will my IRB consider this to be data sharing, given that the data are temporarily being stored on non-university servers?_ | Generally data sharing is between two humans or human groups. ezBIDS is a software service and no human receives, accesses or operates on the data, so technically the data is never shared. Yet, different IRBs make different decisions on this issue, and it will be important for the user to discuss this with their IRB prior to using ezBIDS, if the user believes concerns might arise from using the service. The ezBIDS team provides boilerplate text to assist the user in these discussions. 
+
+---
+## Contributing to ezBIDS
+
+ezBIDS is a community-drive project, and as such, contributions are both welcome and encouraged. For technical contributions, it is highly recommended that users locally install ezBIDS on their machine (see **Installing ezBIDS locally** section for details) and submit a PR for bug fixes and feature enhancements. For additional modality support requests (e.g., NIRS), users should reach out to the developers. A meeting and/or access to test data may be requested, as the developers are less familiar with imaging modalities outside of MRI and DWI.