Reviewed docs on operators, library, sugar. Fixed bug in makeOp due to the...

Reviewed docs on operators, library, sugar. Fixed bug in makeOp due to the recent BlochdiagonalOperator interface change

nifty5/field.py

@@ -25,7 +25,7 @@ from .domain_tuple import DomainTuple
 class Field(object):
     """The discrete representation of a continuous field over multiple spaces.
 
-    Stores data arrays and carries all the needed metainformation (i.e. the
+    Stores data arrays and carries all the needed meta-information (i.e. the
     domain) for operators to be able to operate on them.
 
     Parameters

nifty5/library/adjust_variances.py

@@ -41,7 +41,7 @@ def make_adjust_variances(a,
         Operator which gives the amplitude when evaluated at a position
     xi : Operator
         Operator which gives the excitation when evaluated at a position
-    postion : Field, MultiField
+    position : Field, MultiField
         Position of the whole problem
     samples : Field, MultiField
         Residual samples of the whole problem

nifty5/library/correlated_fields.py

@@ -25,15 +25,15 @@ from ..operators.simple_linear_operators import ducktape
 
 
 def CorrelatedField(target, amplitude_operator, name='xi'):
-    '''Constructs an operator which turns a white Gaussian excitation field
+    """Constructs an operator which turns a white Gaussian excitation field
     into a correlated field.
 
     This function returns an operator which implements:
 
         ht @ (vol * A * xi),
 
-    where `ht` is a harmonic transform operator, `A` is the sqare root of the
-    prior covariance an `xi` is the excitation field.
+    where `ht` is a harmonic transform operator, `A` is the square root of the
+    prior covariance and `xi` is the excitation field.
 
     Parameters
     ----------
@@ -41,12 +41,12 @@ def CorrelatedField(target, amplitude_operator, name='xi'):
         Target of the operator. Must contain exactly one space.
     amplitude_operator: Operator
     name : string
-        :class:`MultiField` key for xi-field.
+        :class:`MultiField` key for the xi-field.
 
     Returns
     -------
     Correlated field : Operator
-    '''
+    """
     tgt = DomainTuple.make(target)
     if len(tgt) > 1:
         raise ValueError
@@ -60,7 +60,7 @@ def CorrelatedField(target, amplitude_operator, name='xi'):
 
 
 def MfCorrelatedField(target, amplitudes, name='xi'):
-    '''Constructs an operator which turns white Gaussian excitation fields
+    """Constructs an operator which turns white Gaussian excitation fields
     into a correlated field defined on a DomainTuple with two entries and two
     separate correlation structures.
 
@@ -79,7 +79,7 @@ def MfCorrelatedField(target, amplitudes, name='xi'):
     Returns
     -------
     Correlated field : Operator
-    '''
+    """
     tgt = DomainTuple.make(target)
     if len(tgt) != 2:
         raise ValueError

nifty5/library/dynamic_operator.py

@@ -144,7 +144,7 @@ def dynamic_operator(*,
                      key,
                      causal=True,
                      minimum_phase=False):
-    '''Constructs an operator encoding the Green's function of a linear
+    """Constructs an operator encoding the Green's function of a linear
     homogeneous dynamic system.
     
     When evaluated, this operator returns the Green's function representation
@@ -189,7 +189,7 @@ def dynamic_operator(*,
     Notes
     -----
     The first axis of the domain is interpreted the time axis.
-    '''
+    """
     dct = {
         'target': target,
         'harmonic_padding': harmonic_padding,

nifty5/library/inverse_gamma_operator.py

@@ -31,11 +31,11 @@ class InverseGammaOperator(Operator):
     The pdf of the inverse gamma distribution is defined as follows:
 
     .. math ::
-        \\frac{\\beta^\\alpha}{\\Gamma(\\alpha)}x^{-\\alpha -1}\\exp \\left(-\\frac{\\beta }{x}\\right)
+        \\frac{q^\\alpha}{\\Gamma(\\alpha)}x^{-\\alpha -1}\\exp \\left(-\\frac{q}{x}\\right)
 
-    That means that for large x the pdf falls off like x^(-alpha -1).
-    The mean of the pdf is at q / (alpha - 1) if alpha > 1.
-    The mode is q / (alpha + 1).
+    That means that for large x the pdf falls off like :math:`x^(-\\alpha -1)`.
+    The mean of the pdf is at :math:`q / (\\alpha - 1)` if :math:`\\alpha > 1`.
+    The mode is :math:`q / (\\alpha + 1)`.
 
     This transformation is implemented as a linear interpolation which maps a
     Gaussian onto a inverse gamma distribution.

nifty5/library/los_response.py

@@ -104,7 +104,7 @@ def apply_erf(wgt, dist, lo, mid, hi, sig, erf):
 class LOSResponse(LinearOperator):
     """Line-of-sight response operator
 
