comp_spectrum_ratio_1d

Authors

Pascal Terray (LOCEAN/IPSL)

Latest revision

13/09/2018

Purpose

Compute the ratio of two Power Spectral Density (PSD) estimates and a pointwise tolerance interval for this ratio under the assumption that the two “true” underlying spectra are the same.

How to compare quantitatively two estimated spectra is an important question solved by comp_spectrum_ratio_1d. Suppose that f1(w) and f2(w) are spectral estimates (where w is a Fourier frequency) with df1 and df2 degrees of freedom, respectively. To answer this question, spectral analysis theory [Diggle] suggests to examine the spectral ratio

R(w) = f1(w) / f2(w)

, which may be assumed to follow an F-distribution with numerator and denominator degrees of freedom df1 and df2, respectively. This result can be used to calculate pointwise confidence (or tolerance) intervals for the spectral ratios at the Fourier frequencies [Diggle] [Masson_etal] [Terray_etalb].

For additional details on these spectral computations, see the second reference cited below.

It is assumed that the two estimated spectra have been computed with calls to comp_spectrum_1d with the -conflim argument.

The pointwise tolerance interval and the ratio of the two estimated spectra (if the -nv= and -dv= arguments are specified) are stored in an output NetCDF dataset.

Further Details

Usage

$ comp_spectrum_ratio_1d \
       -nf=numerator_netcdf_file \
       -df=denominator_netcdf_file       (optional) \
       -nv=numerator_netcdf_variable     (optional) \
       -dv=denominator_netcdf_variable   (optional) \
       -np=numerator_period              (optional) \
       -dp=denominator_period            (optional) \
       -t=freq1,freq2                    (optional) \
       -o=output_netcdf_file             (optional) \
       -pro=probability_interval         (optional : 0.0 > 1.) \
       -mi=missing_value                 (optional) \
       -logratio                         (optional) \
       -double                           (optional) \
       -hdf5                             (optional) \
       -tlimited                         (optional)

By default

-df=

the denominator_netcdf_file is the same as the numerator_netcdf_file

-nv=

a numerator_netcdf_variable is not used and only the upper and lower critical ratios for each frequency are computed

-dv=

a denominator_netcdf_variable is not used and only the upper and lower critical ratios for each frequency are computed

-np=

the numerator_period argument is not used

-dp=

the denominator_period argument is not used

-t=

the whole set of frequencies in the two input NetCDF files

-o=

the output_netcdf_file is named spectrum_ratio.nc

-pro=

the probability_interval is set to 0.90, which means that a 90% tolerance interval for the ratio of the estimated spectra is computed

-mi=

the missing_value for the output NetCDF variables is set to 1.e+20

-logratio

the ratios and their associated upper and lower critical ratios are not Log transformed. If -logratio is specified, the ratios, upper and lower critical ratios are Log transformed

-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 dimension (e.g. the frequency axis) 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=numerator_netcdf_file argument specifies the NetCDF file containing the spectrum estimates and associated degrees of freedom of the numerator of the spectral ratio.

   It is assumed that this NetCDF file has been created by NCSTAT procedures performing spectral computations like comp_spectrum_1d (e.g. this NetCDF file must contain two NetCDF variables named edof and freq).

2. The -df=denominator_netcdf_file argument specifies the NetCDF file containing the spectrum estimates and associated degrees of freedom of the denominator of the spectral ratio. If this argument is not specified, it is assumed that the denominator_netcdf_file is the same as the numerator_netcdf_file.

   It is assumed that this NetCDF file has been created by NCSTAT procedures performing spectral computations like comp_spectrum_1d (e.g. this NetCDF file must contain two NetCDF variables named edof and freq).

3. The -nv=numerator_netcdf_variable and -dv=denominator_netcdf_variable arguments specify the NetCDF variables containing the power spectrum estimates for the numerator and denominator of the spectral ratio, respectively.

   If one or two of these optional arguments are absent, comp_spectrum_ratio_1d computes only the upper and lower critical ratios associated with the ( probability_interval * 100 )% tolerance interval (probability_interval is the value of the -pro= argument described below).

4. If the -np=numerator_period argument is specified, the power spectrum estimates in the numerator_netcdf_file have been computed for different periods separately (as determined by the value of the -p=period_length argument in comp_spectrum_1d for example). In that case, the -np= argument selects the period in the numerator_netcdf_file which must be used for computing the ratio of the PSD estimates (e.g. this argument is only used and useful, if both the -nv= and -dv= arguments are also specified).

5. If the -dp=denominator_period argument is specified, the power spectrum estimates in the denominator_netcdf_file have been computed for different periods separately (as determined by the value of the -p=period_length argument in comp_spectrum_1d for example). In that case, the -dp= argument selects the period in the denominator_netcdf_file which must be used for computing the ratio of the PSD estimates (e.g. this argument is only used and useful if both the -nv= and -dv= arguments are also specified).

