rename the primary grid parameter

[keewis]

• [x] closes #64

With the new name I don't really have an idea on how to describe the parameter in docstrings (level is not as easy to understand as resolution). We could describe it as

the resolution / cell size of the grid

since grids don't have any information content, but not sure if that makes sense. Does anyone have any idea?

[strobpr]

a good phrasing for general description and understanding would be 'grid spacing (levels)'. A bit more special is 'cell size (levels)' as only applicable to cell grids (thus ok for DGGS) but not node grids (often coverages).

[benbovy]

I would simply say something like this:

level : int
    Grid hierarchical level. A higher value corresponds to a finer grid resolution
    with smaller cell areas. The number of cells covering the whole sphere usually
    grows exponentially (*) with increasing level values, ranging from 5-100 cells
    (level 0) to millions or billions of cells (level 10+).

(*) or as a power function?

[keewis]

I'd probably try to fit "depending on the specific grid" somewhere in the second sentence, but that's already really great (and as far as I can tell, exponential seems right because we're talking about $n^{\mathrm{level}}$, i.e. the base is constant but the power varies)

[benbovy]

I'd have been nice to return from a DGGSInfo instance a cell statistics table like those ones: H3, S2. But I don't think that the core libraries provide such thing via their API, unfortunately.

[keewis]

That could indeed be helpful.

For healpy there's hp.nside2npix, which in any case is 12 * 4**level. As far as statistics like min/max/average area and min/max edge length go, this might be trickier but should not be impossible.

I'd say let's open a separate issue to discuss adding a method like that to DGGSInfo.

[strobpr]

Did you consider asking the DGGS API experts?

[keewis]

assuming this is fine (we did have extensive discussion elsewhere), I'm going to merge this tomorrow.

[keewis]

merging. We can always improve later, should it become necessary.