<p>
Multivariate power spectral density is performed by the Welch's averaged, modified periodogram method.
<tt>ao/cpsd</tt> estimates the cross-spectral density of time-series
signals, included in the input <tt>ao</tt>s. Data are windowed prior to the estimation of the spectra, by multiplying
it with a <a href="specwin.html">spectral window object</a>, and can be detrended by polinomial of time in order to reduce the impact
of the border discontinuities. The window length is adjustable to shorter lenghts to reduce the spectral
density uncertainties, and the percentage of subsequent window overlap can be adjusted as well.
<br>
<br>
<b>Syntaxis</b>
</p>
<div class="fragment"><pre>
    b = cpsd(a1,a2,pl)
  </pre>
</div>
<p>
  <tt>a1</tt> and <tt>a2</tt> are the 2 <tt>ao</tt>s containing the input time series to be evaluated; <tt>b</tt> is the output object.
  The parameter list <tt>pl</tt> includes the following parameters:</p>
 <ul>
  <li> <tt>'Nfft'</tt> - number of samples in each fft [default: length of input data]
                         A string value containing the variable 'fs' can
                         also be used, e.g., plist('Nfft', '2*fs') </li>
  <li> <tt>'Win'</tt> - the window to be applied to the data to remove the
                        discontinuities at edges of segments. [default: taken from user prefs]
                        Only the design parameters of the window object are used. Enter either:
			 <ul>
			   <li>a specwin window object OR</li>
			   <li>a string value containing the window name e.g., plist('Win', 'Kaiser', 'psll', 200)</li></ul>
</li>
  <li> <tt>'Olap'</tt> - segment percent overlap [default: -1, (taken from window function)] </li>
  <li> <tt>'Order'</tt> - order of segment detrending <ul>
      <li>      -1 - no detrending  </li>
      <li>       0 - subtract mean [default] </li>
      <li>       1 - subtract linear fit </li>
      <li>       N - subtract fit of polynomial, order N  </li> </ul> </li>
      <li><tt>'Navs'</tt>  - number of averages. If set, and if Nfft was set to 0 or -1, the number of points for each window will be calculated to match the request. [default: -1, not set] </li> 
</ul>
  <p>
    The length of the window is set by the value of the parameter <tt>'Nfft'</tt>, so that the window
    is actually rebuilt using only the key features of the window, i.e. the name and, for Keiser windows, the PSLL.
  </p>
  <p>As an alternative, the user can input, as a value for the <tt>'Win'</tt> key, a string corresponding to the name of the window. In the case of Kaiser window, it's necessary to specify the additional parameter <tt>'psll'</tt>.</p>
<p>As an alternative to setting the number of points <tt>'Nfft'</tt> in each window, it's possible to ask for a given number of CPSD estimates by setting the  <tt>'Navs'</tt> parameter, and the algorithm takes care of calculating the correct window length, according to the amount of overlap between subsequent segments.</p>
  <p>
    <table cellspacing="0" class="note" summary="Note" cellpadding="5" border="1">
      <tr width="90%">
        <td>
          If the user doesn't specify the value of a given parameter, the default value is used.
        </td>
      </tr>
    </table>
  </p>

  <p>
    The function makes CPSD estimates between the 2 input <tt>ao</tt>s. The input argument
    list must contain 2 analysis objects, and the output will contain the CPSD estimate.
    If passing two identical objects <tt>ai</tt>, the output will be equivalent to the output of <tt>psd(ai)</tt>.
  </p>
  </pre> </div>
</p>
<p>
  <b>Example</b>
</p>
<p>
  Evaluation of the CPSD of two time-series represented by: a low frequency sinewave signal superimposed to
  white noise, and a low frequency sinewave signal at the same frequency, phase shifted and with different
  amplitude, superimposed to white noise.
</p>
<div class="fragment"><pre>
    nsecs = 1000;
    x = ao(plist(<span class="string">'waveform'</span>,<span class="string">'sine wave'</span>,<span class="string">'f'</span>,0.1,<span class="string">'A'</span>,1,<span class="string">'nsecs'</span>,nsecs,<span class="string">'fs'</span>,10)) + ...
        ao(plist(<span class="string">'waveform'</span>,<span class="string">'noise'</span>,<span class="string">'type'</span>,<span class="string">'normal'</span>,<span class="string">'nsecs'</span>,nsecs,<span class="string">'fs'</span>,10));
    x.setYunits(<span class="string">'m'</span>);
    y = ao(plist(<span class="string">'waveform'</span>,<span class="string">'sine wave'</span>,<span class="string">'f</span>',0.1,<span class="string">'A'</span>,2,<span class="string">'nsecs'</span>,nsecs,<span class="string">'fs'</span>,10,<span class="string">'phi'</span>,90)) + ...
        4*ao(plist(<span class="string">'waveform'</span>,<span class="string">'noise'</span>,<span class="string">'type'</span>,<span class="string">'normal'</span>,<span class="string">'nsecs'</span>,nsecs,<span class="string">'fs'</span>,10));
    y.setYunits(<span class="string">'V'</span>);
    z = cpsd(x,y,plist(<span class="string">'nfft'</span>,1000));
    iplot(z);
  </pre>
</div>

<img src="images/cpsd_2.png" alt="" border="3">
<br>