comp_freq_func_1d

Authors

Pascal Terray (LOCEAN/IPSL)

Latest revision

28/05/2024

Purpose

Estimate the frequency response function (e.g., the transfer function) of a symmetric linear filter (e.g., a high, low or band-pass Lanczos or Hamming filter in this version of comp_freq_func_1d ) as computed by comp_lanczos_filter_3d or comp_symlin_filter_3d (or the corresponding procedures for unidimensional or fourdimensional NetCDF variables).

For more details on the frequency response function of a frequency filter, see [Bloomfield].

The frequency response function is computed at NFREQ frequencies where NFREQ is the value given at the -nf= argument.

The NFREQ frequencies are regularly sampled between 0 and the Nyquist frequency if the optional argument -fourfreq is not used or are the NFREQ Fourier frequencies 2*pi*j/NFREQ for j=0 to NFREQ-1 if this argument is used.

The frequency response function is written in a NetCDF dataset on output for later use.

Further Details

Usage

$ comp_freq_func_1d \
  -nf=number_of_frequencies \
  -pl=minimum_period \
  -ph=maximum_period \
  -nfc=number_of_filter_coefficients (optional) \
  -o=output_netcdf_file              (optional) \
  -mi=missing_value                  (optional) \
  -hamming                           (optional) \
  -win=window_choice                 (optional : 0.5 > 1.) \
  -fourfreq                          (optional) \
  -notestf                           (optional) \
  -double                            (optional) \
  -hdf5                              (optional) \
  -tlimited                          (optional)

By default

-nfc=
the number_of_filter_coefficients is determined in order to optimize the frequency response function of the selected filter.
-o=
the output_netcdf_file is named filter_freq_func.nc
-mi=
the missing_value for the output variable is equal to 1.e+20
-hamming
a Lanczos window filter is used. If the -hamming argument is specified a Hamming window filter is used instead
-win=
a Hamming window (e.g., -win=0.54) is convolved with the filter response by default if the -hamming argument is used, meaning that a Hamming window filter is estimated. If the -hamming argument is not used, this argument has no effect
-fourfreq
the frequency response function is not computed at the Fourier frequencies. If the -fourfreq argument is used the frequency response function is estimated at the Fourier frequencies
-notestf
Normally, the value of the -nfc= argument must be chosen such that the full transition bands about the cutoff frequencies 1/PH and 1/PL (where PH and PL are the values of the -ph= and -pl= arguments, respectively) of the selected filter are inside the [0., 0.5] frequency interval. By using the -notestf argument you can get ride of this limitation
-double
the results are stored as single-precision floating point numbers in the output NetCDF file. If -double is activated, the results are stored as double-precision floating point numbers
-hdf5
a NetCDF classical format file is created. If -hdf5 is activated, the output NetCDF file is a NetCDF-4/HDF5 format file
-tlimited
the time (e.g., frequency) dimension is defined as unlimited in the output NetCDF file. However, if -tlimited is activated, the time dimension is defined as limited in the output NetCDF file

