Documentation
Tutorials
Basic usage Customizing the heatmap Reproducing scIB figure
Github Changelog NPM package R version Python version

Source

geoms.js

  1. /**
  2.  * @module
  3.  * @description Module with available visualization functions (called `geoms`) to display the data.
  4.  * The following table summarizes available geoms for different data types:
  5.  * | Data type | Name | Link | Size mapping | Color mapping |
  6.  * | --- | --- | --- | --- | --- |
  7.  * | `number` | `funkyrect` | {@link module:geoms.funkyrect} | ✅ | ✅ |
  8.  * | `number` | `circle` | {@link module:geoms.circle} | ✅ | ✅ |
  9.  * | `number` | `bar` | {@link module:geoms.bar} | ✅ | ✅ |
  10.  * | `number` | `rect` | {@link module:geoms.rect} | 🚫 | ✅ |
  11.  * | `string` | `text` | {@link module:geoms.text} | 🚫 | ✅ |
  12.  * | `number[]` | `pie` | {@link module:geoms.pie} | 🚫 | ✅ |
  13.  * | `image` | `image` | {@link module:geoms.image} | 🚫 | 🚫 |
  14.  *
  15.  * Each geom is a function with the signature of {@link module:geoms~geom|geom}.
  16.  */
  18. import * as d3 from 'd3';
  20. /**
  21.  * @name geom
  22.  * @constant
  23.  * @function
  24.  * @abstract
  25.  * @description Abstract virtual function representing a geom.
  26.  *
  27.  * @param {number|number[]|string} value - data value to be visualized, of the above types
  28.  * @param {number|string} colorValue - value to be used for color mapping, if applicable
  29.  * @param {module:columns.Column} column - column object
  30.  * @param {HeatmapOptions} O - heatmap options
  31.  * @param {PositionArgs} P - position arguments
  32.  * @returns {SVGElement} - SVG element representing the geom
  33.  */
  35. export const GEOMS = {
  36.     /**
  37.      * @memberof module:geoms
  38.      * @see {@link module:geoms~geom|geom} for function signature
  39.      * @description Text geom. Renders text string. Configured with `fontSize` and `align` options.
  40.      *   Default fontSize is inherited from {@link HeatmapOptions}. Default align is `left`.
  41.      *   Color is mapped from palette by text value, if palette is defined (see
  42.      *   {@link module:palettes~CustomPalette|CustomPalette}).
  43.      */
  44.     text: (value, _, column, O, P) => {
  45.         let fill = O.theme.textColor;
  46.         if (column.palette && column.palette !== 'none') {
  47.             fill = column.palette(value);
  48.         }
  49.         let align = 'start', x = 0;
  50.         if (column.options.align === 'center' || column.options.align === 'middle') {
  51.             align = 'middle';
  52.             x = P.rowHeight / 2;
  53.         }
  54.         if (column.options.align === 'right' || column.options.align === 'end') {
  55.             align = 'end';
  56.             x = P.rowHeight - P.padding;
  57.         }
  58.         const el = d3.create('svg:text')
  59.             .classed('fh-geom', true)
  60.             .attr('dominant-baseline', 'middle')
  61.             .attr('y', P.rowHeight / 2)
  62.             .attr('x', x)
  63.             .attr('text-anchor', align)
  64.             .style('fill', fill)
  65.             .text(value);
  66.         if (O.fontSize) {
  67.             el.attr('font-size', O.fontSize);
  68.         }
  69.         if (column.options.fontSize) {
  70.             el.attr('font-size', column.options.fontSize);
  71.         }
  72.         return el;
  73.     },
  75.     /**
  76.      * @memberof module:geoms
  77.      * @see {@link module:geoms~geom|geom} for function signature
  78.      * @description Bar geom. Renders a bar with width proportional to value. Maximum bar width is
  79.      *   configured with `width` property ({@link module:columns~ColumnInfo|ColumnInfo}). If value
  80.      *   is 0, minimal bar width is set from {@link PositionArgs} `minGeomSize`.
  81.      */
  82.     bar: (value, colorValue, column, O, P) => {
  83.         const fill = column.palette(colorValue);
  84.         value = column.scale(value);
  85.         let width = value * column.width * P.geomSize;
  86.         if (width === 0) {
  87.             width = P.minGeomSize;
  88.         }
  89.         return d3.create('svg:rect')
  90.             .classed('fh-geom', true)
  91.             .attr('x', P.geomPaddingX)
  92.             .attr('y', P.geomPadding)
  93.             .attr('width', width.toFixed(2))
  94.             .attr('height', P.geomSize)
  95.             .style('stroke', O.theme.strokeColor)
  96.             .style('stroke-width', 1)
  97.             .style('fill', fill);
  98.     },
  100.     /**
  101.      * @memberof module:geoms
  102.      * @see {@link module:geoms~geom|geom} for function signature
  103.      * @description Circle geom. Renders a circle with radius proportional to value. If value is 0,
  104.      *   minimal circle radius is set from {@link PositionArgs} `minGeomSize`.
  105.      */
  106.     circle: (value, colorValue, column, O, P) => {
  107.         const fill = column.palette(colorValue);
  108.         value = column.scale(value);
  109.         let radius = value * P.geomSize / 2;
  110.         if (radius === 0) {
  111.             radius = P.minGeomSize;
  112.         }
  113.         return d3.create('svg:circle')
  114.             .classed('fh-geom', true)
  115.             .style('stroke', O.theme.strokeColor)
  116.             .style('stroke-width', 1)
  117.             .style('fill', fill)
  118.             .attr('cx', P.rowHeight / 2)
  119.             .attr('cy', P.rowHeight / 2)
  120.             .attr('r', radius.toFixed(2));
  121.     },
  123.     /**
  124.      * @memberof module:geoms
  125.      * @see {@link module:geoms~geom|geom} for function signature
  126.      * @description Square geom. Renders a square of standard size, but color is mapped from
  127.      *   palette.
  128.      */
  129.     rect: (value, colorValue, column, O, P) => {
  130.         const fill = column.palette(colorValue);
  131.         value = column.scale(value);
  132.         return d3.create('svg:rect')
  133.             .classed('fh-geom', true)
  134.             .style('stroke', O.theme.strokeColor)
  135.             .style('stroke-width', 1)
  136.             .style('fill', fill)
  137.             .attr('x', P.geomPaddingX)
  138.             .attr('y', P.geomPadding)
  139.             .attr('width', P.geomSize)
  140.             .attr('height', P.geomSize);
  141.     },
  143.     /**
  144.      * @memberof module:geoms
  145.      * @see {@link module:geoms~geom|geom} for function signature
  146.      * @description Funkyrect geom. Renders a circle that grows into a square with rounded corners.
  147.      *   Value below {@link PositionArgs} `funkyMidpoint` is rendered as a circle, above as
  148.      *   a square, with corner radius decreasing as value grows.
  149.      */
  150.     funkyrect: (value, colorValue, column, O, P) => {
  151.         let scaled = column.scale(value);
  152.         const fill = column.palette(colorValue);
  153.         if (scaled < P.funkyMidpoint) {
  154.             // transform value to a 0.0 .. 0.5 range
  155.             value = column.scale.copy()
  156.                 .range([0, 0.5])
  157.                 .domain([column.min, column.min + column.range * P.funkyMidpoint])(value);
  158.             let radius = (value * 0.9 + 0.1) * P.geomSize - P.geomPadding; // 0.5 for stroke
  159.             if (radius <= 0) {
  160.                 radius = P.minGeomSize;
  161.             }
  162.             return d3.create('svg:circle')
  163.                 .classed('fh-geom', true)
  164.                 .style('stroke', O.theme.strokeColor)
  165.                 .style('stroke-width', 1)
  166.                 .style('fill', fill)
  167.                 .attr('cx', P.rowHeight / 2)
  168.                 .attr('cy', P.rowHeight / 2)
  169.                 .attr('r', radius.toFixed(2));
  170.         }
  171.         // transform value to a 0.5 .. 1.0 range
  172.         value = column.scale
  173.             .copy()
  174.             .range([0.5, 1])
  175.             .domain([column.min + column.range * P.funkyMidpoint, column.max])(value);
  176.         const cornerSize = (0.9 - 0.8 * value) * P.geomSize;
  177.         return d3.create('svg:rect')
  178.             .classed('fh-geom', true)
  179.             .style('stroke', O.theme.strokeColor)
  180.             .style('stroke-width', 1)
  181.             .style('fill', fill)
  182.             .attr('x', P.geomPaddingX)
  183.             .attr('y', P.geomPadding)
  184.             .attr('width', P.geomSize)
  185.             .attr('height', P.geomSize)
  186.             .attr('rx', cornerSize.toFixed(2))
  187.             .attr('ry', cornerSize.toFixed(2));
  188.     },
  190.     /**
  191.      * @memberof module:geoms
  192.      * @see {@link module:geoms~geom|geom} for function signature
  193.      * @description Pie chart geom. Renders a pie chart with slices proportional to values.
  194.      */
  195.     pie: (value, _, column, O, P) => {
  196.         let nonZero = 0;
  197.         let nonZeroIdx = 0;
  198.         value.forEach((x, i) => {
  199.             if (x > 0) {
  200.                 nonZero += 1;
  201.                 nonZeroIdx = i;
  202.             }
  203.         });
  204.         if (nonZero === 1) {
  205.             const fill = column.palette(nonZeroIdx);
  206.             return d3.create('svg:circle')
  207.                 .classed('fh-geom', true)
  208.                 .style('stroke', O.theme.strokeColor)
  209.                 .style('stroke-width', 1)
  210.                 .style('fill', fill)
  211.                 .attr('cx', P.rowHeight / 2)
  212.                 .attr('cy', P.rowHeight / 2)
  213.                 .attr('r', P.geomSize / 2);
  214.         }
  216.         const arcs = d3.pie().sortValues(null)(value);
  217.         const g = d3.create('svg:g');
  218.         g.classed('fh-geom', true);
  219.         g.selectAll('arcs')
  220.             .data(arcs)
  221.             .enter()
  222.             .append('path')
  223.                 .attr('d', d3.arc().innerRadius(0).outerRadius(P.geomSize / 2))
  224.                 .attr('fill', (_, i) => {
  225.                     return column.palette(i);
  226.                 })
  227.                 .style('stroke', O.theme.strokeColor)
  228.                 .style('stroke-width', 1)
  229.                 .attr('transform', `translate(${P.rowHeight / 2}, ${P.rowHeight / 2})`);
  230.         return g;
  231.     },
  233.     /**
  234.      * @memberof module:geoms
  235.      * @see {@link module:geoms~geom|geom} for function signature
  236.      * @description Image geom. Renders an image with standard height and width specified in column
  237.      *   options (see {@link module:columns~ColumnInfo|ColumnInfo} `width`).
  238.      */
  239.     image: function(value, _, column, O, P) {
  240.         return d3.create('svg:image')
  241.             .classed('fh-geom', true)
  242.             .attr('y', P.geomPadding)
  243.             .attr('href', value)
  244.             .attr('height', P.geomSize)
  245.             .attr('width', column.width)
  246.             .attr('preserveAspectRatio', 'xMidYMid');
  247.     }
  248. };