-    This operator transforms from a single RGSpace to an unstructured domain
+    This operator transforms from a single RGSpace to an UnstructuredDomain
     with as many entries as there were lines of sight passed to the
     constructor. Adjoint application is also provided.
 

nifty5/library/smooth_linear_amplitude.py

@@ -33,7 +33,7 @@ def _ceps_kernel(k, a, k0):
 
 
 def CepstrumOperator(target, a, k0):
-    '''Turns a white Gaussian random field into a smooth field on a LogRGSpace.
+    """Turns a white Gaussian random field into a smooth field on a LogRGSpace.
 
     Composed out of three operators:
 
@@ -69,10 +69,10 @@ def CepstrumOperator(target, a, k0):
         regularization of the inverse laplace operator to be finite at zero.
         Larger values for the cutoff results in a weaker constraining prior.
     k0 : float, list of float
-        Strength of smothness prior in quefrency space (positive only) along
+        Strength of smoothness prior in quefrency space (positive only) along
         each axis. If float then the strength is the same along each axis.
         Larger values result in a weaker constraining prior.
-    '''
+    """
     a = float(a)
     target = DomainTuple.make(target)
     if a <= 0:

nifty5/multi_field.py

@@ -25,7 +25,8 @@ from .domain_tuple import DomainTuple
 
 class MultiField(object):
     def __init__(self, domain, val):
-        """
+        """The discrete representation of a continuous field over a sum space.
+
         Parameters
         ----------
         domain: MultiDomain

nifty5/operators/block_diagonal_operator.py

@@ -24,9 +24,10 @@ class BlockDiagonalOperator(EndomorphicOperator):
     """
     Parameters
     ----------
+    domain : :class:`MultiDomain`
+        Domain and target of the operator.
     operators : dict
-        Dictionary with operators domain names as keys and LinearOperators as
-        items.
+        Dictionary with subdomain names as keys and :class:`LinearOperators` as items.
     """
     def __init__(self, domain, operators):
         if not isinstance(domain, MultiDomain):

nifty5/operators/chain_operator.py

@@ -23,7 +23,12 @@ from .simple_linear_operators import NullOperator
 
 
 class ChainOperator(LinearOperator):
-    """Class representing chains of operators."""
+    """Class representing chains of operators.
+
+    Notes
+    -----
+    This operator has to be called using the :attr:`make` method.
+    """
 
     def __init__(self, ops, _callingfrommake=False):
         if not _callingfrommake:

nifty5/operators/contraction_operator.py

@@ -24,10 +24,10 @@ from .linear_operator import LinearOperator
 
 
 class ContractionOperator(LinearOperator):
-    """A linear operator which sums up fields into the direction of subspaces.
+    """A  :class:`LinearOperator` which sums up fields into the direction of subspaces.
 
-    This ContractionOperator sums up a field with is defined on a DomainTuple
-    to a DomainTuple which contains the former as a subset.
+    This Operator sums up a field with is defined on a :class:`DomainTuple`
+    to a :class:`DomainTuple` which contains the former as a subset.
 
     Parameters
     ----------

nifty5/operators/diagonal_operator.py

@@ -24,10 +24,10 @@ from .endomorphic_operator import EndomorphicOperator
 
 
 class DiagonalOperator(EndomorphicOperator):
-    """Represents a linear operator which is diagonal.
+    """Represents a :class:`LinearOperator` which is diagonal.
 
     The NIFTy DiagonalOperator class is a subclass derived from the
-    EndomorphicOperator. It multiplies an input field pixel-wise with its
+    :class:`EndomorphicOperator`. It multiplies an input field pixel-wise with its
     diagonal.
 
     Parameters

nifty5/operators/domain_tuple_field_inserter.py

@@ -23,7 +23,7 @@ from .linear_operator import LinearOperator
 
 
 class DomainTupleFieldInserter(LinearOperator):
-    '''Writes the content of a field into one slice of a DomainTuple.
+    """Writes the content of a :class:`Field` into one slice of a :class:`DomainTuple`.
 
     Parameters
     ----------
@@ -33,7 +33,7 @@ class DomainTupleFieldInserter(LinearOperator):
         Index at which new_space shall be added to domain.
     position : tuple
         Slice in new_space in which the input field shall be written into.
