Add Rica integration for interactive ICA component visualization #1288

eurunuela · 2025-12-19T23:48:29Z

Summary

Adds Rica integration for interactive ICA component visualization. Every tedana run now creates a launcher script that handles Rica setup on demand.

Key Changes

No CLI flag needed: tedana always generates open_rica_report.py in the output directory
On-demand download: Rica is downloaded when user runs the launcher script, not during tedana execution
Faster tedana runs: No network calls during analysis
Self-contained launcher: The launcher script includes all download/setup logic
Rica button in HTML report: "Open in Rica" button with popup instructions

How It Works

Run tedana as usual (no special flag needed)
Find open_rica_report.py in your output directory (full path is logged at end of run)
Run python open_rica_report.py
The script downloads Rica (if not cached), starts a local server, and opens your browser

Alternatively, open the HTML report and click the "Open in Rica" button in the top-right corner for instructions.

Features

Automatic Rica download from GitHub releases
Platform-specific caching (Linux: ~/.cache, macOS: ~/Library/Caches, Windows: %LOCALAPPDATA%)
Cross-platform path handling using pathlib.as_posix() for reliable Windows/Mac/Linux support
TEDANA_RICA_PATH environment variable for developers to use local Rica builds
--force-download flag to launcher for manual updates
Cross-platform launcher script with built-in HTTP server and CORS support
Graceful fallback if download fails (uses cached version if available)
"Open in Rica" button in HTML report with modal popup

Usage

