Add user transition guide to 2.0, allow spectral_axis_index = -1 (#1226)

* Allow -1 as spectral_axis_index

* Add short note about 2.0 to README

* Minor doc tweaks

* Changelog

Author: rosteen

CHANGES.rst

@@ -5,7 +5,7 @@ New Features
 ^^^^^^^^^^^^
 
 - Spectral axis can now be any axis, rather than being forced to be last. See docs
-  for more details. [#1033]
+  for more details. [#1033, #1226]
 
 - Spectrum now properly handles GWCS input for wcs attribute. [#1074]
 
@@ -24,6 +24,8 @@ Other Changes and Additions
 - Spectrum arithmetic now checks whether the spectral axes of the two operand ``Spectrum``
   objects are equal, and fails if they are not. [#1211]
 
+- Added documentation about transitioning from 1.x to 2.x. [#1226]
+
 1.20.0 (unreleased)
 -------------------
 

README.rst

@@ -47,6 +47,12 @@ continue to work on Python 2, it is not tested and support cannot be guaranteed
 (due to the sunsetting of Python 2 support by the Python and Astropy development
 teams).
 
+Migrating from Specutils 1.x to 2.x
+-----------------------------------
+
+For details about breaking changes made in 2.0, please see the
+`specutils documentation <http://specutils.readthedocs.io/en/latest/>`_.
+
 License
 -------
 

docs/index.rst

@@ -27,16 +27,50 @@ guiding document for spectroscopic development in the Astropy Project.
 Changes in version 2
 ====================
 
+The ``Spectrum1D`` class has been renamed to `~specutils.Spectrum` to reduce confusion
+about multi-dimensional flux arrays being supported. The current class name will be
+deprecated in version 2.1; importing the old name will work but raise a deprecation
+warning until then.
+
+Single-dimensional flux use cases should be mostly unchanged in 2.0, with the exception
+being that spectrum arithmetic now checks that the spectral axis of both operands are
+equal, rather than simply checking that they are the same length. Thus, you will need
+to resample onto a common spectral axis if doing arithmetic on spectra with differing
+spectral axes.
+
 Specutils version 2 implemented a major change in that `~specutils.Spectrum`
 no longer forces the spectral axis to be last for multi-dimensional data. This
 was motivated by the desire for greater flexibility to allow for interoperability
 with other packages that may wish to use ``specutils`` classes as the basis for
 their own, and by the desire for consistency with the axis order that results
 from a simple ``astropy.io.fits.read`` of a file. The legacy behavior can be
 replicated by setting ``move_spectral_axis='last'`` when creating a new
-`~specutils.Spectrum` object.
-
-For a summary of other changes in version 2, please see the
+`~specutils.Spectrum` object. `~specutils.Spectrum` will attempt to automatically
+determine which flux axis corresponds to the spectral axis during initialization
+based on the WCS (if provided) or the shape of the flux and spectral axis arrays,
+but if the spectral axis index is unable to be automatically determined you will
+need to specify which flux array axis is the dispersion axis with the
+``spectral_axis_index`` keyword. Note that since the ``spectral_axis`` can specify
+either bin edges or bin centers, a flux array of shape ``(10,11)`` with spectral axis
+of length 11 would be ambigious. In this case you could initialize a
+`~specutils.Spectrum` with ``bin_specification`` set to either "edges" or "centers"
+to break the degeneracy.
+
+An additional change for multi-dimensional spectra is that previously, initializing
+such a `~specutils.Spectrum` with a  ``spectral_axis`` specified, but no WCS, would
+create a `~specutils.Spectrum` instance with a one-dimensional GWCS that was essentially
+a lookup table with the spectral axis values. This case will now result in a GWCS with
+dimensionality matching that of the flux array to facilitate use with downstream packages
+that expect WCS dimensionality to match that of the data. The resulting spatial axes
+transforms are simple pixel to pixel identity operations, since no actual spatial
+coordinate information is available.
+
+In addition to the changes to the generated GWCS, handling of input GWCS has also been
+improved. This mostly manifests in the full GWCS (including spatial information) being
+retained in the resulting `~specutils.Spectrum` objects when reading, e.g., JWST spectral
+cubes.
+
+For a summary of the changes in version 2, you many also refer to the
 `release notes <https://github.com/astropy/specutils/releases>`_.
 
 

specutils/spectra/spectrum.py

@@ -86,6 +86,9 @@ def __init__(self, flux=None, spectral_axis=None, spectral_axis_index=None,
                  redshift=None, radial_velocity=None, bin_specification=None,
                  move_spectral_axis=None, **kwargs):
 
+        if spectral_axis_index == -1:
+            spectral_axis_index = flux.ndim - 1
+
         # If the flux (data) argument is already a Spectrum (as it would
         # be for internal arithmetic operations), avoid setup entirely.
         if isinstance(flux, Spectrum):