@formant/ava 3.4.1-formant

package/esm/ntv/generate/generateTextSpec.js

@@ -0,0 +1,157 @@
+import { __assign, __read, __spreadArray } from "tslib";
+/* eslint-disable no-console */
+import { toString } from 'lodash';
+import { isNumberLike } from '../../utils';
+import { isEntityType } from '../utils';
+import { templateStr2Structure, getScopeVariableArray, getFormattedNumberValue, getAssessment, getDisplayValue, getByPath, } from './utils';
+var TextSpecGenerator = /** @class */ (function () {
+    function TextSpecGenerator(_a) {
+        var variable = _a.variable, structures = _a.structures, structureTemps = _a.structureTemps;
+        this.variable = variable;
+        this.structures = structures;
+        this.structureTemps = structureTemps;
+    }
+    TextSpecGenerator.prototype.generateTextPhrase = function (text) {
+        // TODO 是否需要判断 value 为 string ？？是否需要默认的数值格式化？—— 暂时先简单 toString 下
+        return { type: 'text', value: toString(text) };
+    };
+    TextSpecGenerator.prototype.generateVarPhrase = function (scopeVariable, path, value, metadata) {
+        // 没有 meta 的一律按普通文本处理
+        if (!metadata) {
+            return this.generateTextPhrase(value);
+        }
+        var varType = metadata.varType, formatter = metadata.formatter, extraCustomMeta = metadata.extraCustomMeta;
+        var formattedValue = getFormattedNumberValue(varType, value, formatter);
+        // 声明 varType 的可能是 entity 也可能是 custom
+        if (varType) {
+            if (isEntityType(varType)) {
+                return {
+                    type: 'entity',
+                    value: formattedValue,
+                    metadata: {
+                        entityType: varType,
+                        origin: isNumberLike(value) ? value : undefined,
+                        assessment: getAssessment(varType, value),
+                        generateVariableInfo: { scopeVariable: scopeVariable, path: path },
+                    },
+                };
+            }
+            var extra = extraCustomMeta === null || extraCustomMeta === void 0 ? void 0 : extraCustomMeta(this.variable, scopeVariable);
+            return {
+                type: 'custom',
+                value: formattedValue,
+                // TODO 完善自定义短语 metadata
+                metadata: __assign({ customType: varType, generateVariableInfo: { scopeVariable: scopeVariable, path: path } }, extra),
+            };
+        }
+        return this.generateTextPhrase(toString(value));
+    };
+    // 只处理行数据拼接逻辑，表格数据
+    TextSpecGenerator.prototype.generateSentence = function (template, variable, variableMetaMap) {
+        var _this = this;
+        var phrases = [];
+        var templateStructure = templateStr2Structure(template);
+        var _loop_1 = function (i) {
+            var _a = templateStructure[i], tempStrType = _a.type, tempStrValue = _a.value;
+            if (tempStrType === 'template') {
+                var targetTempId_1 = tempStrValue;
+                // get template info by template id
+                var templateInfo = this_1.structureTemps.find(function (_a) {
+                    var templateId = _a.templateId;
+                    return templateId === targetTempId_1;
+                });
+                if (templateInfo) {
+                    var template_1 = templateInfo.template, useVariable = templateInfo.useVariable, variableMetaMap_1 = templateInfo.variableMetaMap, limit = templateInfo.limit, _b = templateInfo.separator, separator_1 = _b === void 0 ? ',' : _b;
+                    var scopeArrayVariable_1 = getScopeVariableArray(this_1.variable, variable, useVariable, limit);
+                    var subPhrases = scopeArrayVariable_1
+                        .map(function (v) { return _this.generateSentence(template_1, v, variableMetaMap_1); })
+                        .reduce(function (prev, curr, index) {
+                        var result = __spreadArray(__spreadArray([], __read(prev), false), __read(curr), false);
+                        if (index !== scopeArrayVariable_1.length - 1)
+                            result.push(_this.generateTextPhrase(separator_1));
+                        return result;
+                    }, []);
+                    phrases = phrases.concat.apply(phrases, __spreadArray([], __read(subPhrases), false));
+                }
+                else {
+                    console.warn("".concat(targetTempId_1, " is not exist"));
+                }
+            }
+            else if (tempStrType === 'variable') {
+                var key = tempStrValue;
+                var metadata = variableMetaMap === null || variableMetaMap === void 0 ? void 0 : variableMetaMap[key];
+                var value = (metadata === null || metadata === void 0 ? void 0 : metadata.getDisplayValue)
+                    ? getDisplayValue(metadata === null || metadata === void 0 ? void 0 : metadata.getDisplayValue, this_1.variable, variable)
+                    : getByPath(this_1.variable, variable, key);
+                phrases.push(this_1.generateVarPhrase(variable, key, value, __assign({}, metadata)));
+            }
+            else if (tempStrType === 'text') {
+                phrases.push(this_1.generateTextPhrase(tempStrValue));
+            }
+        };
+        var this_1 = this;
+        for (var i = 0; i < templateStructure.length; i += 1) {
+            _loop_1(i);
+        }
+        return phrases;
+    };
+    /**
+     * 生成段落
+     * 1. 当前支持段落类型 heading normal bullet
+     * 2. 生成段落个数取决于 variable 的类型：
+     *  2.1 非自带循环属性的段落（heading normal）遇到数组数据时自动循环多段；
+     *  2.2 自身循环段落（bullet）遇到非数组时只生成一个
+     * */
+    TextSpecGenerator.prototype.generateParagraphs = function (structure, variable) {
+        var _this = this;
+        if (variable === void 0) { variable = this.variable; }
+        var variableMetaMap = structure.variableMetaMap, template = structure.template, _a = structure.displayType, displayType = _a === void 0 ? 'paragraph' : _a, _b = structure.useVariable, useVariable = _b === void 0 ? '' : _b, limit = structure.limit, 
+        // 段落级别暂时用不到 separator
+        // separator,
+        bulletOrder = structure.bulletOrder, children = structure.children, className = structure.className;
+        var scopeArrayVariable = getScopeVariableArray(this.variable, variable, useVariable, limit);
+        // TODO 接入更多类型
+        if (displayType === 'paragraph') {
+            return scopeArrayVariable.map(function (v) { return ({
+                type: 'normal',
+                phrases: _this.generateSentence(template, v, variableMetaMap),
+                className: className,
+            }); });
+        }
+        if (displayType === 'bullet') {
+            return [
+                {
+                    type: 'bullets',
+                    className: className,
+                    isOrder: bulletOrder,
+                    bullets: scopeArrayVariable.map(function (v) { return ({
+                        type: 'bullet-item',
+                        phrases: _this.generateSentence(template, v, variableMetaMap),
+                        subBullet: children
+                            ? _this.generateParagraphs(__assign(__assign({}, children), { displayType: 'bullet' }), v)[0]
+                            : undefined,
+                    }); }),
+                },
+            ];
+        }
+        return null;
+    };
+    TextSpecGenerator.prototype.generateSection = function () {
+        var _this = this;
+        return {
+            paragraphs: this.structures.reduce(function (prev, curr) {
+                return __spreadArray(__spreadArray([], __read(prev), false), __read(_this.generateParagraphs(curr)), false);
+            }, []),
+        };
+    };
+    TextSpecGenerator.prototype.generateNarrative = function () {
+        return {
+            // 当前只可能构建出一个 section
+            sections: [this.generateSection()],
+        };
+    };
+    return TextSpecGenerator;
+}());
+export default function generateTextSpec(params) {
+    return new TextSpecGenerator(params).generateNarrative();
+}

