Nocturnal Pumpkin Maelstrom

    @nebula.js/sn-combo-chart

    1.18.3 • Public • Published

    @nebula.js/sn-combo-chart

    The combo chart is suitable for comparing two sets of measure values that have different scale. In its simplest form, a combo chart has one dimension and two measures and is basically a bar chart combined with a line chart.

    Requirements

    Requires @nebula.js/stardust version 1.7.0 or later.

    Installing

    If you use npm: npm install @nebula.js/sn-combo-chart. You can also load through the script tag directly from https://unpkg.com.

    Usage

    In the example below, the Bitcoin price and trade volume in the Bitfinex platform are plotted in a combo chart. Despite being two different measures, they show apparent correlation.

    import { embed } from '@nebula.js/stardust';
    import comboChart from '@nebula.js/sn-combo-chart';
    
    // 'app' is an enigma app model
    const nuked = embed(app, {
      types: [
        {
          // register combo chart
          name: 'combo-chart',
          load: () => Promise.resolve(comboChart),
        },
      ],
    });
    
    // Rendering a simple combo chart
    nuked.render({
      element: document.querySelector('.combo'),
      type: 'combo-chart',
      fields: ['Date.autoCalendar.YearMonth', '=Avg(Price_Bitfinex)', '=Avg(Volume_Bitfinex)'],
      properties: {
        title: 'Bitcoin Price and Trading Volume (USD)',
      },
    });

    More examples

    Customize the look of bars and lines

    You can make the previous chart more appealing by making the bars thicker. For the line, you can change its color, add data points and curviness.

    nuked.render({
      element: document.querySelector('.combo'),
      type: 'combo-chart',
      fields: ['Date.autoCalendar.YearMonth', '=Avg(Price_Bitfinex)', '=Avg(Volume_Bitfinex)'],
    
      // Customizing bars and lines
      properties: {
        title: 'Bitcoin Price and Trading Volume (USD)',
        components: [
          {
            key: 'bar',
            style: {
              strokeWidth: 'large',
              strokeColor: {
                color: '#25A0A8',
              },
            },
          },
          {
            key: 'line',
            style: {
              lineThickness: 3,
              lineCurve: 'monotone',
            },
          },
        ],
        dataPoint: {
          show: true,
        },
        color: {
          auto: false,
          mode: 'primary',
          paletteColor: {
            color: '#be3b03',
          },
        },
      },
    });

    Use markers instead of bars

    Beside bars and lines, there is a third option: markers. In the following example, the bars from the previous chart are replaced by markers.

    To override the default mesure configuration (one bar series, one line), the measures are defined in properties instead of in fields.

    nuked.render({
      element: document.querySelector('.combo'),
      type: 'combo-chart',
      fields: ['Date.autoCalendar.YearMonth'],
    
      // Define measures in `properties`, instead of in `fields`
      properties: {
        title: 'Bitcoin Price and Trading Volume (USD)',
        qHyperCubeDef: {
          qMeasures: [
            {
              qDef: {
                qDef: '=Avg(Price_Bitfinex)',
                series: { axis: 0, type: 'marker', marker: 'triangle' },
              },
            },
            {
              qDef: {
                qDef: '=Avg(Volume_Bitfinex)',
                series: { axis: 1, type: 'line' },
              },
            },
          ],
        },
      },
    });

    Horizontal combo chart

    By default, the combo chart is oriented vertically like in the previous examples: the bars are vertical and the line is horizontal. If you wish, you can change the chart orientation to horizontal.

    nuked.render({
      element: document.querySelector('.combo'),
      type: 'combo-chart',
      fields: ['Date.autoCalendar.YearMonth', '=Avg(Price_Bitfinex)', '=Avg(Volume_Bitfinex)'],
    
      // Making the combo chart horizontal
      properties: {
        title: 'Bitcoin Price and Trading Volume (USD)',
    
        // You should set this ...
        orientation: 'horizontal',
    
        // ... but alse these to turn off continuous dimension scale
        dimensionAxis: {
          continuousAuto: false,
        },
        preferContinuousAxis: false,
    
        // Just make the line looks better
        components: [
          {
            key: 'line',
            style: {
              lineThickness: 3,
              lineCurve: 'monotone',
            },
          },
        ],
      },
    });

    Comparing two pairs of measures

    You can add multiple measures into a combo chart. Each measure can be either a series of bar, a line, or a series of markers.

    In the following example, by using two series of bars and two lines, the Bitcoin price and trading volume of two different trading platforms can be compared in the same chart.

    Some notes about the code:

    • By default, if you add 4 measures, you get one bar series and three lines. To define two bar series and two lines instead, you have to specify that in properties in stead of in fields.
    • To customize colors of bars and lines, the BASIC_COLOR_OPTIONS_PER_MEASURE flag has to be on. Customized colors are defined in qDef.
    • The preferContinuousAxis should be set to false (turn off continuous dimension scale) for the bars to be grouped instead of stacked.
    // Configure nucleus
    const nuked = window.stardust.embed(app, {
      context: { theme: 'light' },
      types: [
        {
          name: 'combo-chart',
          load: () => Promise.resolve(window['sn-combo-chart']),
        },
      ],
      flags: { BASIC_COLOR_OPTIONS_PER_MEASURE: true },
    });
    
    // Render the combo chart
    nuked.render({
      element: document.querySelector('.combo'),
      type: 'combo-chart',
      fields: ['Date.autoCalendar.YearMonth'],
      properties: {
        qHyperCubeDef: {
          qMeasures: [
            {
              qDef: {
                qDef: '=Avg(Price_Bitfinex)',
                series: { axis: 0, type: 'bar' },
                color: {
                  on: true,
                  paletteColor: { color: '#790C4D' },
                },
              },
            },
            {
              qDef: {
                qDef: '=Avg(Price_Gemini)',
                series: { axis: 0, type: 'bar' },
                color: {
                  on: true,
                  paletteColor: { color: '#0C7737' },
                },
              },
            },
            {
              qDef: {
                qDef: '=Avg(Volume_Bitfinex)',
                series: { axis: 1, type: 'line' },
                color: {
                  on: true,
                  paletteColor: { color: '#DB168C' },
                },
              },
            },
            {
              qDef: {
                qDef: '=Avg(Volume_Gemini)',
                series: { axis: 1, type: 'line' },
                color: {
                  on: true,
                  paletteColor: { color: '#16DB64' },
                },
              },
            },
          ],
        },
        dimensionAxis: {
          dock: 'near',
          axisDisplayMode: 'custom',
          maxVisibleItems: 50,
        },
        preferContinuousAxis: false,
    
        // Make the lines look better
        components: [
          {
            key: 'line',
            style: {
              lineThickness: 3,
              lineCurve: 'monotone',
            },
          },
        ],
      },
    });

    Combo chart plugins

    A plugin can be passed into a combo chart to add or modify its capability or visual appearance. A plugin needs to be defined before it can be rendered together with the chart.

    // Step 1: define the plugin
    
    // Modifying the look and the position of the minor secondary axis title
    const minorSecondaryAxisTitlePlugin = {
      info: {
        name: 'minor-secondary-axis-title-plugin',
        type: 'component-definition',
      },
      fn: ({ keys, layout }) => {
        const componentDefinition = {
          type: 'data-title',
    
          // Provide the same name as the exisiting component to override it
          key: keys.COMPONENT.AXIS_TITLE.MINOR.SECONDARY,
          style: {
            fontFamily: 'Tahoma, san-serif',
            fontSize: '15px',
            color: '#EC983D',
          },
        };
        return componentDefinition;
      },
    };
    
    // Step 2: passing the plugin definition into the render function
    
    // Rendering a combo chart with plugins
    nuked.render({
      element: document.getElementById('object'),
      type: 'sn-combo-chart',
      fields: ['Date.autoCalendar.YearMonth', '=Avg(Price_Gemini)', '=Avg(Volume_Gemini)'],
      plugins: [minorSecondaryAxisTitlePlugin],
      properties: {
        title: 'Bitcoin Price and Trading Volume (USD) on Gemini',
      },
    });

    The plugin definition is an object, with two properties info and fn. The fn returns a picasso.js component. To build this component, some important chart internals are passed into the argument object of fn.

    // Structure of the argument object of fn
    const pluginArgs = {
      layout,
      keys: {
        SCALE: {
          MAJOR,
          MAJOR_INNER,
          MINOR: {
            PRIMARY,
            SECONDARY,
          },
        },
        COMPONENT: {
          BAR_PRIMARY,
          BAR_SECONDARY,
          AXIS: {
            MAJOR,
            TIME_INNER,
            MINOR: {
              PRIMARY,
              SECONDARY,
            },
          },
          AXIS_TITLE: {
            MAJOR,
            MINOR: {
              PRIMARY,
              SECONDARY,
            },
          },
        },
        COLLECTION: { MAIN },
      },
    };

    With plugins, you can either add new components or modify existing components of the combo chart.

    Add new components

    The new component can be a standard Picasso component or a custom Picasso component. Here we demo a standard reference line component.

    // Adding reference line at the median of the price
    const medianReferenceLinePlugin = {
      info: {
        name: 'median-reference-line-plugin',
        type: 'component-definition',
      },
      fn: ({ keys, layout }) => {
        // We are only interested in data after year 2018
        const barValues = layout.qHyperCube.qDataPages[0].qMatrix
          .filter((item) => item[0].qText >= '2018')
          .map((item) => item[1].qNum);
        const value = getMedian(barValues);
        const componentDefinition = {
          key: 'median-reference-line',
          type: 'ref-line',
          lines: {
            y: [
              {
                line: {
                  stroke: 'blue',
                  strokeWidth: 2,
                },
                scale: keys.SCALE.MINOR.PRIMARY,
                value,
                label: {
                  text: `Median price since 2018:`,
                },
              },
            ],
          },
        };
        return componentDefinition;
      },
    };

    Modify existing components

    As an example, the appearance of the bars can be modified by plugins.

    To overide an existing component, fn should returns a picasso.js component that has the same key as the existing component (keys.COMPONENT.BAR_PRIMARY in this example)

    // Modifying the look of the existing bar component
    const barPlugin = {
      info: {
        name: 'bar-plugin',
        type: 'component-definition',
      },
      fn: ({ layout, keys }) => {
        const componentDefinition = {
          type: 'box',
    
          // Provide the same name as the exisiting bar component to override it
          key: keys.COMPONENT.BAR_PRIMARY,
          settings: {
            box: { minWidthPx: 10 },
          },
        };
        return componentDefinition;
      },
    };

    Plugins disclaimer

    • The plugins API is still experimental.
    • We can not guarantee our charts to be compatible with all different settings, especially when modifying existing components.

    Install

    npm i @nebula.js/sn-combo-chart

    DownloadsWeekly Downloads

    1,811

    Version

    1.18.3

    License

    MIT

    Unpacked Size

    4.45 MB

    Total Files

    14

    Last publish

    Collaborators

    • niekvanstaveren
    • likang6688
    • ccm33
    • nilzona
    • qlikossbuild
    • veinfors
    • tobias-astrom-qlik