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):