package/esm/ntv/generate/index.js

@@ -0,0 +1,5 @@
+/*
+ * generate text spec by structure and variable
+ * thx @Lobster377
+ */
+export { default as generateTextSpec } from './generateTextSpec';

package/esm/ntv/generate/types.js

@@ -0,0 +1 @@
+export {};

package/esm/ntv/generate/utils.js

@@ -0,0 +1,86 @@
+import { get, isArray, isUndefined, slice, replace, isString, startsWith } from 'lodash';
+import { dataFormat, isNumberLike } from '../../utils';
+/**
+ * simple path system
+ * if starts with '.', it's relative path
+ * // TODO 支持相对路径找到上级
+ * if starts with '..', it's can get prev level variable
+ * otherwise, it's absolute path
+ */
+export function getByPath(globalVar, scopeVar, path) {
+    if (!path)
+        return scopeVar;
+    if (startsWith(path, '.'))
+        return get(scopeVar, path.slice(1));
+    return get(globalVar, path);
+}
+/**
+ * parse template string
+ *    Use $ for variable
+ *    Use & for template
+ * @example 'aaa ${key} &{temp1}'
+ *  => [{ type: 'text', value: 'aaa ' }, { type: 'variable', value: 'key' }, { type: 'template', value: 'temp1' }]
+ */
+export function templateStr2Structure(templateStr) {
+    // eslint-disable-next-line no-useless-escape
+    var splitReg = /([\$|&]{.*?})/;
+    var varReg = /\${(.*?)}/;
+    var tempReg = /&{(.*?)}/;
+    return templateStr
+        .split(splitReg)
+        .filter(function (str) { return str; })
+        .map(function (str) {
+        var _a, _b;
+        var templateId = (_a = tempReg.exec(str)) === null || _a === void 0 ? void 0 : _a[1];
+        if (templateId)
+            return { value: templateId, type: 'template' };
+        var varName = (_b = varReg.exec(str)) === null || _b === void 0 ? void 0 : _b[1];
+        if (varName)
+            return { value: varName, type: 'variable' };
+        return { value: str, type: 'text' };
+    });
+}
+/** format any to array, and filter nil */
+export function formattedAsArray(variable) {
+    if (isUndefined(variable))
+        return [];
+    return isArray(variable) ? variable : [variable];
+}
+export function getScopeVariableArray(globalVar, scopeVar, path, limit) {
+    return slice(formattedAsArray(getByPath(globalVar, scopeVar, path)), 0, limit);
+}
+export function getAssessment(entityType, value) {
+    if (!isNumberLike(value))
+        return undefined;
+    if (entityType === 'delta_value' || entityType === 'ratio_value') {
+        if (value > 0)
+            return 'positive';
+        if (value < 0)
+            return 'negative';
+    }
+    return undefined;
+}
+export function getFormattedNumberValue(varType, value, formatter) {
+    if (!isNumberLike(value))
+        return value;
+    if (varType === 'delta_value' || varType === 'ratio_value') {
+        return formatter ? formatter(Math.abs(value)) : dataFormat(Math.abs(value));
+    }
+    if (varType === 'proportion') {
+        return formatter ? formatter(Math.abs(value)) : "".concat(dataFormat(value * 100), "%");
+    }
+    return formatter ? formatter(value) : dataFormat(value);
+}
+/** get phrase text */
+export function getDisplayValue(getDisplayValuePattern, globalVar, scopeVar) {
+    if (isString(getDisplayValuePattern)) {
+        // 用字符串表示使用变量拼接短语文字内容，这里进行变量替换，eg '${city} = ${value}' => '北京 = 1000'
+        // Use a string to represent the text content of the phrase using variables to splice，eg '${city} = ${value}' => 'Beijing = 1000'
+        return replace(getDisplayValuePattern, /\${(.*?)}/g, function (match) {
+            var _a;
+            var varName = (_a = /\${(.*?)}/.exec(match)) === null || _a === void 0 ? void 0 : _a[1];
+            return varName ? getByPath(globalVar, scopeVar, varName) : '';
+        });
+    }
+    return getDisplayValuePattern(globalVar, scopeVar);
+}

