corrected the docstrings to respect inhereted docstrings and added docsgtrings...

corrected the docstrings to respect inhereted docstrings and added docsgtrings for all methods where they were missing

nifty/domain_object.py

@@ -131,11 +131,43 @@ class DomainObject(Versionable, Loggable, object):
             "There is no generic weight-method for DomainObject.")
 
     def pre_cast(self, x, axes=None):
-        # FIXME This does nothing and non of the children override this. Why does this exist?!
+        """Casting operations that are done before fields are initialized.
+        Parameters
+        ----------
+        x : {array-like, castable}
+            an array-like object or anything that can be cast to arrays. Examples are Floating Point Numbers 
+            (which will get cast to a constant array) and functions (which will get evaluated on the field positions)
+        axes : {int, tuple}, *optional*
+            Specifies the axes of x which represent this domain.
+            (default: None).
+            If axes==None:
+                Assumes the axes to be the fields first axes
+        Returns
+        -------
+        {array-like, castable} : Processed input where casting that needs Space-specific knowledge (for example where points are) was performed.
+        Currently always returns x unless for a power spectrum is given to a PowerSpace, where this spectrum is evaluated at the power indices.
+        """
         return x
 
     def post_cast(self, x, axes=None):
-        # FIXME This does nothing and non of the children override this. Why does this exist?!
+        """Casting operations that are done after fields are initialized.
+        Parameters
+        ----------
+        x : {array-like, castable}
+            an array-like object or anything that can be cast to arrays.
+        axes : {int, tuple}, *optional*
+            Specifies the axes of x which represent this domain.
+            (default: None).
+            If axes==None:
+                Assumes the axes to be the fields first axes
+        See Also
+        --------
+        pre_cast : Casting operations that are done before fields are initialized.
+        Returns
+        -------
+        array-like : Processed input where casting that needs Space-specific knowledge (for example where points are) was performed.
+        Currently always returns x unchanged.
+        """
         return x
 
     # ---Serialization---

nifty/spaces/gl_space/gl_space.py

@@ -98,12 +98,6 @@ class GLSpace(Space):
 
     @property
     def harmonic(self):
-        """True if this can be regarded as a harmonic space.
-        Returns
-        -------
-        bool : False
-            Always returns False as the GLSpace cannot be regarded as harmonic space.
-        """
         return False
 
     @property
@@ -123,39 +117,6 @@ class GLSpace(Space):
                               nlon=self.nlon)
 
     def weight(self, x, power=1, axes=None, inplace=False):
-        """ Weights a field living on this space with a specified amount of volume-weights.
-
-        Weights hereby refer to integration weights, as they appear in discretized integrals.
-        Per default, this function mutliplies each bin of the field x by its volume, which lets
-        it behave like a density (top form). However, different powers of the volume can be applied
-        with the power parameter. If only certain axes are specified via the axes parameter,
-        the weights are only applied with respect to these dimensions, yielding an object that
-        behaves like a lower degree form.
-        Parameters
-        ----------
-        x : Field
-            A field with this space as domain to be weighted.
-        power : int, *optional*
-            The power to which the volume-weight is raised.
-            (default: 1).
-        axes : {int, tuple}, *optional*
-            Specifies for which axes the weights should be applied.
-            (default: None).
-            If axes==None:
-                weighting is applied with respect to all axes
-        inplace : bool, *optional*
-            If this is True, the weighting is done on the values of x,
-            if it is False, x is not modified and this method returns a 
-            weighted copy of x
-            (default: False).
-
-        Returns
-        -------
-        Field
-            A weighted version of x, with volume-weights raised to power.
-            
-        """
-        
         nlon = self.nlon
         nlat = self.nlat
         vol = pyHealpix.GL_weights(nlat, nlon) ** power
@@ -201,10 +162,20 @@ class GLSpace(Space):
 
     @property
     def nlat(self):
+        """Number of latitudinal bins.
+        Returns
+        -------
+        int : Number of latitudinal bins (or rings) that are used in the pixelization
+        """
         return self._nlat
 
     @property
     def nlon(self):
+        """Number of longditudinal bins.
+        Returns
+        -------
+        int : Number of longditudinal bins that are used in the pixelization
+        """
         return self._nlon
 
     def _parse_nlat(self, nlat):

nifty/spaces/hp_space/hp_space.py

@@ -102,42 +102,9 @@ class HPSpace(Space):
         return 4 * np.pi
 
     def copy(self):
-        """Returns a copied version of this HPSpace.
-			
-        Returns
-        -------
-		HPSpace : A copy of this object.
-        """
         return self.__class__(nside=self.nside)
 
     def weight(self, x, power=1, axes=None, inplace=False):
