Waterfall Plot

Horizontal bar chart of gene perturbation effect sizes, sorted by magnitude. Based on the WaterfallPlot component from thedatavizcomponents library, used in the PerturbSeq application to display differential expression results.

Live Demo

Color by:

Sort:

Show threshold lines

Implementation Guide

D3 + React Pattern

Uses the "D3 for rendering, React for lifecycle" pattern. D3 handles SVG creation and data binding inside useEffect, while React manages state (sort order, color mode, threshold visibility).

const svgRef = useRef<SVGSVGElement>(null);

useEffect(() => {
  const svg = d3.select(svgRef.current);
  svg.selectAll('*').remove(); // Clear previous render

  const xScale = d3.scaleLinear()
    .domain([-maxAbs, maxAbs])
    .range([0, plotWidth]);

  // Bars
  g.selectAll('.bar')
    .data(data)
    .enter()
    .append('rect')
    .attr('x', d => d.value >= 0 ? xScale(0) : xScale(d.value))
    .attr('width', d => Math.abs(xScale(d.value) - xScale(0)));
}, [data, colorBy]);

Responsive Sizing

A ResizeObserver watches the container and re-renders the chart when the width changes. Height is computed from the number of data rows.

Tooltip Pattern

Tooltips use a positioned HTML div (not SVG title elements) for richer formatting. The tooltip div is managed via a ref and positioned using mouse event coordinates relative to the container.

Architecture

┌──────────────────────────────────────────┐
│           React Component                │
│                                          │
│  State:                                  │
│  ├─ colorBy: 'effect' | 'category'       │
│  ├─ sortOrder: 'magnitude' | 'alpha'     │
│  └─ showThreshold: boolean               │
│                                          │
│  ┌──────────────────────────────────────┐│
│  │  SVG (D3-managed)                    ││
│  │  ├─ X axis (linear scale)            ││
│  │  ├─ Zero line                        ││
│  │  ├─ Threshold lines (±1 FC)          ││
│  │  ├─ Horizontal bars (sorted)         ││
│  │  ├─ Gene labels (left)               ││
│  │  └─ Value labels (right of bars)     ││
│  └──────────────────────────────────────┘│
│                                          │
│  ┌──────────────────────────────────────┐│
│  │  HTML Tooltip (positioned div)       ││
│  │  ├─ Gene name                        ││
│  │  ├─ Effect size                      ││
│  │  ├─ p-value                          ││
│  │  └─ Category                         ││
│  └──────────────────────────────────────┘│
└──────────────────────────────────────────┘

Source Reference

datavizcomponents/src/components/WaterfallPlot.jsx
datavizcomponents/src/modules/waterfallplot/waterfallplotLib.js
perturbseqapp/src/components/VizComponents/RowWaterfall.js

Use Cases

Perturbation Rankings

Rank gene knockouts by their effect on a target phenotype. Quickly identify the strongest activators and repressors.

Differential Expression

Display log-fold-change values for differentially expressed genes, with threshold lines marking significance cutoffs.

Feature Importance

Visualize feature importance scores from machine learning models, showing which variables contribute most to predictions.