-    '''
+    """
     def __init__(self, domain, new_space, index, position):
         self._domain = DomainTuple.make(domain)
         tgt = list(self.domain)

nifty5/operators/endomorphic_operator.py

@@ -21,7 +21,7 @@ from .linear_operator import LinearOperator
 
 
 class EndomorphicOperator(LinearOperator):
-    """Represents a linear operator which is endomorphic, i.e. one which
+    """Represents a :class:`LinearOperator` which is endomorphic, i.e. one which
     has identical domain and target.
     """
     @property

nifty5/operators/energy_operators.py

@@ -49,7 +49,7 @@ class SquaredNormOperator(EnergyOperator):
     Parameters
     ----------
     domain : Domain, DomainTuple or tuple of Domain
-        Target domain of the operator in which the L2-norm shall be computed.
+        Domain of the operator in which the L2-norm shall be computed.
     """
 
     def __init__(self, domain):
@@ -66,7 +66,7 @@ class SquaredNormOperator(EnergyOperator):
 
 class QuadraticFormOperator(EnergyOperator):
     """Computes the L2-norm of a Field or MultiField with respect to a
-    specific metric `endo`.
+    specific kernel given by `endo`.
 
     .. math ::
         E(f) = \\frac12 f^\\dagger \\text{endo}(f)
@@ -74,7 +74,7 @@ class QuadraticFormOperator(EnergyOperator):
     Parameters
     ----------
     endo : EndomorphicOperator
-         Kernel of quadratic form.
+         Kernel of the quadratic form
     """
 
     def __init__(self, endo):
@@ -283,7 +283,7 @@ class Hamiltonian(EnergyOperator):
     lh : EnergyOperator
         The likelihood energy.
     ic_samp : IterationController
-        Tells an internal :class:`SamplingEnabler` which convergence criterium
+        Tells an internal :class:`SamplingEnabler` which convergence criterion
         to use to draw Gaussian samples.
 
 

nifty5/operators/exp_transform.py

@@ -31,13 +31,13 @@ class ExpTransform(LinearOperator):
 
     This operator creates a log-space subject to the degrees of freedom and
     and its target-domain.
-    Then transforms between this log-space and its target, which is defined in
+    Then it transforms between this log-space and its target, which is defined in
     normal units.
 
     FIXME Write something on t_0 of domain space
 
     E.g: A field in log-log-space can be transformed into log-norm-space,
-         that is the y-axis stays logarithmic, but the x-axis is transfromed.
+         that is the y-axis stays logarithmic, but the x-axis is transformed.
 
     Parameters
     ----------

nifty5/operators/harmonic_operators.py

@@ -143,7 +143,7 @@ class HartleyOperator(LinearOperator):
     (https://en.wikipedia.org/wiki/Discrete_Hartley_transform).
     For complex input fields, the operator will transform the real and
     imaginary parts separately and use the results as real and imaginary parts
-    of the result field, respectivey.
+    of the result field, respectively.
     In many contexts the Hartley transform is a perfect substitute for the
     Fourier transform, but in some situations (e.g. convolution with a general,
     non-symmetric kernel, the full FFT must be used instead.
@@ -386,7 +386,7 @@ class HarmonicTransformOperator(LinearOperator):
 
 def HarmonicSmoothingOperator(domain, sigma, space=None):
     """Returns an operator that carries out a smoothing with a Gaussian kernel
-    of width `sigma` on the part of `domain` given by `space`
+    of width `sigma` on the part of `domain` given by `space`.
 
     Parameters
     ----------
@@ -408,7 +408,7 @@ def HarmonicSmoothingOperator(domain, sigma, space=None):
 
     sigma = float(sigma)
     if sigma < 0.:
-        raise ValueError("sigma must be nonnegative")
+        raise ValueError("sigma must be non-negative")
     if sigma == 0.:
         return ScalingOperator(1., domain)
 

nifty5/operators/linear_interpolation.py

@@ -35,9 +35,8 @@ class LinearInterpolator(LinearOperator):
     Parameters
     ----------
     domain : RGSpace
-    positions : numpy.ndarray
-        Positions at which to interpolate
-        Field with UnstructuredDomain, shape (dim, ndata)
+    sampling_points : numpy.ndarray, shape (dim, ndata)
+        Positions at which to interpolate.
 
     Notes
     -----

nifty5/operators/offset_operator.py

@@ -19,12 +19,13 @@ from .operator import Operator
 
 
 class OffsetOperator(Operator):
-    '''Shifts the input by a fixed field.
+    """Shifts the input by a fixed field.
 
     Parameters
     ----------
     field : Field
-        The field by which the input is shifted.'''
+        The field by which the input is shifted.
+    """
     def __init__(self, field):
         self._field = field
         self._domain = self._target = field.domain

