1.1.2.1. Spectral analysis — altimetry tools 0 documentation

### Navigation

- index
- modules |
- next |
- previous |
- altimetry tools 0 documentation »
- 1. Description of the modules »
- 1.1.2. altimetry.tools Module »

# 1.1.2.1. Spectral analysis

The `altimetry.tools.spectrum` module contains tools dedicated to spectral analysis.

## 1.1.2.1.1. About spectral analysis

Spectral analysis of along-track data is a common thing. There are 2 main steps when computing a spectrum:

> - preprocess the data

>   It consists in detecting gaps, interpolating over short gaps and rejecting longer gaps, subsampling the data into subsegments of valid data of a given length.

>   This step is performed using `altimetry.tools.spectrum.preprocess()`

> - compute the spectrum

>   This step is made through a transform of the signal to the spectral domain (eg. FFT). Then frequency, energy and power spectral densities are computed and averaged. It is also possible to use spectral tapers to lower the noise of the spectrum.

>   > This step is performed using `altimetry.tools.spectrum.spectral_analysis()` (and `altimetry.tools.spectrum.get_spec()` at lower level)

### 1.1.2.1.1.1. Notes on spectral tapering

Tapering and padding are mathematical manipulations sometimes performed on the time series before periodogram analysis to improve the statistical properties of the spectral estimates or to speed up the computations.

Tapering can be applied:
  - to reduce the noise level by oversampling the data in overlapping subsegments (eg. when we don’t have enough samples)
  - to better localise spectral peaks and changes in the spectral slope.
However, you should be aware that:
  - tapering may induce a loss of overall energy, resulting the tapered spectrum to be under (though less noisy) the original spectrum.
  - oversampling the data will result in removing a part of the lower frequencies because of the shorter subsegments.

`altimetry.tools.spectrum.preprocess()` allows using tapers through its `tapering` keyword.

Warning

though it is taken into account in `altimetry.tools.spectrum.spectral_analysis()`, energy loss caused by the tapering may not be properly resolved.

It may be therefore necessary to correct this loss by multiplying the tapered spectrum by the ratio of energies of both spectra

### 1.1.2.1.1.2. Notes on AR spectrum (auto-regression methods)

AR (auto-regressive methods) can be used to model a spectrum from the signal.

Such method, as the Yule-Walker equations, can be used to model the spectrum, and therefore:
  - clean the spectrum (by having an auto-regression approach)
  - compute the energy (or power) at any frequency (ie. not being dependant on the length of input array).

This approach is made possible through the `ARspec` keyword of `altimetry.tools.spectrum.spectral_analysis()` (itself calling `altimetry.tools.spectrum.yule_walker_regression()`).

## 1.1.2.1.2. List of useful functions

> - `altimetry.tools.spectrum.spectral_analysis()` : Compute the average spectrum over a set of data
> - `altimetry.tools.spectrum.preprocess()` : Preprocess the data to be admissible to spectral analysis
> - `altimetry.tools.spectrum.get_slope()` : Compute the spectral slope
> - `altimetry.tools.spectrum.optimal_AR_spectrum()` : Get the order of the optimal AR spectrum

## 1.1.2.1.3. Functions

`altimetry.tools.spectrum.` `spectral_analysis`(dx, Ain, tapering=None, overlap=None, wsize=None, alpha=3.0, detrend=False, normalise=False, integration=True, average=True, ARspec=None)

  Spectral_Analysis : This function performs a spatial spectral analysis with different options on a time series of SLA profiles.

  Parameters: | dx – sampling distance Ain – 2D table of sla data with time along 2nd axis (NXxNT with NX the spatial length and NT the time length) tapering – apply tapering to the data If this keyword is of type bool : apply hamming window. If this keyword is a string : apply a hamming (‘hamm’), hann (‘hann’), kaiser-bessel (‘kaiser’), kaiser-bessel (‘blackman’) or no (‘none’) tapering function. If this keyword is an `numpy.array` object : apply this array as taper. overlap – overlap coefficient of the windows (0.75 means 75% overlap). wsize – size of the sub-segments. normalise – If True, normalise the spectrum by its overall energy content. detrend – If True, removes a linear trend to the segmented signal (if tapered) or to the whole signal (if not tapered). integration – If True, integrate the spectrum between 2 frequencies. sla – data
  Returns: | a spectrum structure
      {'esd':esd,       #Energy Spectral Density
       'psd':psd,       #Power Spectral Density
       'fq':fq,         #frequency
       'p':p,           #wavelength
       'params':params} #tapering parameters.
  Author : | Renaud DUSSURGET (RD) - LER/PAC, Ifremer
  Change : | Created by RD, December 2012

`altimetry.tools.spectrum.` `preprocess`(lat, lon, sla, N_min=None, per_min=15.0, max_gap=None, leave_gaps=False, remove_edges=True, interp_over_continents=False, truncate_if_continents=True, discard_continental_gaps=True, flag_interp=False, return_lonlat=False, return_interpolated=False, last=True, mid=None, first=None, verbose=1)
  Preprocessing of the SLA data ::
    - process positions :
        - interpolate over gaps
        - find continents (extend the positions over continents to get the discontinuity)
        - find track edges
        - find gap lengths
    - clean SLA data::
        - Remove gaps greater than maximum allowed length over which interpolate is OK.
        - Remove time steps with not enough coverage
        - get sub-segments of valid data of a given length

  Parameters: | lon – longitude lat – longitude sla – data N_min – Length of subsegments (cf `altimetry.tools.spectrum.get_segments()`) per_min – Minimum percentage of valid data to allow. max_gap – Maximum gap length to interpolate over (interpolation is done 1st, THEN long gaps are eliminated) leave_gaps – Leave gaps (equivalent to setting max_gap to number of points in track). remove_edges – discard data at track edges. truncate_if_continents – Force truncating data if a continent is found within a segment of data. last – Get segments of data sticked to the last point in track (cf `altimetry.tools.spectrum.get_segments()`) first – Get segments of data sticked to the first point in track (cf `altimetry.tools.spectrum.get_segments()`) mid – Get segments of data sticked to the middle point in track (cf `altimetry.tools.spectrum.get_segments()`)

