fmri-qctoolkit 1.0.0__tar.gz

fmri_qctoolkit-1.0.0/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Change Log
+
+## [Unreleased]
+
+
+## [1.0.0] - 2026-10-24
+### Security
+- The rating interface and dashboards now require a per-session token. The terminal prints a link containing it; requests without it get "Access denied". This keeps other users on a shared machine (such as an HPC login node) out of the pages and the ratings.
+- Requests whose Host header is not a loopback name are refused while the server is bound to localhost, which blocks DNS rebinding from web pages.
+- Subject labels in rating URLs and saves must be alphanumeric BIDS labels. Before, a crafted label could read `.html` files and write ratings outside the input and output directories on Windows.
+- `fmriqc rating afni` no longer runs `open_apqc.py` through a shell, so paths with spaces or shell characters are passed as-is.
+- `fmriqc dashboard --debug` is refused on a non-loopback `--host`, and a non-loopback host prints a warning.
+
+### Fixed
+- Ratings are no longer lost when one session contains more than one task.
+- Ratings are no longer lost when a task has several acquisitions, directions, or echoes.
+- Run numbers in the exported CSV now match the run labels shown in the fMRIPrep report.
+- Fieldmap panels are no longer counted as tasks.
+- Subject IDs keep their leading zeros; `sub-0030` and `sub-30` are no longer the same subject.
+- Subject IDs are no longer truncated when they start with a letter from `sub-` (`s001` became `001`).
+- Non-numeric subject labels such as `sub-A01` no longer crash `fmriqc prep`.
+- `fmriqc prep` now warns when the ratings and MRIQC have no records in common.
+- The dashboard heatmaps no longer crash on non-numeric subject labels (`sub-A01`) or session labels (`ses-pre`), or with pandas 3.
+- Changing a dashboard filter no longer moves the table selection to another run or session of the same subject, so "Download Selected Data" exports the runs that were selected.
+- fMRIPrep ratings are no longer lost when a rating CSV cannot be written (for example while it is open in Excel); the save reports the locked file.
+- Ratings for an fMRIPrep report with only anatomical items can now be saved.
+- Two fMRIPrep report groups no longer share one rating when an acquisition, direction, or run label appears on only some of a task's groups.
+- On Windows, a second `fmriqc dashboard` or `fmriqc rating fmriprep` no longer picks a port that another one is already serving, which showed up as "Access denied".
+- `fmriqc dashboard --host 0.0.0.0` and IPv6 hosts now print a link that opens.
+- A rating that cannot be saved because the server restarted now says to open the new link, instead of reporting a network error.
+- `fmriqc prep afni` no longer keeps only one session when `--task` matches a subject in several sessions; it stops and lists the matches so `--task` can be narrowed to one session.
+- `fmriqc prep afni` now accepts alphanumeric subject labels (`sub-A01`) and treats `--prefix` literally.
+
+### Changed
+- **The command is now `fmriqc` instead of `qc` (`fmriqc prep`, `fmriqc rating`, `fmriqc dashboard`).**
+- `fmriqc rating afni --afni-path` no longer defaults to a cluster-specific path; `open_apqc.py` is taken from `$PATH` unless the option is given.
+- Session labels are kept as written (`ses-pre`, `ses-V1`) instead of being forced to numbers.
+- Subject IDs are kept as labels rather than numbers throughout.
+- The dashboard heatmaps redraw about three times faster after a filter change.
+- Dependencies now have minimum versions (Dash 2.17 to 4.x, pandas 2.1, NumPy 1.26, Plotly 5.20, Flask 3.0, Typer 0.16).
+
+### Added
+- First release on PyPI: `pip install fmri-qctoolkit`.
+- `fmriqc rating fmriprep --no-browser` prints the links without opening browser tabs. Tabs are also not opened on Linux when no display is available.
+- Unit tests for the dashboard's heatmap data.
+
+### Removed
+- `BaseDataProcessor.from_files`, unused and broken since it was added.
+- The unused `flask-cors` dependency.
+
+### Notes
+- Anatomical items (T1mask / Norm / SurfRecon) can show more than one image if the subject was processed by fMRIPrep more than once. See the README.
+- Ratings for a task split by acquisition or direction are saved but not yet shown in the dashboard. The rating app says so when the subject is opened, and `fmriqc prep` lists the files it skips.
+
+
+## [0.11.0] - 2026-06-12
+### Added
+- "Select All (filtered)" and "Clear" buttons in the dashboard table.
+- Horizontal scroll for the heatmap when there are many subjects.
+
+### Changed
+- fMRIPrep rating now reloads from a JSON sidecar; CSV is kept as export only.
+- Heatmap redrawn as a discrete square-marker grid.
+- Lollipop chart split into stacked panels by session and run.
+
+### Removed
+- CSV-column reverse-mapping on rating reload.
+
+
+## [0.10.0-beta.1] - 2025-11-04
+### Added
+- Added a test script for fMRIPrep rating.
+
+### Changed
+- Updated heatmap grouping methods.
+- Improved fMRIPrep preprocessing program: dropped missing values and added common modules.
+
+
+## [0.10.0-alpha.1] - 2025-10-27
+### Added
+- Support for handling `session` in fMRIPrep front end; defaults to `1` if session/run not detected.
+- Data simulation module.
+
+### Changed
+- `gsr_x` and `gsr_y` now remain unchanged instead of being averaged.
+- Aggregation method for MRIQC and fMRIPrep scoring changed from `inner` to `outer`.
+
+### Notes
+- Additional tests needed for session detection feature in fMRIPrep Rating.