nifty5/operators/operator.py

@@ -110,14 +110,14 @@ class Operator(NiftyMetaBase()):
         return _OpChain.make((_Clipper(self.target, min, max), self))
 
     def apply(self, x):
-        '''Applies the operator to a Field or MultiField.
+        """Applies the operator to a Field or MultiField.
 
         Parameters
         ----------
         x : Field or MultiField
             Input on which the operator shall act. Needs to be defined on
             :attr:`domain`.
-        '''
+        """
         raise NotImplementedError
 
     def force(self, x):

nifty5/operators/outer_product_operator.py

@@ -23,7 +23,7 @@ from .linear_operator import LinearOperator
 
 
 class OuterProduct(LinearOperator):
-    """Performs the pointwise outer product of two fields.
+    """Performs the point-wise outer product of two fields.
 
     Parameters
     ---------

nifty5/operators/qht_operator.py

@@ -36,7 +36,7 @@ class QHTOperator(LinearOperator):
         The full output domain
     space : int
         The index of the domain on which the operator acts.
-        target[space] must be a nonharmonic LogRGSpace.
+        target[space] must be a non-harmonic LogRGSpace.
     """
 
     def __init__(self, target, space=0):

nifty5/operators/regridding_operator.py

@@ -26,7 +26,7 @@ from .linear_operator import LinearOperator
 
 
 class RegriddingOperator(LinearOperator):
-    '''Linearly interpolates a RGSpace to an RGSpace with coarser resolution.
+    """Linearly interpolates a RGSpace to an RGSpace with coarser resolution.
 
     Parameters
     ----------
@@ -38,7 +38,7 @@ class RegriddingOperator(LinearOperator):
     space : int
         Index of space in `domain` on which the operator shall act.
         Default is 0.
-    '''
+    """
     def __init__(self, domain, new_shape, space=0):
         self._domain = DomainTuple.make(domain)
         self._space = infer_space(self._domain, space)

nifty5/operators/sampling_enabler.py

@@ -23,7 +23,7 @@ from .endomorphic_operator import EndomorphicOperator
 
 
 class SamplingEnabler(EndomorphicOperator):
-    """Class which acts as the operator object (likelihood + prior)
+    """Class which acts as a operator object built of (`likelihood` + `prior`)
     and enables sampling from its inverse even if the operator object
     itself does not support it.
 
@@ -38,8 +38,8 @@ class SamplingEnabler(EndomorphicOperator):
         The iteration controller to use for the iterative numerical inversion
         done by a :class:`ConjugateGradient` object.
     approximation : :class:`LinearOperator`, optional
-        if not None, this operator should be an approximation to `op`, which
-        supports the operation modes that `op` doesn't have. It is used as a
+        if not None, this linear operator should be an approximation to the operator, which
+        supports the operation modes that the operator doesn't have. It is used as a
         preconditioner during the iterative inversion, to accelerate
         convergence.
     """

nifty5/operators/sandwich_operator.py

