Better documentation needed for 2d slice routines

[jameswilburlewis]

I've been having some discussions with the MMS FPI team about the details of how 2d slices work. Jason Shuster @ UNH apparently has his own tool for generating similar plots, and they're trying to compare his results to the SPEDAS/PySPEDAS results and understand the differences.

The specific question they have for now is understanding how slice "thickness" works in the 2d slices with geometric interpolation.
There are parameters sum_angle and average_angle that specifies a range of rotations to be applied to the primary slice plane (to allow summing over more bins to get better statistics). However, the geometric interpoloation isn't obvious: the code appears to be rotating the slice plane around the +X slice axis. This doesn't result in a uniform-thickness band at each azimuth angle in the slice plane -- at the +/- Y axis, you'll get the full sum_angle, but at +/- X, the thickness will be zero since that is the axis of rotation being applied to the slice plane.

This is perhaps surprising to someone who might be expecting a more rotationally symmetric set of angular bins being summed.

We need a document that more fully describes the various options to 2D slice plots. Ideally it would include lots of graphics, showing how different sets of slice options, rotations, and displacements map onto the angle/energy bins or world coordinates.

It might be useful to have an optional diagnostic parameter to the slice routines, perhaps a user-specified function that can capture the slice coordinates and instrument angle/energy bin correspondence, and produce some diagnostic plots that show exactly what went into that slice.