feat: percent stack strategy

Author: sjcobb

src/component/tooltip/seriesFormatTooltip.ts

@@ -27,7 +27,7 @@ import {
     TooltipMarkupSection
 } from './tooltipMarkup';
 import { retrieveRawValue } from '../../data/helper/dataProvider';
-import { isNameSpecified } from '../../util/model';
+import { isNameSpecified, getStackStrategy } from '../../util/model';
 
 
 export function defaultSeriesFormatTooltip(opt: {
@@ -65,6 +65,20 @@ export function defaultSeriesFormatTooltip(opt: {
         const dimInfo = data.getDimensionInfo(tooltipDims[0]);
         sortParam = inlineValue = retrieveRawValue(data, dataIndex, tooltipDims[0]);
         inlineValueType = dimInfo.type;
+        const stackStrategy = getStackStrategy(series);
+        if (stackStrategy === 'percent') {
+            // Append the normalized value (as a percent of the total stack) when 'percent' stackStrategy is used.
+            const stackResultDim = data.getCalculationInfo('stackResultDimension');
+            const stackedOverDim = data.getCalculationInfo('stackedOverDimension');
+            const stackTop = data.get(stackResultDim, dataIndex) as number;
+            const stackBottom = data.get(stackedOverDim, dataIndex) as number;
+            // Difference between the cumulative sum including this series and the cumulative sum before
+            // this series gives its individual contribution.
+            if (!isNaN(stackTop) && !isNaN(stackBottom)) {
+                const percentVal = stackTop - stackBottom;
+                inlineValue = `${inlineValue} (${percentVal.toFixed(1)}%)`;
+            }
+        }
     }
     else {
         sortParam = inlineValue = isValueArr ? value[0] : value;

src/layout/barGrid.ts

@@ -482,14 +482,20 @@ export function createProgressiveLayout(seriesType: string): StageHandler {
             const baseDimIdx = data.getDimensionIndex(data.mapDimension(baseAxis.dim));
             const drawBackground = seriesModel.get('showBackground', true);
             const valueDim = data.mapDimension(valueAxis.dim);
-            const stackResultDim = data.getCalculationInfo('stackResultDimension');
-            const stacked = isDimensionStacked(data, valueDim) && !!data.getCalculationInfo('stackedOnSeries');
             const isValueAxisH = valueAxis.isHorizontal();
             const valueAxisStart = getValueAxisStart(baseAxis, valueAxis);
             const isLarge = isInLargeMode(seriesModel);
             const barMinHeight = seriesModel.get('barMinHeight') || 0;
 
+            // Determine stacked dimensions and account for stackStrategy.
+            const stackResultDim = data.getCalculationInfo('stackResultDimension');
             const stackedDimIdx = stackResultDim && data.getDimensionIndex(stackResultDim);
+            const stackedOverDim = data.getCalculationInfo('stackedOverDimension');
+            const stackedOverDimIdx = stackedOverDim && data.getDimensionIndex(stackedOverDim);
+            const stackStrategy = seriesModel.get('stackStrategy');
+            const isPercentStack = stackStrategy === 'percent';
+            const stacked = isPercentStack
+            || (isDimensionStacked(data, valueDim) && !!data.getCalculationInfo('stackedOnSeries'));
 
             // Layout info.
             const columnWidth = data.getLayout('size');
@@ -518,7 +524,12 @@ export function createProgressiveLayout(seriesType: string): StageHandler {
                         // Because of the barMinHeight, we can not use the value in
                         // stackResultDimension directly.
                         if (stacked) {
-                            stackStartValue = +value - (store.get(valueDimIdx, dataIndex) as number);
+                            if (isPercentStack) {
+                                stackStartValue = store.get(stackedOverDimIdx, dataIndex);
+                            }
+                            else {
+                                stackStartValue = +value - (store.get(valueDimIdx, dataIndex) as number);
+                            }
                         }
 
                         let x;

src/processor/dataStack.ts

@@ -20,21 +20,9 @@
 import {createHashMap, each} from 'zrender/src/core/util';
 import GlobalModel from '../model/Global';
 import SeriesModel from '../model/Series';
-import { SeriesOption, SeriesStackOptionMixin } from '../util/types';
-import SeriesData, { DataCalculationInfo } from '../data/SeriesData';
+import { SeriesOption, SeriesStackOptionMixin, StackInfo } from '../util/types';
 import { addSafe } from '../util/number';
-
-type StackInfo = Pick<
-    DataCalculationInfo<SeriesOption & SeriesStackOptionMixin>,
-    'stackedDimension'
-    | 'isStackedByIndex'
-    | 'stackedByDimension'
-    | 'stackResultDimension'
-    | 'stackedOverDimension'
-> & {
-    data: SeriesData
-    seriesModel: SeriesModel<SeriesOption & SeriesStackOptionMixin>
-};
+import { calculatePercentStack } from '../util/stack';
 
 // (1) [Caution]: the logic is correct based on the premises:
 //     data processing stage is blocked in stream.
@@ -77,7 +65,15 @@ export default function dataStack(ecModel: GlobalModel) {
         }
     });
 
-    stackInfoMap.each(calculateStack);
+    stackInfoMap.each(function (stackInfoList) {
+        const isPercentStack = stackInfoList.some((info) => info.seriesModel.get('stackStrategy') === 'percent');
+        if (isPercentStack) {
+            calculatePercentStack(stackInfoList);
+        }
+        else {
+            calculateStack(stackInfoList);
+        }
+    });
 }
 
 function calculateStack(stackInfoList: StackInfo[]) {

src/util/model.ts

@@ -45,7 +45,8 @@ import {
     Payload,
     OptionId,
     OptionName,
-    InterpolatableValue
+    InterpolatableValue,
+    SeriesStackOptionMixin
 } from './types';
 import { Dictionary } from 'zrender/src/core/types';
 import SeriesModel from '../model/Series';
@@ -1094,3 +1095,7 @@ export function interpolateRawValues(
         return interpolated;
     }
 }
+
+export function getStackStrategy(series: SeriesModel): SeriesStackOptionMixin['stackStrategy'] | undefined {
+    return (series.get as (path: string) => unknown)('stackStrategy') as SeriesStackOptionMixin['stackStrategy'];
+}

src/util/stack.ts

@@ -0,0 +1,94 @@
+/*
+* Licensed to the Apache Software Foundation (ASF) under one
+* or more contributor license agreements.  See the NOTICE file
+* distributed with this work for additional information
+* regarding copyright ownership.  The ASF licenses this file
+* to you under the Apache License, Version 2.0 (the
+* "License"); you may not use this file except in compliance
+* with the License.  You may obtain a copy of the License at
+*
+*   http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing,
+* software distributed under the License is distributed on an
+* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+* KIND, either express or implied.  See the License for the
+* specific language governing permissions and limitations
+* under the License.
+*/
+
+import { each } from 'zrender/src/core/util';
+import { addSafe } from './number';
+import { StackInfo } from './types';
+
+/**
+ * Percent stackStrategy logic to normalize each value as a percentage of the total per index.
+ */
+export function calculatePercentStack(stackInfoList: StackInfo[]) {
+    const dataLength = stackInfoList[0].data.count();
+    if (dataLength === 0) {
+        return;
+    }
+
+    // Calculate totals per data index across all series in the stack group.
+    const totals = calculateStackTotals(stackInfoList, dataLength);
+
+    // Used to track running total of percent values at each index.
+    const cumulativePercents = new Float64Array(dataLength);
+
+    const resultNaN = [NaN, NaN];
+
+    each(stackInfoList, function (targetStackInfo) {
+        const resultVal: number[] = [];
+        const dims: [string, string] = [targetStackInfo.stackResultDimension, targetStackInfo.stackedOverDimension];
+        const targetData = targetStackInfo.data;
+        const stackedDim = targetStackInfo.stackedDimension;
+
+        // Should not write on raw data, because stack series model list changes
+        // depending on legend selection.
+        targetData.modify(dims, function (v0, v1, dataIndex) {
+            const rawValue = targetData.get(stackedDim, dataIndex) as number;
+
+            // Consider `connectNulls` of line area, if value is NaN, stackedOver
+            // should also be NaN, to draw a appropriate belt area.
+            if (isNaN(rawValue)) {
+                return resultNaN;
+            }
+
+            // Pre-calculated total for this specific data index.
+            const total = totals[dataIndex];
+
+            // Percentage contribution of this segment.
+            const percent = total === 0 ? 0 : (rawValue / total) * 100;
+
+            // Bottom edge of this segment (cumulative % before this series).
+            const stackedOver = cumulativePercents[dataIndex];
+
+            // Update the cumulative percentage for the next series at this index to use.
+            cumulativePercents[dataIndex] = addSafe(stackedOver, percent);
+
+            // Result: [Top edge %, Bottom edge %]
+            resultVal[0] = cumulativePercents[dataIndex];
+            resultVal[1] = stackedOver;
+            return resultVal;
+        });
+    });
+}
+
+/**
+* Helper to calculate the total value across all series for each data index.
+*/
+function calculateStackTotals(stackInfoList: StackInfo[], dataLength: number): number[] {
+    const totals = Array(dataLength).fill(0);
+    each(stackInfoList, (stackInfo) => {
+        const data = stackInfo.data;
+        const dim = stackInfo.stackedDimension;
+        for (let i = 0; i < dataLength; i++) {
+            const val = data.get(dim, i) as number;
+            if (!isNaN(val)) {
+                totals[i] = addSafe(totals[i], val);
+            }
+        }
+    });
+    return totals;
+}

src/util/types.ts

@@ -33,7 +33,7 @@ import ExtensionAPI from '../core/ExtensionAPI';
 import SeriesModel from '../model/Series';
 import { createHashMap, HashMap } from 'zrender/src/core/util';
 import { TaskPlanCallbackReturn, TaskProgressParams } from '../core/task';
-import SeriesData from '../data/SeriesData';
+import SeriesData, { DataCalculationInfo } from '../data/SeriesData';
 import { Dictionary, ElementEventName, ImageLike, TextAlign, TextVerticalAlign } from 'zrender/src/core/types';
 import { PatternObject } from 'zrender/src/graphic/Pattern';
 import { TooltipMarker } from './format';
@@ -1678,8 +1678,20 @@ export interface SeriesLargeOptionMixin {
 }
 export interface SeriesStackOptionMixin {
     stack?: string
-    stackStrategy?: 'samesign' | 'all' | 'positive' | 'negative';
-}
+    stackStrategy?: 'samesign' | 'all' | 'positive' | 'negative' | 'percent';
+}
+
+export type StackInfo = Pick<
+    DataCalculationInfo<SeriesOption & SeriesStackOptionMixin>,
+    'stackedDimension'
+    | 'isStackedByIndex'
+    | 'stackedByDimension'
+    | 'stackResultDimension'
+    | 'stackedOverDimension'
+> & {
+    data: SeriesData
+    seriesModel: SeriesModel<SeriesOption & SeriesStackOptionMixin>
+};
 
 type SamplingFunc = (frame: ArrayLike<number>) => number;