Skip to content

virgil.fields

Gaussian-process priors for pixel images. A GaussianField can take the place of an Image's log-brightness array: the log-brightness is then a stationary Gaussian process about an optional template, parameterized by whitened coefficients on the image's cosine basis, which imaging.image_priors gives standard-normal priors.

Gaussian-process log-brightness fields for pixel images.

A GaussianField can stand in for the log_brightness array of an Image. The image's log-brightness is then a stationary Gaussian process with a Matérn-like spectrum, written in its whitened form: independent standard-normal latent coefficients on the image's cosine (DCT-II) basis. This is the basis that diagonalizes the Laplacian with reflecting boundaries. Fitting the latents under a standard-normal prior (from image_priors) is MAP estimation with a GP prior, and the same parameterization suits sampling.

GaussianField

Bases: Base

A Gaussian-process log-brightness for an Image.

The log-brightness is

\[\eta = \log\left(\frac{\mu}{\max\mu} + \epsilon\right) + \mathrm{IDCT}\left[\sqrt{S} \odot z\right],\]

with the orthonormal inverse DCT-II, the spectrum S of field_spectrum, latent coefficients z (latent) and an optional positive template image μ (mean, floored at ε = mean_floor of its peak). With a standard-normal prior on latent, η is a Gaussian process with standard deviation sigma and correlation length length_mas about the template. Two lengths make it anisotropic: with the Image's rotation_deg set to a structure's position angle, (ℓ_along, ℓ_across) correlates the field along the structure (the grid's "up" axis) and across it, which suits filaments. latent = 0 gives the template raised by the floor, μ/max μ + ε, as an image.

Use it in place of an Image's log-brightness, with priors from image_priors:

field = GaussianField(np.zeros((32, 32)), sigma=2.0, length_mas=3.0,
                      mean=start.env.brightness)
env = Image(field, pixel_scale_mas=0.6, flux=0.3)

Fix sigma and length_mas, or sample them: their MAP values are biased (fit warns), and Stage 5's evidence helpers choose them from the data.

Parameters:

Name Type Description Default
latent (array - like, shape(nrow, ncol))

Whitened cosine coefficients.

 required
sigma float or array - like

Standard deviation of the field (default 1).

 1.0
length_mas float or array - like

Correlation length in milliarcseconds (default 1), or a pair (ℓ_row, ℓ_col): correlated over ℓ_row along the image's vertical axis and ℓ_col along its horizontal axis.

 1.0
order int

Exponent of the spectrum (default 2).

 2
mean array - like

Positive template image, of the same shape (default: none, a flat template).

 None
mean_floor float

Floor on the template, as a fraction of its peak (default 1e-3).

 0.001

latent = np.asarray(latent, dtype=float) instance-attribute

sigma = np.asarray(sigma, dtype=float) instance-attribute

length_mas = np.asarray(length_mas, dtype=float) instance-attribute

order = int(order) class-attribute instance-attribute

mean = mean instance-attribute

mean_floor = float(mean_floor) class-attribute instance-attribute

shape property

The image's shape, (nrow, ncol).

__init__(latent, sigma=1.0, length_mas=1.0, order=2, mean=None, mean_floor=0.001)

evaluate(pixel_scale_mas)

The log-brightness η on pixels of pixel_scale_mas.

field_spectrum(shape, pixel_scale_mas, sigma, length_mas, order=2)

Prior variances of a field's cosine coefficients.

S_jk ∝ (κ² + λ_jk)^(-order), with κ = 1 / length_mas and λ_jk the eigenvalues of the reflecting-boundary (Neumann) Laplacian on the pixel grid, (2/h)² [sin²(πj/2n) + sin²(πk/2m)]. With two lengths (ℓ_row, ℓ_col) the field is anisotropic, S_jk ∝ (1 + ℓ_row² λ_j + ℓ_col² λ_k)^(-order): correlated over ℓ_row along the image's columns (down a column, from row to row) and over ℓ_col along its rows. One length gives the isotropic case. The constant mode is set to zero, since a softmax image does not depend on it, and the spectrum is scaled so that the field's variance, averaged over pixels, is sigma².

Parameters:

Name Type Description Default
shape tuple of int

(nrow, ncol).

 required
pixel_scale_mas float

Pixel size h in milliarcseconds.

 required
sigma float or array - like

Standard deviation of the field, in units of log-brightness.

 required
length_mas (float or array - like, shape() or (2,))

Correlation length 1/κ in milliarcseconds, or the pair (ℓ_row, ℓ_col) for an anisotropic field.

 required
order int

Exponent of the spectrum (default 2). order=1 makes the prior exactly a total-squared-variation plus L2 penalty on the field.

 2

Returns:

Type Description
Array

Variances, of shape shape.