Merge pull request #80 from eurunuela/modernize-app-performance

Modernize Rica v2.0: Brain viewer, component table, and UI improvements

Author: eurunuela

.github/workflows/build.yml

@@ -32,10 +32,8 @@ jobs:
       - name: Inline assets (single-file HTML)
         run: npx gulp
 
-      - name: Copy server files
-        run: |
-          cp scripts/rica_server.py build/
-          cp public/favicon.ico build/
+      - name: Copy server script
+        run: cp scripts/rica_server.py build/
 
       - name: Upload build artifacts
         uses: actions/upload-artifact@v4
@@ -44,7 +42,6 @@ jobs:
           path: |
             build/index.html
             build/rica_server.py
-            build/favicon.ico
           retention-days: 90
 
       # Create release assets when a tag is pushed
@@ -55,5 +52,4 @@ jobs:
           files: |
             build/index.html
             build/rica_server.py
-            build/favicon.ico
           generate_release_notes: true

.gitignore

@@ -13,6 +13,7 @@
 
 # misc
 .DS_Store
+.env
 .env.local
 .env.development.local
 .env.test.local
@@ -21,3 +22,12 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+Thumbs.db

.mise.toml

@@ -0,0 +1,2 @@
+[tools]
+node = "20"

.nvmrc

@@ -0,0 +1 @@
+20

README.md

