@BeginModule
@NewPage
@Name      = Filter
@Title     = Time series filtering
@Section   = Miscellaneous
@Arguments = ifile ofile
@Operators = bandpass lowpass highpass


@BeginDescription
This module takes the time series for each gridpoint in @file{ifile} and fills it with zeros (zero-
padding) up to the next time-step-number that is a power of 2. Then it (fast fourier) transforms 
the time series with @math{2^n} elements into the frequency domain.
According to the particular operator and its parameters certain frequencies are filtered 
(set to zero) in the frequency domain and the spectrum is (inverse fast fourier) transformed 
back into the time domain. This time series is cut to the original number of timesteps from
@file{ifile} and written to @file{ofile}.
To determine the frequency the time-axis of @file{ifile} is used. (Data should have a constant time 
increment since this assumption applies for transformation. However, the time increment 
has to be different from zero.)
All frequencies given as parameter are interpreted per year. This is done by the 
assumption of a 365-day calendar. Consequently if you want to perform multiyear-filtering 
accurately you have to delete the 29th of February. If your @file{ifile} has a 360 year calendar
the frequency parameters fmin respectively fmax should be multiplied with a factor of
360/365 in order to obtain accurate results.  
For the set up of a frequency filter the frequency parameters have to be adjusted to a 
frequency in the data. Here fmin is rounded down and fmax is always rounded up. 
Consequently it is possible to use bandpass with fmin=fmax without getting a zero-field 	
for @file{ofile}. 
Hints for efficient usage: 
@BeginItemize
@Item = to avoid effects of zero-padding cut or extend your time series down/up to the nearest power of two
@Item = to get reliable results the time-series has to be detrended (cdo detrend)
@Item = the lowest frequency greater zero that can be contained in ifile is 1/(N*dT), 
@Item = the greatest frequency is 1/(2dT) (Nyquist frequency),
@EndItemize
with N the number of timesteps and dT the time increment of @file{ifile} in years. 
@EndDescription
@EndModule	


@BeginOperator_bandpass
@Title      = Bandpass filtering
@Parameter = fmin fmax

@BeginDescription
Bandpass filtering (pass for frequencies between fmin and fmax).
Suppresses all variability outside the frequency range specified
by [fmin,fmax].
@EndDescription
@EndOperator


@BeginOperator_highpass
@Title      = Highpass filtering
@Parameter = fmin

@BeginDescription
Highpass filtering (pass for frequencies greater than fmin). 
Suppresses all variabilty with frequencies lower than fmin. 
@EndDescription
@EndOperator


@BeginOperator_lowpass
@Title      = Lowpass filtering
@Parameter = fmax

@BeginDescription
Lowpass filtering (pass for frequencies lower than fmax).
Suppresses all variability with frequencies greater than fmax. 
@EndDescription
@EndOperator

				
@BeginParameter fmax
@Item = fmin
FLOAT	Minimum frequency per year that passes the filter.
@Item = fmax
FLOAT	Maximum frequency per year that passes the filter.  
@EndParameter
	
@BeginExample
Now assume your data are still hourly for a time period of 5 years but with a 365/366-day-
calendar and you want to suppress the variability on timescales greater or equal to one year
(we suggest here to use a number x bigger than one (e.g. x=1.5) since there will be dominant 
frequencies around the peak (if there is one) as well due to the issue that the time series is not of 
infinite length). 
Therefor you can use the following:
@BeginVerbatim
   cdo highpass,x -del29feb ifile ofile
@EndVerbatim

Accordingly you might use the following to suppress variability on timescales shorter than one year:
@BeginVerbatim
   cdo lowpass,1 -del29feb ifile ofile
@EndVerbatim

Finally you might be interested in 2-year variability. If you want to suppress the seasonal cycle as 	
well as say the longer cycles in climate system you might use
@BeginVerbatim
   cdo bandpass,x,y -del29feb ifile ofile
@EndVerbatim
with x<=0.5 and y >=0.5.
@EndExample