`altimetry.tools.spectrum.` `get_kx`(N, dx)

  GET_KX :summary: Returns the frequencies to be used with FFT analysis

  Parameters: | N – number of samples in data dx – sampling step
  Returns: | Returns * k: frequency * L: length * imx: index of maximum frequency (for separating positive and negative frequencies)
  Author : | Renaud DUSSURGET (RD) - LER/PAC, Ifremer
  Change : | Created by RD, July 2012

`altimetry.tools.spectrum.` `get_spec`(dx, Vin, verbose=False, gain=1.0, integration=True)

  GET_SPEC :summary: Returns the spectrum of a regularly sampled dataset

  Parameters: | dq – sampling interval (1D) V – data to analyse (1D).
  Note : | NaN can not be used.
  Returns: | psd: Power Spectral Density esd: Energy Spectral Density fq: frequency p: wavelength (period)
  Author : | Renaud DUSSURGET (RD) - LER/PAC, Ifremer
  Change : | Created by RD, July 2012. Changes * 29/08/2012 : Changed the computation of frequencies and the spectral integration (spectrum is averaged at mid-width frequencies) * 30/11/2012 : Outstanding changes : corrected the spectral integration for computing psd and corrected the normalisation

`altimetry.tools.spectrum.` `get_segment`(sla, N, last=True, mid=None, first=None, remove_edges=True, truncate_if_continents=True)

  Intelligent segmentation of data.

  Parameters: | remove_edges – discard data at track edges. truncate_if_continents – Force truncating data if a continent is found within a segment of data. last – Get segments of data sticked to the last point in track first – Get segments of data sticked to the first point in track mid – Get segments of data sticked to the middle point in track

`altimetry.tools.spectrum.` `get_slope`(fq, spec, degree=1, frange=None, threshold=0.0)

  GET_SLOPE :summary: This function returns the spectral slope of a spectrum using a least-square regression

  Parameters: | fq – frequency spec – spectrum data degree – Degree of the least-square regression model
  Returns: | slope : spectral slope (or model coefficients for a higher order model) intercept : Energy at unit frequency (1 cpkm)
  Author : | Renaud DUSSURGET (RD) - LER/PAC, Ifremer
  Change : | Created by RD, August 2012

`altimetry.tools.spectrum.` `yule_walker`(acf, orden)

  Program to solve Yule-Walker equations for AutoRegressive Models

  Author : | XAVI LLORT (llort(at)grahi.upc.edu)
  Created : | MAY 2007
  Changes : | adapted to python by R.Dussurget
  Parameters: | acf – AutoCorrelation Function orden – Order of the AutoRegressive Model
  Returns: | parameters : Parameters sigma_e : Standard deviation of the noise term

`altimetry.tools.spectrum.` `yule_walker_regression`(dx, Y, deg, res=None)

  Parameters: | X – time vector (disabled) Y – stationary time series deg – AR model degree
  Returns: | a : Yule Walker parameters sig : Standard deviation of the noise term aicc : corrected Akaike Information Criterion gamma : Autocorrelation function ar : Fitted function argamma : Fitted autocorrelation function arspec : Fitted spectral model F : Relative frequency

  Note

  To know more about yule-walker and autoregressive methods, see

  - Example of AR(p) model auto-regression using yule-walker equations
  - Other notes on the autoregressive method

  Example : | IDL example :
      #Define an n-element vector of time-series samples
      X = [6.63, 6.59, 6.46, 6.49, 6.45, 6.41, 6.38, 6.26, 6.09, 5.99, $
          5.92, 5.93, 5.83, 5.82, 5.95, 5.91, 5.81, 5.64, 5.51, 5.31, $
          5.36, 5.17, 5.07, 4.97, 5.00, 5.01, 4.85, 4.79, 4.73, 4.76]

      #Compute auto_correlation function
      acorr=A_CORRELATE(X,INDGEN(30))

      #Solve YW equation to get auto-regression coefficients for AR(2) model
      YULE_WALKER, acorr, 2, a, sig

      #Process auto-regression model
      ar=DBLARR(28)
      FOR i = 2, 29 DO ar[i-2] = SQRT(a[0]*X[i-1]*X[i] + a[1]*x[i-2]*x[i]+sig*x[i])

      #Compute spectrum
      spec=spectrogram(TRANSPOSE(X), INDGEN(N), WSIZE=N, OVERLAY=1.0, DISPLAY_IMAGE=0)

      #Compute AR(2) model spectrum
      ar2=spectrogram(TRANSPOSE(ar), INDGEN(28), WSIZE=28, OVERLAY=1.0, DISPLAY_IMAGE=0)

`altimetry.tools.spectrum.` `optimal_AR_spectrum`(dx, Y, ndegrees=None, return_min=True)

  Get the optimal order AR spectrum by minimizing the BIC.

### Navigation

- index
- modules |
- next |
- previous |
- altimetry tools 0 documentation »
- 1. Description of the modules »
- 1.1.2. altimetry.tools Module »