Adds shape property to NDCube

changelog/684.breaking.rst

@@ -0,0 +1 @@
+"dimensions" property has been depcreated and replaced by "shape"

changelog/684.feature.rst

@@ -0,0 +1 @@
+Added `ndcube.NDCube.shape` as a replacement for "dimensions".

examples/slicing_ndcube.py

@@ -54,8 +54,8 @@
 example_cube.plot()
 
 ##############################################################################
-# We can also inspect the dimensions of the cube:
-example_cube.dimensions
+# We can also inspect the shape of the cube:
+example_cube.shape
 
 ##############################################################################
 # We can also inspect the world coordinates for all array elements:
@@ -77,14 +77,14 @@
 
 sliced_cube = example_cube[1, :, :]
 # here we can see we are left with a 2-D cube which is an image at one wavelength.
-sliced_cube.dimensions
+sliced_cube.shape
 
 # We can also index a region of interest of the cube at a particular wavelength.
 # Again note that we are slicing here based on the ``array`` index rather than cropping by
 # real world value
 
 sliced_cube = example_cube[1, 10:20, 20:40]
-sliced_cube.dimensions
+sliced_cube.shape
 
 # Now we can inspect the sliced cube, and see it's now a smaller region of interest.
 sliced_cube.plot()
@@ -114,9 +114,9 @@
 cropped_cube = example_cube.crop(point1, point2)
 
 ##############################################################################
-# Similar to before, we can inspect the dimensions of the sliced cube:
+# Similar to before, we can inspect the dimensions of the sliced cube via the shape property:
 
-cropped_cube.dimensions
+cropped_cube.shape
 
 ##############################################################################
 # and we can visualize it:
@@ -134,7 +134,7 @@
 ##############################################################################
 # we can inspect the dimensions of the cropped cube:
 
-cropped_cube.dimensions
+cropped_cube.shape
 
 ##############################################################################
 # and again visualize it:
@@ -151,7 +151,7 @@
 ##############################################################################
 # Check dimensions:
 
-cropped_cube.dimensions
+cropped_cube.shape
 
 ##############################################################################
 # Here we can just see how powerful this can be to easily crop over different world coordinates.
@@ -162,4 +162,4 @@
 point6 = [SkyCoord(200*u.arcsec, 100*u.arcsec, frame=frames.Helioprojective), SpectralCoord(10.6*u.angstrom)]
 
 cropped_cube = example_cube.crop(point5, point6)
-cropped_cube.dimensions
+cropped_cube.shape

ndcube/ndcollection.py

