feat: add jitterY (#5887)

* fix(Transform): add jitterY param

* docs(Transform): add jitterY.md

---------

Co-authored-by: xionghe.hx <xionghe.hx@digital-engine.com>

__tests__/plots/static/cars2-point-jitterX.ts

@@ -0,0 +1,23 @@
+import * as d3 from 'd3-random';
+import { G2Spec } from '../../../src';
+
+export function cars2PointJitterX(): G2Spec {
+  const random = d3.randomUniform.source(d3.randomLcg(42))(0, 1);
+  return {
+    type: 'point',
+    data: {
+      type: 'fetch',
+      value: 'data/cars2.csv',
+    },
+    scale: {
+      x: { type: 'point' },
+      color: { type: 'ordinal' },
+    },
+    transform: [{ type: 'sortX' }, { type: 'jitterX', random }],
+    encode: {
+      y: 'Horsepower',
+      x: 'Cylinders',
+      color: 'Cylinders',
+    },
+  };
+}

__tests__/plots/static/cars2-point-jitterY.ts

@@ -10,13 +10,13 @@ export function cars2PointJitterY(): G2Spec {
       value: 'data/cars2.csv',
     },
     scale: {
-      x: { type: 'point' },
+      y: { type: 'point' },
       color: { type: 'ordinal' },
     },
-    transform: [{ type: 'sortX' }, { type: 'jitterX', random }],
+    transform: [{ type: 'sortY' }, { type: 'jitterY', random }],
     encode: {
-      y: 'Horsepower',
-      x: 'Cylinders',
+      y: 'Cylinders',
+      x: 'Horsepower',
       color: 'Cylinders',
     },
   };

__tests__/plots/static/index.ts

@@ -46,6 +46,7 @@ export { stateAgesPointDotPlot } from './stateages-point-dot-plot';
 export { temperaturesPointSequential } from './temperatures-point-sequential';
 export { disastersPointBubble } from './disasters-point-bubble';
 export { cars2PointJitterY } from './cars2-point-jitterY';
+export { cars2PointJitterX } from './cars2-point-jitterX';
 export { peoplePointStacked } from './people-point-stacked';
 export { intakePointAnnotation } from './intake-point-annotation';
 export { intakePointAnnotationWithArrow } from './intake-point-annotation-with-arrow';

__tests__/unit/lib/core.spec.ts

