Reference / binference.samplers.Gibbs

binference.samplers.Gibbs

class binference.samplers.Gibbs(model, *, n_chains=4, n_warmup=500, thin=1, store_labels=False, init=None, chunk=4096, rng=None, progress=False)

Data-augmentation Gibbs sampler (the “hierarchical” sampler).

Alternates (i) drawing every object’s bin label \(z_i \sim \mathrm{Cat}(r_i(\rho))\) and (ii) drawing the population from its conjugate conditional given the counts (Dirichlet family: \(\rho \mid n \sim \mathrm{Dir}(\alpha + n)\); rates: \(\lambda_k \mid n \sim \mathrm{Gamma}(a_k + n_k, b_k + S_k)\)). With a selection function on fractions, the number of undetected objects and their bins are imputed as well (negative-binomial augmentation), keeping every step conjugate.

The marginal posterior of the population is the same as NUTS’s; Gibbs additionally yields joint draws of the labels. It mixes slowly when per-object PDFs are broad compared with the bins (a large fraction of missing information; see PopulationModel.missing_information()), so check the effective sample sizes.

Parameters:

modelPopulationModel

Must use a conjugate prior and integer object weights.

n_chainsint

Independent chains (default 4).

n_warmupint

Burn-in iterations per chain.

thinint

Keep every thin-th draw.

store_labelsbool or array_like of int

Store joint draws of the objects’ bins. True stores them for all objects (unit weights only), an array for the given object indices (sorted and deduplicated, as result.label_index records).

initarray_like (K,), optional

Positive fractions or rates around which the chains start. Each chain starts from its own draw of the population’s conditional given the expected counts there, as by default around a few EM steps.

chunkint or None

Objects processed per block when drawing labels from dense likelihoods, which bounds memory; None processes all at once. Sparse likelihoods are processed at once, in memory proportional to their nonzeros.

rngint, numpy.random.Generator, or None

Random number generator.

progressbool

Show a progress bar.

__init__(model, *, n_chains=4, n_warmup=500, thin=1, store_labels=False, init=None, chunk=4096, rng=None, progress=False)

Methods

__init__(model, *[, n_chains, n_warmup, ...])
run([n_samples])	Burn in (first call only), draw n_samples per chain, and return all draws so far.
sample(n_samples)	Generator over kept iterations, yielding (n_chains, K) values.
unsupported(model)	Why the engine cannot run on model, or None when it can.
warmup()	Run burn-in if it has not been run yet.

Attributes

approximate
joint	whether the engine infers a selection from injections or a tallied response jointly (DECISIONS #30, #80, #81)
markov	whether its draws are Markov chains, described by R-hat and ESS
name
result

joint = True

whether the engine infers a selection from injections or a tallied response jointly (DECISIONS #30, #80, #81)

markov = True

whether its draws are Markov chains, described by R-hat and ESS

run(n_samples=1000)

Burn in (first call only), draw n_samples per chain, and return all draws so far.

Parameters:

n_samplesint, optional

Draws per chain after burn-in.

sample(n_samples)

Generator over kept iterations, yielding (n_chains, K) values.

Parameters:

n_samplesint

Kept iterations per chain.

classmethod unsupported(model)

Why the engine cannot run on model, or None when it can.

Parameters:

modelPopulationModel

The model to run on.

warmup()

Run burn-in if it has not been run yet.