Skip to content

Commit d55b946

Browse files
stevenhua0320stevenhua0320
authored
terminationripples.py numpydoc build (#92)
1 parent 03b18c1 commit d55b946

File tree

1 file changed

+145
-44
lines changed

1 file changed

+145
-44
lines changed

‎src/diffpy/srmise/peaks/terminationripples.py‎

Lines changed: 145 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -26,20 +26,26 @@ class TerminationRipples(PeakFunction):
2626
"""Methods for evaluation and parameter estimation of a peak function with termination ripples."""
2727

2828
def __init__(self, base, qmax, extension=4.0, supersample=5.0, Cache=None):
29-
"""Peak function which adds termination ripples to existing function.
29+
"""Peak function constructor which adds termination ripples to existing function.
3030
3131
Unlike other peak functions, TerminationRipples can only be evaluated
3232
over a uniform grid, or at a single value using an ad hoc uniform grid
3333
defined by qmax, extension, and supersample.
3434
3535
Parameters
36-
base: Instance of PeakFunction subclass.
37-
qmax: Cut-off frequency in reciprocal space.
38-
extension: How many multiples of 2pi/qmax to extend calculations in
39-
order to avoid edge effects.
40-
supersample: Number intervals over 2pi/qmax when a natural interval
41-
cannot be determined while extending calculations.
42-
Cache: A class (not instance) which implements caching of PeakFunction
36+
----------
37+
base : PeakFunction instance
38+
The PeakFunction instance subclass.
39+
qmax : float
40+
The cut-off frequency in reciprocal space.
41+
extension : float
42+
How many multiples of 2pi/qmax to extend calculations in
43+
order to avoid edge effects. Default is 4.0.
44+
supersample : float
45+
Number intervals over 2pi/qmax when a natural interval
46+
cannot be determined while extending calculations. Default is 5.0.
47+
Cache : class
48+
The class (not instance) which implements caching of PeakFunction
4349
evaluations."""
4450
parameterdict = base.parameterdict
4551
formats = base.parformats
@@ -66,12 +72,19 @@ def estimate_parameters(self, r, y):
6672
Uses estimation routine provided by base peak function.
6773
6874
Parameters
69-
r: (Numpy array) Data along r from which to estimate
70-
y: (Numpy array) Data along y from which to estimate
71-
72-
Returns Numpy array of parameters in the default internal format.
73-
Raises SrMiseEstimationError if parameters cannot be estimated for any
74-
reason."""
75+
----------
76+
r : array-like
77+
Data along r from which to estimate
78+
y : array-like
79+
Data along y from which to estimate
80+
81+
Returns
82+
-------
83+
array-like
84+
Numpy array of parameters in the default internal format.
85+
Raises SrMiseEstimationError if parameters cannot be estimated for any
86+
reason.
87+
"""
7588
return self.base.estimate_parameters(r, y)
7689

7790
# TODO: Can this be implemented sanely for termination ripples?
@@ -82,44 +95,91 @@ def scale_at(self, pars, x, scale):
8295
SrMiseScalingError if the parameters cannot be scaled.
8396
8497
Parameters
85-
pars: (Array) Parameters corresponding to a single peak
86-
x: (float) Position of the border
87-
scale: (float > 0) Size of scaling at x."""
98+
----------
99+
pars : array-like
100+
The parameters corresponding to a single peak
101+
x : float
102+
The position of the border
103+
scale : float
104+
The size of scaling at x. Must be positive.
105+
106+
Returns
107+
-------
108+
array-like
109+
The numpy array of scaled parameters.
110+
"""
88111
return self.base.scale_at(pars, x, scale)
89112

90113
def _jacobianraw(self, pars, r, free):
91114
"""Return Jacobian of base function with termination ripples.
92115
93116
Parameters
94-
pars: Sequence of parameters for a single peak
95-
r: sequence or scalar over which pars is evaluated
96-
free: sequence of booleans which determines which derivatives are
97-
needed. True for evaluation, False for no evaluation."""
117+
----------
118+
pars : array-like
119+
The sequence of parameters for a single peak
120+
r : array-like
121+
The sequence or scalar over which pars is evaluated
122+
free : array-like
123+
The sequence of booleans which determines which derivatives are
124+
needed. True for evaluation, False for no evaluation.
125+
126+
Returns
127+
-------
128+
array-like
129+
The Jacobian matrix of base function with termination ripples.
130+
"""
98131
return self.base._jacobianraw(pars, r, free)
99132

100133
def _transform_derivativesraw(self, pars, in_format, out_format):
101134
"""Return gradient matrix for the pars converted from in_format to out_format.
102135
103136
Parameters
104-
pars: Sequence of parameters
105-
in_format: A format defined for base peak function
106-
out_format: A format defined for base peak function"""
137+
----------
138+
pars : array-like
139+
The sequence of parameters
140+
in_format : str
141+
The format defined for base peak function
142+
out_format : str
143+
The format defined for base peak function
144+
145+
Returns
146+
-------
147+
ndarray
148+
The Jacobian matrix of base function with termination ripples with out_format.
149+
"""
107150
return self.base._transform_derivativesraw(pars, in_format, out_format)
108151

109152
def _transform_parametersraw(self, pars, in_format, out_format):
110153
"""Convert parameter values from in_format to out_format.
111154
112155
Parameters
113-
pars: Sequence of parameters
114-
in_format: A format defined for base peak function
115-
out_format: A format defined for base peak function"""
156+
----------
157+
pars : array-like
158+
The sequence of parameters
159+
in_format : str
160+
The format defined for base peak function
161+
out_format : str
162+
The format defined for base peak function
163+
164+
Returns
165+
-------
166+
array-like
167+
The sequence of parameter values with out_format.
168+
"""
116169
return self.base._transform_parametersraw(pars, in_format, out_format)
117170

118171
def _valueraw(self, pars, r):
119172
"""Return value of base peak function for the given parameters and r values.
120173
121-
pars: Sequence of parameters for a single peak
122-
r: sequence or scalar over which pars is evaluated"""
174+
pars : array-like
175+
The sequence of parameters for a single peak
176+
r : array-like or float
177+
The sequence or scalar over which pars is evaluated
178+
179+
Returns
180+
-------
181+
float
182+
The value of base peak function for the given parameters and r."""
123183
return self.base._valueraw(pars, r)
124184

125185
# Overridden PeakFunction functions ####
@@ -130,12 +190,22 @@ def _valueraw(self, pars, r):
130190
def jacobian(self, peak, r, rng=None):
131191
"""Calculate (rippled) jacobian, possibly restricted by range.
132192
133-
peak: The Peak to be evaluated
134-
r: sequence or scalar over which peak is evaluated
135-
rng: Optional slice object restricts which r-values are evaluated.
136-
The output has same length as r, but unevaluated objects have
137-
a default value of 0. If caching is enabled these may be
138-
previously calculated values instead."""
193+
Parameters
194+
----------
195+
peak : PeakFunction instance
196+
The Peak to be evaluated
197+
r : array-like
198+
The sequence or scalar over which peak is evaluated
199+
rng : slice object
200+
Optional slice object restricts which r-values are evaluated.
201+
The output has same length as r, but unevaluated objects have
202+
a default value of 0. If caching is enabled these may be
203+
previously calculated values instead. Default is None
204+
205+
Returns
206+
-------
207+
jac : array-like
208+
The Jacobian of base function with termination ripples."""
139209
if self is not peak._owner:
140210
raise ValueError(
141211
"Argument 'peak' must be evaluated by the "
@@ -180,12 +250,22 @@ def value(self, peak, r, rng=None):
180250
to minimize the impact of edge-effects from introducing termination
181251
ripples into an existing peak function.
182252
183-
peak: The Peak to be evaluated
184-
r: sequence or scalar over which peak is evaluated
185-
rng: Optional slice object restricts which r-values are evaluated.
186-
The output has same length as r, but unevaluated objects have
187-
a default value of 0. If caching is enabled these may be
188-
previously calculated values instead.
253+
Parameters
254+
----------
255+
peak : Peak instance
256+
The Peak to be evaluated
257+
r : array-like
258+
The sequence or scalar over which peak is evaluated
259+
rng : slice object
260+
Optional slice object restricts which r-values are evaluated.
261+
The output has same length as r, but unevaluated objects have
262+
a default value of 0. If caching is enabled these may be
263+
previously calculated values instead. Default is None.
264+
265+
Returns
266+
-------
267+
output : array-like
268+
The (rippled) value of peak, possibly restricted by range.
189269
"""
190270
if self is not peak._owner:
191271
raise ValueError(
@@ -245,8 +325,17 @@ def cut_freq(self, sequence, delta):
245325
function sin(2*pi*r/qmax)/r.
246326
247327
Parameters
248-
sequence: (numpy array) The sequence to alter.
249-
delta: The spacing between elements in sequence."""
328+
----------
329+
sequence : array-like
330+
The sequence to alter.
331+
delta : int
332+
The spacing between elements in sequence.
333+
334+
Returns
335+
-------
336+
array-like
337+
The sequence with high-frequency components removed.
338+
"""
250339
padlen = int(2 ** np.ceil(np.log2(len(sequence))))
251340
padseq = fp.fft(sequence, padlen)
252341
dq = 2 * np.pi / ((padlen - 1) * delta)
@@ -260,7 +349,19 @@ def cut_freq(self, sequence, delta):
260349
return np.real(padseq[0 : len(sequence)])
261350

262351
def extend_grid(self, r, dr):
263-
"""Return (extended r, slice giving original range)."""
352+
"""Return (extended r, slice giving original range).
353+
354+
Parameters
355+
----------
356+
r : array-like or float
357+
The sequence or scalar over which peak is evaluated
358+
dr : array-like or float
359+
The uncertainties over which peak is evaluated
360+
361+
Returns
362+
-------
363+
tuple
364+
The extended r, slice giving original range."""
264365
ext = self.extension * 2 * np.pi / self.qmax
265366
left_ext = np.arange(r[0] - dr, max(0.0, r[0] - ext - dr), -dr)[::-1]
266367
right_ext = np.arange(r[-1] + dr, r[-1] + ext + dr, dr)

0 commit comments

Comments
 (0)