fmri_qctoolkit-1.0.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "fMRI-QCtoolkit"
+abstract: "Quality control dashboard and manual rating tools for AFNI and fMRIPrep outputs, combined with MRIQC metrics."
+authors:
+  - given-names: Qiuyu
+    family-names: Yu
+    email: qiuyuyu.psych@gmail.com
+    orcid: "https://orcid.org/0009-0003-5242-6302"
+version: 1.0.0
+date-released: "2026-10-24"
+license: Apache-2.0
+repository-code: "https://github.com/QiuyuYu3/fMRI-QCtoolkit"
+keywords:
+  - fMRI
+  - quality control
+  - MRIQC
+  - fMRIPrep
+  - AFNI

fmri_qctoolkit-1.0.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

fmri_qctoolkit-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+recursive-include fMRI_QCtoolkit *
+include CHANGELOG.md CITATION.cff
+graft tests
+graft examples/example_data
+global-exclude __pycache__ *.py[cod] .DS_Store

fmri_qctoolkit-1.0.0/PKG-INFO

@@ -0,0 +1,287 @@
+Metadata-Version: 2.4
+Name: fmri_qctoolkit
+Version: 1.0.0
+Summary: MRI Quality Control Dashboard for AFNI and fMRIPrep pipelines
+Author-email: Qiuyu Yu <qiuyuyu.psych@gmail.com>
+Maintainer-email: Qiuyu Yu <qiuyuyu.psych@gmail.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/QiuyuYu3/fMRI-QCtoolkit
+Project-URL: Repository, https://github.com/QiuyuYu3/fMRI-QCtoolkit
+Project-URL: Issues, https://github.com/QiuyuYu3/fMRI-QCtoolkit/issues
+Project-URL: Changelog, https://github.com/QiuyuYu3/fMRI-QCtoolkit/blob/main/CHANGELOG.md
+Keywords: fMRI,quality control,MRIQC,fMRIPrep,AFNI,dashboard
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Dash
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.16
+Requires-Dist: dash<5,>=2.17
+Requires-Dist: plotly>=5.20
+Requires-Dist: pandas>=2.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: flask>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# fMRI-QCtoolkit
+
+fMRI-QCtoolkit is a modular Python package for fMRI (functional Magnetic Resonance Imaging) quality control (QC), integrating quantitative metrics from [MRIQC](https://mriqc.readthedocs.io/en/latest/), [fMRIPrep](https://fmriprep.org/en/stable/), and [AFNI](https://afni.nimh.nih.gov/), along with manual scoring. The package includes an interactive dashboard with customizable filters and visualizations, a lightweight front-end for manual rating for fMRIPrep, and supports batch-level scoring for both fMRIPrep and AFNI outputs.
+
+![workflow](https://raw.githubusercontent.com/QiuyuYu3/fMRI-QCtoolkit/main/images/workflow.png)
+
+## Install
+Python 3.11 or newer is required. Create or activate a virtual environment, then install from PyPI:
+
+```bash
+pip install fmri-qctoolkit
+```
+
+The example data used in the commands below is not part of the PyPI package. To run the examples, or to work on the code, clone the repository and install it in development mode:
+
+```bash
+git clone https://github.com/QiuyuYu3/fMRI-QCtoolkit.git
+cd fMRI-QCtoolkit
+pip install -e .[dev]
+```
+
+# Usage
+
+## STEP1: Rating
+
+After the completion of preprocessing, perform qualitative scoring on the derivatives.
+
+### AFNI
+AFNI provides [scripts](https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/tutorials/apqc_html/browsing.html#using-a-script-to-load-many-apqc-html-files) for browsing multiple subjects' QC files. However, using `firefox` on HPC (High-performance computing) systems may result in issues interacting with buttons, so this using `open_apqc.py` is another option (while ensuring the required Python packages are activated in the environment).
+
+The directory structure of AFNI derivatives is as follows:
+```
+.
+└── AFNI_derivatives/
+    ├── sub-001/
+    │   └── ses-01/
+    │       └── cards_output/
+    │           └── sub-001.results/
+    │               ├── QC_sub-001
+    │               └── ...
+    ├── sub-002
+    ├── sub-003
+    └── ...
+```
+
+**Input Arguments:**
+- `fmriqc rating afni`: Indicate which rating program.
+- `--input-dir`: Root directory, containing results that preprocessed from different participants.
+- `--subjects`: Support input multiple participants IDs.
+- `--task`: Rating program will search `task` in `input-dir` to find the `QC_{subj}`
+- `--prefix`: The prefix of participants IDs. 
+
+**Example Synatx:**
+```bash
+fmriqc rating afni --input-dir /PATH/AFNI_derivatives --subjects "003,009" --task ses-01/cards --prefix sub-
+```
+
+*Although I've tried to make the scoring criteria flexible, it may still not support all pathfinding scenarios. Therefore, you can also try [script version](https://github.com/QiuyuYu3/fMRI-QCtoolkit/blob/main/examples/scripts/rating/afni_rating.sh).*
+
+> [!IMPORTANT]  
+> The rating program relies on the `open_apqc.py` tool developed by AFNI.  
+> You can either:
+> - Make sure `open_apqc.py` is on your `$PATH` (e.g., load the AFNI module first), or  
+> - Provide a custom path using the `--afni-path` option when running the command.
+> `fmriqc rating afni --input-dir /PATH/AFNI_derivatives --subjects "003,009" --task ses-01/cards --prefix sub- --afni-path /PATH`
+
+![AFNI_rating](https://raw.githubusercontent.com/QiuyuYu3/fMRI-QCtoolkit/main/images/AFNI_rating.png)
+
+### fMRIPrep
+The rating module in **fMRI-QCtoolkit** is based on the HTML reports generated by fMRIPrep (e.g., `sub-{ID}.html`).  
+Each QC item maps directly to specific sections of the original [fMRIPrep report](https://fmriprep.org/en/stable/_static/SampleReport/sample_report.html).
+
+- Brain mask and brain tissue segmentation of the T1w (T1mask)
+- Spatial normalization of the anatomical T1w reference (Norm)
+- Surface reconstruction (SurfRecon)
+- Susceptibility distortion correction (SDC)
+- Alignment of functional and anatomical MRI data (coregistration) (Align)
+- Brain mask and (anatomical/temporal) CompCor ROIs (CompCor)
+- Variance explained by t/aCompCor components (Variance)
+- BOLD Summary (BOLD)
+- Correlations among nuisance regressors (Corr)
+
+The interface is divided into two parts:  
+- **Upper panel**: navigate modules with a left-click; scroll horizontally with the mouse wheel.  
+- **Lower panel**: interactive rating area, similar to [AFNI’s APQC HTML](https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/tutorials/apqc_html/main_toc.html).  
+  - Left-click to rate, Ctrl+click to add comments.  
+  - Rating buttons toggle between: good (+, green), bad (×, red), and other (?, yellow).  
+  - Results are saved automatically as CSV files (subject-level and task-level). Upon reopening the program with the same code, it will automatically retrieve the previous scores by extracting the subject-level CSV file.
+
+> [!IMPORTANT]
+> If the program cannot detect the session and run number, both will default to 1. For example, the saved CSV file name would be `sub-{ID}_ses-01_rest.csv`. Therefore, when merging with files generated by MRIQC, you need to modify the `ses` parameters.
+
+> [!IMPORTANT]
+> For multi-session subjects, fMRIPrep merges all T1w images into a single anatomical reference ([longitudinal processing](https://fmriprep.org/en/stable/workflows.html#longitudinal-processing)). T1mask / Norm / SurfRecon therefore describe that merged image: one rating per subject, not per session. If several images appear under one of these headings, the subject was processed more than once; check the `Get figure file:` line and rate the one from your current run.
+
+The directory structure of fMRIPrep derivatives is as follows:
+```
+.
+└── fMRIPrep_derivatives/
+    ├── sub-001
+    ├── sub-001.html
+    ├── sub-002
+    ├── sub-002.html
+    ├── sub-003
+    ├── sub-003.html
+    ├── dataset_description.json
+    ├── desc-aparcaseg_dseg.tsv
+    ├── desc-aseg_dseg.tsv
+    └── ...
+```
+
+**Input Arguments:**
+- `fmriqc rating fmriprep`: Indicate which rating program.
+- `--input-dir`: Root directory, containing results that preprocessed from different participants.
+- `--subjects`: Support input multiple participants IDs.
+- `--output-dir`: Path for exporting the scoring CSV file.
+- `--no-browser`: Only print the links, without opening browser tabs (useful on HPC; see [Access Links](#access-links)).
+
+**Example Synatx:**
+```bash
+fmriqc rating fmriprep --input-dir /PATH/fMRIPrep_derivatives --output-dir /PATH/Output_dir --subjects "1013,1026"
+```
+
+![fMRIPrep_rating](https://raw.githubusercontent.com/QiuyuYu3/fMRI-QCtoolkit/main/images/fMRIPrep_rating.png)
+
+## STEP2: Data Preparation
+By extracting information from qualitative rating files, `fmriqc prep` program then generates two dataframes to put into the dashboard.
+
+### AFNI
+After finishing preprocessing and rating, both quantitative and qualitative rating information are saved in `QC_{subj}/extra_info/out.ss_review.{subj}.json`. 
+
+**Input Arguments:**
+- `fmriqc prep afni`: Indicate which rating program.
+- `--input-dir`: Root directory, containing results that preprocessed from different participants.
+- `--output-dir`: Path for exporting `df_final.csv` and `lollipop_chart_data.csv` files.
+- `--task`: Prep program will search `task` in `input-dir` to find the `QC_{subj}/extra_info/out.ss_review.{subj}.json` across all participants. Each run covers one session: if a subject matches in more than one place (for example `ses-01/rest_output` and `ses-02/rest_output`), narrow `--task` to `ses-01/rest`.
+- `--prefix`: The prefix of participants IDs.
+
+**Example Synatx:**
+```bash
+fmriqc prep afni --input-dir /PATH/AFNI_derivatives --task ses-01/kidvid --output-dir /PATH/Output_dir --prefix sub-
+```
+
+> [!NOTE]
+> The quantitative parameters are extracted and coded according to the following [standards](https://www.frontiersin.org/files/Articles/1073800/fnins-16-1073800-HTML/image_m/fnins-16-1073800-t001.jpg). Users may also modify [JSON file](https://github.com/QiuyuYu3/fMRI-QCtoolkit/blob/main/fMRI_QCtoolkit/dashboard/afni_config.json) and [status file](https://github.com/QiuyuYu3/fMRI-QCtoolkit/blob/main/fMRI_QCtoolkit/utils/status.py) based on their own requirements.
+
+### fMRIPrep
+
+After finishing rating procedure, merge the qualitative rating files with quantitative file (`group_bold.tsv`) that generates by MRIQC, and output two dataframes to put into dashboard.
+
+**Input Arguments:**
+- `fmriqc prep fmriprep`: Indicate which rating program.
+- `--bold-file`:  Input `group_bold.tsv` file that generated by MRIQC.
+- `--rating-dir`: Path for storing fMRIPrep qualitative scores.
+- `--task`: Indicate which task's rating data you want to use.
+- `--output-dir`: Path for exporting `df_final.csv` and `lollipop_chart_data.csv` files.
+
+**Example Synatx:**
+```bash
+fmriqc prep fmriprep --bold-file examples/example_data/fmriprep/group_bold.tsv --rating-dir examples/example_data/fmriprep/ --task rest --output-dir examples/example_data/fmriprep/
+```
+
+> [!NOTE]
+> The quantitative parameters are extracted from [here](https://mriqc.readthedocs.io/en/latest/iqms/bold.html) and coded according to the following [standards](https://www.frontiersin.org/files/Articles/1073800/fnins-16-1073800-HTML/image_m/fnins-16-1073800-t001.jpg). Users may also modify [JSON file](https://github.com/QiuyuYu3/fMRI-QCtoolkit/blob/main/fMRI_QCtoolkit/dashboard/fmriprep_config.json) and [status file](https://github.com/QiuyuYu3/fMRI-QCtoolkit/blob/main/fMRI_QCtoolkit/utils/status.py) based on their own requirements.
+
+### STEP3: Viewing and Filtering Results via Dashboard
+Visualize, filter, and export selected data.
+
+The left side of the dashboard features filter sidebars where users can select the desired ranges. The two central tabs display data tables and visualizations (heatmaps and lollipop charts). After selecting rows in the data table, the blue download button below allows exporting the corresponding data frame.
+
+![dashboard1](https://raw.githubusercontent.com/QiuyuYu3/fMRI-QCtoolkit/main/images/dashboard1.png)
+![dashboard2](https://raw.githubusercontent.com/QiuyuYu3/fMRI-QCtoolkit/main/images/dashboard2.png)
+![dashboard3](https://raw.githubusercontent.com/QiuyuYu3/fMRI-QCtoolkit/main/images/dashboard3.png)
+
+### AFNI
+
+**Input Arguments:**
+- `fmriqc dashboard afni`: Indicate which rating program.
+- `--data-file`: Input the merged dataframe.
+- `--lollipop-file`: Input the data for lollipop chart.
+- `--task`: Specify the task name to be used when downloading data.
+
+**Example Synatx:**
+```bash
+fmriqc dashboard afni --data-file /PATH/Output_dir/df_final.csv --lollipop-file /PATH/Output_dir/lollipop_chart_data.csv --task kidvid
+```
+
+### fMRIPrep
+
+**Input Arguments:**
+- `fmriqc dashboard fmriprep`: Indicate which rating program.
+- `--data-file`: Input the merged dataframe.
+- `--lollipop-file`: Input the data for lollipop chart.
+- `--task`: Specify the task name to be used when downloading data and filtering task in the merged dataframe.
+
+**Example Synatx:**
+```bash
+fmriqc dashboard fmriprep --data-file examples/example_data/fmriprep/df_final.csv --lollipop-file examples/example_data/fmriprep/lollipop_chart_data.csv --task rest
+```
+
+# Access Links
+`fmriqc rating fmriprep` and `fmriqc dashboard` start a local web server that only answers requests carrying a session token. The terminal prints one link per subject (or one for the dashboard), for example:
+
+```
+INFO -   http://localhost:5003/0030?token=Xk3v9QpL2mR7tYwZ8aBcD1eF4gH6jK0n
+```
+
+On your own computer, the rating tabs open automatically. Otherwise, click or paste the printed link. After the first visit, the token is kept in a browser cookie and dropped from the address bar. A new token is created every time the server starts, so after a restart (or after closing the browser) use the newly printed link. An "Access denied" page means the link is missing or out of date.
+
+**Running on HPC.** Start the server on the cluster with `--no-browser`, then forward its port from your own computer and open the printed link there:
+
+```bash
+# Server on the login node
+ssh -N -L 5003:127.0.0.1:5003 user@hpc.example.edu
+# Server on a compute node (e.g. node123 inside an srun/salloc session)
+ssh -N -L 5003:127.0.0.1:5003 -J user@hpc.example.edu user@node123
+```
+
+The local port may differ from the remote one (`-L 8888:127.0.0.1:5003`); change the port in the link accordingly and keep the token. Other users on the same node cannot open the pages without the token.
+
+`fmriqc dashboard --host` can bind to a non-loopback address, in which case the token is the only protection. With `--host 0.0.0.0` the printed link uses this machine's hostname. `--debug` is refused on such a host.
+
+# [Training Materials](https://github.com/QiuyuYu3/fMRI-QCtoolkit/tree/main/training_materials)
+We have summarized the AFNI QC training documentation based on existing literature and included several case studies (still under revision).
+
+# Summary
+
+> [!NOTE]
+> - The data prep feature is designed for users unfamiliar with Python. If you want more flexible data wrangling, try the scripts (or write your scripts).
+> - The sidebar and visualizations are highly customizable, as long as the input dataframe contains the corresponding data. By configuring [AFNI](https://github.com/QiuyuYu3/fMRI-QCtoolkit/blob/main/fMRI_QCtoolkit/dashboard/afni_config.json) and [fMRIPrep](https://github.com/QiuyuYu3/fMRI-QCtoolkit/blob/main/fMRI_QCtoolkit/dashboard/fmriprep_config.json) config files, as well as [asign status to variables](https://github.com/QiuyuYu3/fMRI-QCtoolkit/blob/main/fMRI_QCtoolkit/utils/status.py), users can customize filters and the items displayed in visualizations.
+
+# Citation
+Coming soon!
+
+## Reference
+- Cox R. W. (1996). AFNI: software for analysis and visualization of functional magnetic resonance neuroimages. Computers and biomedical research, an international journal, 29(3), 162–173. https://doi.org/10.1006/cbmr.1996.0014
+- Cox, R. W., & Hyde, J. S. (1997). Software tools for analysis and visualization of fMRI data. NMR in biomedicine, 10(4-5), 171–178. https://pubmed.ncbi.nlm.nih.gov/9430344/
+- Esteban, O., Birman, D., Schaer, M., Koyejo, O. O., Poldrack, R. A., & Gorgolewski, K. J. (2017). MRIQC: Advancing the automatic prediction of image quality in MRI from unseen sites. PloS one, 12(9), e0184661. https://doi.org/10.1371/journal.pone.0184661
+- Esteban, O., Ciric, R., Finc, K. et al. Analysis of task-based functional MRI data preprocessed with fMRIPrep. Nat Protoc 15, 2186–2202 (2020). https://doi.org/10.1038/s41596-020-0327-3
+- Harris, C.R., Millman, K.J., van der Walt, S.J. et al. Array programming with NumPy. Nature 585, 357–362 (2020). https://doi.org/10.1038/s41586-020-2649-2 
+- Kruchten, N., Seier, A., & Parmer, C. (2025). An interactive, open-source, and browser-based graphing library for Python (Version 6.3.1) [Computer software]. https://doi.org/10.5281/zenodo.14503524
+- Pallets. (2025). Flask (Version 3.1.1) [Computer software]. PyPI. https://palletsprojects.com/
+- Parmer, C., Duval, P., & Johnson, A. (2025). A data and analytics web app framework for Python, no JavaScript required. (Version 3.2.0) [Computer software]. https://doi.org/10.5281/zenodo.14182630
+- Ramírez, S. (2025). Typer (Version 0.19.2) [Computer software]. https://github.com/fastapi/typer
+- Reynolds, R. C., Taylor, P. A., & Glen, D. R. (2023). Quality control practices in FMRI analysis: Philosophy, methods and examples using AFNI. Frontiers in Neuroscience, 16, 1073800. https://doi.org/10.3389/fnins.2022.1073800
+- The pandas development team. pandas-dev/pandas: Pandas [Computer software]. https://doi.org/10.5281/zenodo.3509134