File size: 13,079 Bytes
b25f987
 
 
 
 
a17f307
b25f987
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
a17f307
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
import { describe, expect, test } from "bun:test";
import {
  LAG_WINDOW_FRAMES,
  computeCrossEpisodeStats,
  computeCrossEpisodeStatsInSteps,
  computeVelocityStats,
  planEpisodeSample,
  type EpisodeSeries,
} from "@/utils/crossEpisode";

/** A deterministic stand-in for random noise. */
function noise(seed: number): () => number {
  let state = seed;
  return () => {
    state = (state * 1664525 + 1013904223) % 4294967296;
    return state / 4294967296 - 0.5;
  };
}

/**
 * Episodes of `dims` action dimensions. Each state follows its action `delay` frames later, as a
 * real arm follows its command.
 */
function makeEpisodes(options: {
  count: number;
  length: number | ((episode: number) => number);
  dims: number;
  delay?: number;
  signal: (t: number, d: number, episode: number) => number;
}): EpisodeSeries[] {
  const { count, dims, delay = 0, signal } = options;
  return Array.from({ length: count }, (_, e) => {
    const length =
      typeof options.length === "number" ? options.length : options.length(e);
    const actions = new Float32Array(length * dims);
    const states = new Float32Array(length * dims);
    for (let t = 0; t < length; t++) {
      for (let d = 0; d < dims; d++) {
        actions[t * dims + d] = signal(t, d, e);
        states[t * dims + d] = signal(Math.max(0, t - delay), d, e);
      }
    }
    return { index: e, length, actions, states };
  });
}

const names = (dims: number) => Array.from({ length: dims }, (_, d) => `j${d}`);
const input = (episodes: EpisodeSeries[], dims: number) => ({
  episodes,
  actionDim: dims,
  stateDim: dims,
  actionNames: names(dims).map((n) => `action | ${n}`),
  stateNames: names(dims),
  fps: 30,
});

/** A smooth trajectory with enough texture for a cross-correlation to lock onto. */
const wobble = (t: number, d: number, e: number) =>
  Math.sin(0.05 * t * (d + 1) + e) + 0.3 * Math.sin(0.31 * t + d + 2 * e);

describe("planEpisodeSample", () => {
  const dataset = (files: number, perFile: number, rowsPerEpisode: number) =>
    Array.from({ length: files * perFile }, (_, i) => {
      const inFile = i % perFile;
      return {
        index: i,
        file: `file-${Math.floor(i / perFile)}`,
        fromRow: inFile * rowsPerEpisode,
        toRow: (inFile + 1) * rowsPerEpisode,
      };
    });

  test("takes every episode of a dataset within both limits", () => {
    const episodes = dataset(3, 24, 200);
    expect(planEpisodeSample(episodes, 120, 1e9)).toEqual(episodes);
  });

  test("spreads the sample over every file when the budget allows", () => {
    const sample = planEpisodeSample(dataset(6, 100, 500), 120, 1e9);

    expect(sample.length).toBe(120);
    expect(new Set(sample.map((e) => e.file)).size).toBe(6);
    // Evenly within a file too: first and last episode of the first file are both in.
    expect(sample[0].index).toBe(0);
    expect(sample.some((e) => e.index === 99)).toBe(true);
  });

  test("reads only as many files as the row budget allows", () => {
    // 100 files of 50,000 rows; room for 4 of them.
    const sample = planEpisodeSample(dataset(100, 100, 500), 120, 200_000);
    const files = [...new Set(sample.map((e) => e.file))];

    expect(files.length).toBe(4);
    expect(sample.length).toBe(120);
    // Still from across the dataset, not its first four files.
    expect(files[0]).toBe("file-0");
    expect(files[files.length - 1]).toBe("file-99");
  });

  test("a file's unused share of the episodes goes to the later files", () => {
    const episodes = [
      ...dataset(1, 2, 100),
      ...dataset(1, 200, 100).map((e) => ({ ...e, file: "big" })),
    ];
    const sample = planEpisodeSample(episodes, 120, 1e9);

    expect(sample.filter((e) => e.file === "file-0").length).toBe(2);
    expect(sample.length).toBe(120);
  });

  test("never returns a single episode when the dataset has more", () => {
    // One episode per file, and a budget smaller than any file.
    const sample = planEpisodeSample(dataset(50, 1, 10_000), 120, 1);
    expect(sample.length).toBe(2);
  });

  test("an empty dataset gives an empty sample", () => {
    expect(planEpisodeSample([], 120, 1e9)).toEqual([]);
  });
});