@@ -25,7 +25,12 @@ from .scaling_operator import ScalingOperator
 
 class SandwichOperator(EndomorphicOperator):
     """Operator which is equivalent to the expression
-    `bun.adjoint(cheese(bun))`."""
+    `bun.adjoint(cheese(bun))`.
+
+    Notes
+    -----
+    This operator should always be called using the `make` method.
+    """
 
     def __init__(self, bun, cheese, op, _callingfrommake=False):
         if not _callingfrommake:

nifty5/operators/simple_linear_operators.py

@@ -46,7 +46,14 @@ class VdotOperator(LinearOperator):
 
 
 class ConjugationOperator(EndomorphicOperator):
-    """Operator computing the complex conjugate of its input."""
+    """Operator computing the complex conjugate of its input.
+
+    Parameters
+    ----------
+    domain: Domain, tuple of domains or DomainTuple
+        domain of the input field
+
+    """
     def __init__(self, domain):
         self._domain = DomainTuple.make(domain)
         self._capability = self._all_ops
@@ -57,7 +64,14 @@ class ConjugationOperator(EndomorphicOperator):
 
 
 class Realizer(EndomorphicOperator):
-    """Operator returning the real component of its input."""
+    """Operator returning the real component of its input.
+
+    Parameters
+    ----------
+    domain: Domain, tuple of domains or DomainTuple
+        domain of the input field
+
+    """
     def __init__(self, domain):
         self._domain = DomainTuple.make(domain)
         self._capability = self.TIMES | self.ADJOINT_TIMES
@@ -173,8 +187,8 @@ class GeometryRemover(LinearOperator):
     domain: Domain, tuple of Domain, or DomainTuple:
         the full input domain of the operator.
     space: int, optional
-        The index of the subdomain on which the operator should act
-        If None, it acts on all spaces
+        The index of the subdomain on which the operator should act. Default is None.
+        If None, it acts on all spaces.
 
     Notes
     -----

nifty5/operators/slope_operator.py

@@ -29,10 +29,10 @@ class SlopeOperator(LinearOperator):
 
     Slope and y-intercept of this line are the two parameters which are
     defined on an UnstructeredDomain (in this order) which is the domain of
-    the operator. Being a LogRGSpace each pixel has a well-defined coordinate
+    the operator. Being a LogRGSpace instance each pixel has a well-defined coordinate
     value.
 
-    y-intercept is defined to be the value at t_0 of the target.
+    The y-intercept is defined to be the value at t_0 of the target.
 
     Parameters
     ----------

nifty5/operators/sum_operator.py

@@ -26,7 +26,12 @@ from .linear_operator import LinearOperator
 
 
 class SumOperator(LinearOperator):
-    """Class representing sums of operators."""
+    """Class representing sums of operators.
+
+    Notes
+    -----
+    This operator has to be called using the `make` method.
+    """
 
     def __init__(self, ops, neg, dom, tgt, _callingfrommake=False):
         if not _callingfrommake:

nifty5/operators/symmetrizing_operator.py

@@ -23,7 +23,7 @@ from .endomorphic_operator import EndomorphicOperator
 
 
 class SymmetrizingOperator(EndomorphicOperator):
-    '''Subtracts the field axes-wise in reverse order from itself. The slice of
+    """Subtracts the field axes-wise in reverse order from itself. The slice of
     all elements with at least one index being zero is not touched.
 
     Parameters
@@ -33,7 +33,7 @@ class SymmetrizingOperator(EndomorphicOperator):
         :class:`LogRGSpace`.
     space : int
         Index of space in domain on which the operator shall act. Default is 0.
-    '''
+    """
     def __init__(self, domain, space=0):
         self._domain = DomainTuple.make(domain)
         self._capability = self.TIMES | self.ADJOINT_TIMES

nifty5/sugar.py

@@ -65,7 +65,7 @@ def get_signal_variance(spec, space):
     """
     Computes how much a field with a given power spectrum will vary in space
 
-    This is a small helper function that computes how the expected variance
+    This is a small helper function that computes the expected variance
     of a harmonically transformed sample of this power spectrum.
 
     Parameters
@@ -103,14 +103,14 @@ def power_analyze(field, spaces=None, binbounds=None,
     """Computes the power spectrum for a subspace of `field`.
 
     Creates a PowerSpace for the space addressed by `spaces` with the given
-    binning and computes the power spectrum as a Field over this
+    binning and computes the power spectrum as a :class:`Field` over this
     PowerSpace. This can only be done if the subspace to  be analyzed is a
     harmonic space. The resulting field has the same units as the square of the
     initial field.
 
     Parameters
     ----------
-    field : Field
+    field : :class:`Field`
         The field to be analyzed
     spaces : None or int or tuple of int, optional
         The indices of subdomains for which the power spectrum shall be
@@ -122,18 +122,18 @@ def power_analyze(field, spaces=None, binbounds=None,
         if binbounds is None : bins are inferred.
     keep_phase_information : bool, optional
         If False, return a real-valued result containing the power spectrum
-        of the input Field.
+        of `field`.
         If True, return a complex-valued result whose real component
-        contains the power spectrum computed from the real part of the
-        input Field, and whose imaginary component contains the power
-        spectrum computed from the imaginary part of the input Field.
+        contains the power spectrum computed from the real part of `field`,
+        and whose imaginary component contains the power
+        spectrum computed from the imaginary part of `field`.
         The absolute value of this result should be identical to the output
         of power_analyze with keep_phase_information=False.
         (default : False).
 
     Returns
     -------
-    Field
+    :class:`Field`
         The output object. Its domain is a PowerSpace and it contains
         the power spectrum of `field`.
     """
@@ -363,7 +363,7 @@ def makeOp(input):
         return DiagonalOperator(input)
     if isinstance(input, MultiField):
         return BlockDiagonalOperator(
-            input.domain, tuple(makeOp(val) for val in input.values()))
+            input.domain, input.to_dict())
     raise NotImplementedError