package/esm/ntv/index.js

@@ -0,0 +1,4 @@
+export * from './types';
+export { ENTITY_TYPES } from './schema';
+export * from './utils';
+export { generateTextSpec } from './generate';

package/esm/ntv/schema/common.js

@@ -0,0 +1 @@
+export {};

package/esm/ntv/schema/index.js

@@ -0,0 +1,4 @@
+export * from './common';
+export * from './structure';
+export * from './paragraph';
+export * from './phrase';

package/esm/ntv/schema/paragraph.js

@@ -0,0 +1 @@
+export {};

package/esm/ntv/schema/phrase.js

@@ -0,0 +1,52 @@
+export var ENTITY_TYPES = [
+    /**
+     * @description main indicator value 主指标名
+     * @example DAU
+     * */
+    'metric_name',
+    /**
+     * @description main indicator name 主指标值
+     * @example 1.23 million
+     * */
+    'metric_value',
+    /**
+     * @description other indicator value 其他指标值
+     * @example
+     * */
+    'other_metric_value',
+    /**
+     * @description contribution ratio 贡献度
+     * @example 23%
+     * */
+    'contribute_ratio',
+    /**
+     * @description delate value 变化值
+     * @example -1.2
+     * */
+    'delta_value',
+    /**
+     * @description ratio value 变化率
+     * @example +23%
+     * */
+    'ratio_value',
+    /**
+     * @description trend description 趋势描述
+     * @example up/down
+     * */
+    'trend_desc',
+    /**
+     * @description dimension value 维值
+     * @example sex = man
+     * */
+    'dim_value',
+    /**
+     * @description time description 时间描述
+     * @example 2021-11-19
+     * */
+    'time_desc',
+    /**
+     * @description proportion 占比
+     * @example 20%
+     * */
+    'proportion',
+];

