Skip to content

Commit b282a9a

Browse files
eurunuelaclaude
eurunuela
and
claude
authored
docs: Add guide for updating Rica without rerunning tedana (#111)
* docs: Add guide for updating Rica without rerunning tedana Add a new documentation page (docs/updating-rica.md) and a README section explaining how users can update the open_rica_report.py that tedana generates by replacing it with the latest index.html and rica_server.py from a Rica release. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * docs: Correct update guide based on actual open_rica_report.py behavior The script already auto-downloads the latest Rica from GitHub on every run. Update the docs and README to reflect the real workflow: - Just running the script is enough to get the latest version - --force-download bypasses the cache check - TEDANA_RICA_PATH env var pins a local/custom build - Falls back to cache automatically when offline Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 930e21b commit b282a9a

File tree

3 files changed

+138
-0
lines changed

3 files changed

+138
-0
lines changed

‎README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,29 @@ npx gulp
108108
# - rica_server.py (local server)
109109
```
110110

111+
## Updating Rica Without Rerunning Tedana
112+
113+
Tedana generates an `open_rica_report.py` script in its output directory. This script **automatically downloads the latest Rica** from GitHub every time it runs — you usually don't need to do anything special:
114+
115+
```bash
116+
python open_rica_report.py
117+
```
118+
119+
To force a fresh download regardless of the cached version:
120+
121+
```bash
122+
python open_rica_report.py --force-download
123+
```
124+
125+
To use a local or custom build, set the `TEDANA_RICA_PATH` environment variable to a directory containing `index.html` and `rica_server.py`:
126+
127+
```bash
128+
export TEDANA_RICA_PATH=/path/to/rica/build
129+
python open_rica_report.py
130+
```
131+
132+
See the [full guide](https://me-ica.github.io/rica/updating-rica/) for details on offline use, pinning versions, and building Rica from source.
133+
111134
## Required Files
112135

113136
Rica expects these files from tedana output:

‎docs/updating-rica.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Updating Rica Without Rerunning Tedana
2+
3+
When tedana runs, it generates an `open_rica_report.py` script in the output directory. This script automatically downloads the latest Rica from GitHub every time it runs, so **you usually don't need to do anything special** — just run the script and it will self-update.
4+
5+
This page explains how the update mechanism works and what to do in less common situations (offline use, pinning a specific version, or using a local build).
6+
7+
## How `open_rica_report.py` Works
8+
9+
Each time you run `open_rica_report.py`, it:
10+
11+
1. Queries the GitHub API for the latest Rica release
12+
2. Compares it against the version cached at `~/Library/Caches/tedana/rica/` (macOS) or the platform equivalent
13+
3. Downloads `index.html` and `rica_server.py` if a newer version is available
14+
4. Copies the files into a `rica/` subdirectory of your tedana output folder
15+
5. Starts a local HTTP server and opens Rica at `http://localhost:8000/rica/index.html`
16+
17+
So to get the latest Rica, simply run:
18+
19+
```bash
20+
python open_rica_report.py
21+
```
22+
23+
## Forcing a Re-download
24+
25+
If you suspect the cache is stale or want to guarantee a fresh download:
26+
27+
```bash
28+
python open_rica_report.py --force-download
29+
```
30+
31+
This bypasses the version comparison and always downloads the latest release.
32+
33+
## Offline / Air-Gapped Use
34+
35+
When there is no network access, the script falls back to the last cached version automatically. You will see a warning like:
36+
37+
```
38+
[Rica] Warning: Could not check for updates (...)
39+
[Rica] Using cached version v2.1.5
40+
```
41+
42+
No action is needed — Rica continues to work with the cached files.
43+
44+
If you need to set up Rica on a machine that has never had network access, pre-populate the cache directory manually:
45+
46+
| Platform | Cache Path |
47+
|----------|-----------|
48+
| macOS | `~/Library/Caches/tedana/rica/` |
49+
| Linux | `~/.cache/tedana/rica/` |
50+
| Windows | `%LOCALAPPDATA%\tedana\rica\` |
51+
52+
Place `index.html`, `rica_server.py`, and a `VERSION` file (containing the version tag, e.g. `v2.1.5`) in that directory. Download these from the [Rica releases page](https://github.com/ME-ICA/rica/releases/latest).
53+
54+
## Using a Local or Custom Build
55+
56+
Set the `TEDANA_RICA_PATH` environment variable to a directory containing `index.html` and `rica_server.py`. The script will use those files directly and skip the GitHub download entirely.
57+
58+
```bash
59+
export TEDANA_RICA_PATH=/path/to/your/rica/build
60+
python open_rica_report.py
61+
```
62+
63+
This is useful for:
64+
65+
- Testing a development build of Rica against real tedana data
66+
- Pinning a specific version without auto-updates
67+
- Air-gapped environments where you manage files manually
68+
69+
To build Rica from source:
70+
71+
```bash
72+
git clone https://github.com/ME-ICA/rica.git
73+
cd rica
74+
npm install
75+
npm run build
76+
npx gulp
77+
# Built files are in build/
78+
export TEDANA_RICA_PATH=/path/to/rica/build
79+
```
80+
81+
## Checking the Current Version
82+
83+
The Rica version is shown in the **About** popup (the `(i)` button in the top-right corner). The version of the files installed in your output directory is also stored in `rica/VERSION`:
84+
85+
```bash
86+
cat /path/to/tedana/output/rica/VERSION
87+
```
88+
89+
Compare this to the [latest release](https://github.com/ME-ICA/rica/releases/latest) to see if an update is available.
90+
91+
## Troubleshooting
92+
93+
### Port Already in Use
94+
95+
If port 8000 is occupied, the script automatically tries the next available port. You can also specify one explicitly:
96+
97+
```bash
98+
python open_rica_report.py --port 9000
99+
```
100+
101+
### Browser Does Not Open Automatically
102+
103+
Navigate manually to the URL printed in the terminal, or suppress auto-open and open it yourself:
104+
105+
```bash
106+
python open_rica_report.py --no-open
107+
# Then open http://localhost:8000/rica/index.html
108+
```
109+
110+
### Script Can't Find tedana Output Files
111+
112+
Make sure `open_rica_report.py` is in the tedana output directory (where the `*_metrics.tsv` files are). The script uses its own location to find data.
113+
114+
See [Troubleshooting](troubleshooting.md) for more help.

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ nav:
3838
- ICA Tab Guide: ica-tab-guide.md
3939
- Classification Workflow: classification-workflow.md
4040
- QC Tab Guide: qc-tab-guide.md
41+
- Updating Rica: updating-rica.md
4142
- Troubleshooting: troubleshooting.md
4243

4344
markdown_extensions:

0 commit comments

Comments
 (0)