ibs_basic

Note

ibs_basic is a minimal implementation of inverse binomial sampling, for teaching: for each trial in turn, it calls the simulator once per sample until a simulated response matches the observed one, and adds up the trials’ estimates of the log-likelihood. It follows ibs_basic.m of MATLAB IBS.

It returns a log-likelihood estimate without a variance estimate or any stopping limits. Use IBS for fitting models.

pyibs.ibs_basic(sample_from_model, theta, R, S=None, *, random_seed=None)

Estimate a log-likelihood by inverse binomial sampling, one trial at a time.

This teaching implementation of IBS ([1]) processes trials in order. For each trial, it simulates one response at a time until a response matches the observation, then adds that trial’s log-likelihood estimate to the total. Use pyibs.IBS for fitting models: it samples every open trial in each simulator call, estimates the variance, and has a sample cap, a time limit and a likelihood threshold.

Parameters:

sample_from_modelcallable

Called as sample_from_model(theta, s). If it has a parameter named rng that accepts a keyword, the call also supplies its random generator as rng=rng. Here s is S[i], or the 0-based trial index i when S is None.

Return one independent simulated response with shape (C,) or (1, C), where C is the number of response columns. A scalar is also accepted for a single-column response.

thetaarray_like

The parameter vector, passed to the simulator as given.

Rarray_like of shape (N,) or (N, C)

Observed responses, one row per trial; a scalar represents one trial. A simulated response matches only if every column agrees. For responses that mix numbers and text, give both the observed and the simulated responses as object arrays (dtype=object): otherwise NumPy converts the numbers to text, responses can fail to match, and the sampling, which has no cap, never ends.

Sarray_like of shape (N, …), optional

Experimental conditions or other simulator inputs, one row per trial. None (the default) passes the trial index instead.

random_seedNone, int, numpy.random.SeedSequence or numpy.random.Generator, optional

Seed for the generator passed to the simulator. Accepts the same values as random_seed of pyibs.IBS.

Returns:

Lfloat

The IBS estimate of the log-likelihood (not its negative).

Raises:

ValueError

If R is empty, has more than two dimensions, or contains a NaN, an element not equal to itself, which no simulated response matches; if S does not have N rows; or if the simulator returns an output not shaped as one response.

TypeError

If the simulator returns a response of a kind that cannot match R, such as text for numeric responses.

Notes

There is no sample cap or time limit. Sampling continues indefinitely if the simulator cannot produce an observed response.

References

[1]

van Opheusden, B., Acerbi, L. & Ma, W. J. (2020). Unbiased and efficient log-likelihood estimation with inverse binomial sampling. PLOS Computational Biology 16(12): e1008483. https://doi.org/10.1371/journal.pcbi.1008483