@@ -2,57 +2,135 @@
 
 [![DOI](https://zenodo.org/badge/391155862.svg)](https://zenodo.org/badge/latestdoi/391155862)
 
-As part of the ME-ICA pipeline, `Rica` (Reports for ICA) provides a reporting tool for ICA decompositions performed with [tedana](https://github.com/ME-ICA/tedana) and [aroma](https://github.com/ME-ICA/aroma).
+**Rica** (Reports for ICA) is an interactive visualization tool for reviewing and classifying ICA components from [tedana](https://github.com/ME-ICA/tedana) multi-echo fMRI analysis.
 
-**Pronunciation:** [ˈrika]. For an audio recording on how to pronounce Rica [see here](https://easypronunciation.com/en/spanish/word/rica).
+**Pronunciation:** [ˈrika]. [Hear it here](https://easypronunciation.com/en/spanish/word/rica).
 
-## About
+## Features
 
-`Rica` originally came out as an alternative to the reports provided by [tedana](https://github.com/ME-ICA/tedana), with the aim of making manual classification of ICA components possible. At the same time, the tool aspires to be of value for ICA decompositions made with tools other than `tedana`. `Rica` assumes you're working with files that mimic the outputs of `tedana`.
+### ICA Component Analysis
+- **Interactive scatter plots** - Kappa vs Rho, Kappa/Rho Rank plots with elbow threshold lines, zoom/pan
+- **Pie chart** - Component variance distribution, click to select
+- **3D brain viewer** - Interactive stat-z maps using Niivue with mosaic view (7 slices per orientation)
+- **Time series & FFT** - Component time courses and power spectra
+- **Component table** - Full metrics with sorting and selection sync
+- **External regressor heatmap** - Interactive correlation visualization (requires tedana 24.1+)
 
-## How to use Rica
+### Quality Control (QC) Tab
+- **Brain maps** - T2\*, S0, and RMSE maps with Niivue mosaic viewer
+- **Histograms** - Distribution plots for QC metrics
+- **Carpet plots** - Time series visualization in dedicated Carpets tab
 
-Even if Rica is designed to be simple to use, you might want to see how you can use the app by watching this [tutorial video](https://www.loom.com/share/ad37cf6f3c2d41e48721f62168a8284e).
+### User Experience
+- **Classification toggle** - Accept/reject components with A/R keyboard shortcuts
+- **Arrow navigation** - Previous/next component with wrap-around
+- **Light/dark theme** - Toggle with the sun/moon button
+- **Export** - Save modified classifications as TSV
 
-Rica also supports keyboard shortcuts on the ICA components page. You can use the following shortcuts:
+## How to Use
 
-- `a`: Accept component.
-- `r`: Reject component.
-- `i`: Ignore component.
-- `left arrow`: Go to previous component.
-- `right arrow`: Go to next component.
+For a video tutorial, see [this walkthrough](https://www.loom.com/share/ad37cf6f3c2d41e48721f62168a8284e).
 
-## Using Rica online
+### Keyboard Shortcuts
 
-Just head over to https://rica-fmri.netlify.app and have fun!
+| Key | Action |
+|-----|--------|
+| `A` | Accept component |
+| `R` | Reject component |
+| `←` | Previous component |
+| `→` | Next component |
 
-## Using Rica locally
+## Using Rica
 
-### Installation
+### Option 1: Online (Easiest)
 
-`Rica` can be installed by cloning this repository and executing the following command in the cloned repository:
+Visit **https://rica-fmri.netlify.app** and select your tedana output folder.
 
-```npm install```
+### Option 2: Local Server (Recommended for Local Use)
 
-In order to run the tool locally, two options exist:
+Run Rica directly from your tedana output folder with automatic data loading:
 
-#### 1. Using a localhost
+1. Download the latest release files:
+   - `index.html` (self-contained single-file app with embedded logo)
+   - `rica_server.py`
 
-By executing the `npm start` command in the cloned repository, `Rica` will open in a new browser tab at [http://localhost:3000](http://localhost:3000) and you will be able to use the tool.
+2. Copy these files to your tedana output folder:
+   ```bash
+   cp index.html rica_server.py /path/to/tedana/output/
+   ```
 
-#### 2. Compiling the tool
+3. Run the server:
+   ```bash
+   cd /path/to/tedana/output/
+   python rica_server.py
+   ```
 
-You could also compile the project so that you can use the tool just by opening an HTML file. For that, it is necessary to execute the following commands in the cloned repository.
+4. Your browser opens automatically and data loads instantly!
+
+> **Note:** The "New" button is hidden in local server mode since data is loaded automatically.
+
+### Option 3: Development Server
+
+For development or if you want to load different folders:
+
+```bash
+# Clone and install
+git clone https://github.com/ME-ICA/rica.git
+cd rica
+npm install
+
+# Start development server
+npm start
+```
+
+Then open http://localhost:3000 and select your tedana output folder.
+
+### Option 4: Build from Source
+
+Build a single-file HTML distribution:
 
 ```bash
+# Install dependencies
+npm install
+
+# Build with inlined assets
 npm run build
 npx gulp
-mv build/index.html build/rica.html
-open build/rica.html
+
+# Output files in build/
+# - index.html (self-contained single-file app)
+# - rica_server.py (local server)
 ```
 
-> Pro tip: when you open rica.html for the first time, BOOKMARK IT 😉
+## Required Files
+
+Rica expects these files from tedana output:
+
+| File Pattern | Description |
+|--------------|-------------|
+| `*_metrics.tsv` | Component metrics table (required) |
+| `*_mixing.tsv` | ICA mixing matrix (time series) |
+| `*stat-z_components.nii.gz` | 4D component stat maps |
+| `*_desc-ICACrossComponent_metrics.json` | Elbow thresholds for reference lines |
+| `figures/comp_*.png` | Component figures |
+| `*.svg` | Carpet plots and diagnostic figures |
+| `report.txt` | Tedana report |
+| `T2starmap.nii*`, `S0map.nii*`, `rmse_statmap.nii*` | QC brain maps |
+
+## Versioning
+
+Rica version is displayed in the About popup and managed centrally:
+- Version is defined in `package.json`
+- UI automatically displays the current version
+- GitHub releases should be tagged as `v<version>` (e.g., `v2.0.0`)
+
+To bump the version:
+```bash
+npm version patch  # 2.0.0 -> 2.0.1
+npm version minor  # 2.0.0 -> 2.1.0
+npm version major  # 2.0.0 -> 3.0.0
+```
 
-## Getting involved
+## Contributing
 
-Want to learn more about our plans for developing `Rica`? Have a question, comment, or suggestion? Open or comment on one of our issues!
+Questions, suggestions, or contributions? Open an issue on [GitHub](https://github.com/ME-ICA/rica/issues)!