Random Reservoir Stream Sample Generator

Description

Apply Algorithm R to ordered supplied records, returning portable reservoir state and update decisions with deterministic seeded chunk continuation.

Sampling selects from a supplied population under rules for replacement, grouping, or eligibility. Draw probabilities, inclusion probabilities, and repeat counts describe different aspects of selection; a reproducible sample is not automatically representative of a real population.

Apply Algorithm R to ordered supplied records, returning portable reservoir state and update decisions with deterministic seeded chunk continuation.

When to use this tool

Use this generator to create reproducible reservoir stream sample cases from the supplied model or bank. Inspect the returned evidence before using cases in a test or exercise.

How to use the tool and how it works

Supply capacity, chunk, state in the field shapes below. Set seed when you need an explicit replay.
Run the tool and correct any input error. For generated controls, distinguish a successful fixture containing an invalid case from failure to generate the fixture.
Read state, updates, inclusionProbability. Use the conventions below and keep answer-bearing fields separate when presenting an exercise.

Apply Algorithm R: fill the first capacity slots, then for stream index i draw j from zero through i and replace slot j only when j is below capacity. Return portable state and each fill, replace, or skip decision. Inclusion probability is min(capacity,seen)/seen, or zero when empty.^[1]

Input field	Meaning and units	Accepted input
capacity	Capacity	Required. Safe integer; minimum 0; maximum 512.
chunk	Chunk	Required. Array of Object; no unknown keys.; minimum items 0; maximum items 2048.
chunk[].id	Literal identifier used to match records, independently of their display labels.	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128.
chunk[].values	Values	Required. Array of Text; maximum UTF-16 length 4096.; minimum items 0; maximum items 32.
state	State	Optional. Object; no unknown keys.
state.capacity	Capacity	Required. Safe integer; minimum 0; maximum 512.
state.seen	Seen	Required. Safe integer; minimum 0; maximum 100000.
state.reservoir	Reservoir	Required. Array of Object; no unknown keys.; minimum items 0; maximum items 512.
state.reservoir[].streamIndex	Stream Index	Required. Safe integer; minimum 0.
state.reservoir[].record	Record	Required. Object; no unknown keys.
state.reservoir[].record.id	Literal identifier used to match records, independently of their display labels.	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128.
state.reservoir[].record.values	Values	Required. Array of Text; maximum UTF-16 length 4096.; minimum items 0; maximum items 32.
state.randomness	Replay metadata: source is seed or context; seed is the normalized 32-bit seed or null for a context source.	Required. Object; no unknown keys.
state.randomness.seed	Optional numeric replay seed; normalization and precedence are explained below.	Required. Safe integer. or Null.
state.randomness.source	Source	Required. Text; one of "context", "seed".
seed	Optional numeric seed; takes precedence over context randomness. Without either, use the fixed tool.io default seed.	Optional. Safe integer.

Output field	Interpretation	Returned shape
state	State	Required. Object; no unknown keys.
state.capacity	Capacity	Required. Safe integer; minimum 0; maximum 512.
state.seen	Seen	Required. Safe integer; minimum 0; maximum 100000.
state.reservoir	Reservoir	Required. Array of Object; no unknown keys.; minimum items 0; maximum items 512.
state.reservoir[].streamIndex	Stream Index	Required. Safe integer; minimum 0.
state.reservoir[].record	Record	Required. Object; no unknown keys.
state.reservoir[].record.id	Literal identifier used to match records, independently of their display labels.	Required. Text; minimum UTF-16 length 1; maximum UTF-16 length 128.
state.reservoir[].record.values	Values	Required. Array of Text; maximum UTF-16 length 4096.; minimum items 0; maximum items 32.
state.randomness	Replay metadata: source is seed or context; seed is the normalized 32-bit seed or null for a context source.	Required. Object; no unknown keys.
state.randomness.seed	Optional numeric replay seed; normalization and precedence are explained below.	Required. Safe integer. or Null.
state.randomness.source	Source	Required. Text; one of "context", "seed".
updates	Updates	Required. Array of Object; no unknown keys.; minimum items 0; maximum items 2048.
updates[].streamIndex	Stream Index	Required. Safe integer; minimum 0.
updates[].decision	Decision	Required. Object; no unknown keys.
updates[].decision.draw	Draw	Required. Safe integer; minimum 0. or Null.
updates[].decision.slot	Slot	Required. Safe integer; minimum 0. or Null.
updates[].decision.action	Action	Required. Text; one of "fill", "replace", "skip".
inclusionProbability	Inclusion Probability	Required. Finite number; minimum 0; maximum 1.
randomness	Replay metadata: source is seed or context; seed is the normalized 32-bit seed or null for a context source.	Required. Object; no unknown keys.
randomness.seed	Optional numeric replay seed; normalization and precedence are explained below.	Required. Safe integer. or Null.
randomness.source	Source	Required. Text; one of "context", "seed".

