numpydoc build for gaussian.py

src/diffpy/srmise/peaks/gaussian.py

@@ -78,12 +78,19 @@ def estimate_parameters(self, r, y):
         """Estimate parameters for single peak from data provided.
 
         Parameters
-        r: (Numpy array) Data along r from which to estimate
-        y: (Numpy array) Data along y from which to estimate
-
-        Returns Numpy array of parameters in the default internal format.
-        Raises SrMiseEstimationError if parameters cannot be estimated for any
-        reason."""
+        ----------
+        r : array-like
+            Data along r from which to estimate
+        y : array-like
+            Data along y from which to estimate
+
+        Returns
+        -------
+        array-like
+            Numpy array of parameters in the default internal format.
+            Raises SrMiseEstimationError if parameters cannot be estimated for any
+            reason.
+        """
         if len(r) != len(y):
             emsg = "Arrays r, y must have equal length."
             raise SrMiseEstimationError(emsg)
@@ -154,9 +161,18 @@ def scale_at(self, pars, x, scale):
         SrMiseScalingError if the parameters cannot be scaled.
 
         Parameters
-        pars: (Array) Parameters corresponding to a single peak
-        x: (float) Position of the border
-        scale: (float > 0) Size of scaling at x."""
+        ----------
+        pars : array-like
+            Parameters corresponding to a single peak
+        x : float
+            Position of the border
+        scale : float
+            Size of scaling at x. Must be positive.
+
+        Returns
+        -------
+        tuple
+            mu, area, and sigma that are scaled."""
         if scale <= 0:
             emsg = "".join(["Cannot scale by ", str(scale), "."])
             raise SrMiseScalingError(emsg)
@@ -190,16 +206,36 @@ def scale_at(self, pars, x, scale):
         return tpars
 
     def _jacobianraw(self, pars, r, free):
-        """Return Jacobian of width-limited Gaussian.
-
-        pars: Sequence of parameters for a single width-limited Gaussian
-        pars[0]=peak position
-        pars[1]=effective width, up to fwhm=maxwidth as par[1] -> inf.
-              =tan(pi/2*fwhm/maxwidth)
-        pars[2]=multiplicative constant a, equivalent to peak area
-        r: sequence or scalar over which pars is evaluated
-        free: sequence of booleans which determines which derivatives are
-              needed.  True for evaluation, False for no evaluation.
+
+        """Compute the Jacobian of a width-limited Gaussian function.
+
+        This method calculates the partial derivatives of a Gaussian function
+        with respect to its parameters, considering a limiting width. The Gaussian's
+        width approaches its maximum (`fwhm`) as the effective width parameter
+        (`pars[1]`) tends to infinity.
+
+        Parameters
+        ----------
+        pars : array-like
+            Sequence of parameters defining a single width-limited Gaussian:
+            - pars[0]: Peak position.
+            - pars[1]: Effective width, which scales up to the full width at half maximum (fwhm) as
+            `pars[1]` approaches infinity. It is mathematically represented as `tan(pi/2 * fwhm / maxwidth)`.
+            - pars[2]: Multiplicative constant 'a', equivalent to the peak area.
+
+        r : array-like or scalar
+            The sequence or scalar over which the Gaussian parameters `pars` are evaluated.
+
+        free : array-like of bools
+            Determines which derivatives need to be computed. A `True` value indicates that the derivative
+            with respect to the corresponding parameter in `pars` should be calculated; `False` indicates no evaluation is needed.
+
+        Returns
+        -------
+        jacobian : ndarray
+            The Jacobian matrix, where each column corresponds to the derivative of the Gaussian function
+            with respect to one of the input parameters `pars`, evaluated at points `r`.
+            Only columns corresponding to `True` values in `free` are computed.
         """
         jacobian = [None, None, None]
         if (free is False).sum() == self.npars:
@@ -236,20 +272,29 @@ def _jacobianraw(self, pars, r, free):
         return jacobian
 
     def _transform_parametersraw(self, pars, in_format, out_format):
-        """Convert parameter values from in_format to out_format.
+        """Convert parameter values from one format to another.
 
-        Also restores parameters to a preferred range if it permits multiple
-        values that correspond to the same physical result.
+        This method also facilitates restoring parameters to a preferred range if the
+        target format allows for multiple representations of the same physical result.
 
         Parameters
-        pars: Sequence of parameters
-        in_format: A format defined for this class
-        out_format: A format defined for this class
-
-        Defined Formats
-        internal: [position, parameterized width-squared, area]
-        pwa: [position, full width at half maximum, area]
-        mu_sigma_area: [mu, sigma, area]
+        ----------
+        pars : array_like
+            The sequence of parameters in the `in_format`.
+        in_format : str, optional
+            The input format of the parameters. Supported formats are:
+            - 'internal': [position, parameterized width-squared, area]
+            - 'pwa': [position, full width at half maximum, area]
+            - 'mu_sigma_area': [mu, sigma, area]
+            Default is 'internal'.
+        out_format : str, optional
+            The desired output format of the parameters. Same options as `in_format`.
+            Default is 'pwa'.
+
+        Returns
+        -------
+        array_like
+            The transformed parameters in the `out_format`.
         """
         temp = np.array(pars)
 
@@ -301,14 +346,29 @@ def _transform_parametersraw(self, pars, in_format, out_format):
         return temp
 
     def _valueraw(self, pars, r):
-        """Return value of width-limited Gaussian for the given parameters and r values.
-
-        pars: Sequence of parameters for a single width-limited Gaussian
-        pars[0]=peak position
-        pars[1]=effective width, up to fwhm=maxwidth as par[1] -> inf.
-              =tan(pi/2*fwhm/maxwidth)
-        pars[2]=multiplicative constant a, equivalent to peak area
-        r: sequence or scalar over which pars is evaluated
+        """Compute the value of a width-limited Gaussian for the specified parameters at given radial distances.
+
+        This function calculates the value of a Gaussian distribution, where its effective width is constrained and
+        related to the full width at half maximum (FWHM). As `pars[1]` approaches infinity,
+        the effective width reaches `maxwidth`. The returned values represent the Gaussian's intensity
+        across the provided radial coordinates `r`.
+
+        Parameters
+        ----------
+        pars : array_like
+            A sequence of parameters defining the Gaussian shape:
+            - pars[0]: Peak position of the Gaussian.
+            - pars[1]: Effective width factor, approaching infinity implies the FWHM equals `maxwidth`.
+            It is related to the FWHM by `tan(pi/2*FWHM/maxwidth)`.
+            - pars[2]: Multiplicative constant 'a', equivalent to the peak area of the Gaussian when integrated.
+
+        r : array_like or float
+            Radial distances or a single value at which the Gaussian is to be evaluated.
+
+        Returns
+        -------
+        float
+            The value of a width-limited Gaussian for the specified parameters at given radial distances.
         """
         return (
             np.abs(pars[2])
@@ -322,7 +382,16 @@ def getmodule(self):
     # Other methods ####
 
     def max(self, pars):
-        """Return position and height of the peak maximum."""
+        """Return position and height of the peak maximum.
+        Parameters
+        ----------
+        pars : array_like
+            A sequence of parameters defining the Gaussian shape.
+
+        Returns
+        -------
+        array_like
+            The position and height of the peak maximum."""
         # TODO: Reconsider this behavior
         if len(pars) == 0:
             return None
@@ -342,7 +411,6 @@ def max(self, pars):
 
     import matplotlib.pyplot as plt
     from numpy.random import randn
-
     from diffpy.srmise.modelcluster import ModelCluster
     from diffpy.srmise.modelevaluators.aicc import AICc
     from diffpy.srmise.peaks.base import Peaks