-        """ Weights a field living on this space with a specified amount of volume-weights.
-
-		Weights hereby refer to integration weights, as they appear in discretized integrals.
-		Per default, this function mutliplies each bin of the field x by its volume, which lets
-		it behave like a density (top form). However, different powers of the volume can be applied
-		with the power parameter.
-        Parameters
-        ----------
-        x : Field
-            A field with this space as domain to be weighted.
-        power : int, *optional*
-            The power to which the volume-weight is raised.
-            (default: 1).
-        axes : {int, tuple}, *optional*
-            This should not be used. It does nothing.
-        inplace : bool, *optional*
-            If this is True, the weighting is done on the values of x,
-			if it is False, x is not modified and this method returns a 
-			weighted copy of x
-            (default: False).
-
-        Returns
-        -------
-		Field
-			A weighted version of x, with volume-weights raised to power.
-            
-        """    
 
         weight = ((4 * np.pi) / (12 * self.nside**2))**power
 
@@ -150,29 +117,20 @@ class HPSpace(Space):
         return result_x
 
     def get_distance_array(self, distribution_strategy):
-        """This should not be used, it just raises an error when called.
-        
-        Raises
-        ------
-        NotImplementedError
-            Always when called.
-        """
         raise NotImplementedError
 
     def get_fft_smoothing_kernel_function(self, sigma):
-        """This should not be used, it just raises an error when called.
-        
-        Raises
-        ------
-        NotImplementedError
-            Always when called.
-        """
         raise NotImplementedError
 
     # ---Added properties and methods---
 
     @property
     def nside(self):
+        """Returns the nside of the corresponding HEALPix pixelization.
+        Returns
+        -------
+        int : the nside of the corresponding HEALPix pixelization. The total number of pixels is 12*nside**2
+        """
         return self._nside
 
     def _parse_nside(self, nside):

nifty/spaces/lm_space/lm_space.py

@@ -124,65 +124,15 @@ class LMSpace(Space):
         return np.float64(self.dim)
 
     def copy(self):
-        """Returns a copied version of this LMSpace.
-			
-        Returns
-        -------
-		LMSpace : A copy of this object.
-        """
         return self.__class__(lmax=self.lmax)
 
     def weight(self, x, power=1, axes=None, inplace=False):
-        """ Weights a field living on this space with a specified amount of volume-weights.
-
-		Weights hereby refer to integration weights, as they appear in discretized integrals.
-		Per default, this function mutliplies each bin of the field x by its volume, which lets
-		it behave like a density (top form). All volume-weights are 1, thus nothing happens.
-        Parameters
-        ----------
-        x : Field
-            A field with this space as domain to be weighted.
-        power : int, *optional*
-            The power to which the volume-weight is raised. It does nothing.
-            (default: 1). 
-        axes : {int, tuple}, *optional*
-            This should not be used. It does nothing.
-        inplace : bool, *optional*
-            If this is True, the weighting is done on the values of x,
-			if it is False, x is not modified and this method returns a 
-			weighted copy of x
-            (default: False).
-
-        Returns
-        -------
-		Field
-			x or a copy of x.
-            
-        """ 
         if inplace:
             return x
         else:
             return x.copy()
 
     def get_distance_array(self, distribution_strategy):
-     """Returns the distance of the bins to zero.
-        
-        Calculates an 2-dimensional array with its entries being the
-        lengths of the k-vectors from the zero point of the grid.
-
-        Parameters
-        ----------
-        distribution_strategy : 
-        
-        Returns
-        -------
-        nkdict : distributed_data_object
-        
-        Raises
-        ------
-        ValueError
-            The distribution_strategy is neither slicing nor not.
-        """
         dists = arange(start=0, stop=self.shape[0],
                        distribution_strategy=distribution_strategy)
 
@@ -208,10 +158,24 @@ class LMSpace(Space):
 
     @property
     def lmax(self):
+        """Returns the maximal :math:`l`-value of the spherical harmonics being used.
+        Returns
+        -------
+        int : maximal :math:`l` value of any spherical harmonic :math:`Y_{lm}` that is represented in this Space.
+        """
         return self._lmax
 
     @property
     def mmax(self):
+        """Returns the maximal :math:`m`-value of the spherical harmonics being used.
+        See Also
+        --------
+        lmax : Returns the maximal :math:`l`-value of the spherical harmonics being used.
+        Returns
+        -------
+        int : maximal :math:`m` value of any spherical harmonic :math:`Y_{lm}` that is represented in this Space.
+        As :math:`m` goes from :math:`-l` to :math:`l` for every :math:`l` this just returns the same as lmax.
+        """
         return self._lmax
 
     def _parse_lmax(self, lmax):

nifty/spaces/rg_space/rg_space.py

@@ -101,24 +101,6 @@ class RGSpace(Space):
 
     def hermitian_decomposition(self, x, axes=None,
                                 preserve_gaussian_variance=False):
