Irregular rebinning function and Analysis Subpackage

[DanRyanIrish]

PR Description

Following the structure outline by #725, this PR creates an analysis subpackage and a rebin module. Included in the rebin module is the implementation of the rebin method, which now simply calls the rebin function.

However, crucially, it also includes a rebin_by_edges function, which allows users to rebin an NDCube which irregular bin sizes along an axis. This is a very important functionality for certain analyses, e.g. solar X-ray imaging spectroscopy.

Due to technical limitations, ndcube can currently only support this if the WCS axes are independent, and so is not within the scope of an NDCube method. However, if this limitation is overcome in the future, an NDCube.rebin_by_edges method can be implemented as a wrapper around this function.

To Do

• Change name of rebin_by_edges to rebin_by_corners
• Restore function signature to NDCube.rebin. Explicitly list out inputs, rather than using *args and `**kwargs``.
• Currently, wcs and extra coords are lumped together into combined wcs. Separate these so output still has same coords in WCS and extra_coords
• Incorporate feature request in Provide a shorthand for "one bin along this axis" in .rebin #737
• Write tests for rebin_by_corners
• Fix doc test

[settwi]

Hey Dan this looks really good. I especially like the option to propagate uncertainties (and presumably other metadata, too?). It will save us headaches in other applications.

Occasionally it is nice to do some interpolation of bins, too, like when binning a spectral response down from fine photon bins to coarser count bins, or to "directly" compare data from different instruments with different energy bins. For histograms you want to conserve the "flux" in each bin and the simplest way to do it is just a proportional interpolation. For photon count or flux data I reckon this approach makes sense.

I made a gist a while back to do an interpolating rebinning which has proved useful a few times. Might be nice to add a similar functionality to ndcube. Maybe "rebin_interpolated" or something like that. "Normal" rebinning is just a subset of the interpolating version, but it might make sense to specialize the implementations to save on computation time.

[samaloney]

This is GREAT! I still need to actually try it out but just figured get these down now.

[DanRyanIrish]

Hi @settwi. Thanks for the comments. I definitely agree with the use-cases you pointed out. From a technical perspective, I think they are already served by NDCube.reproject_to, assuming you generate the new WCS separately, which, I grant, can be a more cumbersome API. I am right though? Is there a difference between rebin_interpolated and reproject_to other than a more restrictive and hence more friendly API?

[DanRyanIrish]

Suggested change

	__all__ = ["rebin"]
	__all__ = ["rebin", "rebin_by_edges"]

[DanRyanIrish]

We should consider whether rebin_by_edges should be rebin_by_corners to be consistent with the axis_world_coords(corners=True) API.

[Cadair]

We should wrap this to maintain the signature. Perhaps we could use this: https://docs.python.org/3/library/functools.html#functools.wraps to avoid the copy?

[Cadair]

Using extra coords as a way to do this is a bit "weird" using table coordinate directly might be more applicable.

[DanRyanIrish]

Would this require extra code to parse whether it should be a QuantityTableCoordinate, TimeTableCoordinate, etc.? If so, ExtraCoords already does this for us.