Add a keepdims kwarg to crop and crop_by_value to keep length-1 dimensions

[samaloney]

Add a keep_dims kwarg to crop and crop_by_values to allowing length-1 dimensions to be kept see #714

• Docs
  • Doc strings
  • Main docs (https://sunpy--732.org.readthedocs.build/projects/ndcube/en/732/explaining_ndcube/slicing.html#cropping-with-real-world-coordinates)
• Change log
• Tests

[DanRyanIrish]

Thanks for this PR @samaloney. It looks good, but keepdims should also be added to crop_by_values. And a test for that similar to he one you already have.

[DanRyanIrish]

Additionally, the kwargs should be keepdims to be consistent with numpy, not keep_dims.

[DanRyanIrish]

Are you happy for me to merge this @samaloney ?

[Cadair]

That was pleasantly easy

[Cadair]

We should add narrative docs as well?

[DanRyanIrish]

We should add narrative docs as well?

It probably would be good to add a couple sentences and a code snippet at the end of this section: https://github.com/sunpy/ndcube/blob/main/docs/explaining_ndcube/slicing.rst#cropping-with-real-world-coordinates
It doesn't have to be much. Something like:

By default, crop and crop_by_values discard length-1 dimensions to make the resulting cube more wieldy.
However, there are cases where it is preferable to keep the number of dimensions the same.
In this case, uses can set the keepdims kwarg to True in either crop or crop_by_values.

(Add code snippet example showing shape of cropped cube with length-1 dimensions.)

One use case for `keepdims=True` is when cropping leads to a cube with only one array element.
Because cropping an `NDCube` to a scalar is not allowed, such an operation would normally raise an error.
But if `keepdims=True`, a valid NDCube is returned with N length-1 dimensions.

(Perhaps another code snippet example.)

[DanRyanIrish]

Thanks @samaloney!!