describe("computeCrossEpisodeStats", () => {
  test("needs at least two episodes", () => {
    const [only] = makeEpisodes({
      count: 1,
      length: 300,
      dims: 2,
      signal: wobble,
    });
    expect(computeCrossEpisodeStats(input([only], 2))).toBeNull();
  });

  test("finds the delay between command and state, in frames", () => {
    for (const delay of [0, 2, 5]) {
      const episodes = makeEpisodes({
        count: 6,
        length: 400,
        dims: 3,
        delay,
        signal: wobble,
      });
      const stats = computeCrossEpisodeStats(input(episodes, 3))!;

      expect(stats.aggAlignment!.meanPeakLag).toBe(delay);
      expect(stats.aggAlignment!.meanPeakCorr).toBeGreaterThan(0.95);
      expect(stats.aggAlignment!.numPairs).toBe(3);
    }
  });

  test("keeps lags in frames on episodes longer than the lag window", () => {
    // Subsampling these episodes used to stretch every lag by the subsampling factor.
    const length = LAG_WINDOW_FRAMES * 3;
    const episodes = makeEpisodes({
      count: 3,
      length,
      dims: 2,
      delay: 4,
      signal: wobble,
    });
    const stats = computeCrossEpisodeStats(input(episodes, 2))!;

    expect(stats.aggAlignment!.meanPeakLag).toBe(4);
    // sin(0.05 t) falls to half its autocorrelation at about a sixth of its 126-frame period.
    const acf = stats.aggAutocorrelation!;
    const firstBelowHalf = acf.chartData.find((row) => row.j0 < 0.5)!.lag;
    expect(firstBelowHalf).toBeGreaterThan(15);
    expect(firstBelowHalf).toBeLessThan(26);
  });

  test("one aborted episode does not shorten the autocorrelation horizon", () => {
    const episodes = makeEpisodes({
      count: 8,
      length: (e) => (e === 3 ? 30 : 400),
      dims: 2,
      signal: wobble,
    });
    const acf = computeCrossEpisodeStats(
      input(episodes, 2),
    )!.aggAutocorrelation!;

    // The shortest episode allows 15 lags; the typical one allows the full 100.
    expect(acf.chartData.length).toBe(100);
    expect(acf.chartData[0].lag).toBe(1);
    expect(acf.chartData[0].time).toBeCloseTo(1 / 30, 10);
  });

  test("motors at rest are reported inactive and kept out of the chunk suggestion", () => {
    const episodes = makeEpisodes({
      count: 6,
      length: 400,
      dims: 3,
      // j0 moves; j1 and j2 hold one value in every episode.
      signal: (t, d, e) => (d === 0 ? wobble(t, 0, e) : 0.25 * d),
    });
    const stats = computeCrossEpisodeStats(input(episodes, 3))!;

    expect(stats.aggVelocity.map((v) => v.inactive)).toEqual([
      false,
      true,
      true,
    ]);
    expect(stats.aggAutocorrelation!.shortKeys).toEqual(["j0"]);
    // Counted in, each resting motor "decorrelates" at lag 1; two of them against one moving
    // motor made the median, and so the suggested chunk length, 1.
    expect(stats.aggAutocorrelation!.suggestedChunk).toBeGreaterThan(10);
    // And they have no command–state correlation to average in.
    expect(stats.aggAlignment!.numPairs).toBe(1);
  });

  test("a two-valued motor is reported discrete", () => {
    const episodes = makeEpisodes({
      count: 4,
      length: 300,
      dims: 2,
      signal: (t, d, e) =>
        d === 0 ? wobble(t, 0, e) : Math.floor(t / 60) % 2 ? 1 : 0,
    });
    const stats = computeCrossEpisodeStats(input(episodes, 2))!;

    expect(stats.aggVelocity[0].discrete).toBe(false);
    expect(stats.aggVelocity[1].discrete).toBe(true);
  });

  test("ranks episodes by movement and by jerkiness", () => {
    const rand = noise(11);
    const episodes = makeEpisodes({
      count: 5,
      length: 300,
      dims: 2,
      signal: (t, d, e) => {
        if (e === 1) return 0.001 * Math.sin(0.05 * t); // barely moves
        if (e === 4) return wobble(t, d, e) + 0.4 * rand(); // shaky
        return wobble(t, d, e);
      },
    });
    const stats = computeCrossEpisodeStats(input(episodes, 2))!;

    expect(stats.lowMovementEpisodes[0].episodeIndex).toBe(1);
    expect(stats.jerkyEpisodes[0].episodeIndex).toBe(4);
    expect(stats.speedDistribution.length).toBe(5);
    expect(stats.numEpisodes).toBe(5);
  });

  test("variance is zero where every episode agrees and positive where they differ", () => {
    const episodes = makeEpisodes({
      count: 4,
      length: 200,
      dims: 2,
      // j0 is the same in every episode; j1 depends on the episode.
      signal: (t, d, e) => (d === 0 ? Math.sin(0.05 * t) : e * 0.5),
    });
    const { variance, timeBins } = computeCrossEpisodeStats(
      input(episodes, 2),
    )!;

    expect(variance.length).toBe(timeBins.length);
    for (const row of variance) {
      expect(row[0]).toBeCloseTo(0, 6);
      // Values 0, 0.5, 1, 1.5: population variance 0.3125.
      expect(row[1]).toBeCloseTo(0.3125, 6);
    }
  });

  test("episodes without state still give everything but the alignment", () => {
    const episodes = makeEpisodes({
      count: 3,
      length: 300,
      dims: 2,
      signal: wobble,
    }).map((episode) => ({ ...episode, states: null }));
    const stats = computeCrossEpisodeStats(input(episodes, 2))!;

    expect(stats.aggAlignment).toBeNull();
    expect(stats.aggAutocorrelation).not.toBeNull();
    expect(stats.aggVelocity.length).toBe(2);
  });

  test("the stepped version gives the same statistics", async () => {
    const episodes = makeEpisodes({
      count: 5,
      length: 350,
      dims: 3,
      delay: 3,
      signal: wobble,
    });
    let pauses = 0;
    const stepped = await computeCrossEpisodeStatsInSteps(
      input(episodes, 3),
      async () => {
        pauses++;
      },
    );

    expect(stepped).toEqual(computeCrossEpisodeStats(input(episodes, 3)));
    expect(pauses).toBe(2);
  });
});

