shmultitapermaskcse.1

.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "shmultitapermaskcse" "1" "2021-02-15" "Fortran 95" "SHTOOLS 4.10"
.hy
.SH SHMultiTaperMaskCSE
.PP
Perform a localized multitaper cross-spectral analysis using using
arbitrary windows derived from a mask.
.SH Usage
.PP
call SHMultiTaperMaskCSE (\f[V]mtse\f[R], \f[V]sd\f[R], \f[V]cilm1\f[R],
\f[V]lmax1\f[R], \f[V]cilm2\f[R], \f[V]lmax2\f[R], \f[V]tapers\f[R],
\f[V]lmaxt\f[R], \f[V]k\f[R], \f[V]taper_wt\f[R], \f[V]norm\f[R],
\f[V]csphase\f[R], \f[V]exitstatus\f[R])
.SH Parameters
.TP
\f[V]mtse\f[R] : output, real(dp), dimension (\f[V]lmax\f[R]-\f[V]lmaxt\f[R]+1)
The localized multitaper cross-power spectrum estimate.
\f[V]lmax\f[R] is the smaller of \f[V]lmax1\f[R] and \f[V]lmax2\f[R].
.TP
\f[V]sd\f[R] : output, real(dp), dimension (\f[V]lmax\f[R]-\f[V]lmaxt\f[R]+1)
The standard error of the localized multitaper cross-power spectral
estimates.
\f[V]lmax\f[R] is the smaller of \f[V]lmax1\f[R] and \f[V]lmax2\f[R].
.TP
\f[V]cilm1\f[R] : input, real(dp), dimension (2, \f[V]lmax1\f[R]+1, \f[V]lmax1\f[R]+1)
The spherical harmonic coefficients of the first function.
.TP
\f[V]lmax1\f[R] : input, integer(int32)
The spherical harmonic bandwidth of \f[V]cilm1\f[R].
.TP
\f[V]cilm2\f[R] : input, real(dp), dimension (2, \f[V]lmax2\f[R]+1, \f[V]lmax2\f[R]+1)
The spherical harmonic coefficients of the second function.
.TP
\f[V]lmax2\f[R] : input, integer(int32)
The spherical harmonic bandwidth of \f[V]cilm2\f[R].
.TP
\f[V]tapers\f[R] : input, real(dp), dimension ((\f[V]lmaxt\f[R]+1)**2, \f[V]k\f[R])
An array of the \f[V]k\f[R] windowing functions, arranged in columns,
obtained from a call to \f[V]SHReturnTapersMap\f[R].
The spherical harmonic coefficients are packed according to the
conventions in \f[V]SHCilmToVector\f[R].
.TP
\f[V]lmaxt\f[R] : input, integer(int32)
The spherical harmonic bandwidth of the windowing functions in the array
\f[V]tapers\f[R].
.TP
\f[V]k\f[R] : input, integer(int32)
The number of tapers to be utilized in performing the multitaper
spectral analysis.
.TP
\f[V]taper_wt\f[R] : input, optional, real(dp), dimension (\f[V]k\f[R])
The weights used in calculating the multitaper spectral estimates and
standard error.
Optimal values of the weights (for a known global power spectrum) can be
obtained from the routine \f[V]SHMTVarOpt\f[R].
.TP
\f[V]norm\f[R] : input, optional, integer(int32), default = 1
1 (default) = 4-pi (geodesy) normalized harmonics; 2 = Schmidt
semi-normalized harmonics; 3 = unnormalized harmonics; 4 = orthonormal
harmonics.
.TP
\f[V]csphase\f[R] : input, optional, integer(int32), default = 1
1 (default) = do not apply the Condon-Shortley phase factor to the
associated Legendre functions; -1 = append the Condon-Shortley phase
factor of (-1)\[ha]m to the associated Legendre functions.
.TP
\f[V]exitstatus\f[R] : output, optional, integer(int32)
If present, instead of executing a STOP when an error is encountered,
the variable exitstatus will be returned describing the error.
0 = No errors; 1 = Improper dimensions of input array; 2 = Improper
bounds for input variable; 3 = Error allocating memory; 4 = File IO
error.
.SH Description
.PP
\f[V]SHMultiTaperMaskCSE\f[R] will perform a localized multitaper
cross-spectral analysis of two input functions expressed in spherical
harmonics, \f[V]cilm1\f[R] and \f[V]cilm2\f[R], using an arbitrary set
of windows derived from a mask.
The maximum degree of the localized multitaper power spectrum estimate
is \f[V]lmax-lmaxt\f[R], where \f[V]lmax\f[R] is the smaller of
\f[V]lmax1\f[R] and \f[V]lmax2\f[R].
The matrix \f[V]tapers\f[R] contains the spherical harmonic coefficients
of the windows and can be obtained by a call to
\f[V]SHReturnTapersMap\f[R].
The coefficients of each window are stored in a single column, ordered
according to the conventions used in \f[V]SHCilmToVector\f[R].
.PP
If the optional array \f[V]taper_wt\f[R] is specified, then these
weights will be used in calculating a weighted average of the individual
\f[V]k\f[R] tapered estimates (\f[V]mtse\f[R]) and the corresponding
standard error of the estimates (\f[V]sd\f[R]).
If not present, the weights will all be assumed to be equal.
When \f[V]taper_wt\f[R] is not specified, the mutltitaper spectral
estimate for a given degree will be calculated as the average obtained
from the \f[V]k\f[R] individual tapered estimates.
The standard error of the multitaper estimate at degree l is simply the
population standard deviation,
\f[V]S = sqrt(sum (Si - mtse)\[ha]2 / (k-1))\f[R], divided by
sqrt(\f[V]k\f[R]).
See Wieczorek and Simons (2007) for the relevant expressions when
weighted estimates are used.
.PP
The employed spherical harmonic normalization and Condon-Shortley phase
convention can be set by the optional arguments \f[V]norm\f[R] and
\f[V]csphase\f[R]; if not set, the default is to use geodesy 4-pi
normalized harmonics that exclude the Condon-Shortley phase of
(-1)\[ha]m.
.SH References
.PP
Wieczorek, M.
A.
and F.
J.
Simons, Minimum-variance multitaper spectral estimation on the sphere,
J.
Fourier Anal.
Appl., 13, doi:10.1007/s00041-006-6904-1, 665-692, 2007.
.SH See also
.PP
shmultitapermaskse, shreturntapersmap, shcilmtovector