Feature Triage: IGV Configuration for Templates (Galaxy #21474)

FEATURE_21474.md

Feature Request: IGV Configuration for Templates

Issue: #21474 Author: @mvdbeek Created: 2025-12-16 State: OPEN Labels: kind/enhancement, kind/feature, area/visualizations

Summary

We're working on an end 2 end differential expression workflow and it'd be awesome if we can build and embed a multi-track IGV instance in pages and workflow reports.

Requirements

What's necessary is a config syntax that works with multiple inputs and collections.

Proposed Syntax

visualization(visualization_id=igv, alignment_tracks=<referece_to_hdca>, gene_model_tracks=<path_to_gtf>

Comments

@mvdbeek (2025-12-16)

@guerler would you have some time to work on this ?

Metadata

• Assignees: None
• Milestone: None
• Reactions: None

FEATURE_21474_APPROACHES.md

Feature #21474: IGV Configuration for Templates - Implementation Approaches

Summary

Build and embed multi-track IGV instances in Galaxy Pages and Workflow Reports. The feature requires a configuration syntax that supports multiple inputs and collections for creating complex visualizations with alignment tracks, gene models, and other genomic data.

Current Architecture

Visualization Embedding Overview

Galaxy uses "Galaxy Flavored Markdown" to embed visualizations in Pages and Workflow Reports. The system has three main layers:

1. Backend Parser (lib/galaxy/managers/markdown_parse.py)

   • Defines valid directives and their arguments
   • Current visualization directive uses DYNAMIC_ARGUMENTS - meaning it accepts any arguments without validation
   • Arguments are parsed as key-value pairs: directive(key1=value1, key2=value2)

2. Backend Handler (lib/galaxy/managers/markdown_util.py)

   • GalaxyInternalMarkdownDirectiveHandler.walk() processes directives
   • Current handle_visualization() does minimal processing - passes through the raw line
   • Workflow invocation resolution converts output="label" to history_dataset_id=<id>

3. Client Rendering (client/src/components/Markdown/)

   • SectionWrapper.vue routes to appropriate component by name
   • MarkdownGalaxy.vue renders the visualization directive
   • MarkdownVisualization.vue handles JSON-based visualization configs

Current Visualization Directive Syntax

The current syntax only supports a single dataset:

visualization(visualization_id=igv, history_dataset_id=abc123)

Limitations:

• Single dataset reference only (history_dataset_id)
• No support for collections
• No track configuration

Special Cases: Vitessce

Vitessce has custom handling (MarkdownVitessce.vue) that demonstrates multi-dataset support using JSON with special markers:

• __gx_dataset_id for direct dataset references
• __gx_dataset_label for workflow output references
• Client-side resolution of dataset URLs

---

Proposed Implementation Approaches

Approach 1: Extended Directive Syntax

Concept: Extend the existing visualization() directive to support multiple named track parameters.

Syntax:

visualization(
  visualization_id=igv,
  alignment_tracks=output_bam,
  gene_model_tracks=reference_gtf,
  reference=genome_fasta,
  height=600
)

Implementation:

1. Backend Changes:

   • Keep DYNAMIC_ARGUMENTS for visualization directive
   • Add new resolution patterns in resolve_invocation_markdown() for track parameters
   • Resolve each track parameter to appropriate dataset/collection IDs

2. Client Changes:

   • Update MarkdownGalaxy.vue to pass track config to VisualizationWrapper
   • IGV plugin receives config and builds track definitions

Tradeoffs:

Criteria	Rating	Notes
Complexity	Low	Minimal new code, extends existing patterns
Breaking Changes	None	Backward compatible
Performance	Good	Single parse pass
Maintainability	Medium	Track parameters scattered across codebase
Flexibility	Medium	Limited to predefined track types

---

Approach 2: JSON Configuration Block (RECOMMENDED)

Concept: Use a dedicated JSON block for complex visualization configuration, similar to Vitessce.

Syntax:

{
  "visualization_name": "igv",
  "height": 600,
  "tracks": [
    {
      "type": "alignment",
      "name": "Sample Alignments",
      "dataset_label": {"output": "mapped_reads"}
    },
    {
      "type": "annotation",
      "name": "Gene Models",
      "dataset_label": {"output": "gtf_output"}
    },
    {
      "type": "variant",
      "name": "Variants",
      "dataset_id": "abc123def456"
    }
  ],
  "reference": {
    "genome": "hg38"
  }
}

Implementation:

1. Backend Changes:

   • Already supported: VISUALIZATION_FENCED_BLOCK regex exists
   • Add process_visualization_datasets() similar to process_invocation_ids()
   • Resolve dataset_label and dataset_id markers to actual IDs

2. Client Changes:

   • MarkdownVisualization.vue already handles JSON content
   • Update to resolve track dataset references before rendering
   • Pass structured config to visualization iframe

Tradeoffs:

Criteria	Rating	Notes
Complexity	Medium	New JSON schema, validation needed
Breaking Changes	None	New block type, existing unchanged
Performance	Good	Single JSON parse
Maintainability	Good	Self-contained config, clear schema
Flexibility	High	Arbitrary track configuration

---

Approach 3: Dedicated IGV Directive

Concept: Create a new igv directive specifically for IGV visualizations.

Syntax:

igv(
  reference=hg38,
  alignment=output_bam,
  alignment=output_bam2,
  annotation=genes_gtf,
  variant=vcf_output,
  height=600
)

Implementation:

1. Backend Changes:

   • Add igv to VALID_ARGUMENTS dict with specific allowed parameters
   • Add handle_igv() method to directive handlers
   • Resolution logic specific to IGV track types

2. Client Changes:

   • Add MarkdownIGV.vue component
   • Build IGV configuration from resolved parameters
   • Direct IGV.js integration (not via generic visualization wrapper)

Tradeoffs:

Criteria	Rating	Notes
Complexity	Medium-High	New directive, handler, component
Breaking Changes	None	Additive change
Performance	Excellent	Optimized for IGV
Maintainability	Medium	Separate from generic visualization
Flexibility	Low-Medium	IGV-specific only

---

Approach 4: Multi-Track Visualization Extension

Concept: Create a general-purpose multi-track visualization system that can be reused for IGV and other visualizations.

Syntax (directive style):

visualization_tracks(
  visualization_id=igv,
  genome=hg38,
  tracks=[
    {type=alignment, data=bam_output, name="Alignments"},
    {type=annotation, data=gtf_output, name="Genes"},
    {type=variant, data=vcf_collection}
  ],
  height=600
)

Alternative (YAML-like syntax):

visualization_id: igv
genome: hg38
height: 600
tracks:
  - type: alignment
    data: bam_output
    name: Sample Alignments
  - type: annotation
    data: gtf_output
    name: Gene Models

Implementation:

1. Backend Changes:

   • Add visualization_tracks directive
   • Create track resolution framework
   • Define track type registry (alignment, annotation, variant, etc.)

2. Client Changes:

   • New MarkdownVisualizationTracks.vue component
   • Track configuration builder
   • Plugin-specific track adapters

Tradeoffs:

Criteria	Rating	Notes
Complexity	High	New parsing, registry, adapters
Breaking Changes	None	New directive
Performance	Good	Batch track resolution
Maintainability	Good	Reusable framework
Flexibility	Excellent	Any multi-track visualization

---

Comparison Matrix

Approach	Complexity	Breaking Changes	Performance	Maintainability	Flexibility	Recommended For
1. Extended Directive	Low	None	Good	Medium	Medium	Quick MVP
2. JSON Configuration	Medium	None	Good	Good	High	Most flexible
3. Dedicated IGV	Medium-High	None	Excellent	Medium	Low	IGV-only focus
4. Multi-Track Extension	High	None	Good	Good	Excellent	Long-term solution

---

Recommendations

Short-term (MVP)

Approach 2: JSON Configuration Block is recommended for initial implementation:

1. Infrastructure already exists (visualization block parsing)
2. Maximum flexibility for IGV configuration
3. Pattern established by Vitessce
4. No breaking changes
5. Users can copy/modify existing JSON configs

Long-term

Consider Approach 4: Multi-Track Extension as a follow-up:

1. Provides consistent syntax for all multi-track visualizations
2. Better discoverability (toolbox integration)
3. Validation and autocomplete support
4. Reusable for future visualizations (JBrowse2, etc.)

---

Implementation Plan for JSON Configuration (Approach 2)

Phase 1: Backend Support

1. Update markdown_parse.py:

   • No changes needed (already supports visualization blocks)

2. Update markdown_util.py:

   • Add process_visualization_datasets() function
   • Resolve __gx_dataset_label markers in track configs
   • Handle collection references

Phase 2: Client Support

1. Update MarkdownVisualization.vue:

   • Support tracks array in config
   • Resolve dataset labels via invocation store
   • Build dataset URLs

2. Update visualization plugins API:

   • Define tracks configuration schema
   • IGV plugin receives tracks array

Phase 3: Documentation and Tooling

1. Add documentation for JSON visualization config
2. Add example configurations in workflow report editor
3. Consider JSON schema for validation/autocomplete

---

Key Files for Implementation

Backend:

• /lib/galaxy/managers/markdown_parse.py - Directive validation
• /lib/galaxy/managers/markdown_util.py - Directive processing and resolution

Client:

• /client/src/components/Markdown/Sections/SectionWrapper.vue - Component routing
• /client/src/components/Markdown/Sections/MarkdownVisualization.vue - Visualization rendering
• /client/src/components/Markdown/Sections/MarkdownVitessce.vue - Reference for multi-dataset pattern
• /client/src/components/Markdown/Sections/MarkdownGalaxy.vue - Galaxy directive handling
• /client/src/components/Visualizations/VisualizationFrame.vue - Plugin iframe rendering

Visualization Plugin:

• /client/visualizations.yml - IGV plugin registration (version 0.0.23)

---

Unresolved Questions

1. How should collections be expanded - all elements as separate tracks, or single merged track?
2. Should track ordering be explicit or inferred from config order?
3. How to handle reference genome specification - by name (hg38) or dataset reference?
4. Should there be a UI for building IGV configs, or JSON-only?
5. How to handle track-specific options (color, height, display mode)?
6. Should PDF export render IGV as static image or placeholder?

FEATURE_21474_CODE_RESEARCH.md

Feature #21474: IGV Configuration for Templates - Code Research

Summary

This document contains research findings for implementing multi-track IGV visualization embedding in Galaxy pages and workflow reports, as requested in GitHub issue #21474.

1. Existing Visualization Embedding in Pages/Workflow Reports

Current Syntax

Galaxy uses "Galaxy Flavored Markdown" for embedding visualizations. The syntax is:

```galaxy
visualization(visualization_id=<plugin_name>, history_dataset_id=<encoded_id>)

**Key Files:**
- `/lib/galaxy/managers/markdown_parse.py` - Defines valid directives and argument parsing
- `/lib/galaxy/managers/markdown_util.py` - Handles directive resolution and rendering

### Valid Arguments for `visualization` Directive

From `markdown_parse.py:65`:
```python
VALID_ARGUMENTS: dict[str, Union[list[str], DynamicArguments]] = {
    ...
    "visualization": DYNAMIC_ARGUMENTS,  # Allows any arguments
    ...
}

The visualization directive uses DYNAMIC_ARGUMENTS which allows arbitrary key-value pairs, providing flexibility for custom visualization configurations.

How Directives Are Processed

1. Backend (markdown_util.py):

   • GalaxyInternalMarkdownDirectiveHandler.walk() parses markdown
   • handle_visualization() method (line 505) - currently just returns the line unchanged
   • For PDF export, ToBasicMarkdownDirectiveHandler.handle_visualization() returns "*Visualization inputs not implemented*"

2. Frontend (client/src/components/Markdown/Sections/MarkdownGalaxy.vue):

   • Line 242-246 shows current visualization handling:

   <VisualizationWrapper
       v-else-if="name == 'visualization'"
       :name="args.visualization_id"
       :config="{ dataset_id: args.history_dataset_id }"
       :height="args.height && parseInt(args.height)" />

Limitations

Current implementation only supports:

• Single history_dataset_id parameter
• Single visualization per directive
• No support for collections or multiple tracks

2. IGV Visualization Plugin Status

Current State

No IGV visualization plugin exists in the codebase. Galaxy has:

• Display applications for IGV (external viewer integration) at /lib/galaxy/datatypes/display_applications/configs/igv/
• These are display applications, not embeddable visualizations

Display applications found:

• bam.xml - Opens BAM files in external IGV
• vcf.xml - Opens VCF files in external IGV
• gff.xml, bigwig.xml, interval_as_bed.xml, etc.

Display Applications vs Visualization Plugins

Feature	Display Applications	Visualization Plugins
Location	External viewer	Embedded in Galaxy
Embeddable	No	Yes (if embeddable=true)
Multi-track	External app handles	Needs custom implementation

An IGV visualization plugin would need to be created using libraries like igv.js.

3. Visualization Plugin Architecture

Plugin Registration

Registry: /lib/galaxy/visualization/plugins/registry.py

• Searches static/plugins/visualizations/ and configured directories
• Loads plugins from XML configuration files

Plugin Class: /lib/galaxy/visualization/plugins/plugin.py

class VisualizationPlugin:
    def to_dict(self):
        return {
            "name": self.name,
            "embeddable": self.config.get("embeddable"),
            "entry_point": self.config.get("entry_point"),
            "params": self.config.get("params"),
            "tracks": self.config.get("tracks"),  # <-- Already supports tracks!
            "settings": self.config.get("settings"),
            ...
        }

Example Plugin Configuration

From /config/plugins/visualizations/example/static/example.xml:

<visualization name="Minimal Example" hidden="true">
    <data_sources>
        <data_source>
            <model_class>HistoryDatasetAssociation</model_class>
            <test test_attr="ext">tabular</test>
        </data_source>
    </data_sources>
    <params>
        <param required="true">dataset_id</param>
    </params>
    <entry_point entry_point_type="script" src="script.js" />
    <tracks>
        <input>
            <name>track_input</name>
            <help>track help</help>
            <type>track_type</type>
        </input>
    </tracks>
</visualization>

Note: The <tracks> element is already supported in the plugin schema but not fully utilized.

4. Patterns for Multiple Inputs/Collections

Vitessce as a Model

Vitessce visualization (client/src/components/Markdown/Sections/MarkdownVitessce.vue) demonstrates handling multiple datasets:

<script setup lang="ts">
// Iterates over datasets array in configuration
if (Array.isArray(parsedContent.datasets)) {
    for (const dataset of parsedContent.datasets) {
        if (Array.isArray(dataset.files)) {
            for (const file of dataset.files) {
                if ("__gx_dataset_id" in file) {
                    file.url = `${getAppRoot()}api/datasets/${file.__gx_dataset_id}/display`;
                }
                if ("__gx_dataset_label" in file) {
                    // Resolves invocation outputs/inputs to dataset IDs
                    const datasetId = getDatasetId(invocation, datasetLabel);
                    file.url = `${getAppRoot()}api/datasets/${datasetId}/display`;
                }
            }
        }
    }
}
</script>

Key Pattern: JSON Configuration Block

Vitessce uses a JSON configuration block in markdown:

```vitessce
{
  "datasets": [
    {
      "files": [
        { "__gx_dataset_id": "abc123" },
        { "__gx_dataset_label": { "invocation_id": "xyz", "output": "alignment" } }
      ]
    }
  ]
}

This pattern could be adopted for IGV:
```markdown
```visualization
{
  "visualization_name": "igv",
  "genome": "hg38",
  "tracks": [
    { "__gx_dataset_id": "bam_file_id", "type": "alignment" },
    { "__gx_collection_id": "bam_collection_id", "type": "alignment" },
    { "__gx_dataset_label": { "output": "gtf_file" }, "type": "annotation" }
  ]
}

### Invocation Resolution

From `client/src/components/Markdown/Utilities/parseInvocation.ts`:
- `parseInput(invocation, label)` - resolves input labels to dataset IDs
- `parseOutput(invocation, label)` - resolves output labels to dataset IDs

These utilities support resolving workflow invocation outputs to actual dataset IDs.

## 5. Files/Modules Requiring Modification

### Backend Changes

| File | Change Required |
|------|-----------------|
| `/lib/galaxy/managers/markdown_parse.py` | Add new arguments to `visualization` directive (e.g., `tracks`, `genome`, collection IDs) |
| `/lib/galaxy/managers/markdown_util.py` | Update `handle_visualization()` to resolve track references, support collections |
| `/lib/galaxy/visualization/plugins/registry.py` | Possibly extend to support track configurations |
| `/lib/galaxy/visualization/plugins/config_parser.py` | No changes needed - already parses `<tracks>` |

### Frontend Changes

| File | Change Required |
|------|-----------------|
| `/client/src/components/Markdown/Sections/MarkdownVisualization.vue` | Handle multi-track configs, collection expansion |
| `/client/src/components/Markdown/Sections/MarkdownGalaxy.vue` | Update visualization directive handling (lines 242-246) |
| `/client/src/components/Markdown/Utilities/requirements.yml` | Add `history_dataset_collection_id` as valid for `visualization` |
| `/client/src/components/Markdown/Editor/Configurations/ConfigureVisualization.vue` | Add track/collection configuration UI |
| `/client/src/components/Visualizations/VisualizationFrame.vue` | Pass track configurations to plugin iframe |

### New Files Needed

| File | Purpose |
|------|---------|
| `static/plugins/visualizations/igv/` | IGV visualization plugin directory |
| `static/plugins/visualizations/igv/static/igv.xml` | Plugin configuration |
| `static/plugins/visualizations/igv/static/script.js` | IGV.js wrapper script |

## 6. Proposed Syntax Options

### Option A: Extended Directive Syntax (Proposed in Issue)

```markdown
```galaxy
visualization(visualization_id=igv, alignment_tracks=<hdca_id>, gene_model_tracks=<gtf_dataset_id>)

**Pros:**
- Familiar directive syntax
- Simple for basic use cases

**Cons:**
- Limited flexibility for complex configurations
- Hard to specify multiple track types

### Option B: JSON Configuration Block (Vitessce Pattern)

```markdown
```visualization
{
  "visualization_name": "igv",
  "visualization_title": "RNA-Seq Alignment Viewer",
  "genome": "hg38",
  "tracks": [
    {
      "type": "alignment",
      "name": "Sample Alignments",
      "__gx_collection_id": "abc123"
    },
    {
      "type": "annotation",
      "name": "Gene Models",
      "__gx_dataset_label": { "output": "gtf_output" }
    }
  ]
}

**Pros:**
- Maximum flexibility
- Can specify per-track options
- Follows established Vitessce pattern

**Cons:**
- More verbose
- Requires JSON editing

### Option C: Hybrid Approach

Support both:
1. Simple directive for single-track: `visualization(visualization_id=igv, history_dataset_id=X)`
2. JSON block for multi-track configurations

**Recommended:** Option C provides backward compatibility while enabling advanced use cases.

## 7. Collection Handling Considerations

### Expanding Collections to Individual Tracks

For `alignment_tracks=<hdca_id>`, the system needs to:

1. Resolve HDCA to individual HDA elements
2. Generate track configuration for each element
3. Handle nested collections (e.g., `list:list` structures)

**Backend code for collection resolution:**
```python
# lib/galaxy/managers/hdcas.py
class HDCASerializer:
    def serialize_to_view(hdca, ...)  # Already exists

Frontend collection handling:

// Similar to existing collection display logic
function expandCollection(collectionId: string): Track[] {
    // Fetch collection elements
    // Create track entry for each HDA
}

API Endpoints Needed

Existing endpoints that can be leveraged:

• GET /api/dataset_collections/{id} - Get collection contents
• GET /api/datasets/{id}/display - Get dataset content URL

8. Implementation Roadmap

Phase 1: Backend Foundation

1. Update markdown_parse.py to accept collection references in visualization directive
2. Add collection resolution in markdown_util.py
3. Create data provider for multi-track visualization configs

Phase 2: IGV Plugin

1. Create basic IGV visualization plugin using igv.js
2. Define plugin XML with track configuration schema
3. Implement iframe communication for track updates

Phase 3: Frontend Integration

1. Update MarkdownVisualization.vue to handle multi-track configs
2. Create configuration UI for track selection
3. Add collection expansion logic

Phase 4: Workflow Report Integration

1. Enable workflow output label references (e.g., output=alignment_bams)
2. Test with actual differential expression workflow
3. Documentation and examples

9. Unresolved Questions

1. Should collections be auto-expanded or allow user to select specific elements?
2. How to handle very large collections (performance limits for IGV)?
3. Should genome/reference be specified per-visualization or inferred from datasets?
4. PDF export behavior - static screenshot vs "visualization not available" message?
5. Should track order be user-configurable in the editor UI?
6. How to handle mixed datatypes in a collection (e.g., BAM + BAI in same collection)?
7. Authentication for dataset access URLs when embedding in shared pages?

10. Related Code References

Key Classes and Functions

Backend:
- GalaxyInternalMarkdownDirectiveHandler (markdown_util.py)
- VisualizationsRegistry (registry.py)
- VisualizationsConfigParser (config_parser.py)
- HDCASerializer (hdcas.py)

Frontend:
- MarkdownVisualization.vue
- MarkdownVitessce.vue (reference implementation)
- VisualizationFrame.vue
- ConfigureVisualization.vue
- parseInvocation.ts

Test Files

- lib/galaxy_test/api/test_visualizations.py
- client/src/components/Markdown/Sections/MarkdownVitessce.test.js
- client/src/components/Markdown/Editor/Configurations/ConfigureVitessce.test.js

---

Research conducted: 2026-01-13 Issue: galaxyproject/galaxy#21474

FEATURE_21474_DEMAND.md

Feature Demand Analysis: IGV Configuration for Templates (#21474)

Issue Overview

• Issue: #21474 - IGV configuration for templates
• Author: @mvdbeek (Galaxy core committer)
• Created: 2025-12-16
• Labels: kind/enhancement, kind/feature, area/visualizations
• State: Open

Request Summary

Build and embed multi-track IGV instance in pages and workflow reports for an end-to-end differential expression workflow. Proposed syntax:

visualization(visualization_id=igv, alignment_tracks=<reference_to_hdca>, gene_model_tracks=<path_to_gtf>)

---

Engagement Metrics

Metric	Count
Reactions (thumbs up)	0
Comments	1 (author asking @guerler to work on it)
Linked PRs	0
Age	~4 weeks

Assessment: Very recent issue with minimal external engagement so far. However, the request comes from a core committer working on a specific workflow use case.

---

Related Issues Analysis

Directly Related: Visualization in Reports/Collections

Issue	Title	State	Comments	Reactions
#18448	Inserting visualizations into workflow reports is broken	Open	0	0
#20420	Enable visualization in reports for HDCAs	Open	1	0
#19126	Integration of Vega into Workflow Reports	Open	2	1 heart

Key Finding: #20420 (by same author @mvdbeek) directly addresses HDCA visualization in reports - a prerequisite for #21474. This shows a pattern of building toward multi-track visualization capability.

IGV-Specific Issues (Recent Activity)

Issue	Title	State	Comments	Reactions
#21057	IGV issues	Closed	6	0
#21216	IGV visualization: BAMs and undefined genomes	Closed	3	1 thumbs up
#21183	IGV visualization not loading reference Genomes	Closed	9	1 thumbs up
#21186	IGV visualization private field error on t2t genome	Open	0	1 thumbs up
#11075	IGV.js	Closed	6	1 thumbs up

Key Finding: Significant recent activity (Oct-Dec 2025) on IGV integration, including:

• IGV.js was implemented in Sept 2025 after 5 years of requests (PR #20943)
• Multiple bug fixes for genome loading and collection support
• @nekrut specifically stated "We REALLY need this now (in particular for BRC)" regarding IGV.js

Workflow Reports Enhancement Requests

Issue	Title	State	Comments	Reactions
#15220	Workflow Reports/Pages papercuts	Open	3	3 thumbs up
#11426	Workflow reporting - support for IFrames, Fancy Tables	Open	8	1 hooray
#15088	Workflow reporting - support for expandable sections, ToC, multitabs	Open	8	0
#21256	Pages or Reports Editor Enhancements and AI Integration	Open	0	0

Key Finding: #11426 (by @hexylena) specifically mentions:

• Embedded JBrowse instances that are live/browseable
• This is exactly the same use case as #21474 but for JBrowse instead of IGV
• Multiple core team members engaged in that discussion

Visualization Plugin Issues

Issue	Title	State	Comments	Reactions
#20338	Config for "visualization plugin" missing for type like bam	Open	3	0
#20608	UCSC Genome Browser should be a vis option for VCF	Open	1	0

---

Demand Signals Summary

Strong Indicators

1. Internal demand from core team:

   • @mvdbeek (author) is building end-to-end differential expression workflow
   • @nekrut explicitly requested IGV.js for BRC project
   • @guerler assigned to work on it

2. Prerequisite work recently completed:

   • IGV.js integration merged Sept 2025 (PR #20943)
   • Collection support improvements made (Oct-Dec 2025)
   • Multiple IGV bugs fixed in preparation

3. Related feature requests exist:

   • #11426: JBrowse embedding in reports (2021, 8 comments)
   • #19126: Vega integration in reports (2 comments, 1 heart)
   • #20420: HDCA visualization in reports (same author)

4. Infrastructure work converging:

   • Vega backend/frontend rendering capability being developed
   • Pages editor modernization planned (#21256)

Weak Indicators

1. No community reactions on this specific issue yet (but very new)
2. No duplicate issues found (novel feature request)
3. No external community discussion found (limited search capability)

---

Quantified Demand Assessment

Signal	Weight	Score
Core team member request	High	+3
Active related development	High	+3
Prerequisite features recently added	Medium	+2
Similar past requests (JBrowse embed)	Medium	+2
Community reactions	Low	0
External discussion	Low	0
Total		10/15

Interpretation

• Score 10/15: Moderate-to-strong internal demand with clear technical path
• Primary driver is team's workflow use case rather than broad community request
• Feature aligns with ongoing visualization modernization efforts

---

Stakeholder Analysis

Direct Beneficiaries

1. Differential expression workflow users - Primary use case
2. BRC project - @nekrut indicated IGV need for this initiative
3. RNA-seq analysts - Multi-track alignment visualization common need

Related Stakeholders

• @guerler - Assigned to implement
• @dannon - Working on visualization infrastructure (Vega, bam-js)
• @jmchilton - Workflow reports architecture

---

Dependencies and Blockers

Prerequisites (Completed)

• IGV.js integration (#11075, closed Sept 2025)
• Collection element selection in visualizations (#21057 items)

Prerequisites (Pending)

• HDCA visualization in reports (#20420)
• Fix broken visualization insertion (#18448)
• Track settings persistence (galaxy-visualizations#133)

---

Conclusion

Demand Level: MODERATE-HIGH (Internal)

This feature has strong internal demand from the Galaxy development team for a specific workflow use case. While external community engagement is minimal (likely due to issue being very new), the request aligns with:

1. Years of requests for embedded genome browsers in reports
2. Active visualization modernization work
3. Specific BRC project needs

The feature represents a natural evolution of recently completed IGV.js work and addresses a gap in workflow reporting capabilities. Implementation appears to be proceeding with @guerler assigned.

---

Generated: 2026-01-13

FEATURE_21474_IMPORTANCE.md

Feature #21474: IGV Configuration for Templates - Importance Assessment

Issue: #21474 Feature: Build and embed multi-track IGV instances in Pages and Workflow Reports

---

1. User Demand

Rating: MEDIUM-HIGH

Signals

Signal	Strength	Evidence
Core team request	Strong	@mvdbeek (core committer) opened issue for differential expression workflow
BRC project dependency	Strong	@nekrut: "We REALLY need this now (in particular for BRC)"
5-year IGV history	Strong	IGV.js requested since 2020 (#11075), finally merged Sept 2025
Community reactions	Weak	Issue new (~4 weeks), 0 reactions, 1 comment
Related requests	Medium	#11426 (JBrowse embed, 8 comments), #20420 (HDCA in reports)

Assessment

Internal demand is strong - this is a direct ask from a core committer building an end-to-end workflow. The feature represents the logical next step after IGV.js integration (merged Sept 2025) and addresses a long-standing gap in workflow reporting capabilities.

External community engagement is minimal, but the issue is new and the underlying need (embedded genome browsers in reports) has been requested since 2021.

---

2. Strategic Value

Rating: HIGH

Alignment with Project Direction

Factor	Assessment
Visualization modernization	Directly aligned - complements IGV.js integration, Vega work
Workflow reporting maturity	Directly aligned - addresses key gap in report capabilities
BRC initiative	Strategic - supports funded project requirements
End-to-end workflows	Strategic - improves differential expression workflow completeness

Enables Other Features

• Template for other multi-track visualizations - JBrowse2, custom genome browsers
• Enhanced workflow reports - Rich interactive output presentation
• Pages modernization - Interactive embedding capabilities

UX Impact

• Significant improvement for RNA-seq/genomics workflows
• Reduces friction - Users stay in Galaxy instead of exporting to external viewers
• Better reproducibility - Visualization configuration stored with workflow

Strategic Assessment

This feature sits at the intersection of multiple project priorities: visualization modernization, workflow report enhancement, and BRC project support. The JSON configuration pattern (following Vitessce) establishes a reusable foundation for future multi-dataset visualizations.

---

3. Effort Estimate

Rating: MEDIUM

Breakdown by Component

Component	Effort	Rationale
Backend changes	Small	DYNAMIC_ARGUMENTS already exists; add track resolution
Frontend changes	Medium	Update MarkdownVisualization.vue, track URL resolution
IGV plugin creation	Medium	New plugin required using igv.js
Collection handling	Small-Medium	Expand HDCA to track configs
Testing	Medium	Integration tests for multi-track scenarios
Documentation	Small	Examples, JSON schema

Key Factors

1. Infrastructure exists: Visualization block parsing, Vitessce pattern for reference
2. No new APIs needed: Leverage existing dataset/collection endpoints
3. Isolated changes: Most work in visualization components, minimal core changes
4. Clear reference implementation: Vitessce demonstrates multi-dataset pattern

---

4. Risk Assessment

Breaking Changes

Risk: NONE

• JSON configuration block is additive
• Existing visualization() directive unchanged
• New syntax optional, not required

Migration Needs

Risk: NONE

• No existing data affected
• No schema changes
• Users adopt when ready

Security Considerations

Risk: LOW

Concern	Mitigation
Dataset access URLs	Use existing authenticated endpoints
Shared pages	Respect existing visibility controls
Cross-origin iframe	Existing CSP policies apply

Technical Risks

Risk	Likelihood	Impact	Mitigation
Large collection performance	Medium	Medium	Limit tracks, lazy loading
IGV.js compatibility	Low	Medium	Version pinning, fallback
Complex nested collections	Medium	Low	Support flat collections first

Overall Risk

LOW - Feature is additive with clear implementation patterns established by Vitessce.

---

5. Recommendation

PRIORITIZE NOW

Rationale

1. Strategic alignment: Directly supports BRC project and visualization modernization
2. Effort justified: Medium effort for high strategic value
3. Low risk: No breaking changes, clear implementation path
4. Foundation building: Establishes pattern for future multi-track visualizations
5. Active development: IGV.js recently integrated, momentum exists
6. Internal customer: Core team needs this for specific workflow use case

Implementation Sequence

1. JSON configuration support for visualization directive (Phase 1)
2. IGV visualization plugin with multi-track support (Phase 2)
3. Collection expansion logic (Phase 3)
4. UI configuration tooling (Phase 4, optional)

Dependencies to Address First

• Fix broken visualization insertion (#18448) if not already resolved
• HDCA visualization in reports (#20420) for collection support

Success Criteria

• Multi-track IGV embedded in workflow report
• Support for alignment tracks (BAM collection) + annotation tracks (GTF)
• Configuration via JSON block in Galaxy Flavored Markdown
• Works with workflow output label references

---

Summary

Dimension	Rating
User Demand	Medium-High
Strategic Value	High
Effort	Medium
Risk	Low
Recommendation	Prioritize Now

This feature addresses a clear internal need, aligns with multiple strategic priorities, and has manageable implementation risk. The recent IGV.js integration provides foundation and momentum. Recommend proceeding with JSON configuration approach (Approach 2 from code research) as it provides maximum flexibility with established patterns.

---

Assessment Date: 2026-01-13 Issue: galaxyproject/galaxy#21474

FEATURE_21474_PLAN.md

Feature #21474: IGV Configuration for Templates - Implementation Plan

Overview

Build and embed multi-track IGV instances in Galaxy Pages and Workflow Reports, supporting multiple inputs and collections for differential expression workflows.

Issue: #21474

---

1. Recommended Approach

Summary: JSON Configuration Block (Approach 2)

The recommended approach uses a dedicated JSON configuration block within Galaxy Flavored Markdown, following the pattern established by Vitessce visualization.

Proposed Syntax:

{
  "visualization_name": "igv",
  "height": 600,
  "reference": {
    "genome": "hg38"
  },
  "tracks": [
    {
      "type": "alignment",
      "name": "Sample Alignments",
      "dataset_label": {"output": "mapped_reads"}
    },
    {
      "type": "annotation",
      "name": "Gene Models",
      "dataset_label": {"output": "gtf_output"}
    },
    {
      "type": "alignment",
      "name": "RNA-Seq Collection",
      "collection_label": {"output": "bam_collection"}
    }
  ]
}

Why This Approach Was Selected

1. Infrastructure Exists - Visualization block parsing and MarkdownVisualization.vue already handle JSON content
2. Proven Pattern - Vitessce demonstrates multi-dataset resolution using __gx_dataset_label markers
3. Maximum Flexibility - JSON allows arbitrary track configuration, per-track options, and future extensibility
4. No Breaking Changes - New block type leaves existing visualization() directive unchanged
5. User-Friendly - JSON configs can be copied, shared, and modified; enables template sharing

---

2. Affected Files

Backend Files

File	Changes Required
/lib/galaxy/managers/markdown_util.py	Add process_visualization_tracks() function to resolve track dataset/collection references
/lib/galaxy/managers/hdcas.py	Add helper method to expand collection to element IDs for track generation

No changes needed:

• /lib/galaxy/managers/markdown_parse.py - Already supports DYNAMIC_ARGUMENTS for visualization directive

Frontend Files

File	Changes Required
/client/src/components/Markdown/Sections/MarkdownVisualization.vue	Support tracks array in config; resolve dataset labels via invocation; build dataset URLs
/client/src/components/Visualizations/VisualizationFrame.vue	Pass track configuration array to plugin iframe via postMessage
/client/src/components/Markdown/Utilities/parseInvocation.ts	Add parseCollectionOutput() function for collection label resolution

New Files to Create

File	Purpose
/client/src/components/Markdown/Sections/MarkdownIGV.vue	IGV-specific component handling track configuration and igv.js initialization
/client/src/components/Markdown/Editor/Configurations/ConfigureIGV.vue	UI for building IGV JSON configuration in workflow report editor

---

3. Implementation Steps

Step 1: Backend Track Resolution

Goal: Resolve track dataset/collection labels to actual IDs and URLs

Changes to /lib/galaxy/managers/markdown_util.py:

def process_visualization_tracks(trans, invocation, tracks_config):
    """Resolve track references in visualization config."""
    resolved_tracks = []
    for track in tracks_config.get("tracks", []):
        if "dataset_label" in track:
            dataset_id = resolve_label_to_id(invocation, track["dataset_label"])
            track["dataset_id"] = dataset_id
            track["url"] = f"/api/datasets/{dataset_id}/display"
        elif "collection_label" in track:
            collection_id = resolve_collection_label(invocation, track["collection_label"])
            expanded = expand_collection_to_tracks(trans, collection_id, track)
            resolved_tracks.extend(expanded)
            continue
        resolved_tracks.append(track)
    return resolved_tracks

Step 2: Collection Expansion Helper

Goal: Expand HDCA to individual track entries

Step 3: Frontend Track Resolution

Goal: Client-side resolution of track references and URL building

Step 4: IGV Component Creation

Goal: Create dedicated IGV visualization component

Step 5: Section Router Update

Goal: Route visualization blocks with visualization_name=igv to IGV component

Step 6: Configuration Editor UI (Optional)

Goal: Visual editor for building IGV configurations

---

4. Testing Strategy

Unit Tests

Test File	Coverage
/client/src/components/Markdown/Sections/MarkdownIGV.test.ts	IGV component rendering, config parsing
/lib/galaxy_test/unit/managers/test_markdown_util.py	Track resolution, collection expansion

Integration Tests

Test File	Coverage
/lib/galaxy_test/api/test_pages.py	IGV config in pages API
/lib/galaxy_test/api/test_workflow_reports.py	IGV in workflow reports

Manual Testing Scenarios

1. Basic IGV Display - Single BAM track in page
2. Multi-Track Configuration - BAM + GTF + VCF tracks
3. Collection Expansion - HDCA with multiple BAM files
4. Workflow Report Integration - Differential expression workflow

---

5. Migration Considerations

Backward Compatibility

• No breaking changes - existing visualization() directive syntax unchanged
• New JSON config block is additive
• Existing visualizations continue to work

Data Migration

• None required - no schema changes to stored data

Documentation Updates

Document	Updates Needed
/doc/source/dev/visualization.rst	Add IGV multi-track configuration section
/doc/source/user/workflow_reports.rst	Add IGV embedding examples

---

6. Phased Delivery

Phase 1: Core Functionality (MVP)

Goal: Basic IGV embedding with multi-track support

Deliverables:

• Backend track resolution (markdown_util.py)
• Frontend IGV component (MarkdownIGV.vue)
• Dataset reference resolution

Acceptance Criteria:

• IGV loads with JSON config in page
• Multiple dataset tracks display correctly
• Workflow output labels resolve to datasets

Phase 2: Collection Support

Goal: Expand collections to individual tracks

Deliverables:

• Collection expansion helper
• Collection label resolution in frontend
• Integration tests

Acceptance Criteria:

• HDCA expands to individual tracks
• Each collection element named appropriately

Phase 3: Editor UI & Polish

Goal: Visual configuration builder

Deliverables:

• ConfigureIGV.vue component
• Selenium e2e tests

Phase 4: Documentation & Examples

Goal: User-facing documentation

Deliverables:

• User documentation for IGV embedding
• Example workflow with IGV report

---

7. Unresolved Questions

1. Collection expansion limits - cap number of tracks from large collections?
2. Reference genome handling - support both named genomes (hg38) and custom FASTA references?
3. Track ordering - preserve config order or allow reordering in UI?
4. Per-track options - support IGV display options (color, height, visibility)?
5. PDF export - static screenshot, placeholder, or skip IGV entirely?
6. Index files - how to associate BAI with BAM when both are needed?

---

Plan created: 2026-01-13 Issue: galaxyproject/galaxy#21474

FEATURE_21474_SUMMARY.md

Feature Triage Summary: IGV Configuration for Templates (#21474)

Issue: #21474 Author: @mvdbeek Created: 2025-12-16

---

Executive Summary

This feature request proposes building and embedding multi-track IGV instances in Galaxy Pages and Workflow Reports to support end-to-end differential expression workflows. The recommended approach uses a JSON configuration block (similar to Vitessce) that allows specifying multiple alignment tracks from collections plus annotation tracks like GTF files. This feature has strong internal demand from core team members (@mvdbeek, @nekrut for BRC project), represents a natural evolution of the recently integrated IGV.js visualization (Sept 2025), and aligns with ongoing visualization modernization efforts. With medium effort and low risk (no breaking changes, clear implementation patterns), this feature is recommended for immediate prioritization.

---

Importance Assessment Summary

Dimension	Rating
User Demand	Medium-High
Strategic Value	High
Effort Estimate	Medium
Risk	Low
Recommendation	Prioritize Now

Key Factors

• Internal demand is strong: Core committer building differential expression workflow
• Strategic alignment: Supports BRC project, complements recent IGV.js integration
• Clear implementation path: Vitessce pattern provides blueprint, infrastructure exists
• No breaking changes: Additive JSON configuration block syntax

---

Key Questions for Discussion

Requirements Clarification

1. Collection handling: Should large collections (50+ BAMs) be automatically limited, or should users manually select which elements become tracks?

2. Reference genome: Support only named genomes (hg38, mm10) or also allow custom FASTA datasets as references?

3. Track grouping: For collections, should tracks be grouped visually (e.g., "Sample Alignments" as a collapsible group) or kept as flat individual tracks?

Implementation Decisions

4. Index file handling: How should BAI files be associated with BAM files when both are needed for IGV display? Same collection element? Separate reference?

5. PDF export behavior: Static screenshot capture, placeholder text ("Interactive visualization not available in PDF"), or omit entirely?

6. Configuration UI priority: Is a visual JSON builder needed for MVP, or is JSON-only acceptable initially?

Scope Boundaries

7. Other genome browsers: Should this infrastructure be designed to also support JBrowse2 embedding, or focus solely on IGV?

8. Track-level options: Support IGV display options per-track (color, height, visibility mode) in v1, or defer to future enhancement?

---

Concerns

Scope Creep Risk

The request is focused on IGV specifically, but the infrastructure could generalize to any multi-track genome browser. Consider whether to:

• Implement IGV-specific solution (faster, simpler)
• Build generalized multi-track visualization framework (more effort, more reusable)

Recommendation: Start with IGV-specific, refactor to generalize if JBrowse2 request follows.

Breaking Changes

None identified. The JSON configuration block is additive and doesn't affect existing visualization() directive syntax.

Long-term Maintenance

• IGV.js version pinning needed to prevent breaking changes from upstream
• JSON schema should be versioned if configuration format evolves
• Collection expansion logic could become complex for nested collections

Dependencies

Two related issues may need resolution first:

• #18448 - Inserting visualizations into workflow reports is broken
• #20420 - Enable visualization in reports for HDCAs (same author)

---

Related Documents

Document	Contents
FEATURE_21474.md	Original issue details
FEATURE_21474_DEMAND.md	User demand analysis, related issues, engagement metrics
FEATURE_21474_CODE_RESEARCH.md	Codebase analysis, affected files, existing patterns
FEATURE_21474_APPROACHES.md	4 implementation approaches with tradeoffs
FEATURE_21474_IMPORTANCE.md	Priority assessment and recommendation
FEATURE_21474_PLAN.md	Detailed implementation plan with phased delivery

---

Triage completed: 2026-01-13 Generated for discussion on Issue #21474