@@ -102,7 +102,7 @@
         If there are no aligned axes, returns None.
         """
         if self.aligned_axes is not None:
-            return np.asanyarray(self[self._first_key].dimensions, dtype=object)[
+            return np.asanyarray(self[self._first_key].shape, dtype=object)[
                 np.array(self.aligned_axes[self._first_key])
             ]
 
@@ -178,7 +178,7 @@
         # and drop any aligned axes that are sliced out.
 
         # First, define empty lists of slice items to be applied to each cube in collection.
-        collection_items = [[slice(None)] * len(self[key].dimensions) for key in self]
+        collection_items = [[slice(None)] * len(self[key].shape) for key in self]
         # Define empty list to hold aligned axes dropped by the slicing.
         drop_aligned_axes_indices = []
 
@@ -275,7 +275,7 @@
         first_old_aligned_axes = self.aligned_axes[self._first_key] if self.aligned_axes is not None else None
         first_new_aligned_axes = new_aligned_axes[new_keys[0]] if new_aligned_axes is not None else None
         collection_utils.assert_aligned_axes_compatible(
-            self[self._first_key].dimensions, new_data[0].dimensions,
+            self[self._first_key].shape, new_data[0].shape,
             first_old_aligned_axes, first_new_aligned_axes
         )
         # Update collection

ndcube/ndcube.py

@@ -28,6 +28,7 @@
 from ndcube.global_coords import GlobalCoords, GlobalCoordsABC
 from ndcube.mixins import NDCubeSlicingMixin
 from ndcube.ndcube_sequence import NDCubeSequence
+from ndcube.utils.exceptions import warn_deprecated
 from ndcube.utils.wcs_high_level_conversion import values_to_high_level_objects
 from ndcube.visualization import PlotterDescriptor
 from ndcube.wcs.wrappers import CompoundLowLevelWCS, ResampledLowLevelWCS
@@ -415,8 +416,13 @@
 
     @property
     def dimensions(self):
+        warn_deprecated("Replaced by ndcube.NDCube.shape")
         return u.Quantity(self.data.shape, unit=u.pix)
 
+    @property
+    def shape(self):
+        return self.data.shape
+
     @property
     def array_axis_physical_types(self):
         # Docstring in NDCubeABC.

ndcube/ndcube_sequence.py

@@ -7,6 +7,7 @@
 import astropy.units as u
 
 from ndcube import utils
+from ndcube.utils.exceptions import warn_deprecated
 from ndcube.visualization.descriptor import PlotterDescriptor
 
 
@@ -46,22 +47,26 @@
         """
         The length of each axis including the sequence axis.
         """
-        return self._dimensions
+        warn_deprecated("Replaced by ndcube.NDCubeSequence.shape")
+        return tuple([d * u.pix for d in self._shape])
 
     @property
-    def _dimensions(self):
-        dimensions = [len(self.data) * u.pix] + list(self.data[0].dimensions)
+    def shape(self):
+        return self._shape
+
+    @property
+    def _shape(self):
+        dimensions = [len(self.data)] + list(self.data[0].shape)
         if len(dimensions) > 1:
             # If there is a common axis, length of cube's along it may not
             # be the same. Therefore if the lengths are different,
             # represent them as a tuple of all the values, else as an int.
             if self._common_axis is not None:
                 common_axis_lengths = [cube.data.shape[self._common_axis] for cube in self.data]
                 if len(np.unique(common_axis_lengths)) != 1:
-                    common_axis_dimensions = [cube.dimensions[self._common_axis]
-                                              for cube in self.data]
-                    dimensions[self._common_axis + 1] = u.Quantity(
-                        common_axis_dimensions, unit=common_axis_dimensions[0].unit)
+                    common_axis_dimensions = tuple([cube.shape[self._common_axis]
+                                                   for cube in self.data])
+                    dimensions[self._common_axis + 1] = common_axis_dimensions
         return tuple(dimensions)
 
     @property

ndcube/tests/test_ndcube.py

@@ -46,7 +46,7 @@
                          indirect=("ndc",))
 def test_slicing_ln_lt(ndc, item):
     sndc = ndc[item]
-    assert len(sndc.dimensions) == 2
+    assert len(sndc.shape) == 2
     assert set(sndc.wcs.world_axis_physical_types) == {"custom:pos.helioprojective.lat",
                                                        "custom:pos.helioprojective.lon"}
     if sndc.uncertainty is not None:
@@ -82,7 +82,7 @@
                          indirect=("ndc",))
 def test_slicing_wave(ndc, item):
     sndc = ndc[item]
-    assert len(sndc.dimensions) == 1
+    assert len(sndc.shape) == 1
     assert set(sndc.wcs.world_axis_physical_types) == {"em.wl"}
     if sndc.uncertainty is not None:
         assert np.allclose(sndc.data, sndc.uncertainty.array)
@@ -117,7 +117,7 @@
                          indirect=("ndc",))
 def test_slicing_split_celestial(ndc, item):
     sndc = ndc[item]
-    assert len(sndc.dimensions) == 2
+    assert len(sndc.shape) == 2
     if sndc.uncertainty is not None:
         assert np.allclose(sndc.data, sndc.uncertainty.array)
     if sndc.mask is not None:
@@ -815,7 +815,7 @@
     expected_time.format = "fits"
 
     # Confirm output is as expected.
-    assert (output.dimensions.value == np.array([1, 2, 8])).all()
+    assert (output.shape.value == np.array([1, 2, 8])).all()
     assert (output.data == expected_data).all()
     assert (output.mask == expected_mask).all()
     assert output.uncertainty == expected_uncertainty
@@ -1184,11 +1184,11 @@
 
 
 def test_squeeze(ndcube_4d_ln_l_t_lt):
-    assert np.array_equal(ndcube_4d_ln_l_t_lt.squeeze().dimensions, ndcube_4d_ln_l_t_lt.dimensions)
-    assert np.array_equal(ndcube_4d_ln_l_t_lt[:,:,0,:].dimensions, ndcube_4d_ln_l_t_lt[:,:,0:1,:].squeeze().dimensions)
-    assert np.array_equal(ndcube_4d_ln_l_t_lt[:,:,0,:].dimensions, ndcube_4d_ln_l_t_lt[:,:,0:1,:].squeeze(2).dimensions)
-    assert np.array_equal(ndcube_4d_ln_l_t_lt[:,0,0,:].dimensions, ndcube_4d_ln_l_t_lt[:,0:1,0:1,:].squeeze([1,2]).dimensions)
-    assert np.array_equal(ndcube_4d_ln_l_t_lt[:,0:1,0,:].dimensions, ndcube_4d_ln_l_t_lt[:,0:1,0:1,:].squeeze(2).dimensions)
+    assert np.array_equal(ndcube_4d_ln_l_t_lt.squeeze().shape, ndcube_4d_ln_l_t_lt.shape)
+    assert np.array_equal(ndcube_4d_ln_l_t_lt[:,:,0,:].shape, ndcube_4d_ln_l_t_lt[:,:,0:1,:].squeeze().shape)
+    assert np.array_equal(ndcube_4d_ln_l_t_lt[:,:,0,:].shape, ndcube_4d_ln_l_t_lt[:,:,0:1,:].squeeze(2).shape)
+    assert np.array_equal(ndcube_4d_ln_l_t_lt[:,0,0,:].shape, ndcube_4d_ln_l_t_lt[:,0:1,0:1,:].squeeze([1,2]).shape)
+    assert np.array_equal(ndcube_4d_ln_l_t_lt[:,0:1,0,:].shape, ndcube_4d_ln_l_t_lt[:,0:1,0:1,:].squeeze(2).shape)
 
 
 def test_squeeze_error(ndcube_4d_ln_l_t_lt):

ndcube/tests/test_ndcubesequence.py

@@ -35,12 +35,12 @@
 def test_slice_sequence_axis(ndc, item):
     # Calculate expected dimensions of cubes with sequence after slicing.
     tuple_item = item if isinstance(item, tuple) else (item,)
-    expected_cube0_dims = derive_sliced_cube_dims(ndc.data[tuple_item[0]][0].dimensions, tuple_item)
+    expected_cube0_dims = derive_sliced_cube_dims(ndc.data[tuple_item[0]][0].shape, tuple_item)
     # Assert output is as expected.
     sliced_sequence = ndc[item]
     assert isinstance(sliced_sequence, NDCubeSequence)
-    assert int(sliced_sequence.dimensions[0].value) == tuple_item[0].stop - tuple_item[0].start
-    assert (sliced_sequence[0].dimensions == expected_cube0_dims).all()
+    assert int(sliced_sequence.shape[0].value) == tuple_item[0].stop - tuple_item[0].start
+    assert (sliced_sequence[0].shape == expected_cube0_dims).all()
 
 
 @pytest.mark.parametrize("ndc, item",
@@ -54,9 +54,9 @@
 def test_extract_ndcube(ndc, item):
     cube = ndc[item]
     tuple_item = item if isinstance(item, tuple) else (item,)
-    expected_cube_dims = derive_sliced_cube_dims(ndc.data[tuple_item[0]].dimensions, tuple_item)
+    expected_cube_dims = derive_sliced_cube_dims(ndc.data[tuple_item[0]].shape, tuple_item)
     assert isinstance(cube, NDCube)
-    assert (cube.dimensions == expected_cube_dims).all()
+    assert (cube.shape == expected_cube_dims).all()
 
 
 @pytest.mark.parametrize("ndc, item, expected_common_axis",
@@ -72,7 +72,7 @@
     assert sliced_sequence._common_axis == expected_common_axis
 
 
-@pytest.mark.parametrize("ndc, item, expected_dimensions",
+@pytest.mark.parametrize("ndc, item, expected_shape",
                          (
                              ("ndcubesequence_4c_ln_lt_l_cax1", np.s_[1:7], (3 * u.pix,
                                                                              2 * u.pix,
@@ -96,14 +96,14 @@
                                                                                    2 * u.pix))
                          ),
                          indirect=("ndc",))
-def test_index_as_cube(ndc, item, expected_dimensions):
+def test_index_as_cube(ndc, item, expected_shape):
     sliced_sequence = ndc.index_as_cube[item]
-    sliced_dims = sliced_sequence.dimensions
-    for dim, expected_dim in zip(sliced_dims, expected_dimensions):
+    sliced_dims = sliced_sequence.shape
+    for dim, expected_dim in zip(sliced_dims, expected_shape):
         (dim == expected_dim).all()
 
 
-@pytest.mark.parametrize("ndc, axis, expected_dimensions",
+@pytest.mark.parametrize("ndc, axis, expected_shape",
                          (
                              ("ndcubesequence_4c_ln_lt_l", 0, (8 * u.pix,
                                                                3 * u.pix,
@@ -113,46 +113,46 @@
                                                                     4 * u.pix))
                          ),
                          indirect=("ndc",))
-def test_explode_along_axis_common_axis_None(ndc, axis, expected_dimensions):
+def test_explode_along_axis_common_axis_None(ndc, axis, expected_shape):
     exploded_sequence = ndc.explode_along_axis(axis)
-    assert exploded_sequence.dimensions == expected_dimensions
+    assert exploded_sequence.shape == expected_shape
     assert exploded_sequence._common_axis is None
 
 
 @pytest.mark.parametrize("ndc", (('ndcubesequence_4c_ln_lt_l_cax1',)), indirect=("ndc",))
 def test_explode_along_axis_common_axis_same(ndc):
     exploded_sequence = ndc.explode_along_axis(2)
-    assert exploded_sequence.dimensions == (16*u.pix, 2*u.pix, 3*u.pix)
+    assert exploded_sequence.shape == (16*u.pix, 2*u.pix, 3*u.pix)
     assert exploded_sequence._common_axis == ndc._common_axis
 
 
 @pytest.mark.parametrize("ndc", (('ndcubesequence_4c_ln_lt_l_cax1',)), indirect=("ndc",))
 def test_explode_along_axis_common_axis_changed(ndc):
     exploded_sequence = ndc.explode_along_axis(0)
-    assert exploded_sequence.dimensions == (8*u.pix, 3*u.pix, 4*u.pix)
+    assert exploded_sequence.shape == (8*u.pix, 3*u.pix, 4*u.pix)
     assert exploded_sequence._common_axis == ndc._common_axis - 1
 
 
-@pytest.mark.parametrize("ndc, expected_dimensions",
+@pytest.mark.parametrize("ndc, expected_shape",
                          (
                              ("ndcubesequence_4c_ln_lt_l_cax1", (4 * u.pix,
                                                                  2. * u.pix,
                                                                  3. * u.pix,
                                                                  4. * u.pix)),
                          ),
                          indirect=("ndc",))
-def test_dimensions(ndc, expected_dimensions):
+def test_shape(ndc, expected_shape):
     unit_tester = unittest.TestCase()
-    unit_tester.assertEqual(ndc.dimensions, expected_dimensions)
+    unit_tester.assertEqual(ndc.shape, expected_shape)
 
 
-@pytest.mark.parametrize("ndc, expected_dimensions",
+@pytest.mark.parametrize("ndc, expected_shape",
                          (
                              ("ndcubesequence_4c_ln_lt_l_cax1", [2., 12, 4] * u.pix),
                          ),
                          indirect=("ndc",))
-def test_cube_like_dimensions(ndc, expected_dimensions):
-    assert (ndc.cube_like_dimensions == expected_dimensions).all()
+def test_cube_like_shape(ndc, expected_shape):
+    assert (ndc.cube_like_dimensions == expected_shape).all()
 
 
 @pytest.mark.parametrize("ndc", (("ndcubesequence_4c_ln_lt_l",)), indirect=("ndc",))

ndcube/utils/exceptions.py

@@ -0,0 +1,35 @@
+"""
+This module provides errors/exceptions and warnings of general use for NDCube.
+
+Exceptions that are specific to a given subpackage should **not** be here,
+but rather in the particular package.
+"""
+import warnings
+
+__all__ = ["NDCubeWarning", "NDCubeDeprecationWarning", "warn_deprecated"]
+
+
+class NDCubeWarning(UserWarning):
+    """
+    A general NDCube warning
+    """
+
+class NDCubeDeprecationWarning(FutureWarning, NDCubeWarning):
+    """
+    A warning class to indicate a deprecated feature.
+    """
+
+def warn_deprecated(msg, stacklevel=1):
+    """
+    Raise a `NDCubeDeprecationWarning`.
+
+    Parameters
+    ----------
+    msg : str
+        Warning message.
+    stacklevel : int
+        This is interpreted relative to the call to this function,
+        e.g. ``stacklevel=1`` (the default) sets the stack level in the
+        code that calls this function.
+    """
+    warnings.warn(msg, NDCubeDeprecationWarning , stacklevel + 1)