package/esm/ntv/schema/structure.js

@@ -0,0 +1 @@
+export {};

package/esm/ntv/types.js

@@ -0,0 +1 @@
+export {};

package/esm/ntv/utils/index.js

@@ -0,0 +1 @@
+export * from './isSpecType';

package/esm/ntv/utils/isSpecType.js

@@ -0,0 +1,58 @@
+import { isObject, isString } from '../../utils';
+import { ENTITY_TYPES } from '../schema';
+export function isCustomSection(spec) {
+    return isObject(spec) && 'customType' in spec;
+}
+export function isCustomParagraph(spec) {
+    return isObject(spec) && 'customType' in spec;
+}
+export function isStandardSection(spec) {
+    return isObject(spec) && 'paragraphs' in spec && Array.isArray(spec === null || spec === void 0 ? void 0 : spec.paragraphs);
+}
+export function isTextParagraph(spec) {
+    return isObject(spec) && (spec === null || spec === void 0 ? void 0 : spec.type) === 'normal' && Array.isArray(spec === null || spec === void 0 ? void 0 : spec.phrases);
+}
+export function isBulletParagraph(spec) {
+    return isObject(spec) && (spec === null || spec === void 0 ? void 0 : spec.type) === 'bullets' && Array.isArray(spec === null || spec === void 0 ? void 0 : spec.bullets);
+}
+export function isDividerParagraph(spec) {
+    return isObject(spec) && (spec === null || spec === void 0 ? void 0 : spec.type) === 'divider';
+}
+export function getHeadingWeight(pType) {
+    if (pType === null || pType === void 0 ? void 0 : pType.startsWith('heading')) {
+        var weight = Number(pType === null || pType === void 0 ? void 0 : pType.slice(-1));
+        if (weight >= 1 && weight <= 6)
+            return weight;
+    }
+    return NaN;
+}
+export function isHeadingParagraph(spec) {
+    if (isObject(spec) && 'type' in spec && isString(spec.type)) {
+        var weight = getHeadingWeight(spec === null || spec === void 0 ? void 0 : spec.type);
+        return spec.type.startsWith('heading') && !Number.isNaN(weight);
+    }
+    return false;
+}
+export function isCustomPhrase(spec) {
+    var _a;
+    return (spec === null || spec === void 0 ? void 0 : spec.type) === 'custom' && !!((_a = spec === null || spec === void 0 ? void 0 : spec.metadata) === null || _a === void 0 ? void 0 : _a.customType);
+}
+export function isEntityType(type) {
+    return ENTITY_TYPES.includes(type);
+}
+export function isEntityPhrase(spec) {
+    var _a;
+    return (spec === null || spec === void 0 ? void 0 : spec.type) === 'entity' && ENTITY_TYPES.includes((_a = spec === null || spec === void 0 ? void 0 : spec.metadata) === null || _a === void 0 ? void 0 : _a.entityType);
+}
+export function isTextPhrase(spec) {
+    return (spec === null || spec === void 0 ? void 0 : spec.type) === 'text';
+}
+export function isEscapePhrase(spec) {
+    return (spec === null || spec === void 0 ? void 0 : spec.type) === 'escape';
+}
+export function isFormulaPhrase(spec) {
+    return (spec === null || spec === void 0 ? void 0 : spec.type) === 'formula';
+}
+export function isImagePhrase(spec) {
+    return (spec === null || spec === void 0 ? void 0 : spec.type) === 'image';
+}

