Merge branch 'sebastian_review' into 'NIFTy_5'

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

See merge request ift/nifty-dev!188

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

@@ -27,7 +27,8 @@ class BlockDiagonalOperator(EndomorphicOperator):
     domain : MultiDomain
         Domain and target of the operator.
     operators : dict
-        Dictionary with subdomain names as keys and LinearOperators as items.
+        Dictionary with subdomain names as keys and :class:`LinearOperator`s
+        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
+        Positions at which to interpolate, shape (dim, ndata),
 
     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(metaclass=NiftyMeta):
         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))`.
+
+    Note
+    ----
+    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,7 +103,7 @@ 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.
@@ -122,11 +122,11 @@ 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).