---
name: rave-module
description: "Load, configure, run pipelines and read module source files to understand RAVE module architecture"
---

## Instructions

Interact with RAVE modules under `modules/{module_id}/`. This skill provides
two categories of operations:

1. **Pipeline operations** — Configure inputs, run pipelines, read results
2. **Source reading** — Read module source code to understand architecture

### Module vs. Pipeline

- A **RAVE module** is a Shiny module that provides UI interactivity.
  It may or may not contain a pipeline.
- A **pipeline** is a standalone `targets`-based computation unit with
  `settings.yaml` (inputs) and target scripts. Pipelines can run without
  Shiny, offering coding portability.
- When a module contains a pipeline, `module_id` and `pipeline_name` are
  identical, and the UI delegates computation to the pipeline.
  
### When to use module or pipeline

- Use UI modules when user asks to change inputs, interpret results
- Use UI first when user asks for quantitative results. If the UI contains no such information, you may then use pipelines
- Use pipelines when user asks for low-level implementations

- Do NOT use pipelines when user asks to set UI inputs

### Data-flow (when a module wraps a pipeline)

1. **Shiny UI inputs** — user-facing widgets
2. **User clicks "Run Analysis"** — UI "reshapes" values into `settings.yaml`
3. **Pipeline targets** — reads `settings.yaml`, runs computation, produces results
4. **UI outputs** — reads pipeline results and renders visualizations


---

## Module tools (recommended)

| Script | Purpose |
|--------|---------|
| shiny_input_info | obtain input information |
| shiny_input_update | Update input from module UI |
| shiny_output_info | get output information |
| shiny_query_ui | get HTML elements (mostly output) by css selector |
| trigger_rave_analysis | trigger module to "run-analysis" |

## Pipeline Scripts 

> Not recommended unless the task requires no UI interaction (e.g. check current status, get pipeline input formats)

| Script | Purpose |
|--------|---------|
| `set_inputs.R` | Read or update a module's `settings.yaml` |
| `get_targets.R` | List targets, dependencies, and build status |
| `run.R` | Execute pipeline targets |
| `get_results.R` | Read results from completed targets |

### Usage

Read-only ops:

**Read current settings:**

    action='script', file_name='set_inputs.R', args=['notch_filter']

**List targets and status:**

    action='script', file_name='get_targets.R', args=['notch_filter']
    
**Read a target result:**

    action='script', file_name='get_results.R', args=['notch_filter', '--target=apply_notch']

Destructive/Dangerous ops: 

> Although you have access to the pipelines, in general you should NOT modify the pipelines directly. Instruct users on how to set up module UI instead, unless the user asks specifically to change/run the pipeline.

**Update settings:**

    action='script', file_name='set_inputs.R', args=['notch_filter', '{"subject_code":"YAB","project_name":"demo"}']

**Run all targets:**

    action='script', file_name='run.R', args=['notch_filter']

**Run specific targets:**

    action='script', file_name='run.R', args=['notch_filter', '--targets=apply_notch,diagnostic_plots']


---

## Source Reading Scripts

Read module source files to understand UI components, pipeline logic, and
module architecture. **Privacy protected**: only canonical source files are
accessible (no user data, settings, or cached results).

| Script | Purpose |
|--------|---------|
| `list_source_files.R` | List canonical source files in a module |
| `read_source_file.R` | Read file with line numbers (default 200 lines) |
| `grep_source_file.R` | Search file with context (before/after lines) |

### Canonical Files

| File/Directory | Purpose |
|----------------|---------|
| `DESCRIPTION` | Module metadata (title, version, authors) |
| `main.Rmd` | Pipeline targets defined as R Markdown chunks |
| `R/` | R source files (UI, server logic, utilities) |
| `py/` | Python source files (if present) |
| `server.R` | Shiny server entry point |
| `report-*.Rmd` | Report templates |

### Usage

**List all source files:**

    action='script', file_name='list_source_files.R', args=['notch_filter']

**Read file (first 200 lines, with line numbers):**

    action='script', file_name='read_source_file.R', args=['notch_filter', '--file=DESCRIPTION']

**Read file starting from line 50:**

    action='script', file_name='read_source_file.R', args=['notch_filter', '--file=R/module_server.R', '--start=50']

**Read file with custom line count:**

    action='script', file_name='read_source_file.R', args=['notch_filter', '--file=main.Rmd', '--start=1', '--nlines=100']

**Search for pattern with context:**

    action='script', file_name='grep_source_file.R', args=['notch_filter', '--file=R/module_server.R', '--pattern=bindEvent']

**Search with custom context (5 lines before, 20 after):**

    action='script', file_name='grep_source_file.R', args=['notch_filter', '--file=R/module_html.R', '--pattern=sliderInput', '--before=5', '--after=20']

### Output Format

`read_source_file.R` outputs:
```
## module_id/file.R (lines 1-200 of 350)

  1: # First line
  2: # Second line
...
```

`grep_source_file.R` outputs (matching lines marked with `>`):
```
--- Match 1 (line 45) ---
 40: context before
 45: >matching line
 50: context after
```

---

## Understanding Module Architecture

1. **Start with DESCRIPTION** — understand what the module does
2. **Read main.Rmd** — see pipeline targets and data flow
3. **Read R/module_html.R** — UI component definitions
4. **Read R/module_server.R** — server logic and reactivity
5. **Read R/loader.R** — data loading logic (if present)
6. **Read report-*.Rmd** — report generation templates

### Key Patterns to Search

- `pipeline$read(var_names)` — read pipeline target results
- `pipeline$run(as_promise = TRUE)` — trigger pipeline execution
- `ravedash::watch_data_loaded()` — react to data loading
- `local_reactives` / `local_data` — module state management
- `shiny::bindEvent` — reactive event bindings
- `shiny::updateSelectInput` — UI updates

---

## Reference Files

Module-specific documentation is available via `action='reference'`:

    action='reference', file_name='notch_filter.md'

Each module reference has the following contents: (you can `grep` the reference)

```
# {module_name} Module Reference

Brief description of what the module does.

## 1. Pipeline Interface

### 1.1 Prerequisites
### 1.2 Pipeline Settings
### 1.3 Key Targets

## 2. Module UI Interface

### 2.1 Input Components
### 2.2 UI to Pipeline Mapping
### 2.3 Pipeline Execution Flow
### 2.4 Outputs and Visualizations

## 3. Data Export and Reports

### 3.1 Reading Pipeline Results in R
### 3.2 Built-in Export Functions
### 3.3 Available Reports
```

---

## Notes

- The first argument to every script is always `module_id` (e.g., `notch_filter`)
- Module path resolves to `modules/{module_id}/` relative to project root
- Source reading is privacy-protected: `settings.yaml` and `_targets/` are blocked