Make common kwargs for NDCube.to_nddata explicit in call signature.

Author: DanRyanIrish

ndcube/ndcube.py

@@ -48,6 +48,8 @@
 except ImportError:
     pass
 
+COPY = object()
+
 
 class NDCubeABC(astropy.nddata.NDDataBase):
 
@@ -1461,33 +1463,63 @@ def fill_masked(self, fill_value, uncertainty_fill_value=None, unmask=False, fil
             self.mask = False
         return None
 
-    def to_nddata(self, *, nddata_type=NDData, **kwargs):
+    def to_nddata(self,
+                  *,
+                  data=COPY,
+                  wcs=COPY,
+                  uncertainty=COPY,
+                  mask=COPY,
+                  unit=COPY,
+                  meta=COPY,
+                  psf=COPY,
+                  extra_coords=COPY,
+                  global_coords=COPY,
+                  nddata_type=NDData,
+                  **kwargs,
+                 ):
         """
         Constructs new type instance with the same attribute values as this `~ndcube.NDCube`.
 
+        Attribute values can be altered on the output object by setting a kwarg with the new
+        value, e.g. ``data=new_data``.
         Any attributes not supported by the new class (``nddata_type``), will be discarded.
-        Values of supported attributes can be altered on the output object by setting a
-        kwarg with the new value, e.g. ``data=new_data``.
 
         Parameters
         ----------
-        nddata_type:
+        data: array-like, optional
+            Data array of new instance. Default is to use data of this instance.
+        wcs: `astropy.wcs.wcsapi.BaseLowLevelWCS`, `astropy.wcs.wcsapi.BaseHighLevelWCS`, optional
+            WCS object of new instance. Default is to use data of this instance.
+        uncertainty: Any, optional
+            Uncertainy object of new instance. Default is to use data of this instance.
+        mask: Any, optional
+            Mask object of new instance. Default is to use data of this instance.
+        unit: Any, optional
+            Unit of new instance. Default is to use data of this instance.
+        meta: dict-like, optional
+            Metadata object of new instance. Default is to use data of this instance.
+        psf: Any, optional
+            PSF object of new instance. Default is to use data of this instance.
+        extra_coords: `ndcubeextra_coords.ExtraCoordsABC`, optional
+            Extra coords object of new instance. Default is to use data of this instance.
+        global_coords: `ndcube.global_coords.GlobalCoordsABC`, optional
+            WCS object of new instance. Default is to use data of this instance.
+        nddata_type: Any, optional
             The type of the returned object. Must be a subclass of `~astropy.nddata.NDData`
             or a class that behaves like one.  Default=`~astropy.nddata.NDData`.
-
         kwargs:
-            Inputs to the ``nddata_type`` constructor that should differ from the values
-            stored in attributes of this instance. For example, to set different data values
-            on the returned object, set a kwarg ``data=new_data``, where ``new_data`` is an
-            an array of compatible shape and dtype.  Note that kwargs given by the user and
-            attributes on this instance that are not supported by the ``nddata_type``
-            constructor are ignored.
+            Additional inputs to the ``nddata_type`` constructor that should differ from,
+            or are not represented by, the  attributes of this instance. For example, to
+            set different data values on the returned object, set a kwarg ``data=new_data``,
+            where ``new_data`` is an array of compatible shape and dtype. Note that kwargs
+            given by the user and attributes on this instance that are not supported by the
+            ``nddata_type`` constructor are ignored.
 
         Returns
         -------
-        new_nddata: object
-            An object of class given by ``nddata_type`` with the same attribute values as
-            this `~ndcube.NDCube` instance, except for any alterations specified by the
+        new_nddata: Any
+            The new instance of class given by ``nddata_type`` with the same attribute values
+            as this `~ndcube.NDCube` instance, except for any alterations specified by the
             kwargs.
 
         Examples
@@ -1498,22 +1530,33 @@ def to_nddata(self, *, nddata_type=NDData, **kwargs):
         >>> nddata_without_coords = cube.to_nddata(wcs=None) # doctest: +SKIP
         """
         # Build dictionary of new attribute values from this NDCube instance
-        # and update with user-defined kwargs.
-        new_kwargs = {key.strip("_"): value for key, value in self.__dict__.items()}
-        new_kwargs.update(kwargs)
+        # and update with user-defined kwargs. Remove any kwargs not set by user.
+        user_kwargs = {"data": data,
+                       "wcs": wcs,
+                       "uncertainty": uncertainty,
+                       "mask": mask,
+                       "unit": unit,
+                       "meta": meta,
+                       "psf": psf,
+                       "extra_coords": extra_coords,
+                       "global_coords": global_coords}
+        user_kwargs = {key: value for key, value in user_kwargs.items() if value is not COPY}
+        user_kwargs.update(kwargs)
+        all_kwargs = {key.strip("_"): value for key, value in self.__dict__.items()}
+        all_kwargs.update(user_kwargs)
         extra_coords, global_coords = None, None
         if nddata_type is NDCube:
-            extra_coords = new_kwargs.pop("extra_coords")
-            global_coords = new_kwargs.pop("global_coords")
+            extra_coords = all_kwargs.pop("extra_coords")
+            global_coords = all_kwargs.pop("global_coords")
         # Inspect call signature of new_nddata class and
         # remove unsupported items from new_kwargs.
         nddata_sig = inspect.signature(nddata_type).parameters.keys()
-        new_kwarg_keys = list(new_kwargs.keys())
-        for key in new_kwarg_keys:
+        all_kwarg_keys = list(all_kwargs.keys())
+        for key in all_kwarg_keys:
             if key not in nddata_sig:
-                del new_kwargs[key]
+                del all_kwargs[key]
         # Construct and return new instance.
-        new_nddata = nddata_type(**new_kwargs)
+        new_nddata = nddata_type(**all_kwargs)
         if extra_coords:
             extra_coords._ndcube = new_nddata
             new_nddata._extra_coords = extra_coords