These are chat archives for SHTOOLS/SHTOOLS

2nd
Nov 2016
Mark Wieczorek
@MarkWieczorek
Nov 02 2016 13:43
Is this clear?
        Return a numpy array with the power spectrum.

Usage
-----
power = x.powerspectrum([unit])

Returns
-------
power : ndarray, shape (lmax+1)
1-D numpy ndarray of the power spectrum, where lmax
is the maximum spherical harmonic degree.

Parameters
----------
unit : str, optional, default = 'per_l'
If unit is 'per_l', return the total power for each spherical
harmonic degree l. If 'per_lm', return the average contribution
to the power for each coefficient at spherical harmonic degree l.
I'll also add a unit='per_logband' or something like that later...
MMesch
@MMesch
Nov 02 2016 14:51
yes, I think that's clear
make sure that it is clear what energy and power means !?
This could go on top under the first line with the general description
Mark Wieczorek
@MarkWieczorek
Nov 02 2016 15:15

Also, could you explain to me what the powerperband actually means? Here is the code

        ls = self.get_degrees()
return self._powerspectrum() * ls * _np.log(bandwidth)

It is just the power, multiplied by the spherical harmonic degree, and I'm having a hard time understanding why someone would want this. Could you give me a reference?

Mark Wieczorek
@MarkWieczorek
Nov 02 2016 15:25
Here is the clarification on power:
        power : ndarray, shape (lmax+1)
1-D numpy ndarray of the power spectrum, where lmax is the maximum
spherical harmonic degree. Power is defined as the integral of the
function squared over all space, divided by the area the
function spans.
Next question to resolve: Should we provide an optional arguement that allows to return the "energy" instead of the "power". In this case, energy would be defined as the integral of the function squared, and would differ from the power only by 4pi. We could use an optional argument energy=True/False.
MMesch
@MMesch
Nov 02 2016 16:13
regarding band power: it is useful if you want to see dominant scales
Mark Wieczorek
@MarkWieczorek
Nov 02 2016 16:14
Can you give me a reference? and/or more precise definition? I originally though it was the total power within a band l1->l2, where the interval was logarithmic.
MMesch
@MMesch
Nov 02 2016 16:14
that's what it is
it's just a density
so you have $d(logl) = dl / l$
wait, I'll try to write it cleanly
$S(l) dl$ is the normal power (continuous spectrum, so only in the high frequency limit on the sphere)
MMesch
@MMesch
Nov 02 2016 16:21
The power in a log band is then: $S_{\log(l)} d(log l) = S(l) dl$
$S_{\log}(l)d(log(l)) = S(l) dl \Rightarrow S_{\log}(l) = l S(l)$
MMesch
@MMesch
Nov 02 2016 16:34
I don't know how to put this into really proper terminology to be honest. Another option would be to use constant and relative bandwidth as a distinction ...
This unit is everywhere in acoustics, so they tend not to reintroduce it properly and it appears only very rarely in geophysics, fluid dynamics etc...
Mark Wieczorek
@MarkWieczorek
Nov 02 2016 17:15
So what do we call this? People who use this must call it something, even if they don't know what it means...: power spectral density over bandwidth log_a(l) ?
From the old docs, we say Return the power per log_{bandwidth}(degree) spectrum. but I think that "bandwidth" here is only the base, and is not a real bandwidth.
Mark Wieczorek
@MarkWieczorek
Nov 02 2016 17:21
'per_logbandwidth' ?
Elliott Sales de Andrade
@QuLogic
Nov 02 2016 19:32
The Usage heading is kind of redundant.
Mark Wieczorek
@MarkWieczorek
Nov 02 2016 20:20
I based that on the unix man pages, but replaced 'synopsis' with 'usage'. E.g.,
NAME
gpg2 - OpenPGP encryption and signing tool

SYNOPSIS
gpg2 [--homedir dir] [--options file] [options] command [args]

DESCRIPTION
gpg2  is  the  OpenPGP  part  of  the  GNU Privacy Guard (GnuPG). It is a tool to provide digital encryption and signing services using the
OpenPGP standard. gpg2 features complete key management and all bells and whistles you can expect from a decent OpenPGP implementation.
If I remove 'usage' from the python docs, should I do the same for the man pages? And should I relabel usage->synopsis?
Elliott Sales de Andrade
@QuLogic
Nov 02 2016 20:22
I don't know about the man pages, but if you do help(function), it prints the call signature at the beginning.
And the same for most sphinx docs, if using that.
Mark Wieczorek
@MarkWieczorek
Nov 02 2016 20:37

Here is what it looks like now:

Docstring:
MakeGridDH
----------
Create a 2D map from a set of spherical harmonic coefficients using the Driscoll and Healy (1994) sampling theorem.

Usage
-----
griddh = pyshtools.MakeGridDH(cilm, [lmax, norm, sampling, csphase, lmax_calc])

Returns
-------

I think that the function name is redundant in the docstring (but not man pages), which would give

Docstring:
Create a 2D map from a set of spherical harmonic coefficients using the Driscoll and Healy (1994) sampling theorem.

Usage
-----
griddh = pyshtools.MakeGridDH(cilm, [lmax, norm, sampling, csphase, lmax_calc])

Returns
-------

Removing usage gives

Docstring:
Create a 2D map from a set of spherical harmonic coefficients using the Driscoll and Healy (1994) sampling theorem.

griddh = pyshtools.MakeGridDH(cilm, [lmax, norm, sampling, csphase, lmax_calc])

Returns
-------

How is that?

Elliott Sales de Andrade
@QuLogic
Nov 02 2016 20:53
I meant the whole section, actually.
But if you're keeping them in man pages, then maybe they'll have to stay.