package/esm/utils/arr2map.js

@@ -0,0 +1,7 @@
+export function arr2map(arr, keyId) {
+    return arr.reduce(function (prev, curr) {
+        // eslint-disable-next-line no-param-reassign
+        prev[curr[keyId]] = curr;
+        return prev;
+    }, {});
+}

package/esm/utils/dataFormat.js

@@ -0,0 +1,32 @@
+/**
+ * data format.
+ * dataFormat(0.8849) = 0.88
+ * dataFormat(12, 1) = 12
+ * dataFormat(1234, 1) = 1.2k
+ * dataFormat(123.456, 2) = 123.46
+ * @param value value to be formatted
+ * @param digits the number of digits to keep after the decimal point, 2 by default
+ * @returns formatted value string
+ */
+export default function dataFormat(value, digits) {
+    if (digits === void 0) { digits = 2; }
+    if (typeof value === 'string')
+        return value;
+    var formatMap = [
+        { value: 1, symbol: '' },
+        { value: 1e3, symbol: 'k' },
+        { value: 1e6, symbol: 'M' },
+        { value: 1e9, symbol: 'G' },
+        { value: 1e12, symbol: 'T' },
+        { value: 1e15, symbol: 'P' },
+        { value: 1e18, symbol: 'E' },
+    ];
+    var rx = /\.0+$|(\.[0-9]*[1-9])0+$/;
+    var item = formatMap
+        .slice()
+        .reverse()
+        .find(function (item) {
+        return value >= item.value;
+    });
+    return item ? (value / item.value).toFixed(digits).replace(rx, '$1') + item.symbol : value.toFixed(digits);
+}

package/esm/utils/index.js

@@ -0,0 +1,3 @@
+export * from './isType';
+export * from './arr2map';
+export { default as dataFormat } from './dataFormat';

package/esm/utils/isType.js

@@ -0,0 +1,14 @@
+import { toNumber, isNaN } from 'lodash';
+export function isString(val) {
+    return typeof val === 'string';
+}
+export function isObject(val) {
+    return val !== null && typeof val === 'object';
+}
+export function isUndefined(val) {
+    return val === undefined;
+}
+export function isNumberLike(val) {
+    var numVal = toNumber(val);
+    return !isNaN(numVal);
+}

package/lib/advisor/advise-pipeline/advicesForChart.d.ts

@@ -0,0 +1,13 @@
+import type { ChartKnowledgeBase } from '../../ckb';
+import type { Data } from '../../common/types';
+import type { AdviseResult, ChartAdviseParams } from '../types';
+import type { BasicDataPropertyForAdvice, RuleModule } from '../ruler';
+/**
+ * A utility function that assemble dataProps with user input and DataFrame
+ * @param copyData a copy of original data
+ * @param fields the fields that user specified to be used in dataset
+ * @param inputDataProps user input dataProps which will cover or combine with dataProps from DataFrame
+ * @returns assembled data props
+ */
+export declare function assembleDataProps(copyData: Data, fields?: string[], inputDataProps?: Partial<BasicDataPropertyForAdvice>[]): BasicDataPropertyForAdvice[];
+export declare function advicesForChart(params: ChartAdviseParams, ckb: ChartKnowledgeBase, ruleBase: Record<string, RuleModule>): AdviseResult;

