diff --git a/src/diffpy/srmise/peaks/gaussianoverr.py b/src/diffpy/srmise/peaks/gaussianoverr.py index 8b125a9..2cf9d65 100644 --- a/src/diffpy/srmise/peaks/gaussianoverr.py +++ b/src/diffpy/srmise/peaks/gaussianoverr.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,19 @@ 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 + ------- + array-like + The sequence of scaled parameters. + """ if scale <= 0: emsg = "".join(["Cannot scale by ", str(scale), "."]) raise SrMiseScalingError(emsg) @@ -204,19 +221,37 @@ def scale_at(self, pars, x, scale): return tpars def _jacobianraw(self, pars, r, free): - """Return Jacobian of width-limited Gaussian/r. - - 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/r function. + + This method calculates the partial derivatives of a Gaussian/r function + with respect to its parameters, considering a limiting width. The Gaussian/r's + width approaches its maximum FWHM (maxwidth) 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=maxwidth) 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/r 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: + if np.sum(np.logical_not(free)) == self.npars: return jacobian # Optimization @@ -304,18 +339,28 @@ def _transform_derivativesraw(self, pars, in_format, out_format): def _transform_parametersraw(self, pars, in_format, out_format): """Convert parameter values from in_format to out_format. - Also restores parameters to a preferred range if it permits multiple - values that correspond to the same physical result. + This method convert parameter values from one format to another and optionally restore + them to a preferred range if the target format supports multiple values + representing 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 + 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) @@ -367,14 +412,27 @@ def _transform_parametersraw(self, pars, in_format, out_format): return temp def _valueraw(self, pars, r): - """Return value of width-limited Gaussian/r 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/r for the specified parameters at given radial distances. + + This function calculates the value of a Gaussian/r distribution, + where its effective width is constrained and related to the maxwidth. As `pars[1]` approaches infinity, + the effective width reaches `FWHM` (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]) @@ -388,7 +446,17 @@ 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 + The sequence of parameters defining the Gaussian shape. + + Returns + ------- + array-like + The sequence of position and height of the peak maximum.""" # TODO: Reconsider this behavior if len(pars) == 0: return None