Skip to content

distributions.md

Latest commit

 

History

History
158 lines (116 loc) · 6.78 KB

distributions.md

File metadata and controls

158 lines (116 loc) · 6.78 KB
Raw

Value distributions and cardinality

Building a new config? See How to build a config for the design process. This page is the distribution type reference.

Distribution JSON objects define the distribution pattern to follow when creating synthetic data.

They appear in emitter dimensions lists, and in cardinality_distribution fields - including event:start:timer and event:intermediate:timer states.

Field Use timestamp string int float ipaddress
distribution Determines how the values for the dimension are generated. Y Y Y Y
length_distribution Determines the length of the generated value of the dimension. Y
cardinality_distribution When cardinality for a dimension is not 0, enables skewing the selection of values from the generated list of possible values. Y Y Y Y Y

Distribution types

Specify the cardinality type in the type field.

  • constant generates a single specific value.
  • uniform creates a flat distribution.
  • exponential for an exponential distribution.
  • normal for a normal ("bell curve") distribution.
  • gmm_temporal for time-of-day and day-of-week modulated rates using a Gaussian Mixture Model.

constant

The constant distribution generates the same single value.

Field Description Possible values Required? Default
type The data type for the dimension. constant Yes
value The constant value to output. Integer Yes

Both uniform and normal distributions are common for cardinality_distributions, while constant is less useful.

uniform

The uniform distribution generates values uniformly between min and max, inclusive.

Field Description Possible values Required? Default
type The data type for the dimension. uniform Yes
min Smallest possible value, inclusive. Integer Yes
max Largest possible value, inclusive. Integer Yes

exponential

To generate values following an exponential distribution around the mean, use exponential.

Field Description Possible values Required? Default
type The data type for the dimension. exponential Yes
mean The resulting average value of the distribution. Integer Yes

The data generator rounds down values that exceed the length of any list. Exercise special caution when using exponential in a cardinality_distribution as this may produce a distorted distribution.

normal

Normal distributions generate values with a normal (i.e., bell-shaped) distribution.

When used in cardinality_distribution on a timer state, negative values generated by the normal distribution are forced to zero.

Field Description Possible values Required? Default
type The data type for the dimension. normal Yes
mean The resulting average value of the distribution. Integer Yes
stddev The standard deviation of the distribution. Integer Yes

gmm_temporal

A Gaussian Mixture Model temporal distribution that modulates an exponential interarrival time based on time of day and day of week. Use this to simulate realistic traffic patterns such as peak business hours, evening browsing, and quieter weekends.

Each day profile is an array of Gaussian components. The utc_hour field is the mean (μ) and sigma is the standard deviation (σ) of each Gaussian component.

Field Description Possible values Required? Default
type The distribution type. gmm_temporal Yes
mean The base average interarrival time in seconds. Number Yes
days Day-of-week profiles, keyed by ISO weekday number (1=Monday, 7=Sunday). Object Yes

Each day profile is an array of component objects:

Field Description Possible values Required? Default
utc_hour The peak hour in UTC (μ). Fractional hours are supported. 0.0–24.0 Yes
sigma The width of the peak in hours (σ). Number > 0 Yes
weight The amplitude of this peak. Number > 0 Yes

Day-of-week lookup: You only need to define days where the profile changes. The generator looks up the current ISO weekday number and walks backwards (with wraparound) to find the nearest defined day. For example, if you define "1" and "6", then Monday through Friday use the "1" profile, and Saturday and Sunday use the "6" profile.

Example: An e-commerce traffic pattern with a midday peak and an evening bump on weekdays, and a shifted, broader pattern on weekends:

{
  "type": "gmm_temporal",
  "mean": 0.5,
  "days": {
    "1": [
      {"utc_hour": 12, "sigma": 3.0, "weight": 1.8},
      {"utc_hour": 20.5, "sigma": 1.5, "weight": 0.7}
    ],
    "6": [
      {"utc_hour": 14, "sigma": 3.5, "weight": 1.4},
      {"utc_hour": 21, "sigma": 2.0, "weight": 1.0}
    ]
  }
}

For the same pattern every day, define a single day key:

{
  "type": "gmm_temporal",
  "mean": 0.5,
  "days": {
    "1": [
      {"utc_hour": 12, "sigma": 3.0, "weight": 1.8}
    ]
  }
}

Note: gmm_temporal is only supported in cardinality_distribution on event:start:timer and event:intermediate:timer states. It is not supported for dimension value or cardinality distributions.

Cardinality

Use cardinality in an emitter's list of dimensions to define the length of the set of possible values.

The generator creates a list of values with length cardinality.

  • If cardinality is zero, there are no constraints on the number of values in the list.
  • When cardinality is > 0, cardinality_distribution is required, informing the data generator how to select items from the list.

In this example, a string-type dimension has no cardinality constraint.

{
  "name": "Str1",
  "type": "string",
  "length_distribution": {"type": "uniform", "min": 3, "max": 6},
  "chars": "abcdefg",
  "cardinality": 0
}

In this example, cardinality of 5 requires that there only be a maximum of 5 distinct values for this dimension. From this list of unique values, there is a uniform cardinality_distribution selecting (zero-indexed) values from that list.

{
  "name": "Str1",
  "type": "string",
  "length_distribution": {"type": "uniform", "min": 3, "max": 6},
  "cardinality": 5,
  "cardinality_distribution": {"type": "uniform", "min": 0, "max": 4},
  "chars": "abcdefg"
}