================ Spectral Regions ================ A spectral region may be defined and may encompass one, or more, sub-regions. They are independent of a `~specutils.Spectrum1D` object. There, one may define a spectral region and it may be used on `~specutils.Spectrum1D` objects of different dispersion sampling. Spectral regions can be defined either as a single region by passing two `~astropy.units.Quantity`'s or by passing a list of 2-tuples. By definition the `~specutils.SpectralRegion` will be ordered based on the lower bound of each 2-tuple. .. code-block:: python >>> from astropy import units as u >>> from specutils.spectra import SpectralRegion >>> sr = SpectralRegion(0.45*u.um, 0.6*u.um) >>> sr_two = SpectralRegion([(0.45*u.um, 0.6*u.um), (0.8*u.um, 0.9*u.um)]) `~specutils.SpectralRegion` can be combined by using the '+' operator: .. code-block:: python >>> from astropy import units as u >>> from specutils.spectra import SpectralRegion >>> sr = SpectralRegion(0.45*u.um, 0.6*u.um) + SpectralRegion(0.8*u.um, 0.9*u.um) Regions can also be added in place: .. code-block:: python >>> from astropy import units as u >>> from specutils.spectra import SpectralRegion >>> sr1 = SpectralRegion(0.45*u.um, 0.6*u.um) >>> sr2 = SpectralRegion(0.8*u.um, 0.9*u.um) >>> sr1 += sr2 Regions can be sliced by indexing by an integer or by a range: .. code-block:: python >>> from astropy import units as u >>> from specutils.spectra import SpectralRegion >>> sr = SpectralRegion(0.15*u.um, 0.2*u.um) + SpectralRegion(0.3*u.um, 0.4*u.um) +\ ... SpectralRegion(0.45*u.um, 0.6*u.um) + SpectralRegion(0.8*u.um, 0.9*u.um) +\ ... SpectralRegion(1.0*u.um, 1.2*u.um) + SpectralRegion(1.3*u.um, 1.5*u.um) >>> # Get on spectral region (returns a SpectralRegion instance) >>> sone = sr1[0] >>> # Slice spectral region. >>> subsr = sr[3:5] >>> # SpectralRegion: 0.8 um - 0.9 um, 1.0 um - 1.2 um The lower and upper bounds on a region are accessed by calling lower or upper. The lower bound of a `~specutils.SpectralRegion` is the minimum of the lower bounds of each sub-region and the upper bound is the maximum of the upper bounds: .. code-block:: python >>> from astropy import units as u >>> from specutils.spectra import SpectralRegion >>> sr = SpectralRegion(0.15*u.um, 0.2*u.um) + SpectralRegion(0.3*u.um, 0.4*u.um) +\ ... SpectralRegion(0.45*u.um, 0.6*u.um) + SpectralRegion(0.8*u.um, 0.9*u.um) +\ ... SpectralRegion(1.0*u.um, 1.2*u.um) + SpectralRegion(1.3*u.um, 1.5*u.um) >>> # Bounds on the spectral region (most minimum and maximum bound) >>> print(sr.bounds) #doctest:+SKIP (, ) >>> # Lower bound on the spectral region (most minimum) >>> sr.lower #doctest:+SKIP >>> sr.upper #doctest:+SKIP >>> # Lower bound on one element of the spectral region. >>> sr[3].lower #doctest:+SKIP One can also delete a sub-region: .. code-block:: python >>> from astropy import units as u >>> from specutils.spectra import SpectralRegion >>> sr = SpectralRegion(0.15*u.um, 0.2*u.um) + SpectralRegion(0.3*u.um, 0.4*u.um) +\ ... SpectralRegion(0.45*u.um, 0.6*u.um) + SpectralRegion(0.8*u.um, 0.9*u.um) +\ ... SpectralRegion(1.0*u.um, 1.2*u.um) + SpectralRegion(1.3*u.um, 1.5*u.um) >>> del sr[1] >>> sr #doctest:+SKIP [(, ), (, ), (, ), (, ), (, )] There is also the ability to iterate: .. code-block:: python >>> from astropy import units as u >>> from specutils.spectra import SpectralRegion >>> sr = SpectralRegion(0.15*u.um, 0.2*u.um) + SpectralRegion(0.3*u.um, 0.4*u.um) +\ ... SpectralRegion(0.45*u.um, 0.6*u.um) + SpectralRegion(0.8*u.um, 0.9*u.um) +\ ... SpectralRegion(1.0*u.um, 1.2*u.um) + SpectralRegion(1.3*u.um, 1.5*u.um) >>> for s in sr: ... print(s.lower) #doctest:+SKIP SpectralRegion: 0.15 um - 0.2 um SpectralRegion: 0.3 um - 0.4 um SpectralRegion: 0.45 um - 0.6 um SpectralRegion: 0.8 um - 0.9 um SpectralRegion: 1.0 um - 1.2 um SpectralRegion: 1.3 um - 1.5 um And, lastly, there is the ability to invert a `~specutils.SpectralRegion` given a lower and upper bound. For example, if a set of ranges are defined each defining a range around lines, then calling invert will return a `~specutils.SpectralRegion` that defines the baseline/noise regions: .. code-block:: python >>> from astropy import units as u >>> from specutils.spectra import SpectralRegion >>> sr = SpectralRegion(0.15*u.um, 0.2*u.um) + SpectralRegion(0.3*u.um, 0.4*u.um) +\ ... SpectralRegion(0.45*u.um, 0.6*u.um) + SpectralRegion(0.8*u.um, 0.9*u.um) +\ ... SpectralRegion(1.0*u.um, 1.2*u.um) + SpectralRegion(1.3*u.um, 1.5*u.um) >>> sr_inverted = sr.invert(0.05*u.um, 3*u.um) >>> sr_inverted #doctest:+SKIP SpectralRegion: 0.05 um - 0.15 um, 0.2 um - 0.3 um, 0.4 um - 0.45 um, 0.6 um - 0.8 um, 0.9 um - 1.0 um, 1.2 um - 1 .3 um, 1.5 um - 3.0 um Region Extraction ----------------- Given a `~specutils.SpectralRegion`, one can extract a sub-spectrum from a `~specutils.Spectrum1D` object. If the `~specutils.SpectralRegion` has multiple sub-regions then a list of `~specutils.Spectrum1D` objects will be returned. An example of a single sub-region `~specutils.SpectralRegion`: .. code-block:: python >>> from astropy import units as u >>> import numpy as np >>> from specutils import Spectrum1D, SpectralRegion >>> from specutils.manipulation import extract_region >>> region = SpectralRegion(8*u.nm, 22*u.nm) >>> spectrum = Spectrum1D(spectral_axis=np.arange(1, 50) * u.nm, flux=np.random.sample(49)*u.Jy) >>> sub_spectrum = extract_region(spectrum, region) >>> sub_spectrum.spectral_axis An example of a multiple sub-region `~specutils.SpectralRegion`: .. code-block:: python >>> from astropy import units as u >>> import numpy as np >>> from specutils import Spectrum1D, SpectralRegion >>> from specutils.manipulation import extract_region >>> region = SpectralRegion([(8*u.nm, 22*u.nm), (34*u.nm, 40*u.nm)]) >>> spectrum = Spectrum1D(spectral_axis=np.arange(1, 50) * u.nm, flux=np.random.sample(49)*u.Jy) >>> sub_spectra = extract_region(spectrum, region) >>> sub_spectra[0].spectral_axis >>> sub_spectra[1].spectral_axis Reference/API ------------- .. automodapi:: specutils.spectra.spectral_region :no-heading: