'Plot the power spectral density.
Call signature::
psd(x, NFFT=256, Fs=2, Fc=0, detrend=mlab.detrend_none,
window=mlab.window_hanning, noverlap=0, pad_to=None,
sides=\'default\', scale_by_freq=None, return_line=None, **kwargs)
The power spectral density :math:`P_{xx}` by Welch\'s average
periodogram method.  The vector *x* is divided into *NFFT* length
segments.  Each segment is detrended by function *detrend* and
windowed by function *window*.  *noverlap* gives the length of
the overlap between segments.  The :math:`|\mathrm{fft}(i)|^2`
of each segment :math:`i` are averaged to compute :math:`P_{xx}`,
with a scaling to correct for power loss due to windowing.
If len(*x*) < *NFFT*, it will be zero padded to *NFFT*.
Parameters
x : 1-D array or sequence
Array or sequence containing the data
%(Spectral)s
%(PSD)s
noverlap : integer
The number of points of overlap between segments.
The default value is 0 (no overlap).
Fc : integer
The center frequency of *x* (defaults to 0), which offsets
the x extents of the plot to reflect the frequency range used
when a signal is acquired and then filtered and downsampled to
baseband.
return_line : bool
Whether to include the line object plotted in the returned values.
Default is False.
Returns
Pxx : 1-D array
The values for the power spectrum `P_{xx}` before scaling
(real valued)
freqs : 1-D array
The frequencies corresponding to the elements in *Pxx*
line : a :class:`~matplotlib.lines.Line2D` instance
The line created by this function.
Only returned if *return_line* is True.
Other Parameters
**kwargs :
Keyword arguments control the :class:`~matplotlib.lines.Line2D`
properties:
%(Line2D)s
Notes
For plotting, the power is plotted as
:math:`10\log_{10}(P_{xx})` for decibels, though *Pxx* itself
is returned.
References
Bendat & Piersol -- Random Data: Analysis and Measurement Procedures,
John Wiley & Sons (1986)
See Also
:func:`specgram`
:func:`specgram` differs in the default overlap; in not returning
the mean of the segment periodograms; in returning the times of the
segments; and in plotting a colormap instead of a line.
:func:`magnitude_spectrum`
:func:`magnitude_spectrum` plots the magnitude spectrum.
:func:`csd`
:func:`csd` plots the spectral density between two signals.'

@_preprocess_data(replace_names=[u'x'], label_namer=None)
@docstring.dedent_interpd
def psd(self, x, NFFT=None, Fs=None, Fc=None, detrend=None, window=None, noverlap=None, pad_to=None, sides=None, scale_by_freq=None, return_line=None, **kwargs):

    if (not self._hold):
        self.cla()
    if (Fc is None):
        Fc = 0
    (pxx, freqs) = mlab.psd(x=x, NFFT=NFFT, Fs=Fs, detrend=detrend, window=window, noverlap=noverlap, pad_to=pad_to, sides=sides, scale_by_freq=scale_by_freq)
    freqs += Fc
    if (scale_by_freq in (None, True)):
        psd_units = u'dB/Hz'
    else:
        psd_units = u'dB'
    line = self.plot(freqs, (10 * np.log10(pxx)), **kwargs)
    self.set_xlabel(u'Frequency')
    self.set_ylabel((u'Power    Spectral    Density    (%s)' % psd_units))
    self.grid(True)
    (vmin, vmax) = self.viewLim.intervaly
    intv = (vmax - vmin)
    logi = int(np.log10(intv))
    if (logi == 0):
        logi = 0.1
    step = (10 * logi)
    ticks = np.arange(math.floor(vmin), (math.ceil(vmax) + 1), step)
    self.set_yticks(ticks)
    if ((return_line is None) or (not return_line)):
        return (pxx, freqs)
    else:
        return (pxx, freqs, line)