Remarks

  1. The -nf= argument specifies the number of frequencies at which the frequency response function must be evaluated. The -nf= argument is a strictly positive integer.

  2. The -pl= argument specifies the minimum period of oscillation of the resulting filtered time series. The minimum_period is expressed in number of time observations.

    Do not use the -pl= argument or use -pl=0 for high-pass filtering frequencies corresponding to periods shorter than -ph=PH .

    The -pl= argument is a positive integer equal to 0 or greater than 2.

  3. The -ph= argument specifies the maximum period of oscillation of the resulting filtered time series. The maximum_period is expressed in number of time observations. Do not use the -ph= argument or use -ph=0 for low-pass filtering frequencies corresponding to periods longer than -pl=PL . For example, -pl=6 (or 18) and -ph=32 (or 96) select periods between 1.5 and 8 years for quarterly (monthly) time series.

    The -ph= argument is a positive integer equal to 0 or greater than 2 and less than the length of the multichannel time series or the periodicity if the -p= argument is used.

    The -ph= argument must also be greater or equal to the -pl= argument if both are specified.

  4. Setting -pl= and -ph= to the same value P is allowed. In this case, an -ideal- band-pass filter with peak response near one at the single period P is computed and applied to the time series.

  5. Setting both -pl=0 and -ph=0 is not allowed since in that case, no frequency filtering is done.

  6. The -nfc= argument specifies the desired number of symmetric linear filter coefficients. If -nfc= is not specified, an optimal value is chosen in order to obtain a good frequency response function for the selected filter.

    However, if -nfc= is set to K, the first and last (K-1)/2 time observations in the resulting filtered time series will be affected by end effects. Thus, the user must choose the number of filter terms, K, as a compromise between:

    1. A sharp cutoff, that is, 1/K small; and
    2. Minimizing the number of data points lost or affected by the filtering operations (since (K-1)/2 data points will be lost or affected from each end of the series).

    Finally, the -nfc= argument must be greater or equal to 3 and odd.

  7. The -mi=missing_value argument specifies the missing value indicator for the output variable in the output_netcdf_file.

    If the -mi= argument is not specified, the missing_value is set to 1.e+20.

  8. If the -hamming argument is specified, a Hamming window filter is used instead of Lanczos window filter.

  9. The -win= argument controls the form of the window which will be convolved with the filter if a Hamming window filter is requested with the -hamming argument. By default, a Hamming window is used (e.g., -win=0.54).

    Set -win=0.5 for using a Hanning window or -win=1.. for a rectangular window (e.g., “ideal” filter).

    This argument has an effect only if the -hamming argument is also specified. The -win= argument is a real number greater or equal to O.5 and less or equal to 1..

  10. If the -fourfreq argument is used the frequency response function is evaluated at the Fourier frequencies 2*pi*j/NFREQ for j=0 to NFREQ-1, where NFREQ is the value of the -nf= argument.

  11. The -notestf argument allows to bypass some of the restrictions on the number of filter coefficients as specified with the -nfc= argument.

    By default, the value of the -nfc= argument must be chosen such that the full transition bands about the cutoff frequencies (1/PH and 1/PL) of the selected filter are inside the [0., 0.5] frequency interval.

    When the -notestf argument is specified, only the cutoff frequencies (e.g., 1/PH and 1/PL) of the selected filter must lie in the [0., 0.5] frequency interval and not the full transition bands around them.

    This allows to diminish the number of filter coefficients and, thus, to minimize the number of data points lost by the filtering operation (if -nfc= is set to K, (K-1)/2 data points will be “lost” or affected by end effects from each end of the series).

  12. The -double argument specifies that, the results are stored as double-precision floating point numbers in the output NetCDF file.

    By default, the results are stored as single-precision floating point numbers in the output NetCDF file.

  13. The -hdf5 argument is allowed only if the NCSTAT software has been compiled with the _USE_NETCDF4 macro (e.g., -D_USE_NETCDF4) and linked to the NetCDF 4 library or higher.

    If this argument is specified, the output_netcdf_file will be a NetCDF-4/HDF5 format file instead of a NetCDF classic format file. However, this argument is recognized in the procedure only if the NCSTAT software has been built with the _USE_NETCDF4 CPP macro.

  14. Duplicate parameters are allowed, but this is always the last occurrence of a parameter which will be used for the computations. Moreover, the number of specified parameters must not be greater than the total number of allowed parameters.

  15. For more details on Lanczos or symmetric linear filtering and examples of use in the climate literature, see

Outputs

comp_freq_func_1d creates an output NetCDF file that contains the frequency response function of the selected filter. The output NetCDF dataset contains the following NetCDF variable (in the description below, NFREQ is the number_of_frequencies specified for the -nf= argument) :

  1. transfert_function(NFREQ) : the frequency response function of the selected filter at the selected frequencies.

Examples

  1. For estimating the frequency response function of a band-passed Lanczos filter (in the biennial time scale if we assume monthly time series since -pl=18 and -ph=30 are specified) at 200 frequencies regularly sampled between 0 and the Nyquist frequency, use the following commands :

    $ comp_freq_func_1d  \
  -nf=200 \
  -pl=18  \
  -ph=30  \
  -o=freq_func.nc

  2. For estimating the frequency response function of the same band-passed Lanczos filter, but at the 200 Fourier frequencies between 0 and the Nyquist frequency, use the following commands :

    $ comp_freq_func_1d  \
  -nf=200    \
  -pl=18     \
  -ph=30     \
  -fourfreq  \
  -o=freq_func.nc
Flag Counter