# fourier_info

Performs Fourier analysis on one or more periodic series.

## Prototype

function fourier_info ( x : numeric, nhx [1] : integer, sclPhase [1] : numeric ) return_val : float or double

## Arguments

*x*

An array of one or more dimensions. If more than one dimension, the harmonic analysis will be performed on the rightmost dimension. Further, the rightmost dimension must be periodic. The periodic (i.e. cyclic) point should not be included. Missing values are not allowed.

*nhx*

The number of harmonics to be returned. If the series is of length
*N*, then 0 < *nhx* <= *N*/2. If
*nhx*=0, then the maximum number of harmonics (*N*/2)
will be returned.

*sclPhase*

Constant which will be used to scale the phases. If no scaling is
desired, set *sclPhase*=1.0.

## Description

A Fourier analysis is performed on each series. The Fourier coefficients are used to derive the amplitude, phase and percent variance explained by each harmonic. The user may request that only a subset of the harmonic information be returned.

The *amplitude* for each harmonic is computed via

amp(n) =where "a" and "b" represent the real and imaginary coefficients of each harmonic.sqrt(a(n)*a(n) + b(n)*b(n))

The phase represents the location of the first maximum. The user may
wish to scale the phase. For example, let's say that the rightmost
dimension is longitude and has size of *mlon*=72. This makes
the distance between adjacent grid points equal to five degrees. If
*sclPhase*=1.0, then no phase scaling will occur and the
returned phases will be 0 < = *phase* < *mlon*. If
*sclPhase*=5. then the returned phases will be 0 <=
*phase* < 360.

The returned variable's type will be double if *x* is double,
and float otherwise. The dimensions are as follows, where *N*
represents the rightmost dimension of *x*, and [...]
represents the rest of the dimensions of *x*, if any:

The leftmost dimension size is three (3), where the subscripts 0, 1, and 2 reference the amplitude, phase and percent variance explained. See examples below for further information.xhas 1 dimension,nhx> 0 : finfo[3][nhx]xhas 1 dimension,nhx= 0 : finfo[3][N/2]xhas 2+ dimensions,nhx> 0 : finfo[3][...][nhx]xhas 2+ dimensions,nhx= 0 : finfo[3][...][N/2]

**NOTE:** The underlying code that computes the Fourier information
has an internal parameter (*eps*) which is set to 1e-12. If
the total variance of the input series is less than *eps*,
then the amplitude, phase and percent variance will be set to zero.
The reason for this is that users have input arrays that contain
a constant value (hence, variance is zero). Since the percent variance
is calculated by dividing by the total variance, the *eps*
insures that division by zero will not occur.

## Examples

**There are some Fourier analysis examples available
here.**

**Example 1**

Assume *x* is a one-dimensional array of length
*N*=72. Then:

finfo =fourier_info(x, 4, 1.) => finfo(3,4) [unscaled] finfo =fourier_info(x, 0, 5.) => finfo(3,36) [returned phases scaled by 5] finfo =fourier_info(x, N/2, 5.) => finfo(3,36)

finfo(0,:) will refer to the amplitude of each harmonic

finfo(1,:) will refer to the phase of each harmonic

finfo(2,:) will refer to the percent variance explained by each harmonic

**Example 2**

Assume *x* is a one-dimensional monthly climatology
(*N*=12), then the following will return fourier information
for the first two harmonics only:

finfo =fourier_info(x, 2, 1.) => finfo(3,2) [phases will be unscaled]

**Example 3**

Assume *x* is dimensioned *ntim* x *nlat* x
*mlon*. Then, where *mlon*=128
(*dlon*=360./*mlon*=2.8125):

finfo =fourier_info(x, 10, dlon) => finfo(3,ntim,nlat,10) finfo =fourier_info(x, 0, dlon) => finfo(3,ntim,nlat,64) finfo =fourier_info(x, N/2,dlon) => finfo(3,ntim,nlat,64)

**Example 4**

Assume *x* is a monthly climatology of size *ntim*[=12]
x *klev* x *nlat* x *mlon* with named dimensions
"time", "lev", "lat" and "lon", and that the information from the
first three harmonics of the mean annual cycle is desired. Then:

finfo =fourier_info(x(lev|:,lat|:,lon|:,time|:), 3, 1.) => finfo(3,klev,nlat,mlon,3)