describe("velocity histograms", () => {
  /** One episode whose single action follows `value(t)`. */
  const single = (length: number, value: (t: number) => number) => {
    const actions = new Float32Array(length);
    for (let t = 0; t < length; t++) actions[t] = value(t);
    return [{ index: 0, length, actions, states: null }];
  };
  const middle = (bins: number[]) => (bins.length - 1) / 2;

  test("are symmetric about zero, with no change in the middle bin", () => {
    // A steady ramp up, then the same ramp down: as many +1 steps as -1 steps.
    const [stat] = computeVelocityStats(
      single(401, (t) => (t <= 200 ? t : 400 - t)),
      1,
      ["action | j0"],
    );

    expect(stat.bins.length % 2).toBe(1);
    expect(stat.lo).toBeCloseTo(-stat.hi, 12);
    expect(stat.bins.reduce((a, b) => a + b, 0)).toBe(400);
    const m = middle(stat.bins);
    const below = stat.bins.slice(0, m).reduce((a, b) => a + b, 0);
    const above = stat.bins.slice(m + 1).reduce((a, b) => a + b, 0);
    expect(below).toBe(200);
    expect(above).toBe(200);
  });

  test("one spike does not flatten the rest into a single bin", () => {
    const rand = noise(5);
    // Small jitter everywhere, and one jump two hundred times its size.
    let level = 0;
    const values = Array.from({ length: 2001 }, (_, t) => {
      level += rand() * 0.02 + (t === 1000 ? 4 : 0);
      return level;
    });
    const [stat] = computeVelocityStats(
      single(values.length, (t) => values[t]),
      1,
      ["action | j0"],
    );

    // The reach covers the jitter, not the jump...
    expect(stat.hi).toBeLessThan(stat.maxAbs / 20);
    // ...so the jitter spreads over many bins instead of piling into the middle one.
    const occupied = stat.bins.filter((count) => count > 0).length;
    expect(occupied).toBeGreaterThan(15);
    // The jump is still counted: in the last bin, with everything else.
    expect(stat.bins.reduce((a, b) => a + b, 0)).toBe(2000);
    expect(stat.bins[stat.bins.length - 1]).toBeGreaterThan(0);
  });

  test("a motor that never changes puts everything in the middle bin", () => {
    const [stat] = computeVelocityStats(
      single(100, () => 0.5),
      1,
      ["action | j0"],
    );

    expect(stat.inactive).toBe(true);
    expect(stat.std).toBe(0);
    expect(stat.bins[middle(stat.bins)]).toBe(99);
    expect(stat.bins.reduce((a, b) => a + b, 0)).toBe(99);
  });

  test("a single episode is enough", () => {
    const stats = computeVelocityStats(
      single(300, (t) => Math.sin(0.05 * t)),
      1,
      ["action | elbow"],
    );

    expect(stats.length).toBe(1);
    expect(stats[0].name).toBe("elbow");
    expect(stats[0].std).toBeGreaterThan(0);
    expect(computeVelocityStats([], 1, ["action | elbow"])).toEqual([]);
  });

  test("the dataset-wide statistics use the same histograms", () => {
    const episodes = makeEpisodes({
      count: 3,
      length: 300,
      dims: 2,
      signal: wobble,
    });
    const names = ["action | j0", "action | j1"];

    expect(computeCrossEpisodeStats(input(episodes, 2))!.aggVelocity).toEqual(
      computeVelocityStats(episodes, 2, names),
    );
  });
});