6. If the -t=freq1,freq2 argument is missing, the ratios are computed for the whole set of frequencies in the numerator_netcdf_file and denominator_netcdf_file files (e.g. the spectra must have been estimated for the same set of frequencies).

   The selected frequency interval is a vector of two integers specifying the first and last frequencies for which the ratios and the associated tolerance intervals must be computed. The indices are relative to 1.

7. The -pro=probability_interval argument specifies that a ( probability_interval * 100 )% tolerance interval must be computed. This argument is used to determine the upper and lower critical ratios of the computed tolerance interval. probability_interval must be greater than 0 and less than 1. The default value is 0.90.

8. The -mi=missing_value argument specifies the missing value indicator for the output NetCDF variables in the output_netcdf_file.

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

9. The -logratio argument specifies that the logarithms of the ratios must be computed and stored in the output NetCDF file.

10. 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.

11. The -hdf5 argument is allowed only if the NCSTAT software has been compiled with the _USE_NETCDF4 CPP 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.

12. 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.

13. For more details on power spectrum analysis, theory for computing a pointwise tolerance interval for the ratio of two estimated spectra and examples in the climate literature, see

    • “Fourier analysis of time series- An introduction”, by Bloomfield, P., John Wiley and Sons, New York, Chapter 6, 1976. http://as.wiley.com/WileyCDA/WileyTitle/productCd-0471889482.html
    • “Time series: a biostatistical introduction”, by P.J. Diggle, Clarendon Press, Oxford, Chap. 4, 1990. http://www.oupcanada.com/catalog/9780198522263.html
    • “Impact of intra-daily SST variability on ENSO characteristics in a coupled model” by S. Masson et al., 2012, Climate Dynamics, Vol. 39:681-707, doi: 10.1007/s00382-011-1247-2
    • “The role of the intra-daily SST variability in the Indian monsoon variability in a global coupled model” by P. Terray et al., 2012, Climate Dynamics, Vol. 39:729-754, doi: 10.1007/s00382-011-1240-9
    • “Southern Hemisphere extra-tropical forcing: A new paradigm for El Nino-Southern Oscillation” by P. Terray, 2011, Climate Dynamics, Vol. 36:2171-2199, doi: 10.1007/s00382-010-0825-z

Outputs

comp_spectrum_ratio_1d creates an output NetCDF file that contains the upper and lower critical spectral ratios associated with the specified pointwise tolerance interval and, eventually, the spectral ratios of two estimated spectra, if both the -nv= and -dv= arguments have been used in the call to comp_spectrum_ratio_1d. The output NetCDF dataset contains the following NetCDF variables (in the description below, nfreq is the number of frequencies for which upper and lower critical (and eventually estimated) spectral ratios are computed as determined by the -t= and -p= arguments) :

1. frequency(nfreq) : the frequencies at which the spectral ratios are computed.

2. periodicity(nfreq) : the corresponding periods in number of time observations.

3. lower_critical_ratio(nfreq) : the lower critical spectral ratios associated with the specified pointwise tolerance interval.

   This variable is stored only if the -logratio argument has not been specified when calling comp_spectrum_1d.

4. upper_critical_ratio(nfreq) : the upper critical spectral ratios associated with the specified pointwise tolerance interval.

   This variable is stored only if the -logratio argument has not been specified when calling comp_spectrum_1d.

5. numerator_netcdf_variable_denominator_netcdf_variable_ratio(nfreq) : the spectral ratios computed from the spectra specified with the two input NetCDF variables numerator_netcdf_variable and denominator_netcdf_variable.

   This variable is stored only if the two -nv= and -dv= arguments have been specified and if the -logratio argument has not been specified when calling comp_spectrum_1d.

6. lower_critical_logratio(nfreq) : the lower critical spectral ratios associated with the specified pointwise tolerance interval.

   This variable is stored only if the -logratio argument has been specified when calling comp_spectrum_1d.

7. upper_critical_logratio(nfreq) : the upper critical spectral ratios associated with the specified pointwise tolerance interval.

   This variable is stored only if the -logratio argument has been specified when calling comp_spectrum_1d.

8. numerator_netcdf_variable_denominator_netcdf_variable_logratio(nfreq) : the spectral ratios computed from the spectra specified with the two input NetCDF variables numerator_netcdf_variable and denominator_netcdf_variable.

   This variable is stored only if both the -nv= and -dv= arguments have been specified and if the -logratio argument has not been specified when calling comp_spectrum_1d.

Examples

1. For computing the upper and lower critical spectral ratios associated with a 90% confidence interval of two spectra stored, respectively, in the files spectrum_sst.monthly.nino34.1979_2005.nc and spectrum_sst.monthly.nino34.1950_1978.nc, use the following command :

   $ comp_spectrum_ratio_1d  -fn=spectrum_sst.monthly.nino34.1979_2005.nc \
                             -fd=spectrum_sst.monthly.nino34.1950_1978.nc \
                             -o=spectrum_ratio_sst_nino34.nc