29:null 2a:["$","title",null,{"children":"Color legend with outliers (and automatic outlier color assignment) | Lee Mason | Observable"}] 2f:T9b3,/** * Creates a trimmed color scheme with outlier colors. * * @param {string[]} colors - Array of color strings (any colorjs.io-parseable format) * @param {number} pLow - Proportion to cut from the low end (0 to <0.5), * measured perceptually in OKLab space. Defaults to 0. * @param {number} pHigh - Proportion to cut from the high end (0 to <0.5), * measured perceptually in OKLab space. Defaults to 0. * @param {number} numStops - Number of colors to return in the trimmed scheme. * Defaults to max(colors.length, 5). * @returns {{ * scheme: string[], // trimmed color scheme as array of hex strings * lowerOutlier: string, // original lowest color * higherOutlier: string // original highest color * }} */ function buildTrimmedColorScheme(colors, pLow = 0, pHigh = 0, numStops = null) { if (!Array.isArray(colors) || colors.length < 2) { throw new Error("Need at least 2 colors"); } if (pLow < 0 || pHigh < 0 || pLow + pHigh >= 1) { throw new Error("pLow and pHigh must be non-negative and sum to less than 1"); } const parsed = colors.map((c) => new Color(c).to("oklab")); const segmentLengths = []; for (let i = 0; i < parsed.length - 1; i++) { segmentLengths.push(parsed[i].deltaE(parsed[i + 1], "OK")); } const cumulative = [0]; for (const len of segmentLengths) { cumulative.push(cumulative[cumulative.length - 1] + len); } const totalLength = cumulative[cumulative.length - 1]; const stopCount = numStops ?? Math.max(colors.length, 5); if (totalLength === 0) { return { scheme: Array(stopCount).fill(colors[0]), lowerOutlier: colors[0], higherOutlier: colors[colors.length - 1], }; } const sampleAt = (t) => { const target = t * totalLength; let i = 0; while (i < segmentLengths.length - 1 && cumulative[i + 1] < target) i++; const segStart = cumulative[i]; const segLen = segmentLengths[i]; const localT = segLen === 0 ? 0 : (target - segStart) / segLen; return parsed[i] .range(parsed[i + 1], { space: "oklab" })(localT) .to("srgb") .toString({ format: "hex" }); }; const scheme = []; for (let i = 0; i < stopCount; i++) { const u = i / (stopCount - 1); const t = pLow + u * (1 - pLow - pHigh); scheme.push(sampleAt(t)); } return { scheme, leftOutlier: colors[0], rightOutlier: colors[colors.length - 1], }; }30:T2fe7,/** * Renders a color ramp legend with optional low/high outlier swatches. * * @param {Object} options - Configuration options for the legend. * @param {HTMLElement} options.container - The DOM element to render the legend into (if null, creates and returns element). * @param {Array} options.domain - The [min, max] data bounds. * @param {string|Function|Array} options.scheme - D3 interpolator name (e.g., 'Blues'), * an interpolator function, or an array of CSS color strings to interpolate across. * @param {string} [options.label=''] - The text label to display above the legend. * @param {number|null} [options.pivot=null] - Optional midpoint to balance the color scale around. * @param {boolean} [options.reverse=false] - Whether to reverse the color scale mapping. * @param {string|false} [options.lowOutlierColor=false] - Color for the low outlier swatch (falsy to omit). * @param {string|false} [options.highOutlierColor=false] - Color for the high outlier swatch (falsy to omit). * @param {boolean} [options.stripedOutliers=false] - Whether to overlay white diagonal stripes on the outlier swatches. * @param {number} [options.width=400] - Base width of the entire legend container. * @param {number} [options.height=50] - Base height of the legend. */ function renderColorLegend(options = {}) { let { container, domain, scheme, label = '', pivot = null, reverse = false, lowOutlierColor = false, highOutlierColor = false, stripedOutliers = false, width = 400, height = 50, } = options; if (!container) { container = document.createElement("span"); } if (!domain || !scheme) { container.replaceChildren(); return; } // --------------------------------------------------------------------------- // Layout constants. Every visible element derives its position from these, // so the gradient, ticks, outlier swatches, and outlier labels all share one // coordinate system and one vertical baseline. // --------------------------------------------------------------------------- const LAYOUT = { labelY: 15, // baseline of the title text rampTop: 20, // top edge of the gradient rect and outlier swatches rampBottom: height - 19, // bottom edge of the gradient rect and outlier swatches tickLabelY: height - 6, // baseline of tick text and outlier labels sideMargin: 20, // horizontal padding inside the gradient SVG swatchWidth: 16, // width of an outlier color swatch swatchGutter: 12, // horizontal gap between gradient edge and swatch swatchRadius: 3, gradientStops: 16, fontSize: 14, fontFamily: 'sans-serif', textColor: '#424242', stripeSpacing: 4, // distance between stripe centerlines stripeWidth: 1.5, // thickness of each stripe stripeColor: '#ffffff', }; const rampHeight = LAYOUT.rampBottom - LAYOUT.rampTop; // --------------------------------------------------------------------------- // Helpers // --------------------------------------------------------------------------- const formatNumber = (d) => { if (d < 1000) { return d % 1 ? d3.format('.1f')(d) : d3.format('.0f')(d); } return d3.format('.2s')(d); }; const resolveInterpolator = (scheme) => { if (Array.isArray(scheme)) { return d3 .scaleLinear() .domain(scheme.map((_, i) => i / (scheme.length - 1))) .range(scheme) .interpolate(d3.interpolateRgb); } if (typeof scheme === 'string') { return d3['interpolate' + scheme]; } return scheme; }; // Measure rendered text width by briefly attaching an off-screen SVG text node // to the document. Falls back to a rough character-width estimate if the DOM // isn't available (e.g. SSR). const measureTextWidth = (text) => { if (typeof document === 'undefined') { return text.length * LAYOUT.fontSize * 0.6; } const svgNS = 'http://www.w3.org/2000/svg'; const tempSvg = document.createElementNS(svgNS, 'svg'); tempSvg.setAttribute('width', '0'); tempSvg.setAttribute('height', '0'); tempSvg.style.position = 'absolute'; tempSvg.style.visibility = 'hidden'; const tempText = document.createElementNS(svgNS, 'text'); tempText.style.fontFamily = LAYOUT.fontFamily; tempText.style.fontSize = LAYOUT.fontSize + 'px'; tempText.textContent = text; tempSvg.appendChild(tempText); document.body.appendChild(tempSvg); const w = tempText.getComputedTextLength(); document.body.removeChild(tempSvg); return w; }; // --------------------------------------------------------------------------- // Color scale // --------------------------------------------------------------------------- let colorDomain = [...domain]; if (pivot !== null) { const maxSide = Math.max(pivot - colorDomain[0], colorDomain[1] - pivot); colorDomain = [pivot - maxSide, pivot + maxSide]; } const colorScale = d3 .scaleSequential(resolveInterpolator(scheme)) .domain(reverse ? [colorDomain[1], colorDomain[0]] : colorDomain); const tickValues = pivot !== null ? [domain[0], pivot, domain[1]] : [domain[0], domain[1]]; // --------------------------------------------------------------------------- // Geometry: one SVG, one coordinate system. The gradient sits in the middle; // optional outlier swatches sit flush against its left/right edges, offset // by swatchGutter. The horizontal space reserved on each side is the larger // of (a) the swatch width and (b) the outlier label width, since the label // anchors outward from the swatch center and can extend past the swatch edge. // --------------------------------------------------------------------------- const lowLabelText = lowOutlierColor ? `<${formatNumber(domain[0])}` : ''; const highLabelText = highOutlierColor ? `>${formatNumber(domain[1])}` : ''; // The label is anchored at the outer edge of the swatch and extends outward, // so the space it needs beyond the swatch center is max(swatchWidth/2, labelWidth). // Round up to avoid sub-pixel overlap. const outerSpace = (labelText) => { if (!labelText) return 0; const labelWidth = Math.ceil(measureTextWidth(labelText)); return Math.max(LAYOUT.swatchWidth, labelWidth); }; const lowReserve = lowOutlierColor ? outerSpace(lowLabelText) + LAYOUT.swatchGutter : 0; const highReserve = highOutlierColor ? outerSpace(highLabelText) + LAYOUT.swatchGutter : 0; const gradientX0 = lowReserve + LAYOUT.sideMargin; const gradientX1 = width - highReserve - LAYOUT.sideMargin; const gradientWidth = gradientX1 - gradientX0; // --------------------------------------------------------------------------- // Build the SVG // --------------------------------------------------------------------------- const svg = d3.create('svg').attr('width', width).attr('height', height); // Title svg .append('text') .attr('x', gradientX0) .attr('y', LAYOUT.labelY) .style('font-family', LAYOUT.fontFamily) .style('font-size', LAYOUT.fontSize) .text(label); // Gradient definition const uniqueSuffix = Math.floor(Math.random() * 10000000); const gradientId = 'ramp-gradient-' + uniqueSuffix; const stripePatternId = 'ramp-stripes-' + uniqueSuffix; const defs = svg.append('defs'); const gradient = defs .append('linearGradient') .attr('id', gradientId) .attr('x1', '0%') .attr('x2', '100%'); const stopScale = d3.scaleLinear().domain([0, LAYOUT.gradientStops]).range(domain); for (let i = 0; i <= LAYOUT.gradientStops; i++) { const t = i === 0 ? domain[0] : i === LAYOUT.gradientStops ? domain[1] : stopScale(i); gradient .append('stop') .attr('offset', `${(100 * i) / LAYOUT.gradientStops}%`) .attr('stop-color', colorScale(t)); } // Diagonal stripe pattern for outlier swatches. The pattern tile is a square // of side `stripeSpacing`; a single diagonal line through it tiles seamlessly // into a repeating 45° stripe field. if (stripedOutliers && (lowOutlierColor || highOutlierColor)) { const s = LAYOUT.stripeSpacing; const pattern = defs .append('pattern') .attr('id', stripePatternId) .attr('patternUnits', 'userSpaceOnUse') .attr('width', s) .attr('height', s) .attr('patternTransform', 'rotate(45)'); pattern .append('line') .attr('x1', 0) .attr('y1', 0) .attr('x2', 0) .attr('y2', s) .attr('stroke', LAYOUT.stripeColor) .attr('stroke-width', LAYOUT.stripeWidth); } // Gradient rect svg .append('rect') .attr('x', gradientX0) .attr('y', LAYOUT.rampTop) .attr('width', gradientWidth) .attr('height', rampHeight) .attr('fill', `url(#${gradientId})`); // Axis ticks under the gradient const tickScale = d3.scaleLinear().domain(domain).range([0, gradientWidth]); const axis = d3 .axisBottom(tickScale) .tickValues(tickValues) .tickSize(rampHeight) .tickSizeOuter(0) .tickFormat(formatNumber); const axisG = svg .append('g') .attr('transform', `translate(${gradientX0}, ${LAYOUT.rampTop})`) .style('font-size', LAYOUT.fontSize) .style('color', LAYOUT.textColor) .style('stroke-width', '1px') .call(axis); axisG.selectAll('.tick line').attr('stroke', LAYOUT.textColor); // Nudge the middle tick label if pivot sits very close to the left edge, // to keep it from overlapping the min label. if (tickValues.length === 3) { const percent = (tickValues[1] * 100) / (tickValues[2] - tickValues[0]); if (percent < 5) { const nudge = Math.trunc(tickValues[0].toString().length * 8); const middleTickValue = Math.trunc(tickValues[1]); axisG .selectAll('.tick text') .filter(function () { const textVal = +(d3.select(this).text().replaceAll(',', '')); return textVal >= middleTickValue - 10 && textVal <= middleTickValue + 10; }) .attr('transform', `translate(${nudge})`); } } // --------------------------------------------------------------------------- // Outlier swatch + label, drawn into the same SVG. The swatch top/bottom // match the gradient's rampTop/rampBottom; the label baseline matches the // axis tick labels (tickLabelY). Center of the swatch is centerX. // // When stripedOutliers is true, a second rect is layered on top of the // color swatch, filled with the diagonal stripe pattern. Both rects share // the same rounded corners so the stripes are clipped to the swatch shape. // --------------------------------------------------------------------------- const drawOutlier = (centerX, color, anchor, text) => { const swatchX = centerX - LAYOUT.swatchWidth / 2; svg .append('rect') .attr('x', swatchX) .attr('y', LAYOUT.rampTop) .attr('width', LAYOUT.swatchWidth) .attr('height', rampHeight) .attr('rx', LAYOUT.swatchRadius) .attr('ry', LAYOUT.swatchRadius) .attr('fill', color); if (stripedOutliers) { svg .append('rect') .attr('x', swatchX) .attr('y', LAYOUT.rampTop) .attr('width', LAYOUT.swatchWidth) .attr('height', rampHeight) .attr('rx', LAYOUT.swatchRadius) .attr('ry', LAYOUT.swatchRadius) .attr('fill', `url(#${stripePatternId})`); } svg .append('text') .attr('x', centerX - (anchor == "start" ? LAYOUT.swatchWidth / 2 : -LAYOUT.swatchWidth / 2)) .attr('y', LAYOUT.tickLabelY) .attr('text-anchor', anchor) .attr('fill', LAYOUT.textColor) .style('font-size', LAYOUT.fontSize) .style('font-family', LAYOUT.fontFamily) .text(text); }; if (lowOutlierColor) { const centerX = gradientX0 - LAYOUT.sideMargin - LAYOUT.swatchWidth / 2; drawOutlier(centerX, lowOutlierColor, "end", lowLabelText); } if (highOutlierColor) { const centerX = gradientX1 + LAYOUT.sideMargin + LAYOUT.swatchWidth / 2; drawOutlier(centerX, highOutlierColor, "start", highLabelText); } container.replaceChildren(svg.node()); return container; }31:[] 2d:{"id":"3066142908066099","slug":"color-legend-with-outliers","title":"Color legend with outliers (and automatic outlier color assignment)","thumbnail":"919ec23b715723d93f059fcb87092a0418aa0e27f7c42aca76097b499901ac87","access_level":"public","create_time":"$D2026-05-18T18:04:36.183Z","update_time":"$D2026-05-18T19:36:21.924Z","view_time":null,"first_public_time":"$D2026-05-18T18:43:58.467Z","has_unpublished_edits":null,"fork":false,"stars":1,"starred":false,"owner":{"type":"team","id":"aeba13ccd439d1a5","login":"siliconjazz","name":"Lee Mason","avatar_url":"https://avatars-next.observableusercontent.com/c4c5a3e295d0725774878e8d8bc1675789d3ba7c1755c3f8ac1ba1b06c7c2b88","tier":"starter_2024"},"version":113,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"fbdd2b94d96f3c3c","login":"siliconjazz","name":"Lee Mason","avatar_url":"https://avatars-next.observableusercontent.com/6f7da31c0ab5d37355f81ae230a04aa4e504d6516803dba0ce51e12285aad934","tier":null}],"members":[{"type":"team","id":"aeba13ccd439d1a5","login":"siliconjazz","name":"Lee Mason","avatar_url":"https://avatars-next.observableusercontent.com/c4c5a3e295d0725774878e8d8bc1675789d3ba7c1755c3f8ac1ba1b06c7c2b88","tier":"starter_2024","role":"editor"},{"type":"individual","id":"fbdd2b94d96f3c3c","login":"siliconjazz","name":"Lee Mason","avatar_url":"https://avatars-next.observableusercontent.com/6f7da31c0ab5d37355f81ae230a04aa4e504d6516803dba0ce51e12285aad934","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"title":"Color legend with outliers (and automatic outlier color assignment)","cells":[{"id":0,"value":"# Color legend with outliers (and automatic outlier color assignment)\n\nThis notebook provides two things:\n- A color legend that supports both a standard color gradient and outlier swatches\n- A method of trimming off the ends of a color scheme in a perceptually uniform manner, for the purpose of choosing colors to represent outliers.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":14,"value":"viewof scheme = Inputs.select(COLOR_SCHEMES, {label: \"Color scheme\", format: d => d.label})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":77,"value":"viewof form = Inputs.form({\n showLeftOutlier: Inputs.toggle({label: \"Show left outlier\", value: true}),\n leftOutlierProportion: Inputs.range([0, 1], {label: \"Left outlier proportion\", value: 0.1}),\n showRightOutlier: Inputs.toggle({label: \"Show left outlier\", value: true}),\n rightOutlierProportion: Inputs.range([0, 1], {label: \"Right outlier proportion\", value: 0.1}),\n})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":93,"value":"viewof toggle = Inputs.toggle({label: \"Active\", value: true})","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":46,"value":"trimmedScheme = buildTrimmedColorScheme(d3[\"scheme\" + scheme.value].at(-1), form.leftOutlierProportion, form.rightOutlierProportion)","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":17,"value":"renderColorLegend({\n domain: [1000, 2000],\n scheme: trimmedScheme.scheme,\n label: 'Crude Rate (per 100,000)',\n pivot: 1600,\n lowOutlierColor: form.showLeftOutlier ? trimmedScheme.leftOutlier : false,\n highOutlierColor: form.showRightOutlier ? trimmedScheme.rightOutlier : false,\n stripedOutliers: true,\n})","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":7,"value":"## Helper","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":36,"value":"$2f","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":5,"value":"$30","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":11,"value":"COLOR_SCHEMES = [\n { value: 'RdYlBu', label: 'Red-Yellow-Blue' },\n { value: 'RdYlGn', label: 'Red-Yellow-Green' },\n { value: 'RdBu', label: 'Red-Blue' },\n { value: 'PiYG', label: 'Pink-Yellow-Green' },\n { value: 'PRGn', label: 'Purple-Green' },\n { value: 'BrBG', label: 'Brown-Blue-Green' },\n { value: 'Spectral', label: 'Spectral' },\n { value: 'RdPu', label: 'Red-Purple' },\n { value: 'YlGnBu', label: 'Yellow-Green-Blue' },\n { value: 'YlOrRd', label: 'Yellow-Orange-Red' },\n { value: 'Blues', label: 'Blues' },\n { value: 'Greens', label: 'Greens' },\n { value: 'Oranges', label: 'Oranges' },\n { value: 'Reds', label: 'Reds' },\n { value: 'Purples', label: 'Purples' },\n { value: 'Greys', label: 'Greys' },\n]","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":38,"value":"## Imports","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":40,"value":"Color = (await import('https://unpkg.com/colorjs.io@0.6.1/dist/color.js?module')).default","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W31","stdlib":"1","titling":"auto"}} 2e:"$2d:body"