Skip to content
Logo

Distributions

By default, a value drawn from a range is uniform: every value in the range is equally likely. That covers T.number.whereby({ min, max }), T.date.whereby({ min, max }), T.date.past, T.date.future, and the length of T.string and T.array. A plain min or max is inclusive, and { value, exclusive: true } excludes that end. A distribution changes how values spread across the range, so generated data can cluster the way real data does.

T.number.whereby({
  min: 0,
  max: 1000,
  distribution: { kind: "normal", mean: 500, spread: 100 },
});

Explore

Pick a variant, set the range, and drag its parameters until the shape matches your data. The bars are real draws from T.number.whereby, the line is the exact curve they follow, and the code underneath produces what you see. If fabricator rejects a configuration, you see its error.

If you have real data, a census can fit these variants to it and report the parameters.

02004006008001,000
5,000 draws exact density
T.number.whereby({
  min: 0,
  max: 1000,
  distribution: { kind: "normal", mean: 500, spread: 100 },
});

The variants

uniform

{ kind: 'uniform' } is the default. Every value in the range is equally likely.

02004006008001,000

No parameters — every value is equally likely.

2,000 draws exact density

normal

{ kind: 'normal', mean?, spread? } is a bell curve truncated to the range. mean defaults to the middle of the range. spread is the standard deviation and defaults to a sixth of the range, which puts the ends about three standard deviations from the middle.

02004006008001,000
2,000 draws exact density

skew

{ kind: 'skew', exponent } is a power curve. An exponent above 1 favors min, below 1 favors max, and exactly 1 is uniform.

02004006008001,000
2,000 draws exact density

triangular

{ kind: 'triangular', mode? } rises linearly to a peak at mode and falls linearly after it. mode defaults to the middle of the range. Use it when you want values to cluster around a point and thin out toward the edges, without a bell curve.

02004006008001,000
2,000 draws exact density

logarithmic

{ kind: 'logarithmic' } spreads values evenly across orders of magnitude, so they cluster toward min. A value between 10 and 100 is as likely as one between 1,000 and 10,000. It suits things like request latencies or file sizes. The range's min must be greater than zero. Switch on the log axis to see the same draws come out flat.

12,0004,0006,0008,00010,000

No parameters — the range must start above zero.

2,000 draws exact density

multi

{ kind: 'multi', components: [{ weight, distribution }, ...] } blends several distributions over the same range. Two normals with different means give two separate peaks. Weights are relative and don't need to add up to one. A component with weight 0 is ignored, and it throws if every weight is 0.

{
  kind: 'multi',
  components: [
    { weight: 3, distribution: { kind: 'normal', mean: 20, spread: 5 } },
    { weight: 1, distribution: { kind: 'normal', mean: 80, spread: 5 } },
  ],
}
// clusters mostly around 20, with a smaller cluster around 80
020406080100
component 1
component 2
2,000 draws exact density

custom

{ kind: 'custom', shape } is for any shape the others don't cover. shape is an inverse CDF, (u: number) => number: it takes a uniform draw in [0, 1) and returns a position in the range, where 0 is min and 1 is max. The result is clamped to [0, 1], so it stays in the range regardless of what shape returns.

What every variant guarantees

Every distribution, including custom, produces a value inside the range on the first draw. Nothing is redrawn, so no distribution can loop or skew the result by throwing draws away. The built-in variants are cut off at the range's ends, and custom is clamped.