package/lib/advisor/advise-pipeline/advicesForChart.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.advicesForChart = exports.assembleDataProps = void 0;
+var tslib_1 = require("tslib");
+var data_1 = require("../../data");
+var utils_1 = require("../utils");
+var data_to_advices_1 = require("./data-to-advices");
+/**
+ * A utility function that assemble dataProps with user input and DataFrame
+ * @param copyData a copy of original data
+ * @param fields the fields that user specified to be used in dataset
+ * @param inputDataProps user input dataProps which will cover or combine with dataProps from DataFrame
+ * @returns assembled data props
+ */
+function assembleDataProps(copyData, fields, inputDataProps) {
+    // transform data into DataFrame
+    var dataFrame;
+    if (fields) {
+        dataFrame = new data_1.DataFrame(copyData, { columns: fields });
+    }
+    else {
+        dataFrame = new data_1.DataFrame(copyData);
+    }
+    var dataPropsForAdvice;
+    var defaultDataProps = dataFrame.info();
+    if (inputDataProps) {
+        dataPropsForAdvice = defaultDataProps.map(function (dwItem) {
+            var inputProps = inputDataProps.find(function (item) {
+                return item.name === dwItem.name;
+            });
+            return tslib_1.__assign(tslib_1.__assign({}, dwItem), inputProps);
+        });
+    }
+    else {
+        dataPropsForAdvice = defaultDataProps;
+    }
+    return dataPropsForAdvice;
+}
+exports.assembleDataProps = assembleDataProps;
+function advicesForChart(params, ckb, ruleBase) {
+    var data = params.data, dataProps = params.dataProps, smartColor = params.smartColor, options = params.options, colorOptions = params.colorOptions, fields = params.fields;
+    try {
+        // otherwise the input data will be mutated
+        var copyData = (0, utils_1.cloneDeep)(data);
+        // get dataProps from DataFrame
+        var dataPropsForAdvice = assembleDataProps(copyData, fields, dataProps);
+        // filter out fields that are not included for advising
+        var filteredData = [];
+        if (fields) {
+            filteredData = copyData.map(function (row) {
+                var filteredRow = row;
+                Object.keys(filteredRow).forEach(function (col) {
+                    if (!fields.includes(col)) {
+                        delete filteredRow[col];
+                    }
+                });
+                return row;
+            });
+        }
+        else {
+            filteredData = copyData;
+        }
+        var adviceResult = (0, data_to_advices_1.dataToAdvices)(filteredData, dataPropsForAdvice, ckb, ruleBase, smartColor, options, colorOptions);
+        return adviceResult;
+    }
+    catch (error) {
+        // if the input data cannot be transformed into DataFrame
+        // eslint-disable-next-line no-console
+        console.error('error: ', error);
+        return { advices: [], log: [] };
+    }
+}
+exports.advicesForChart = advicesForChart;

package/lib/advisor/advise-pipeline/data-to-advices.d.ts

@@ -0,0 +1,22 @@
+import type { ChartKnowledge } from '../../ckb';
+import type { Data } from '../../common/types';
+import type { BasicDataPropertyForAdvice, RuleModule } from '../ruler/types';
+import type { AdvisorOptions, SmartColorOptions, AdviseResult } from '../types';
+/**
+ * options for advising inner pipeline
+ */
+type PipeAdvisorOptions = AdvisorOptions;
+/**
+ * recommending charts given data and dataProps, based on CKB and RuleBase
+ *
+ * @param data input data [ {a: xxx, b: xxx}, ... ]
+ * @param dataProps data props derived from data or customized by users
+ * @param chartWIKI ckb
+ * @param ruleBase rule base
+ * @param smartColor switch smart color on/off, optional props, default is off
+ * @param options options for advising such as log, preferences
+ * @param colorOptions color options, optional props, @see {@link SmartColorOptions}
+ * @returns chart list [ { type: chartTypes, spec: antv-spec, score: >0 }, ... ]
+ */
+export declare function dataToAdvices(data: Data, dataProps: BasicDataPropertyForAdvice[], chartWIKI: Record<string, ChartKnowledge>, ruleBase: Record<string, RuleModule>, smartColor?: boolean, options?: PipeAdvisorOptions, colorOptions?: SmartColorOptions): AdviseResult;
+export {};