An explicit safe-integer seed takes precedence over injected context randomness and is normalized to an unsigned 32-bit integer. With no seed and no context source, replay uses the fixed tool.io default seed. A context source must return finite values from zero inclusive to one exclusive; its advancing state must be retained separately. randomness records the source and normalized seed, or null for context. These generators are not cryptographic random sources.

json

{
  "input": {
    "capacity": 2,
    "chunk": [
      {
        "id": "A",
        "values": [
          "oak"
        ]
      },
      {
        "id": "B",
        "values": [
          "pine"
        ]
      },
      {
        "id": "C",
        "values": [
          "elm"
        ]
      },
      {
        "id": "D",
        "values": [
          "ash"
        ]
      }
    ],
    "seed": 42
  },
  "output": {
    "state": {
      "capacity": 2,
      "seen": 4,
      "reservoir": [
        {
          "streamIndex": 0,
          "record": {
            "id": "A",
            "values": [
              "oak"
            ]
          }
        },
        {
          "streamIndex": 3,
          "record": {
            "id": "D",
            "values": [
              "ash"
            ]
          }
        }
      ],
      "randomness": {
        "seed": 42,
        "source": "seed"
      }
    },
    "updates": [
      {
        "streamIndex": 0,
        "decision": {
          "draw": null,
          "slot": 0,
          "action": "fill"
        }
      },
      {
        "streamIndex": 1,
        "decision": {
          "draw": null,
          "slot": 1,
          "action": "fill"
        }
      },
      {
        "streamIndex": 2,
        "decision": {
          "draw": 1,
          "slot": 1,
          "action": "replace"
        }
      },
      {
        "streamIndex": 3,
        "decision": {
          "draw": 1,
          "slot": 1,
          "action": "replace"
        }
      }
    ],
    "inclusionProbability": 0.5,
    "randomness": {
      "seed": 42,
      "source": "seed"
    }
  }
}

Limitations and assumptions

Capacity zero skips without draws. Continuation must preserve capacity and valid unique stream indexes. Seeded continuation restores the original normalized seed and skips prior post-fill draws; context continuation needs the same advancing random source. Cumulative seen is at most 100,000.
A replay requires the same complete input and implementation. Randomized construction does not guarantee uniform coverage of every feasible output; finite samples can repeat unless a distinct-selection rule is explicitly stated.
The field tables state structural bounds; cross-field constraints and bounded search or output budgets also apply. Unknown keys are rejected where the object contract disallows them. Input errors are distinct from null fields and deliberate invalid controls in a successful output.

Alternative or Complementary methods

For a supplied example, inspect the returned construction or delegated check directly. To evaluate a consumer, also test cases chosen for its own boundaries; a generated finite corpus does not establish exhaustive coverage.

References

Tool behavior and example: Random Reservoir Stream Sample Generator — tool.io

Similar or alternative tools

Random Stratified Row Sample Generator
Sample supplied records under exact stratum quotas and replacement rules, retaining row inclusion probabilities and observed draw counts.
Random Negative Pair Sampler Generator
Sample uniformly among supplied-item pairs after positive and self exclusions, with explicit endpoint ordering, replacement, and conditional weights.