# Run tedana
tedana -d data/*.nii.gz -e 14.5 29.0 43.5 --out-dir output

# View results in Rica (full path shown in tedana output)
python output/open_rica_report.py

# Or with ica_reclassify
ica_reclassify -c report.txt --out-dir output
python output/open_rica_report.py

Test Plan

Unit tests for rica.py module (91% coverage)
Integration tests include open_rica_report.py in expected outputs
Works with both tedana and ica_reclassify workflows
Cross-platform path handling verified (Windows backslash fix)

Files Changed

tedana/rica.py - Simplified to generate self-contained launcher script
tedana/workflows/tedana.py - Always calls setup_rica_report()
tedana/workflows/ica_reclassify.py - Always calls setup_rica_report()
tedana/tests/test_rica.py - Updated tests for new behavior
docs/outputs.rst - Updated documentation
tedana/reporting/data/html/report_body_template.html - Added Rica button with popup

Closes #1283.

codecov · 2025-12-20T00:51:23Z

Codecov Report

❌ Patch coverage is 93.33333% with 9 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.06%. Comparing base (4e9d548) to head (cbab059).

Files with missing lines	Patch %	Lines
tedana/rica.py	93.18%	5 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1288      +/-   ##
==========================================
+ Coverage   89.97%   90.06%   +0.09%     
==========================================
  Files          29       30       +1     
  Lines        4497     4631     +134     
  Branches      746      771      +25     
==========================================
+ Hits         4046     4171     +125     
- Misses        303      308       +5     
- Partials      148      152       +4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

eurunuela · 2026-01-11T00:14:59Z

Update: Rica v2.0.0 Compatibility and Test Coverage Improvements

Just pushed commit 6fcf19a8 with the following changes:

Changes Made:

Rica v2.0.0 Compatibility: Removed favicon.ico from RICA_FILES list to support Rica v2.0.0 (file no longer provided in releases)
Test Coverage: Improved from 66% to 91% (24 → 43 tests)
New Tests Added:
- Windows platform support tests (LOCALAPPDATA environment variable handling)
- Comprehensive network function tests for get_latest_rica_version with API response handling
- Asset filtering and validation tests
- Error handling for various edge cases
- Better test isolation with improved mocking of is_rica_cached

Files Modified:

tedana/rica.py: Removed favicon.ico from RICA_FILES list
tedana/tests/test_rica.py: Added 19 new tests (+373 lines)

All pre-commit hooks passed successfully.

Copilot

Pull request overview

This PR adds integration with Rica, an interactive web-based visualization tool for exploring ICA components. When users enable the --rica-report flag, tedana downloads Rica from GitHub releases, caches it locally, copies it to the output directory, and generates a launcher script for easy visualization.

Changes:

Added tedana/rica.py module with functions for downloading, caching, and setting up Rica reports
Added --rica-report flag to tedana and ica_reclassify workflows
Added comprehensive test coverage in tedana/tests/test_rica.py with 18 unit tests
Added extensive documentation in docs/outputs.rst covering usage, troubleshooting, and advanced features

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`tedana/rica.py`	New module implementing Rica download, caching, validation, and launcher script generation with cross-platform support
`tedana/workflows/tedana.py`	Added `--rica-report` flag and integration to call Rica setup after report generation
`tedana/workflows/ica_reclassify.py`	Added `--rica-report` flag and integration to call Rica setup after report generation
`tedana/tests/test_rica.py`	Comprehensive test suite with 18 unit tests covering all Rica functionality
`docs/outputs.rst`	Added detailed documentation section covering Rica usage, setup, troubleshooting, and advanced configuration

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

docs/outputs.rst

tedana/rica.py

docs/outputs.rst

tsalo · 2026-01-13T16:56:01Z

What about adding a button to the HTML report to open the Rica website? If possible, it would be amazing to automatically select the tedana output folder as well.

eurunuela · 2026-01-13T17:15:56Z

What about adding a button to the HTML report to open the Rica website? If possible, it would be amazing to automatically select the tedana output folder as well.

I feel like if users click on the tedana report HTML files, they could just as easily click on (or run) the open_rica_report.py script, which automatically opens the folder in Rica. WE can discuss at our meeting on Thu.

handwerkerd

I'm starting to look at this and noticed two issues:

Nearly identical messages are logged twice in a row. Not sure which location is better, but we probably want the one that includes python. Also, if the goal is to have this run, append the output directory onto open_rica_report.py so the command could run from the location the script was called:

INFO     rica:setup_rica_report:603 Rica report setup complete. Run 'open_rica_report.py' to visualize results.
INFO     tedana:tedana_workflow:1277 Rica report ready. Run 'python open_rica_report.py' to visualize results.

On my Mac, I got a crash with python open_rica_report.py because of

open_rica_report.py", line 72
    rel_path = str(f.relative_to(cwd)).replace("\", "/")

It works with replace("\\", but I'm not sure if the double \ might cause problems in other systems.

eurunuela · 2026-01-15T18:04:28Z

I'm waiting for #1318 to check the report with the new button looks good in the artifacts.

eurunuela · 2026-01-15T18:08:37Z

Fixed both issues from @handwerkerd's review in commit 075e090:

Log message with full path: Now logs Run 'python /full/path/to/open_rica_report.py' to visualize results. so users can run from any directory.
Backslash crash on Mac: Replaced the problematic replace("\\\\", "/") with as_posix() which is a cleaner pathlib method that properly converts paths to forward slashes on all platforms without escaping issues.

handwerkerd · 2026-01-15T21:27:45Z

I think the test failures are because the reclassify integration tests are comparing against the lists of expected file outputs and open_rica_report.py is not on their lists.

This commit adds the ability to generate Rica interactive reports directly from tedana output directories. New features: - Add tedana/rica.py module for Rica download and report generation - Add --rica-report flag to tedana and ica_reclassify workflows - Download Rica from GitHub releases and cache locally - Generate open_rica_report.py launcher script in output directory - Cross-platform support for Linux, macOS, and Windows When --rica-report is used: 1. Rica files are downloaded from ME-ICA/rica GitHub releases (cached) 2. Files are copied to output_dir/rica/ 3. A launcher script (open_rica_report.py) is created 4. Users can run the script to visualize ICA components in Rica 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Document the --rica-report flag and explain how to use Rica for interactive ICA component visualization. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Use typing module imports (Optional, Union, Tuple, Dict) instead of Python 3.10+ syntax (str | None, str | Path) for type annotations. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Remove --rica-path CLI flag for simpler user experience - Rica now auto-downloads from GitHub if not found locally - Keep TEDANA_RICA_PATH env var for developers using custom builds - Add priority order: env var > bundled > cached > download - Add troubleshooting section to documentation - Add tests for local Rica path validation Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Remove favicon.ico from RICA_FILES to support Rica v2.0.0 (file no longer provided in releases) - Expand test coverage from 66% to 91% (24 → 43 tests) - Add Windows platform support tests (LOCALAPPDATA handling) - Add comprehensive network function tests for get_latest_rica_version - Improve test isolation with better mocking of is_rica_cached function Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Fix Windows path backslash replacement in tedana/rica.py line 404 Changed replace("\\\\", "/") to replace("\\", "/") for proper single backslash matching - Remove favicon.ico references from docs/outputs.rst Removed from Rica Output Files table, local bundle files list, and wget/mv commands Rica v2.0.0 no longer includes favicon.ico Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Remove --rica-report CLI flag from tedana and ica_reclassify workflows - Always generate open_rica_report.py launcher script in output directory - Move Rica download logic from tedana runtime to launcher script - Launcher now handles: checking cache, downloading from GitHub, copying files - Add --force-download flag to launcher for manual updates - Update tests to reflect simplified setup_rica_report() behavior - Update documentation to reflect new flow This simplifies user experience (no flag to remember), keeps tedana fast (no network calls during analysis), and provides on-demand Rica download. Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Add "Open in Rica" button fixed to top-right corner of report - Button opens a modal explaining how to run Rica locally - Modal includes command: python open_rica_report.py - "Learn more" button links to Rica GitHub repository - Modal can be closed via click outside, Escape key, or X button Co-Authored-By: Claude Opus 4.5 <[email protected]>

- Remove unused shutil import - Break long lines in launcher script template to comply with line length limit Co-Authored-By: Claude Opus 4.5 <[email protected]>

Since Rica launcher script is now always generated, add it to all expected output files for integration tests that run tedana_workflow. Co-Authored-By: Claude Opus 4.5 <[email protected]>

@handwerkerd

Addresses two issues found by @handwerkerd: 1. Use as_posix() instead of manual backslash replacement to convert Windows paths to forward slashes. This avoids escaping issues that caused crashes on Mac. 2. Log the full path to open_rica_report.py so users can run the command from any directory. Co-Authored-By: Claude Opus 4.5 <[email protected]>

The reclassify integration tests were failing because open_rica_report.py was not listed in the expected output files. Co-Authored-By: Claude Opus 4.5 <[email protected]>

eurunuela · 2026-01-16T01:27:31Z

Fixed! Added open_rica_report.py to all 4 reclassify expected output files:

reclassify_quiet_out.txt
reclassify_debug_out.txt
reclassify_no_bold.txt
reclassify_run_twice.txt

eurunuela · 2026-01-16T16:13:40Z

I have added the feedback from yesterday's meeting. Let me know what you think.

handwerkerd

The changes all look good.
I did notice one issue. The bugs in rica visualization that you fixed appeared in rica when I opened it with python open_rica_report.py. The same report rendered properly when I opened it with my local version of rica using npm install; npm start I'm fairly sure what happened is that, when the program checks to see if it should download rica, it saw it was already present and didn't re-download. You might want some way to see if there's a newer version of rica available & to then download that version.

tedana/reporting/data/html/report_body_template.html

Co-authored-by: Dan Handwerker <[email protected]>

eurunuela · 2026-01-16T21:06:05Z

Ah good catch! I had the latest on mine and didn't see this. Thanks Dan! Can you try now @handwerkerd ?

The open_rica_report.py launcher now checks GitHub for the latest Rica version on each run and automatically downloads updates if a newer version is available. This ensures users get the latest bug fixes without needing to use --force-download. - Always query GitHub API for latest version before using cache - Compare cached version with latest and download if outdated - Fall back to cached version if network is unavailable - Respect TEDANA_RICA_PATH env var (no auto-update when set) Requested by: handwerkerd Co-Authored-By: Claude Opus 4.5 <[email protected]>

eurunuela marked this pull request as ready for review January 11, 2026 00:15

Copilot AI review requested due to automatic review settings January 11, 2026 00:15

Copilot started reviewing on behalf of eurunuela January 11, 2026 00:15 View session

Copilot AI reviewed Jan 11, 2026

View reviewed changes

docs/outputs.rst Outdated Show resolved Hide resolved

docs/outputs.rst Outdated Show resolved Hide resolved

tedana/rica.py Outdated Show resolved Hide resolved

docs/outputs.rst Outdated Show resolved Hide resolved

eurunuela requested review from handwerkerd and tsalo January 12, 2026 15:04

handwerkerd reviewed Jan 14, 2026

View reviewed changes

eurunuela mentioned this pull request Jan 15, 2026

Interactive component table in the tedana report #1235

Closed

eurunuela force-pushed the open_rica branch from 075e090 to 4eef33e Compare January 15, 2026 20:16

eurunuela and others added 11 commits January 15, 2026 18:26

Add Rica integration documentation

b08db07

Document the --rica-report flag and explain how to use Rica for interactive ICA component visualization. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>

Fix linting issues in rica.py

2cc38d7

- Remove unused shutil import - Break long lines in launcher script template to comply with line length limit Co-Authored-By: Claude Opus 4.5 <[email protected]>

Add open_rica_report.py to expected integration test outputs

12af42b

Since Rica launcher script is now always generated, add it to all expected output files for integration tests that run tedana_workflow. Co-Authored-By: Claude Opus 4.5 <[email protected]>

eurunuela force-pushed the open_rica branch from 4eef33e to f9f1bb1 Compare January 16, 2026 01:26

Add open_rica_report.py to reclassify expected outputs

dacda1c

The reclassify integration tests were failing because open_rica_report.py was not listed in the expected output files. Co-Authored-By: Claude Opus 4.5 <[email protected]>

Trigger ReadTheDocs rebuild

7bc05b0

eurunuela requested a review from handwerkerd January 16, 2026 16:13

handwerkerd requested changes Jan 16, 2026

View reviewed changes

tedana/reporting/data/html/report_body_template.html Outdated Show resolved Hide resolved

Update tedana/reporting/data/html/report_body_template.html

b2e17e1

Co-authored-by: Dan Handwerker <[email protected]>

eurunuela requested a review from handwerkerd January 16, 2026 21:27

Add Rica integration for interactive ICA component visualization #1288

Are you sure you want to change the base?

Add Rica integration for interactive ICA component visualization #1288

Uh oh!

Conversation

eurunuela commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Changes

How It Works

Features

Usage

Test Plan

Files Changed

Uh oh!

codecov bot commented Dec 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

eurunuela commented Jan 11, 2026

Update: Rica v2.0.0 Compatibility and Test Coverage Improvements

Changes Made:

Files Modified:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tsalo commented Jan 13, 2026

Uh oh!

eurunuela commented Jan 13, 2026

Uh oh!

handwerkerd left a comment

Choose a reason for hiding this comment

Uh oh!

eurunuela commented Jan 15, 2026

Uh oh!

eurunuela commented Jan 15, 2026

Uh oh!

handwerkerd commented Jan 15, 2026

Uh oh!

eurunuela commented Jan 16, 2026

Uh oh!

eurunuela commented Jan 16, 2026

Uh oh!

handwerkerd left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

eurunuela commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

eurunuela commented Dec 19, 2025 •

edited

Loading

codecov bot commented Dec 20, 2025 •

edited

Loading

handwerkerd left a comment •

edited

Loading

eurunuela commented Jan 16, 2026 •

edited

Loading