-
Notifications
You must be signed in to change notification settings - Fork 106
/
shbiaskmask.1
134 lines (134 loc) · 4.43 KB
/
shbiaskmask.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
.\" Automatically generated by Pandoc 2.2.3
.\"
.TH "shbiaskmask" "1" "2018\-05\-20" "Fortran 95" "SHTOOLS 4.3"
.hy
.SH SHBiasKMask
.PP
Calculate the multitaper (cross\-)power spectrum expectation of a
function localized by arbitrary windows derived from a mask.
.SH Usage
.PP
call SHBiasK (\f[C]tapers\f[], \f[C]lwin\f[], \f[C]k\f[],
\f[C]incspectra\f[], \f[C]ldata\f[], \f[C]outcspectra\f[],
\f[C]taper_wt\f[], \f[C]save_cg\f[], \f[C]exitstatus\f[])
.SH Parameters
.TP
.B \f[C]tapers\f[] : input, real*8, dimension ((\f[C]lwin\f[]+1)**2, \f[C]k\f[])
The spherical harmonic coefficients of the localization windows
generated by a call to \f[C]SHReturnTapersMap\f[].
The coefficients in each column are ordered according to the convention
in \f[C]SHCilmToVector\f[].
.RS
.RE
.TP
.B \f[C]lwin\f[] : input, integer
The spherical harmonic bandwidth of the localizing windows.
.RS
.RE
.TP
.B \f[C]k\f[] : input, integer
The number of localization windows to use.
Only the first \f[C]k\f[] columns of \f[C]tapers\f[] will be employed,
which corresponds to the best\-concentrated windows.
.RS
.RE
.TP
.B \f[C]incspectra\f[] : input, real*8, dimension (\f[C]ldata\f[]+1)
The global unwindowed power spectrum.
.RS
.RE
.TP
.B \f[C]ldata\f[] : input, integer
The maximum degree of the global unwindowed power spectrum.
.RS
.RE
.TP
.B \f[C]outcspectra\f[] : output, real*8, dimension (\f[C]ldata\f[]+\f[C]lwin\f[]+1)
The expectation of the localized multitaper power spectrum.
.RS
.RE
.TP
.B \f[C]taper_wt\f[] : input, optional, real*8, dimension (\f[C]k\f[])
The weights to apply to each individual windowed spectral estimate.
.RS
.RE
.TP
.B \f[C]save_cg\f[] : input, optional, integer, default = 0
If set equal to 1, the Clebsch\-Gordon coefficients will be precomputed
and saved for future use (if \f[C]lwin\f[] or \f[C]ldata\f[] change,
these will be recomputed).
To deallocate the saved memory, set this parameter equal to 1.
If set equal to 0 (default), the Clebsch\-Gordon coefficients will be
recomputed for each call.
.RS
.RE
.TP
.B \f[C]exitstatus\f[] : output, optional, integer
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.
.RS
.RE
.SH Description
.PP
\f[C]SHBiasKMask\f[] will calculate the multitaper (cross\-)power
spectrum expectation of a function multiplied by the \f[C]k\f[]
best\-concentrated localization windows derived from an arbitrary mask.
This is given by equation 36 of Wieczorek and Simons (2005) (see also
eq.
2.11 of Wieczorek and Simons 2007).
In contrast to \f[C]SHBias\f[], which takes as input the power spectrum
of a single localization window, this routine expects as input a matrix
containing the spherical harmonic coefficients of the windows.
These can be generated by a call to \f[C]SHReturnTapersMap\f[] and the
coefficients in each column are ordered according to the convention in
\f[C]SHCilmToVector\f[].
.PP
The maximum calculated degree of the windowed power spectrum expectation
corresponds to the smaller of (\f[C]ldata\f[]+\f[C]lwin\f[]) and
\f[C]size(outcspectra)\-1\f[].
It is assumed implicitly that the power spectrum of \f[C]inspectrum\f[]
is zero beyond degree \f[C]ldata\f[].
If this is not the case, the ouput power spectrum should be considered
valid only for the degrees up to and including \f[C]ldata\f[] \-
\f[C]lwin\f[].
.PP
The default is to apply equal weights to each individual windowed
estimate of the spectrum, but this can be modified by specifying the
weights in the optional argument \f[C]taper_wt\f[].
The weights must sum to unity.
If this routine is to be called several times using the same values of
\f[C]lwin\f[] and \f[C]ldata\f[], then the Clebsch\-Gordon coefficients
can be precomputed and saved by setting the optional parameter
\f[C]save_cg\f[] equal to 1.
.SH References
.PP
Wieczorek, M.
A.
and F.
J.
Simons, Minimum\-variance multitaper spectral estimation on the sphere,
J.
Fourier Anal.
Appl., 13, 665\-692, doi:10.1007/s00041\-006\-6904\-1, 2007.
.PP
Simons, F.
J., F.
A.
Dahlen and M.
A.
Wieczorek, Spatiospectral concentration on a sphere, SIAM Review, 48,
504\-536, doi:10.1137/S0036144504445765, 2006.
.PP
Wieczorek, M.
A.
and F.
J.
Simons, Localized spectral analysis on the sphere, Geophys.
J.
Int., 162, 655\-675, doi:10.1111/j.1365\-246X.2005.02687.x, 2005.
.SH See also
.PP
shbias, shreturntapersmap, shmtcouplingmatrix