@@ -117,6 +117,7 @@ import {
   NormalizeY,
   Jitter,
   JitterX,
+  JitterY,
   SymmetryY,
   DiffY,
   Select,
@@ -182,6 +183,7 @@ describe('corelib', () => {
       'transform.dodgeX': DodgeX,
       'transform.jitter': Jitter,
       'transform.jitterX': JitterX,
+      'transform.jitterY': JitterY,
       'transform.symmetryY': SymmetryY,
       'transform.diffY': DiffY,
       'transform.stackEnter': StackEnter,

__tests__/unit/lib/std.spec.ts

@@ -129,6 +129,7 @@ import {
   NormalizeY,
   Jitter,
   JitterX,
+  JitterY,
   SymmetryY,
   DiffY,
   Select,
@@ -200,6 +201,7 @@ describe('stdlib', () => {
       'transform.dodgeX': DodgeX,
       'transform.jitter': Jitter,
       'transform.jitterX': JitterX,
+      'transform.jitterY': JitterY,
       'transform.symmetryY': SymmetryY,
       'transform.diffY': DiffY,
       'transform.stackEnter': StackEnter,

site/docs/spec/overview.zh.md

@@ -69,6 +69,7 @@ G2 是一个简洁的、渐进式的可视化语法。文档将按照下面的
 - [groupY](/spec/transform/group-y) - 对离散的 y 通道进行分组，并且对通道根据指定的 Reducer 进行聚合。
 - [jitter](/spec/transform/jitter) - 根据离散的 x 和 离散的 y 比例尺，生成 dy 和 dx 通道，实现在某个区域散开的效果。
 - [jitterX](/spec/transform/jitter-x) - 根据离散的 x 比例尺，生成 dx 通道，实现在某个区域的 x 方向散开的效果。
+- [jitterY](/spec/transform/jitter-y) - 根据离散的 y 比例尺，生成 dy 通道，实现在某个区域的 y 方向散开的效果。
 - [normalizeY](/spec/transform/normalize-y) - 对 y 和 y1 通道根据指定的 basis 进行归一化处理。
 - [select](/spec/transform/select) - 按照指定通道进行分组，根据指定通道和 selector 从每组选择出数据。
 - [selectX](/spec/transform/select-x) - 按照指定通道进行分组，根据 x 通道和 selector 从每组选择出数据。

site/docs/spec/transform/jitterY.en.md

@@ -0,0 +1,6 @@
+---
+title: jitterY
+order: 1
+---
+
+<embed src="@/docs/spec/transform/jitterY.zh.md"></embed>

site/docs/spec/transform/jitterY.zh.md

@@ -0,0 +1,42 @@
+---
+title: jitterY
+order: 1
+---
+
+根据离散的 y 比例尺，生成 dy 通道，实现在某个区域的 y 方向散开的效果。
+
+## 开始使用
+
+<img alt="jitterY" src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*8JbhTLgg5ucAAAAAAAAAAAAADmJ7AQ/original" width="500" />
+
+```ts
+import { Chart } from '@antv/g2';
+
+const chart = new Chart({
+  container: 'container',
+});
+
+chart
+  .point()
+  .data({
+    type: 'fetch',
+    value:
+      'https://gw.alipayobjects.com/os/bmw-prod/2c813e2d-2276-40b9-a9af-cf0a0fb7e942.csv',
+  })
+  .transform({ type: 'sortY' })
+  .transform({ type: 'jitterY' })
+  .encode('x', 'Horsepower')
+  .encode('y', 'Cylinders')
+  .encode('color', 'Cylinders')
+  .scale('y', { type: 'point' })
+  .scale('color', { type: 'ordinal' });
+
+chart.render();
+```
+
+## 选项
+
+| 属性               | 描述                                           | 类型                 | 默认值                 |
+|-------------------|------------------------------------------------|---------------------|-----------------------|
+| padding           | 每个分组之间的间距 [0 ~ 1]                        | `number`            | `0`                   |  
+| random            | 随机函数，返回值为 [0, 1)                         | `() => number`      | `Math.random`         |

src/lib/core.ts

@@ -116,6 +116,7 @@ import {
   NormalizeY,
   Jitter,
   JitterX,
+  JitterY,
   SymmetryY,
   DiffY,
   Select,
@@ -180,6 +181,7 @@ export function corelib() {
     'transform.dodgeX': DodgeX,
     'transform.jitter': Jitter,
     'transform.jitterX': JitterX,
+    'transform.jitterY': JitterY,
     'transform.symmetryY': SymmetryY,
     'transform.diffY': DiffY,
     'transform.stackEnter': StackEnter,

src/spec/transform.ts

@@ -8,6 +8,7 @@ export type Transform =
   | StackEnterTransform
   | JitterTransform
   | JitterXTransform
+  | JitterYTransform
   | SymmetryYTransform
   | DiffYTransform
   | SelectTransform
@@ -34,6 +35,7 @@ export type TransformTypes =
   | 'stackEnter'
   | 'jitter'
   | 'jitterX'
+  | 'jitterY'
   | 'symmetryY'
   | 'diffY'
   | 'select'
@@ -109,6 +111,12 @@ export type JitterXTransform = {
   random?: () => number;
 };
 
+export type JitterYTransform = {
+  type?: 'jitterY';
+  padding?: number;
+  random?: () => number;
+};
+
 export type StackEnterTransform = {
   type?: 'stackEnter';
   groupBy?: string[] | string;

src/transform/index.ts

@@ -23,6 +23,7 @@ export { StackEnter } from './stackEnter';
 export { NormalizeY } from './normalizeY';
 export { Jitter } from './jitter';
 export { JitterX } from './jitterX';
+export { JitterY } from './jitterY';
 export { SymmetryY } from './symmetryY';
 export { DiffY } from './diffY';
 export { Select } from './select';
@@ -66,6 +67,7 @@ export type { StackEnterOptions } from './stackEnter';
 export type { NormalizeYOptions } from './normalizeY';
 export type { JitterOptions } from './jitter';
 export type { JitterXOptions } from './jitterX';
+export type { JitterYOptions } from './jitterY';
 export type { SymmetryYOptions } from './symmetryY';
 export type { DiffYOptions } from './diffY';
 export type { SelectOptions } from './select';

src/transform/jitterY.ts

@@ -0,0 +1,30 @@
+import { deepMix } from '@antv/util';
+import { TransformComponent as TC } from '../runtime';
+import { JitterYTransform } from '../spec';
+import { column, columnOf } from './utils/helper';
+import { rangeOf, interpolate } from './jitter';
+
+export type JitterYOptions = Omit<JitterYTransform, 'type'>;
+
+/**
+ * The JitterY transform produce dy channels for marks (especially for point)
+ * with ordinal x and y dimension, say to make them jitter in their own space.
+ */
+export const JitterY: TC<JitterYOptions> = (options = {}) => {
+  const { padding = 0, random = Math.random } = options;
+  return (I, mark) => {
+    const { encode, scale } = mark;
+    const { y: scaleY } = scale;
+    const [Y] = columnOf(encode, 'y');
+    const rangeY = rangeOf(Y, scaleY, padding);
+    const DY = I.map(() => interpolate(random(), ...rangeY));
+    return [
+      I,
+      deepMix({ scale: { y: { padding: 0.5 } } }, mark, {
+        encode: { dy: column(DY) },
+      }),
+    ];
+  };
+};
+
+JitterY.props = {};