rank_next_tests
Read-only
Rank candidate experiments by what running them would TEACH — Lindley's expected information gain, the drop in uncertainty about a hypothesis expected before anything is run. Three grains: tests ranks candidate falsification tests against the beliefs a discovery ledger holds, each with the posterior its two outcomes would leave, by gain and separately by gain per unit cost; measurements says what n readings of a normal quantity would teach, and how many it takes to reach a target; trials says the same for a rate held as a Beta. A gain is what a result would settle whichever way it lands — never evidence that a hypothesis is true, which stays with the ledger's e-values.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| n | No | how many measurements the run would take. Only applies when mode is measurements. | |
| beta | No | the Beta prior's β — failures already believed in. Only applies when mode is trials. | |
| mode | No | which grain of the question: rank candidate tests, size a run of measurements, or size a run of trials. Values: tests (Candidate tests), measurements (Measurements of a mean), trials (Trials of a rate). | tests |
| alpha | No | the Beta prior's α — successes already believed in. Only applies when mode is trials. | |
| tests | No | the candidates, each `{id, hypothesis, power, alpha}` and optionally `cost`, `reads` (what it would read) and `label`. Only applies when mode is tests. | |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| ledger | No | a jane.discovery-ledger file, as `run_discovery_programme` returns: its elicited beliefs and the sources its evidence already read. Only applies when mode is tests. | |
| trials | No | how many trials the run would take. Only applies when mode is trials. | |
| beliefs | No | belief that each hypothesis is true, as `{hypothesisId: probability}` — given directly, or to override the ledger's. Only applies when mode is tests. | |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. | |
| noise_sd | No | the measurement noise, in the same units. Only applies when mode is measurements. | |
| prior_sd | No | how uncertain the mean is now, as a standard deviation. Only applies when mode is measurements. | |
| target_bits | No | a gain to reach: the answer says how many measurements it would take. Only applies when mode is measurements. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| best | Yes | the most informative candidate's id, or the mode's own answer in words | |
| bits | Yes | the expected information gain of the top answer, in bits | |
| gain | Yes | the gain itself: nats, bits, and the entropies before and after. Absent when candidate tests were ranked, where each one carries its own | |
| note | Yes | why a ranking is short or empty, when it is | |
| byCost | Yes | the same candidates ordered by gain per unit cost, when every one was priced | |
| ranked | Yes | every ranked candidate: gain, gain per unit cost, the prior it stands on and the posterior each outcome would leave | |
| result | Yes | the full answer, with the settings that produced it | |
| beliefs | Yes | the belief each hypothesis was ranked against, and where it came from | |
| samplesForTarget | Yes | how many measurements reach `target_bits`; null when no target was set |