-        """Separates the hermitian and antihermitian part of a field.
-        
-        This is a function which is called by the field in order to separate itself for 
-        each of its domains. 
-        
-        Parameters
-        ----------
-        x: Field
-            Field to be decomposed.
-        axes: {int, tuple}, *optional*
-            Specifies which indices of the field belongs to this RGSpace. If None, it 
-            takes the first dimensions of the field.
-            (default: None)
-        preserve_gaussian_variance: bool, *optional*
-            
-            (default: False)
-        
-        """
         # compute the hermitian part
         flipped_x = self._hermitianize_inverter(x, axes=axes)
         flipped_x = flipped_x.conjugate()
@@ -208,50 +190,12 @@ class RGSpace(Space):
         return self.dim * reduce(lambda x, y: x*y, self.distances)
 
     def copy(self):
-        """Returns a copied version of this RGSpace.
-			
-        Returns
-        -------
-		RGSpace : A copy of this object.
-        """
         return self.__class__(shape=self.shape,
                               zerocenter=self.zerocenter,
                               distances=self.distances,
                               harmonic=self.harmonic)
 
     def weight(self, x, power=1, axes=None, inplace=False):
-        """ Weights a field living on this space with a specified amount of volume-weights.
-
-		Weights hereby refer to integration weights, as they appear in discretized integrals.
-		Per default, this function mutliplies each bin of the field x by its volume, which lets
-		it behave like a density (top form). However, different powers of the volume can be applied
-		with the power parameter. If only certain axes are specified via the axes parameter,
-		the weights are only applied with respect to these dimensions, yielding an object that
-		behaves like a lower degree form.
-        Parameters
-        ----------
-        x : Field
-            A field with this space as domain to be weighted.
-        power : int, *optional*
-            The power to which the volume-weight is raised.
-            (default: 1).
-        axes : {int, tuple}, *optional*
-            Specifies for which axes the weights should be applied.
-            (default: None).
-            If axes==None:
-                weighting is applied with respect to all axes
-        inplace : bool, *optional*
-            If this is True, the weighting is done on the values of x,
-			if it is False, x is not modified and this method returns a 
-			weighted copy of x
-            (default: False).
-
-        Returns
-        -------
-		Field
-			A weighted version of x, with volume-weights raised to power.
-            
-        """
         weight = reduce(lambda x, y: x*y, self.distances)**power
         if inplace:
             x *= weight
@@ -261,26 +205,6 @@ class RGSpace(Space):
         return result_x
 
     def get_distance_array(self, distribution_strategy):
-        """Returns the distance of the bins to zero.
-        
-        Calculates an n-dimensional array with its entries being the
-        lengths of the k-vectors from the zero point of the grid.
-        MR FIXME: Since this is about k-vectors, it might make sense to
-        throw NotImplementedError if harmonic==False.
-
-        Parameters
-        ----------
-        None : All information is taken from the parent object.
-
-        Returns
-        -------
-        nkdict : distributed_data_object
-        
-        Raises
-        ------
-        ValueError
-            The distribution_strategy is neither slicing nor not.
-        """
         shape = self.shape
         # prepare the distributed_data_object
         nkdict = distributed_data_object(
@@ -336,10 +260,23 @@ class RGSpace(Space):
 
     @property
     def distances(self):
+        """Returns the distance of gridpoints along each axis
+        Returns 
+        -------
+        array-like : An array of positive floating point numbers with the 
+        n-th entry giving the distances of grid points along the n-th dimension.
+        """
         return self._distances
 
     @property
     def zerocenter(self):
+        """Returns True if grid points lie symmetrically around zero
+        Returns
+        -------
+        bool : True if the grid points are centered around the 0 grid point. This option
+        makes most sense for harmonic space (where the zero-mode plays a special role) 
+        but may be used for position space, too.
+        """
         return self._zerocenter
 
     def _parse_shape(self, shape):

nifty/spaces/space/space.py

@@ -160,6 +160,16 @@ class Space(DomainObject):
 
     @abc.abstractproperty
     def harmonic(self):
+        """Returns True if this Space can be regarded as a harmonic space.
+        
+        Returns
+        -------
+        bool : True if can be regarded as a harmonic space to another space. False otherwise
+        Raises
+        ------
+        NotImplementedError : If it is called for an abstract class, all non-abstract child-classes should
+        implement this.        
+        """
         raise NotImplementedError
 
     @abc.abstractproperty
@@ -247,7 +257,7 @@ class Space(DomainObject):
             Specifies the axes of x which represent this domain.
             (default: None).
             If axes==None:
-                weighting is applied with respect to all axes
+                Assumes the axes to be the fields first axes
         preserve_gaussian_variance : bool *optional*
             FIXME: figure out what this does
         Returns