From 35f1222dac44ceaa05e18db86058fa2461935e23 Mon Sep 17 00:00:00 2001 From: Kyle Westfall Date: Wed, 9 Aug 2023 14:19:09 -0700 Subject: [PATCH] doc fixes + package updates --- README.rst | 3 +- doc/conf.py | 2 +- doc/help/run_pypeit.rst | 2 +- doc/include/class_datamodel_datacube.rst | 24 +- doc/include/dependencies_table.rst | 2 +- doc/include/links.rst | 2 + doc/spectrographs/gemini_gmos.rst | 3 +- doc/spectrographs/mmt_bluechannel.rst | 3 +- doc/spectrographs/soar_goodman.rst | 1 + doc/spectrographs/spectrographs.rst | 2 + pypeit/bitmask.py | 2 - pypeit/core/datacube.py | 297 +++++++++++++---------- pypeit/datamodel.py | 2 - pypeit/images/bitmaskarray.py | 2 - pypeit/par/pypeitpar.py | 2 - setup.cfg | 14 +- 16 files changed, 209 insertions(+), 154 deletions(-) diff --git a/README.rst b/README.rst index 58edc7eac5..1bfea2284e 100644 --- a/README.rst +++ b/README.rst @@ -171,4 +171,5 @@ development of PypeIt. * Timothy Pickering * Timothy Ellsworth-Bowers * Gregory Simonian -* Heather Martin \ No newline at end of file +* Heather Martin + diff --git a/doc/conf.py b/doc/conf.py index 9ecfc8023f..50a0c7a93d 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -349,5 +349,5 @@ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} +intersphinx_mapping = {'python': ('https://docs.python.org/3', None)} diff --git a/doc/help/run_pypeit.rst b/doc/help/run_pypeit.rst index b281fa0597..9e72e0f556 100644 --- a/doc/help/run_pypeit.rst +++ b/doc/help/run_pypeit.rst @@ -4,7 +4,7 @@ usage: run_pypeit [-h] [-v VERBOSITY] [-r REDUX_PATH] [-m] [-s] [-o] [-c] pypeit_file - ## PypeIt : The Python Spectroscopic Data Reduction Pipeline v1.13.1.dev537+g0261baa1b.d20230728 + ## PypeIt : The Python Spectroscopic Data Reduction Pipeline v1.13.1.dev562+g146ed41eb.d20230809 ## ## Available spectrographs include: ## bok_bc, gemini_flamingos1, gemini_flamingos2, gemini_gmos_north_e2v, diff --git a/doc/include/class_datamodel_datacube.rst b/doc/include/class_datamodel_datacube.rst index 2a2ac61bf3..6449104d1b 100644 --- a/doc/include/class_datamodel_datacube.rst +++ b/doc/include/class_datamodel_datacube.rst @@ -1,15 +1,15 @@ **Version**: 1.1.0 -============== ================ ================= ================================================================================ -Attribute Type Array Type Description -============== ================ ================= ================================================================================ -``PYP_SPEC`` str PypeIt: Spectrograph name -``blaze_spec`` `numpy.ndarray`_ `numpy.floating`_ The spectral blaze function -``blaze_wave`` `numpy.ndarray`_ `numpy.floating`_ Wavelength array of the spectral blaze function -``bpm`` `numpy.ndarray`_ `numpy.uint8`_ Bad pixel mask of the datacube (0=good, 1=bad) -``flux`` `numpy.ndarray`_ `numpy.floating`_ Flux datacube in units of counts/s/Ang/arcsec^2or 10^-17 erg/s/cm^2/Ang/arcsec^2 -``fluxed`` bool Boolean indicating if the datacube is fluxed. -``sensfunc`` `numpy.ndarray`_ `numpy.floating`_ Sensitivity function 10^-17 erg/(counts/cm^2) -``sig`` `numpy.ndarray`_ `numpy.floating`_ Error datacube (matches units of flux) -============== ================ ================= ================================================================================ +============== ================ ================= ================================================================================= +Attribute Type Array Type Description +============== ================ ================= ================================================================================= +``PYP_SPEC`` str PypeIt: Spectrograph name +``blaze_spec`` `numpy.ndarray`_ `numpy.floating`_ The spectral blaze function +``blaze_wave`` `numpy.ndarray`_ `numpy.floating`_ Wavelength array of the spectral blaze function +``bpm`` `numpy.ndarray`_ `numpy.uint8`_ Bad pixel mask of the datacube (0=good, 1=bad) +``flux`` `numpy.ndarray`_ `numpy.floating`_ Flux datacube in units of counts/s/Ang/arcsec^2 or 10^-17 erg/s/cm^2/Ang/arcsec^2 +``fluxed`` bool Boolean indicating if the datacube is fluxed. +``sensfunc`` `numpy.ndarray`_ `numpy.floating`_ Sensitivity function 10^-17 erg/(counts/cm^2) +``sig`` `numpy.ndarray`_ `numpy.floating`_ Error datacube (matches units of flux) +============== ================ ================= ================================================================================= diff --git a/doc/include/dependencies_table.rst b/doc/include/dependencies_table.rst index 28e333784a..d4a0372b79 100644 --- a/doc/include/dependencies_table.rst +++ b/doc/include/dependencies_table.rst @@ -1,5 +1,5 @@ ======================= ================================================================================================================================================================================================================================================================================================= Python Version ``>=3.9,<3.12`` Required for users ``IPython>=7.10.0``, ``PyYAML>=5.1``, ``astropy>=4.3``, ``bottleneck``, ``configobj>=5.0.6``, ``extension-helpers>=0.1``, ``ginga>=3.2``, ``linetools``, ``matplotlib>=3.7``, ``numpy>=1.22``, ``packaging>=0.19``, ``pygithub``, ``pyqt6``, ``qtpy>=1.9``, ``scikit-learn>=1.0``, ``scipy>=1.7`` -Required for developers ``coverage``, ``docutils<0.18``, ``pytest-astropy``, ``pytest-cov``, ``pytest>=6.0.0``, ``sphinx-automodapi``, ``sphinx<6,>=1.6``, ``sphinx_rtd_theme==1.1.1``, ``tox`` +Required for developers ``coverage``, ``docutils<0.19``, ``pytest-astropy``, ``pytest-cov``, ``pytest>=6.0.0``, ``scikit-image``, ``specutils``, ``sphinx-automodapi``, ``sphinx<7,>=1.6``, ``sphinx_rtd_theme==1.2.2``, ``tox`` ======================= ================================================================================================================================================================================================================================================================================================= diff --git a/doc/include/links.rst b/doc/include/links.rst index 0138a4a60f..dddaf2ac0d 100644 --- a/doc/include/links.rst +++ b/doc/include/links.rst @@ -154,3 +154,5 @@ .. _L.A.Cosmic: http://www.astro.yale.edu/dokkum/lacosmic/ .. _van Dokkum (2001, PASP, 113, 1420): https://ui.adsabs.harvard.edu/abs/2001PASP..113.1420V/abstract .. _LowRedux: http://www.ucolick.org/~xavier/LowRedux/ + + diff --git a/doc/spectrographs/gemini_gmos.rst b/doc/spectrographs/gemini_gmos.rst index bcf44a1b72..4a64176f10 100644 --- a/doc/spectrographs/gemini_gmos.rst +++ b/doc/spectrographs/gemini_gmos.rst @@ -163,4 +163,5 @@ The modifications to the :ref:`pypeit_file` will look like: The two files provided must be located either: (1) in the path(s) of the raw files provided in the :ref:`data_block`, (2) the current working data, and/or - (3) be named with the full path. \ No newline at end of file + (3) be named with the full path. + diff --git a/doc/spectrographs/mmt_bluechannel.rst b/doc/spectrographs/mmt_bluechannel.rst index 65f86da6ba..b865873649 100644 --- a/doc/spectrographs/mmt_bluechannel.rst +++ b/doc/spectrographs/mmt_bluechannel.rst @@ -43,4 +43,5 @@ A few notes on setting up observations to work optimally with ``pypeit`` and wha this is not the case or otherwise define which observations are standard stars. * Images taken as part of spectrograph focus runs are automatically identified and configured as ``tilt`` images, but not ``arc``. This - is because their line widths can vary by quite a bit and thus shouldn't be coadded to/averaged with in-focus ``arc`` images. \ No newline at end of file + is because their line widths can vary by quite a bit and thus shouldn't be coadded to/averaged with in-focus ``arc`` images. + diff --git a/doc/spectrographs/soar_goodman.rst b/doc/spectrographs/soar_goodman.rst index b12175048f..d8f6f34726 100644 --- a/doc/spectrographs/soar_goodman.rst +++ b/doc/spectrographs/soar_goodman.rst @@ -15,3 +15,4 @@ archive: PypeIt will only work with the .fz format, so please ensure that you are only using data in this format. + diff --git a/doc/spectrographs/spectrographs.rst b/doc/spectrographs/spectrographs.rst index 7f278b754f..822fd9a3a1 100644 --- a/doc/spectrographs/spectrographs.rst +++ b/doc/spectrographs/spectrographs.rst @@ -53,3 +53,5 @@ instrument-specific details for running PypeIt. shane_kast soar_goodman xshooter + + diff --git a/pypeit/bitmask.py b/pypeit/bitmask.py index 499ec57bb2..caa92c96d5 100644 --- a/pypeit/bitmask.py +++ b/pypeit/bitmask.py @@ -8,8 +8,6 @@ .. include:: ../include/bitmask_usage.rst ----- - .. include common links, assuming primary doc root is up one directory .. include:: ../include/links.rst diff --git a/pypeit/core/datacube.py b/pypeit/core/datacube.py index c88c06fbc2..b1e60aa118 100644 --- a/pypeit/core/datacube.py +++ b/pypeit/core/datacube.py @@ -1,7 +1,6 @@ """ Module containing routines used by 3D datacubes. -.. include common links, assuming primary doc root is up one directory .. include:: ../include/links.rst """ @@ -60,25 +59,31 @@ class DataCube(datamodel.DataContainer): If the cube has been flux calibrated, this will be set to "True" Attributes: - head0 (`astropy.io.fits.Header`): + head0 (`astropy.io.fits.Header`_): Primary header filename (str): Filename to use when loading from file spect_meta (:obj:`dict`): Parsed meta from the header - spectrograph (:class:`pypeit.spectrographs.spectrograph.Spectrograph`): + spectrograph (:class:`~pypeit.spectrographs.spectrograph.Spectrograph`): Build from PYP_SPEC """ version = '1.1.0' - datamodel = {'flux': dict(otype=np.ndarray, atype=np.floating, descr='Flux datacube in units of counts/s/Ang/arcsec^2' - 'or 10^-17 erg/s/cm^2/Ang/arcsec^2'), - 'sig': dict(otype=np.ndarray, atype=np.floating, descr='Error datacube (matches units of flux)'), - 'bpm': dict(otype=np.ndarray, atype=np.uint8, descr='Bad pixel mask of the datacube (0=good, 1=bad)'), - 'blaze_wave': dict(otype=np.ndarray, atype=np.floating, descr='Wavelength array of the spectral blaze function'), - 'blaze_spec': dict(otype=np.ndarray, atype=np.floating, descr='The spectral blaze function'), - 'sensfunc': dict(otype=np.ndarray, atype=np.floating, descr='Sensitivity function 10^-17 erg/(counts/cm^2)'), + datamodel = {'flux': dict(otype=np.ndarray, atype=np.floating, + descr='Flux datacube in units of counts/s/Ang/arcsec^2 or ' + '10^-17 erg/s/cm^2/Ang/arcsec^2'), + 'sig': dict(otype=np.ndarray, atype=np.floating, + descr='Error datacube (matches units of flux)'), + 'bpm': dict(otype=np.ndarray, atype=np.uint8, + descr='Bad pixel mask of the datacube (0=good, 1=bad)'), + 'blaze_wave': dict(otype=np.ndarray, atype=np.floating, + descr='Wavelength array of the spectral blaze function'), + 'blaze_spec': dict(otype=np.ndarray, atype=np.floating, + descr='The spectral blaze function'), + 'sensfunc': dict(otype=np.ndarray, atype=np.floating, + descr='Sensitivity function 10^-17 erg/(counts/cm^2)'), 'PYP_SPEC': dict(otype=str, descr='PypeIt: Spectrograph name'), 'fluxed': dict(otype=bool, descr='Boolean indicating if the datacube is fluxed.')} @@ -88,7 +93,8 @@ class DataCube(datamodel.DataContainer): 'spect_meta' ] - def __init__(self, flux, sig, bpm, PYP_SPEC, blaze_wave, blaze_spec, sensfunc=None, fluxed=None): + def __init__(self, flux, sig, bpm, PYP_SPEC, blaze_wave, blaze_spec, sensfunc=None, + fluxed=None): args, _, _, values = inspect.getargvalues(inspect.currentframe()) _d = dict([(k, values[k]) for k in args[1:]]) @@ -127,15 +133,19 @@ def _bundle(self): def to_file(self, ofile, primary_hdr=None, hdr=None, **kwargs): """ - Over-load :func:`pypeit.datamodel.DataContainer.to_file` + Over-load :func:`~pypeit.datamodel.DataContainer.to_file` to deal with the header Args: - ofile (:obj:`str`): Filename + ofile (:obj:`str`): + Filename primary_hdr (`astropy.io.fits.Header`_, optional): + Base primary header. Updated with new subheader keywords. If + None, initialized using :func:`~pypeit.io.initialize_header`. wcs (`astropy.io.fits.Header`_, optional): The World Coordinate System, represented by a fits header - **kwargs: Passed to super.to_file() + kwargs (dict): + Keywords passed directly to parent ``to_file`` function. """ if primary_hdr is None: @@ -155,7 +165,7 @@ def to_file(self, ofile, primary_hdr=None, hdr=None, **kwargs): @classmethod def from_file(cls, ifile): """ - Over-load :func:`pypeit.datamodel.DataContainer.from_file` + Over-load :func:`~pypeit.datamodel.DataContainer.from_file` to deal with the header Args: @@ -181,14 +191,16 @@ def wcs(self): return wcs.WCS(self.head0) -def dar_fitfunc(radec, coord_ra, coord_dec, datfit, wave, obstime, location, pressure, temperature, rel_humidity): +def dar_fitfunc(radec, coord_ra, coord_dec, datfit, wave, obstime, location, pressure, + temperature, rel_humidity): """ Generates a fitting function to calculate the offset due to differential atmospheric refraction Args: radec (tuple): - A tuple containing two floats representing the shift in ra and dec due to DAR. + A tuple containing two floats representing the shift in ra and dec + due to DAR. coord_ra (float): RA in degrees coord_dec (float): @@ -256,9 +268,9 @@ def correct_dar(wave_arr, coord, obstime, location, pressure, temperature, rel_h Returns ------- ra_diff : `numpy.ndarray`_ - Relative RA shift at each wavelength given by `wave_arr` + Relative RA shift at each wavelength given by ``wave_arr`` dec_diff : `numpy.ndarray`_ - Relative DEC shift at each wavelength given by `wave_arr` + Relative DEC shift at each wavelength given by ``wave_arr`` """ msgs.info("Performing differential atmospheric refraction correction") if wave_ref is None: @@ -294,10 +306,11 @@ def correct_dar(wave_arr, coord, obstime, location, pressure, temperature, rel_h def correct_grating_shift(wave_eval, wave_curr, spl_curr, wave_ref, spl_ref, order=2): - """ Using spline representations of the blaze profile, calculate the grating correction - that should be applied to the current spectrum (suffix 'curr') relative to the reference - spectrum (suffix 'ref'). The grating correction is then evaluated at the wavelength - array given by 'wave_eval'. + """ + Using spline representations of the blaze profile, calculate the grating + correction that should be applied to the current spectrum (suffix ``curr``) + relative to the reference spectrum (suffix ``ref``). The grating correction + is then evaluated at the wavelength array given by ``wave_eval``. Args: wave_eval (`numpy.ndarray`_): @@ -314,7 +327,7 @@ def correct_grating_shift(wave_eval, wave_curr, spl_curr, wave_ref, spl_ref, ord Polynomial order used to fit the grating correction. Returns: - grat_corr (`numpy.ndarray`_): The grating correction to apply + `numpy.ndarray`_: The grating correction to apply """ msgs.info("Calculating the grating correction") # Calculate the grating correction @@ -331,15 +344,19 @@ def correct_grating_shift(wave_eval, wave_curr, spl_curr, wave_ref, spl_ref, ord def gaussian2D_cube(tup, intflux, xo, yo, dxdz, dydz, sigma_x, sigma_y, theta, offset): - """ Fit a 2D Gaussian function to a datacube. This function assumes that each wavelength - slice of the datacube is well-fit by a 2D Gaussian. The centre of the Gaussian is allowed - to vary linearly as a function of wavelength. + """ + Fit a 2D Gaussian function to a datacube. This function assumes that each + wavelength slice of the datacube is well-fit by a 2D Gaussian. The centre of + the Gaussian is allowed to vary linearly as a function of wavelength. + + .. note:: - NOTE : the integrated flux does not vary with wavelength. + The integrated flux does not vary with wavelength. Args: tup (:obj:`tuple`): - A three element tuple containing the x, y, and z locations of each pixel in the cube + A three element tuple containing the x, y, and z locations of each + pixel in the cube intflux (float): The Integrated flux of the Gaussian xo (float): @@ -360,7 +377,7 @@ def gaussian2D_cube(tup, intflux, xo, yo, dxdz, dydz, sigma_x, sigma_y, theta, o Constant offset Returns: - gtwod (`numpy.ndarray`_): The 2D Gaussian evaluated at the coordinate (x, y, z) + `numpy.ndarray`_: The 2D Gaussian evaluated at the coordinate (x, y, z) """ # Extract the (x, y, z) coordinates of each pixel from the tuple (x, y, z) = tup @@ -378,11 +395,13 @@ def gaussian2D_cube(tup, intflux, xo, yo, dxdz, dydz, sigma_x, sigma_y, theta, o def gaussian2D(tup, intflux, xo, yo, sigma_x, sigma_y, theta, offset): - """ Fit a 2D Gaussian function to an image. + """ + Fit a 2D Gaussian function to an image. Args: tup (:obj:`tuple`): - A two element tuple containing the x and y coordinates of each pixel in the image + A two element tuple containing the x and y coordinates of each pixel + in the image intflux (float): The Integrated flux of the 2D Gaussian xo (float): @@ -399,7 +418,7 @@ def gaussian2D(tup, intflux, xo, yo, sigma_x, sigma_y, theta, offset): Constant offset Returns: - gtwod (`numpy.ndarray`_): The 2D Gaussian evaluated at the coordinate (x, y) + `numpy.ndarray`_: The 2D Gaussian evaluated at the coordinate (x, y) """ # Extract the (x, y, z) coordinates of each pixel from the tuple (x, y) = tup @@ -441,7 +460,6 @@ def fitGaussian2D(image, norm=False): of the model. pcov : `numpy.ndarray`_ Corresponding covariance matrix - """ # Normalise if requested wlscl = np.max(image) if norm else 1 @@ -462,21 +480,29 @@ def fitGaussian2D(image, norm=False): def extract_standard_spec(stdcube, subpixel=20, method='boxcar'): - """ Extract a spectrum of a standard star from a datacube + """ + Extract a spectrum of a standard star from a datacube - Args: - std_cube (`astropy.io.fits.HDUList`_): - An HDU list of fits files - subpixel (int): - Number of pixels to subpixelate spectrum when creating mask - method (str): - Method used to extract standard star spectrum. Currently, only 'boxcar' is supported + Parameters + ---------- + std_cube : `astropy.io.fits.HDUList`_ + An HDU list of fits files + subpixel : int + Number of pixels to subpixelate spectrum when creating mask + method : str + Method used to extract standard star spectrum. Currently, only 'boxcar' + is supported - Returns: - wave (`numpy.ndarray`_): Wavelength of the star. - Nlam_star (`numpy.ndarray`_): counts/second/Angstrom - Nlam_ivar_star (`numpy.ndarray`_): inverse variance of Nlam_star - gpm_star (`numpy.ndarray`_): good pixel mask for Nlam_star + Returns + ------- + wave : `numpy.ndarray`_ + Wavelength of the star. + Nlam_star : `numpy.ndarray`_ + counts/second/Angstrom + Nlam_ivar_star : `numpy.ndarray`_ + inverse variance of Nlam_star + gpm_star : `numpy.ndarray`_ + good pixel mask for Nlam_star """ # Extract some information from the HDU list flxcube = stdcube['FLUX'].data.T.copy() @@ -635,10 +661,11 @@ def extract_standard_spec(stdcube, subpixel=20, method='boxcar'): def make_good_skymask(slitimg, tilts): - """ Mask the spectral edges of each slit (i.e. the pixels near the ends of - the detector in the spectral direction). Some extreme values of the tilts are - only sampled with a small fraction of the pixels of the slit width. This leads - to a bad extrapolation/determination of the sky model. + """ + Mask the spectral edges of each slit (i.e. the pixels near the ends of the + detector in the spectral direction). Some extreme values of the tilts are + only sampled with a small fraction of the pixels of the slit width. This + leads to a bad extrapolation/determination of the sky model. Args: slitimg (`numpy.ndarray`_): @@ -647,7 +674,7 @@ def make_good_skymask(slitimg, tilts): Spectral tilts. Returns: - gpm (`numpy.ndarray`_): A mask of the good sky pixels (True = good) + `numpy.ndarray`_: A mask of the good sky pixels (True = good) """ msgs.info("Masking edge pixels where the sky model is poor") # Initialise the GPM @@ -735,22 +762,26 @@ def get_whitelight_range(wavemin, wavemax, wl_range): def make_whitelight_fromcube(cube, wave=None, wavemin=None, wavemax=None): - """ Generate a white light image using an input cube. + """ + Generate a white light image using an input cube. Args: cube (`numpy.ndarray`_): 3D datacube (the final element contains the wavelength dimension) wave (`numpy.ndarray`_, optional): - 1D wavelength array. Only required if wavemin or wavemax are not None. - wavemin (float, None): - Minimum wavelength (same units as wave) to be included in the whitelight image. - You must provide wave as well if you want to reduce the wavelength range. - wavemax (float, None): - Maximum wavelength (same units as wave) to be included in the whitelight image. - You must provide wave as well if you want to reduce the wavelength range. + 1D wavelength array. Only required if wavemin or wavemax are not + None. + wavemin (float, optional): + Minimum wavelength (same units as wave) to be included in the + whitelight image. You must provide wave as well if you want to + reduce the wavelength range. + wavemax (float, optional): + Maximum wavelength (same units as wave) to be included in the + whitelight image. You must provide wave as well if you want to + reduce the wavelength range. Returns: - wl_img (`numpy.ndarray`_): Whitelight image of the input cube. + `numpy.ndarray`_: Whitelight image of the input cube. """ # Make a wavelength cut, if requested cutcube = cube.copy() @@ -777,7 +808,8 @@ def make_whitelight_fromcube(cube, wave=None, wavemin=None, wavemax=None): def load_imageWCS(filename, ext=0): - """ Load an image and return the image and the associated WCS. + """ + Load an image and return the image and the associated WCS. Args: filename (str): @@ -799,29 +831,37 @@ def load_imageWCS(filename, ext=0): def make_whitelight_frompixels(all_ra, all_dec, all_wave, all_sci, all_wghts, all_idx, dspat, all_ivar=None, whitelightWCS=None, numra=None, numdec=None, trim=1): - """ Generate a whitelight image using the individual pixels of every input frame + """ + Generate a whitelight image using the individual pixels of every input frame Args: all_ra (`numpy.ndarray`_): - 1D flattened array containing the RA values of each pixel from all spec2d files + 1D flattened array containing the RA values of each pixel from all + spec2d files all_dec (`numpy.ndarray`_): - 1D flattened array containing the DEC values of each pixel from all spec2d files + 1D flattened array containing the DEC values of each pixel from all + spec2d files all_wave (`numpy.ndarray`_): - 1D flattened array containing the wavelength values of each pixel from all spec2d files + 1D flattened array containing the wavelength values of each pixel + from all spec2d files all_sci (`numpy.ndarray`_): - 1D flattened array containing the counts of each pixel from all spec2d files + 1D flattened array containing the counts of each pixel from all + spec2d files all_wghts (`numpy.ndarray`_): - 1D flattened array containing the weights attributed to each pixel from all spec2d files + 1D flattened array containing the weights attributed to each pixel + from all spec2d files all_idx (`numpy.ndarray`_): - 1D flattened array containing an integer identifier indicating which spec2d file - each pixel originates from. For example, a 0 would indicate that a pixel originates - from the first spec2d frame listed in the input file. a 1 would indicate that this - pixel originates from the second spec2d file, and so forth. + 1D flattened array containing an integer identifier indicating which + spec2d file each pixel originates from. For example, a 0 would + indicate that a pixel originates from the first spec2d frame listed + in the input file. a 1 would indicate that this pixel originates + from the second spec2d file, and so forth. dspat (float): The size of each spaxel on the sky (in degrees) all_ivar (`numpy.ndarray`_, optional): - 1D flattened array containing of the inverse variance of each pixel from all spec2d files. - If provided, inverse variance images will be calculated and returned for each white light image. + 1D flattened array containing of the inverse variance of each pixel + from all spec2d files. If provided, inverse variance images will be + calculated and returned for each white light image. whitelightWCS (`astropy.wcs.WCS`_, optional): The WCS of a reference white light image. If supplied, you must also supply numra and numdec. @@ -833,10 +873,11 @@ def make_whitelight_frompixels(all_ra, all_dec, all_wave, all_sci, all_wghts, al Number of pixels to grow around a masked region Returns: - tuple : two 3D arrays will be returned, each of shape [N, M, numfiles], - where N and M are the spatial dimensions of the combined white light images. - The first array is a white light image, and the second array is the corresponding - inverse variance image. If all_ivar is None, this will be an empty array. + tuple: two 3D arrays will be returned, each of shape [N, M, numfiles], + where N and M are the spatial dimensions of the combined white light + images. The first array is a white light image, and the second array is + the corresponding inverse variance image. If all_ivar is None, this will + be an empty array. """ # Determine number of files numfiles = np.unique(all_idx).size @@ -1028,40 +1069,49 @@ def generate_WCS(crval, cdelt, equinox=2000.0, name="PYP_SPEC"): def compute_weights(all_ra, all_dec, all_wave, all_sci, all_ivar, all_idx, whitelight_img, dspat, dwv, sn_smooth_npix=None, relative_weights=False): - """ Calculate wavelength dependent optimal weights. The weighting - is currently based on a relative (S/N)^2 at each wavelength + r""" + Calculate wavelength dependent optimal weights. The weighting is currently + based on a relative :math:`(S/N)^2` at each wavelength Args: all_ra (`numpy.ndarray`_): - 1D flattened array containing the RA values of each pixel from all spec2d files + 1D flattened array containing the RA values of each pixel from all + spec2d files all_dec (`numpy.ndarray`_): - 1D flattened array containing the DEC values of each pixel from all spec2d files + 1D flattened array containing the DEC values of each pixel from all + spec2d files all_wave (`numpy.ndarray`_): - 1D flattened array containing the wavelength values of each pixel from all spec2d files + 1D flattened array containing the wavelength values of each pixel + from all spec2d files all_sci (`numpy.ndarray`_): - 1D flattened array containing the counts of each pixel from all spec2d files + 1D flattened array containing the counts of each pixel from all + spec2d files all_ivar (`numpy.ndarray`_): - 1D flattened array containing the inverse variance of each pixel from all spec2d files + 1D flattened array containing the inverse variance of each pixel + from all spec2d files all_idx (`numpy.ndarray`_): - 1D flattened array containing an integer identifier indicating which spec2d file - each pixel originates from. For example, a 0 would indicate that a pixel originates - from the first spec2d frame listed in the input file. a 1 would indicate that this - pixel originates from the second spec2d file, and so forth. + 1D flattened array containing an integer identifier indicating which + spec2d file each pixel originates from. For example, a 0 would + indicate that a pixel originates from the first spec2d frame listed + in the input file. a 1 would indicate that this pixel originates + from the second spec2d file, and so forth. whitelight_img (`numpy.ndarray`_): - A 2D array containing a whitelight image, that was created with the input all_* arrays. + A 2D array containing a whitelight image, that was created with the + input ``all_`` arrays. dspat (float): The size of each spaxel on the sky (in degrees) dwv (float): The size of each wavelength pixel (in Angstroms) sn_smooth_npix (float, optional): - Number of pixels used for determining smoothly varying S/N ratio weights. - This is currently not required, since a relative weighting scheme with a - polynomial fit is used to calculate the S/N weights. + Number of pixels used for determining smoothly varying S/N ratio + weights. This is currently not required, since a relative weighting + scheme with a polynomial fit is used to calculate the S/N weights. relative_weights (bool, optional): Calculate weights by fitting to the ratio of spectra? + Returns: - `numpy.ndarray`_ : a 1D array the same size as all_sci, containing relative wavelength - dependent weights of each input pixel. + `numpy.ndarray`_ : a 1D array the same size as all_sci, containing + relative wavelength dependent weights of each input pixel. """ msgs.info("Calculating the optimal weights of each pixel") # Determine number of files @@ -1176,13 +1226,13 @@ def generate_image_subpixel(image_wcs, all_ra, all_dec, all_wave, all_sci, all_i spec_subpixel (:obj:`int`, optional): What is the subpixellation factor in the spectral direction. Higher values give more reliable results, but note that the time required - goes as (spec_subpixel * spat_subpixel). The default value is 5, + goes as (``spec_subpixel * spat_subpixel``). The default value is 5, which divides each detector pixel into 5 subpixels in the spectral direction. spat_subpixel (:obj:`int`, optional): What is the subpixellation factor in the spatial direction. Higher values give more reliable results, but note that the time required - goes as (spec_subpixel * spat_subpixel). The default value is 5, + goes as (``spec_subpixel * spat_subpixel``). The default value is 5, which divides each detector pixel into 5 subpixels in the spatial direction. combine (:obj:`bool`, optional): @@ -1232,7 +1282,7 @@ def generate_cube_subpixel(outfile, output_wcs, all_ra, all_dec, all_wave, all_s all_idx=None, spec_subpixel=10, spat_subpixel=10, overwrite=False, blaze_wave=None, blaze_spec=None, fluxcal=False, sensfunc=None, whitelight_range=None, specname="PYP_SPEC", debug=False): - """ + r""" Save a datacube using the subpixel algorithm. Refer to the subpixellate() docstring for further details about this algorithm @@ -1288,13 +1338,13 @@ def generate_cube_subpixel(outfile, output_wcs, all_ra, all_dec, all_wave, all_s spec_subpixel (int, optional): What is the subpixellation factor in the spectral direction. Higher values give more reliable results, but note that the time required - goes as (spec_subpixel * spat_subpixel). The default value is 5, + goes as (``spec_subpixel * spat_subpixel``). The default value is 5, which divides each detector pixel into 5 subpixels in the spectral direction. spat_subpixel (int, optional): What is the subpixellation factor in the spatial direction. Higher values give more reliable results, but note that the time required - goes as (spec_subpixel * spat_subpixel). The default value is 5, + goes as (``spec_subpixel * spat_subpixel``). The default value is 5, which divides each detector pixel into 5 subpixels in the spatial direction. overwrite (bool, optional): @@ -1304,9 +1354,10 @@ def generate_cube_subpixel(outfile, output_wcs, all_ra, all_dec, all_wave, all_s blaze_spec (`numpy.ndarray`_, optional): Spectral blaze function fluxcal (bool, optional): - Are the data flux calibrated? If True, the units are: - erg/s/cm^2/Angstrom/arcsec^2 multiplied by the PYPEIT_FLUX_SCALE. - Otherwise, the units are: counts/s/Angstrom/arcsec^2 + Are the data flux calibrated? If True, the units are: :math:`{\rm + erg/s/cm}^2{\rm /Angstrom/arcsec}^2` multiplied by the + PYPEIT_FLUX_SCALE. Otherwise, the units are: :math:`{\rm + counts/s/Angstrom/arcsec}^2`. sensfunc (`numpy.ndarray`_, None, optional): Sensitivity function that has been applied to the datacube whitelight_range (None, list, optional): @@ -1377,13 +1428,13 @@ def generate_cube_subpixel(outfile, output_wcs, all_ra, all_dec, all_wave, all_s def subpixellate(output_wcs, all_ra, all_dec, all_wave, all_sci, all_ivar, all_wghts, all_spatpos, all_specpos, all_spatid, tilts, slits, astrom_trans, bins, all_idx=None, spec_subpixel=10, spat_subpixel=10, debug=False): - """ - Subpixellate the input data into a datacube. This algorithm splits - each detector pixel into multiple subpixels, and then assigns each - subpixel to a voxel. For example, if spec_subpixel = spat_subpixel = 10, - then each detector pixel is divided into 10^2=100 subpixels. Alternatively, - when spec_subpixel = spat_subpixel = 1, this corresponds to the nearest - grid point (NGP) algorithm. + r""" + Subpixellate the input data into a datacube. This algorithm splits each + detector pixel into multiple subpixels, and then assigns each subpixel to a + voxel. For example, if ``spec_subpixel = spat_subpixel = 10``, then each + detector pixel is divided into :math:`10^2=100` subpixels. Alternatively, + when spec_subpixel = spat_subpixel = 1, this corresponds to the nearest grid + point (NGP) algorithm. Important Note: If spec_subpixel > 1 or spat_subpixel > 1, the errors will be correlated, and the covariance is not being tracked, so the errors will @@ -1393,13 +1444,13 @@ def subpixellate(output_wcs, all_ra, all_dec, all_wave, all_sci, all_ivar, all_w Args: output_wcs (`astropy.wcs.WCS`_): Output world coordinate system. - all_ra (`numpy.ndarray`_) + all_ra (`numpy.ndarray`_): 1D flattened array containing the right ascension of each pixel (units = degrees) - all_dec (`numpy.ndarray`_) + all_dec (`numpy.ndarray`_): 1D flattened array containing the declination of each pixel (units = degrees) - all_wave (`numpy.ndarray`_) + all_wave (`numpy.ndarray`_): 1D flattened array containing the wavelength of each pixel (units = Angstroms) all_sci (`numpy.ndarray`_): @@ -1411,27 +1462,27 @@ def subpixellate(output_wcs, all_ra, all_dec, all_wave, all_sci, all_ivar, all_w all_wghts (`numpy.ndarray`_): 1D flattened array containing the weights of each pixel to be used in the combination - all_spatpos (`numpy.ndarray`_) + all_spatpos (`numpy.ndarray`_): 1D flattened array containing the detector pixel location in the spatial direction - all_specpos (`numpy.ndarray`_) + all_specpos (`numpy.ndarray`_): 1D flattened array containing the detector pixel location in the spectral direction - all_spatid (`numpy.ndarray`_) + all_spatid (`numpy.ndarray`_): 1D flattened array containing the spatid of each pixel - tilts (`numpy.ndarray`_, list) + tilts (`numpy.ndarray`_, list): 2D wavelength tilts frame, or a list of tilt frames (see all_idx) - slits (:class:`~pypeit.slittrace.SlitTraceSet`_, list) + slits (:class:`~pypeit.slittrace.SlitTraceSet`, list): Information stored about the slits, or a list of SlitTraceSet (see all_idx) - astrom_trans (:class:`~pypeit.alignframe.AlignmentSplines`_, list): + astrom_trans (:class:`~pypeit.alignframe.AlignmentSplines`, list): A Class containing the transformation between detector pixel coordinates and WCS pixel coordinates, or a list of Alignment Splines (see all_idx) bins (tuple): A 3-tuple (x,y,z) containing the histogram bin edges in x,y spatial and z wavelength coordinates - all_idx (`numpy.ndarray`_, optional) + all_idx (`numpy.ndarray`_, optional): If tilts, slits, and astrom_trans are lists, this should contain a 1D flattened array, of the same length as all_sci, containing the index the tilts, slits, and astrom_trans lists that corresponds to @@ -1440,13 +1491,13 @@ def subpixellate(output_wcs, all_ra, all_dec, all_wave, all_sci, all_ivar, all_w spec_subpixel (:obj:`int`, optional): What is the subpixellation factor in the spectral direction. Higher values give more reliable results, but note that the time required - goes as (spec_subpixel * spat_subpixel). The default value is 5, + goes as (``spec_subpixel * spat_subpixel``). The default value is 5, which divides each detector pixel into 5 subpixels in the spectral direction. spat_subpixel (:obj:`int`, optional): What is the subpixellation factor in the spatial direction. Higher values give more reliable results, but note that the time required - goes as (spec_subpixel * spat_subpixel). The default value is 5, + goes as (``spec_subpixel * spat_subpixel``). The default value is 5, which divides each detector pixel into 5 subpixels in the spatial direction. debug (bool): @@ -2297,3 +2348,5 @@ def coadd_cube(files, opts, spectrograph=None, parset=None, overwrite=False): all_idx=all_idx[ww], overwrite=overwrite, blaze_wave=blaze_wave, blaze_spec=blaze_spec, fluxcal=fluxcal, sensfunc=sensfunc, specname=specname, whitelight_range=wl_wvrng, spec_subpixel=spec_subpixel, spat_subpixel=spat_subpixel) + + diff --git a/pypeit/datamodel.py b/pypeit/datamodel.py index c922478d2c..9101420aa5 100644 --- a/pypeit/datamodel.py +++ b/pypeit/datamodel.py @@ -453,8 +453,6 @@ def _validate(self): print(data.func == _data.func) # True ----- - .. include common links, assuming primary doc root is up one directory .. include:: ../include/links.rst diff --git a/pypeit/images/bitmaskarray.py b/pypeit/images/bitmaskarray.py index ee8ba13b76..db9c6898b6 100644 --- a/pypeit/images/bitmaskarray.py +++ b/pypeit/images/bitmaskarray.py @@ -6,8 +6,6 @@ .. include:: ../include/bitmaskarray_usage.rst ----- - .. include common links, assuming primary doc root is up one directory .. include:: ../include/links.rst """ diff --git a/pypeit/par/pypeitpar.py b/pypeit/par/pypeitpar.py index 38fade759b..f3fcef6723 100644 --- a/pypeit/par/pypeitpar.py +++ b/pypeit/par/pypeitpar.py @@ -54,8 +54,6 @@ def __init__(self, existing_par=None, foo=None): sets as a template, then add the parameter set to :class:`PypeItPar`, assuming you want it to be accessed throughout the code. ----- - .. include common links, assuming primary doc root is up one directory .. include:: ../include/links.rst diff --git a/setup.cfg b/setup.cfg index 1e3a44bae7..a78fcc6dd2 100644 --- a/setup.cfg +++ b/setup.cfg @@ -67,20 +67,22 @@ test = pytest-cov coverage docs = - sphinx<6,>=1.6 - docutils<0.18 + sphinx<7,>=1.6 + docutils<0.19 sphinx-automodapi - sphinx_rtd_theme==1.1.1 + sphinx_rtd_theme==1.2.2 dev = + scikit-image + specutils pytest>=6.0.0 pytest-astropy tox pytest-cov coverage - sphinx<6,>=1.6 - docutils<0.18 + sphinx<7,>=1.6 + docutils<0.19 sphinx-automodapi - sphinx_rtd_theme==1.1.1 + sphinx_rtd_theme==1.2.2 [options.package_data] * = *.rst, *.txt, data/*, data/*/*, data/*/*/*, data/*/*/*/*, data/*/*/*/*/*, data/*/*/*/*/*/*