nifty8.library.correlated_fields module#

class CorrelatedFieldMaker(prefix, total_N=0)[source]#

Bases: object

Construction helper for hierarchical correlated field models.

The correlated field models are parametrized by creating square roots of power spectrum operators (“amplitudes”) via calls to add_fluctuations*() that act on the targeted field subdomains. During creation of the CorrelatedFieldMaker, a global offset from zero of the field model can be defined and an operator applying fluctuations around this offset is parametrized.

The resulting correlated field model operator has a MultiDomain as its domain and expects its input values to be univariately gaussian.

The target of the constructed operator will be a DomainTuple containing the target_subdomains of the added fluctuations in the order of the add_fluctuations calls.

Creation of the model operator is completed by calling the method finalize(), which returns the configured operator.

An operator representing an array of correlated field models can be constructed by setting the total_N parameter of. It will have an UnstructuredDomain of shape (total_N,) prepended to its target domain and represent total_N correlated fields simulataneously. The degree of information sharing between the correlated field models can be configured via the dofdex parameter of add_fluctuations().

See the methods add_fluctuations*() and finalize() for further usage information.

See also

For one power spectrum, the correlated field model has first been described in “Comparison of classical and Bayesian imaging in radio interferometry”, A&A 646, A84 (2021) by P. Arras et al. https://doi.org/10.1051/0004-6361/202039258
For multiple power spectra, it has first been used in “M87* in space, time and frequency”, Nature Astronomy (2022), by P. Arras et al. https://doi.org/10.1038/s41550-021-01548-0

Consider citing these papers, if you use the correlated field model.

__init__(prefix, total_N=0)[source]#

Instantiate a CorrelatedFieldMaker object.

Parameters:

prefix (string) – Prefix to the names of the domains of the cf operator to be made. This determines the names of the operator domain.
total_N (integer, optional) – Number of field models to create. If not 0, the first entry of the operators target will be an UnstructuredDomain with length total_N.

add_fluctuations(target_subdomain, fluctuations, flexibility, asperity, loglogavgslope, prefix='', index=None, dofdex=None, harmonic_partner=None)[source]#

Function to add correlation structures to the field to be made.

Correlations are described by their power spectrum and the subdomain on which they apply.

The parameters fluctuations, flexibility, asperity and loglogavgslope configure the power spectrum model used on the target field subdomain target_subdomain. It is assembled as the sum of a power law component (linear slope in log-log power-frequency-space), a smooth varying component (integrated Wiener process) and a ragged component (un-integrated Wiener process).

Multiple calls to add_fluctuations are possible, in which case the constructed field will have the outer product of the individual power spectra as its global power spectrum.

Parameters:

target_subdomain (Domain, DomainTuple) – Target subdomain on which the correlation structure defined in this call should hold.
fluctuations (tuple of float (mean, std)) – Total spectral energy -> Amplitude of the fluctuations LogNormal distribution
flexibility (tuple of float (mean, std) or None) – Amplitude of the non-power-law power spectrum component LogNormal distribution
asperity (tuple of float (mean, std) or None) – Roughness of the non-power-law power spectrum component Used to accommodate single frequency peaks LogNormal distribution
loglogavgslope (tuple of float (mean, std)) – Power law component exponent Normal distribution
prefix (string) – prefix of the power spectrum parameter domain names
index (int) – Position target_subdomain in the final total domain of the correlated field operator.
dofdex (np.array, optional) – An integer array specifying the power spectrum models used if total_N > 1. It needs to have length of total_N. If total_N=3 and dofdex=[0,0,1], that means that two power spectrum models are instantiated; the first one is used for the first and second field model and the second one is used for the third field model. If not given, use the same power spectrum model for all constructed field models.
harmonic_partner (Domain, DomainTuple) – In which harmonic space to define the power spectrum

add_fluctuations_matern(target_subdomain, scale, cutoff, loglogslope, prefix='', adjust_for_volume=True, harmonic_partner=None)[source]#

Function to add matern kernels to the field to be made.

The matern kernel amplitude is parametrized in the following way:

$A(k) = \frac{a}{\left(1 + { \left(\frac{|k|}{b}\right) }^2\right)^{-c/4}}$

where $a$ is the scale, $b$ the cutoff and $c$ the spectral index of the power spectrum.

Parameters:

target_subdomain (Domain, DomainTuple) – Target subdomain on which the correlation structure defined in this call should hold.
scale (tuple of float (mean, std)) – Overall scale of the fluctuations in the target subdomain. The parameter is a-priori lognormal distribution.
cutoff (tuple of float (mean, std)) – Frequency at which the power spectrum should transition into a spectra following a power-law. The parameter is a-priori lognormal distribution.
loglogslope (tuple of float (mean, std)) – The slope of the power-spectrum spectrum on double logarithmic scales, i.e. the spectral index. The parameter is a-priori normal distribution.
prefix (string) – Prefix of the power spectrum parameter domain names.
adjust_for_volume (bool, optional) – Whether to implicitly adjust the scale parameter of the Matern kernel and the zero-mode of the overall model for the volume in the target subdomain or assume them to be adjusted already.
harmonic_partner (Domain, DomainTuple) – Harmonic space in which to define the power spectrum.

Notes

The parameters of the amplitude model are assumed to be relative to a unit-less power spectrum, i.e. the parameters are assumed to be agnostic to changes in the volume of the target subdomain. This is in steep contrast to the non-parametric amplitude operator in add_fluctuations.

Up to the Matern amplitude only works for total_N == 0.

property amplitude#

property amplitude_total_offset#: Returns the total offset of the amplitudes

average_fluctuation(space)[source]#: Returns operator which acts on prior or posterior samples

static average_fluctuation_realized(samples, space)[source]#: Computes average fluctuations from collection of field (defined in signal space) realizations.

property azm#: Alias for amplitude_total_offset

finalize(prior_info=100)[source]#

Finishes model construction process and returns the constructed operator.

Parameters:: prior_info (integer) – How many prior samples to draw for property verification statistics If zero, skips calculating and displaying statistics.

property fluctuations#: Returns the added fluctuations operators used in the model

get_normalized_amplitudes()[source]#

Returns the normalized amplitude operators used in the final model

The amplitude operators are corrected for the otherwise degenerate zero-mode. Their scales are only meaningful relative to one another. Their absolute scale bares no information.

Notes

In the case of no zero-mode, i.e. an assumed zero-mode of unity, this call is equivalent to the fluctuations property.

moment_slice_to_average(fluctuations_slice_mean, nsamples=1000)[source]#

Translates the slice fluctuations into average flucutations to use single space results in multi-space setups.

This method allows to use single-space reconstruction results to set the hyperparameters in multi-space settings. Given the results of a reconstruction in a single space setting (say for example an image at a specific frequency or a specific moment in time), it is possible to use the fluctuations of these results to determine the fluctuations of this (sub-)space in a multi-space setup (e.g. when reconstructing a collection of images over a frequency range or in a time interval). To do so, the single-space fluctuations have to be translated to match their multi-space counterparts, since the single-space results represent a slice of the multi-space setting. The fluctuations in the multi-space setting represent average fluctuations (i.E. the variability that remains when integrating over all other spaces) and therefore the slice fluctuations have to be rescaled. After all new sub-spaces (say time and/or frequency) have been added to the model, this method can be used to obtain the mean of fluctuations of the last sub-space from the fluctuations given from the single space result. Note that to properly use this method it should be called only after all other sub-spaces (time/frequency) as well as the amplitude_total_offset have been set in the CorrelatedFieldMaker (see example below).

Parameters:

fluctuations_slice_mean (float) – Mean fluctuations of the single space reconstruction that is a slice of this multi-space setting.
nsamples (int, optional) – Number of samples used internally to estimate the rescaling of the fluctuations. Default is 1000.

Returns:

out – Mean of the average fluctuations that can be used as an input to add the final sub-space matching the space used for the slice case.

Return type:

float

Examples

>>> slice_fluct = ... # Fluctuations obtained from the single-space run
>>> cf = ift.CorrelatedFieldMaker(...) # The cf of the multi-space case
>>> cf.add_fluctuations(...) # Add a sub-space (e.g. frequency)
>>> cf.add_fluctuations(**freq_params) # An optional second space (time)
>>> cf.set_amplitude_total_offset(...) # Set zero mode of the spectrum
>>> avg_fluct = cf.moment_slice_to_average(slice_fluct)
>>> cf.add_fluctuations(fluctuations=(avg_fluct, ...), ...)
>>> cf.finalize()

static offset_amplitude_realized(samples)[source]#

property power_spectrum#

set_amplitude_total_offset(offset_mean, offset_std, dofdex=None)[source]#

Sets the zero-mode for the combined amplitude operator

Parameters:

offset_mean (float) – Mean offset from zero of the correlated field to be made.
offset_std (tuple of float, instance of Operator acting on scalar domain, scalar or None) – Mean standard deviation and standard deviation of the standard deviation of the offset. No, this is not a word duplication. The option to specify None or equivalently a scalar value of 1. only really makes sense for one dimensional amplitude spectral. Take special care if using this option for multi-dimensional amplitude spectra that this is really what you want.
dofdex (np.array of integers, optional) – An integer array specifying the zero mode models used if total_N > 1. It needs to have length of total_N. If total_N=3 and dofdex=[0,0,1], that means that two models for the zero mode are instantiated; the first one is used for the first and second field model and the second is used for the third field model. If not specified, use the same zero mode model for all constructed field models.

slice_fluctuation(space)[source]#: Returns operator which acts on prior or posterior samples

static slice_fluctuation_realized(samples, space)[source]#: Computes slice fluctuations from collection of field (defined in signal space) realizations.

statistics_summary(prior_info)[source]#

property total_fluctuation#: Returns operator which acts on prior or posterior samples

static total_fluctuation_realized(samples)[source]#