DOC: add documentation for kwargs passed to reader+writer backends [c…

…i skip]

docs/spectrum1d.rst

@@ -3,15 +3,15 @@ Working with Spectrum1Ds
 ========================
 
 As described in more detail in :doc:`types_of_spectra`, the core data class in
-specutils for a single spectrum is `~specutils.Spectrum1D`.  This object
+specutils for a single spectrum is :class:`~specutils.Spectrum1D`.  This object
 can represent either one or many spectra, all with the same ``spectral_axis``.
 This section describes some of the basic features of this class.
 
 Basic Spectrum Creation
 -----------------------
 
-The simplest way to create a `~specutils.Spectrum1D` is to
-create it explicitly from arrays or `~astropy.units.Quantity` objects:
+The simplest way to create a :class:`~specutils.Spectrum1D` is to create
+it explicitly from arrays or :class:`~astropy.units.Quantity` objects:
 
 .. plot::
     :include-source:
@@ -94,7 +94,10 @@ installed, which is an optional dependency for ``specutils``.
 
 Call the help function for a specific loader to access further documentation
 on that format and optional parameters accepted by the ``read`` function,
-e.g. as ``Spectrum1D.read.help('tabular-fits')``.
+e.g. as ``Spectrum1D.read.help('tabular-fits')``. Additional optional parameters
+are generally passed through to the backend functions performing the actual
+reading operation, which depend on the loader. For loaders for FITS files for example,
+this will often be :func:`~astropy.io.fits.open`.
 
 More information on creating custom loaders for formats not covered
 by the above list can be found in the :doc:`custom loading </custom_loading>` page.
@@ -115,6 +118,8 @@ any format, will default to the ``wcs1d-fits`` loader if the `~specutils.Spectru
 has a compatible WCS, and to ``tabular-fits`` otherwise, or if writing
 to another than the primary HDU (``hdu=0``) has been selected.
 For better control of the file type, the ``format`` parameter should be explicitly passed.
+Again, additional optional parameters are forwarded to the backend writing functions,
+which for the FITS writers is :meth:`~astropy.io.fits.HDUList.writeto`.
 
 | More information on creating custom writers can be found in :ref:`custom_writer`.
 

specutils/io/default_loaders/ascii.py

@@ -51,7 +51,7 @@ def ascii_loader(file_name, column_mapping=None, **kwargs):
     # If no column mapping is given, attempt to parse the ascii files using
     # unit information
     if column_mapping is None:
-        return generic_spectrum_from_table(tab, **kwargs)
+        return generic_spectrum_from_table(tab)
 
     return spectrum_from_column_mapping(tab, column_mapping)
 
@@ -95,6 +95,6 @@ def ipac_loader(file_name, column_mapping=None, **kwargs):
     # If no column mapping is given, attempt to parse the ascii files using
     # unit information
     if column_mapping is None:
-        return generic_spectrum_from_table(tab, **kwargs)
+        return generic_spectrum_from_table(tab)
 
     return spectrum_from_column_mapping(tab, column_mapping)

specutils/io/default_loaders/generic_ecsv_reader.py

@@ -45,6 +45,6 @@ def generic_ecsv(file_name, column_mapping=None, **kwargs):
     table = Table.read(file_name, format='ascii.ecsv')
 
     if column_mapping is None:
-        return generic_spectrum_from_table(table, **kwargs)
+        return generic_spectrum_from_table(table)
 
     return spectrum_from_column_mapping(table, column_mapping)

specutils/io/default_loaders/tabular_fits.py

@@ -43,16 +43,16 @@ def identify_tabular_fits(origin, *args, **kwargs):
              dtype=Spectrum1D, extensions=['fits', 'fit'], priority=6)
 def tabular_fits_loader(file_obj, column_mapping=None, hdu=1, store_data_header=False, **kwargs):
     """
-    Load spectrum from a FITS file.
+    Load spectrum from a FITS file tabular extension.
 
     Parameters
     ----------
-    file_obj: str, file-like, or HDUList
+    file_obj : str, file-like, or :class:`~astropy.io.fits.HDUList`
             FITS file name, object (provided from name by Astropy I/O Registry),
-            or HDUList (as resulting from astropy.io.fits.open()).
-    hdu: int
+            or HDU list (as resulting from `~astropy.io.fits.open`).
+    hdu : int
         The HDU of the fits file (default: 1st extension) to read from
-    store_data_header: bool
+    store_data_header : bool
         Defaults to ``False``, which stores the primary header in ``Spectrum1D.meta['header']``.
         Set to ``True`` to instead store the header from the specified data HDU.
     column_mapping : dict
@@ -61,14 +61,20 @@ def tabular_fits_loader(file_obj, column_mapping=None, hdu=1, store_data_header=
         information. The dictionary keys should be the FITS file column names
         while the values should be a two-tuple where the first element is the
         associated `Spectrum1D` keyword argument, and the second element is the
-        unit for the ASCII file column::
+        unit for the file column (or ``None`` to take unit from the table header)::
 
-            column_mapping = {'FLUX': ('flux', 'Jy')}
+            column_mapping = {'FLUX': ('flux', 'Jy'),
+                              'WAVE': ('spectral_axis', 'um')}
+
+    **kwargs
+        Additional optional keywords passed to
+        :func:`~specutils.io.parsing_utils.read_fileobj_or_hdulist`, and when
+        reading from a file-like object, through to :func:`~astropy.io.fits.open`.
 
     Returns
     -------
-    data: Spectrum1D
-        The spectrum that is represented by the data in this table.
+    data : :class:`Spectrum1D`
+        The spectrum that is represented by the data in the input table.
     """
     # Parse the wcs information. The wcs will be passed to the column finding
     # routines to search for spectral axis information in the file.
@@ -90,7 +96,7 @@ def tabular_fits_loader(file_obj, column_mapping=None, hdu=1, store_data_header=
     # If no column mapping is given, attempt to parse the file using
     # unit information
     if column_mapping is None:
-        return generic_spectrum_from_table(tab, wcs=wcs, **kwargs)
+        return generic_spectrum_from_table(tab, wcs=wcs)
 
     return spectrum_from_column_mapping(tab, column_mapping, wcs=wcs)
 
@@ -102,15 +108,15 @@ def tabular_fits_writer(spectrum, file_name, hdu=1, update_header=False, store_d
 
     Parameters
     ----------
-    spectrum: Spectrum1D
-    file_name: str
-        The path to the FITS file
-    hdu: int
+    spectrum : :class:`Spectrum1D`
+    file_name : str, file-like or `pathlib.Path`
+        File to write to. If a file object, must be opened in a writeable mode.
+    hdu : int
         Header Data Unit in FITS file to write to (currently only extension HDU 1)
-    update_header: bool
+    update_header : bool
         Write all compatible items in ``Spectrum1D.meta`` directly to FITS header;
         this will overwrite any identically named keys from ``Spectrum1D.meta['header']``.
-    store_data_header: bool
+    store_data_header : bool
         If ``True``, store ``Spectrum1D.meta['header']`` in the header of the target data HDU
         instead of the primary header (default ``False``).
     wunit : str or `~astropy.units.Unit`
@@ -121,6 +127,9 @@ def tabular_fits_writer(spectrum, file_name, hdu=1, update_header=False, store_d
         Floating point type for storing spectral axis array
     ftype : str or `~numpy.dtype`
         Floating point type for storing flux array
+    hdulist : :class:`~astropy.io.fits.HDUList`
+    **kwargs
+        Additional optional keywords passed to :func:`~astropy.io.fits.HDUList.writeto`.
     """
     if hdu < 1:
         raise ValueError(f'FITS does not support BINTABLE extension in HDU {hdu}.')

specutils/io/default_loaders/wcs_fits.py

@@ -92,7 +92,9 @@ def wcs1d_fits_loader(file_obj, spectral_axis_unit=None, flux_unit=None,
         The ``uncertainty_type`` of `~astropy.nddata.NDUncertainty`
         (one of 'std', 'var', 'ivar'; default: try to infer from HDU EXTNAME).
     **kwargs
-        Extra keywords for :func:`~specutils.io.parsing_utils.read_fileobj_or_hdulist`.
+        Additional optional keywords passed to
+        :func:`~specutils.io.parsing_utils.read_fileobj_or_hdulist`, and when
+        reading from a file-like object, through to :func:`~astropy.io.fits.open`.
 
     Returns
     -------
@@ -225,22 +227,24 @@ def wcs1d_fits_writer(spectrum, file_name, hdu=0, update_header=False,
     Parameters
     ----------
     spectrum : :class:`~specutils.Spectrum1D`
-    file_name : str
-        The path to the FITS file
+    file_name : str, file-like or `pathlib.Path`
+        File to write to. If a file object, must be opened in a writeable mode.
     hdu : int, optional
-        Header Data Unit in FITS file to write to (base 0; default primary HDU)
+        Header Data Unit in FITS file to write to (base 0; default primary HDU).
     update_header : bool, optional
-        Update FITS header with all compatible entries in `spectrum.meta`
+        Update FITS header with all compatible entries in `spectrum.meta`.
     flux_name : str, optional
-        HDU name to store flux spectrum under (default 'FLUX')
+        HDU name to store flux spectrum under (default 'FLUX').
     mask_name : str or `None`, optional
-        HDU name to store mask under (default 'MASK'; `None`: do not save)
+        HDU name to store mask under (default 'MASK'; `None`: do not save).
     uncertainty_name : str or `None`, optional
-        HDU name to store uncertainty under (default set from type; `None`: do not save)
+        HDU name to store uncertainty under (default set from type; `None`: do not save).
     unit : str or :class:`~astropy.units.Unit`, optional
-        Unit for the flux (and associated uncertainty; defaults to ``spectrum.flux.unit``)
+        Unit for the flux (and associated uncertainty; defaults to ``spectrum.flux.unit``).
     dtype : str or :class:`~numpy.dtype`, optional
-        Floating point type for storing flux array (defaults to ``spectrum.flux.dtype``)
+        Floating point type for storing flux array (defaults to ``spectrum.flux.dtype``).
+    **kwargs
+        Additional optional keywords passed to :func:`~astropy.io.fits.HDUList.writeto`.
     """
     # Create HDU list from WCS
     try:

specutils/io/parsing_utils.py

@@ -68,10 +68,10 @@ def spectrum_from_column_mapping(table, column_mapping, wcs=None, verbose=False)
         information. The dictionary keys should be the table column names
         while the values should be a two-tuple where the first element is the
         associated `Spectrum1D` keyword argument, and the second element is the
-        unit for the file column (or ``None`` to take unit from the table)::
+        unit for the file column (or ``None`` to take unit from the table header)::
 
             column_mapping = {'FLUX': ('flux', 'Jy'),
-                              'WAVE': ('spectral_axis'spectral_axisu', 'um')}
+                              'WAVE': ('spectral_axis', 'um')}
 
     wcs : :class:`~astropy.wcs.WCS` or :class:`gwcs.WCS`
         WCS object passed to the Spectrum1D initializer.
@@ -138,7 +138,7 @@ def spectrum_from_column_mapping(table, column_mapping, wcs=None, verbose=False)
     return Spectrum1D(**spec_kwargs, wcs=wcs, meta={'header': table.meta})
 
 
-def generic_spectrum_from_table(table, wcs=None, **kwargs):
+def generic_spectrum_from_table(table, wcs=None):
     """
     Load spectrum from an Astropy table into a Spectrum1D object.
     Uses the following logic to figure out which column is which: