DOC: Filter docstring additions #298

Merged
merged 8 commits into from Sep 18, 2012

Conversation

Projects
None yet
3 participants
Contributor

endolith commented Aug 28, 2012

  • add parameters and returns to all matlab-style filter docstrings
  • fixed default bandpass mistake in butter()
  • missed some while changing analog to boolean
  • remove "lowpass" from descriptions since they all do all types (iirfilter() is actually bandpass by default)
  • clarify units (dB, rad/second vs rad/sample)

Please double-check the accuracy of these, I made a mistake the last time

@rgommers rgommers and 1 other commented on an outdated diff Sep 8, 2012

scipy/signal/filter_design.py
@@ -642,17 +642,18 @@ def butter(N, Wn, btype='low', analog=False, output='ba'):
N : int
The order of the filter.
Wn : array_like
- A scalar or length-2 sequence giving the critical frequencies.
+ A scalar or length-2 sequence giving the critical frequencies,
+ normalized from 0 to 1, where 1 is the Nyquist frequency.
@rgommers

rgommers Sep 8, 2012

Owner

This normalization only seems to be done when analog=True, right?

@endolith

endolith Sep 9, 2012

Contributor

Oh, I think you're right, but when analog=False. I will read more to make sure and update it.

@endolith

endolith Sep 10, 2012

Contributor

Wordy, but more clear:

    For digital filters, Wn is normalized from 0 to 1, where 1 is the 
    Nyquist frequency, pi radians / sample.  (In other words, Wn is in 
    half-cycles / sample.)
    For analog filters, Wn is in radians / second.

Good?

@rgommers

rgommers Sep 11, 2012

Owner

Sounds good to me.

@endolith

endolith Sep 11, 2012

Contributor

I added it and changed all the existing docstrings too

Owner

rgommers commented Sep 8, 2012

Looks good to me.

@WarrenWeckesser WarrenWeckesser commented on an outdated diff Sep 16, 2012

scipy/signal/filter_design.py
rs : float, optional
- For chebyshev and elliptic filters provides the minimum attenuation in
- the stop band.
- btype : str, optional
- The type of filter (lowpass, highpass, bandpass, bandstop).
- Default is bandpass.
+ For chebyshev and elliptic filters, provides the minimum attenuation
@WarrenWeckesser

WarrenWeckesser Sep 16, 2012

Member

Capitalize "Chebyshev"--this is consistent with the comment immediately just abve this one.

@WarrenWeckesser WarrenWeckesser and 1 other commented on an outdated diff Sep 16, 2012

scipy/signal/filter_design.py
rs : float, optional
- For chebyshev and elliptic filters provides the minimum attenuation in
- the stop band.
- btype : str, optional
- The type of filter (lowpass, highpass, bandpass, bandstop).
- Default is bandpass.
+ For chebyshev and elliptic filters, provides the minimum attenuation
+ in the stop band. (dB)
+ btype : {'bandpass', 'lowpass', 'highpass', 'bandstop'}, optional
+ The type of filter. Default is bandpass.
@WarrenWeckesser

WarrenWeckesser Sep 16, 2012

Member

Default is 'bandpass'. (Be explicit that it is the string value.)

@endolith

endolith Sep 16, 2012

Contributor

Oh, ok.

@WarrenWeckesser WarrenWeckesser and 1 other commented on an outdated diff Sep 16, 2012

scipy/signal/filter_design.py
@@ -643,20 +652,23 @@ def butter(N, Wn, btype='low', analog=False, output='ba'):
The order of the filter.
Wn : array_like
A scalar or length-2 sequence giving the critical frequencies.
- btype : str, optional
- The type of filter (lowpass, highpass, bandpass, bandstop).
- Default is bandpass.
- analog : int, optional
- Non-zero to return an analog filter, otherwise a digital filter is
+ For digital filters, `Wn` is normalized from 0 to 1, where 1 is the
+ Nyquist frequency, pi radians / sample. (`Wn` is thus in
+ half-cycles / sample.)
+ For analog filters, `Wn` is in radians / second.
+ btype : {'lowpass', 'highpass', 'bandpass', 'bandstop'}, optional
+ The type of filter. Default is lowpass.
@WarrenWeckesser

WarrenWeckesser Sep 16, 2012

Member

Default is 'lowpass'.

@endolith

endolith Sep 16, 2012

Contributor

Yes, iirfilter and butter have different defaults

@WarrenWeckesser WarrenWeckesser pushed a commit that referenced this pull request Sep 18, 2012

Warren Weckesser Merge pull request #298 from endolith/patch-7
DOC: Filter docstring additions
6981d8b

@WarrenWeckesser WarrenWeckesser merged commit 6981d8b into scipy:master Sep 18, 2012

Member

WarrenWeckesser commented Sep 18, 2012

Thanks, this is great work!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment