2.1. utils.specutils package

2.1.1. avoidregion

class utils.specutils.avoidregion.AvoidRegion(minwl=None, maxwl=None, description='')

Bases: object

Defines an avoid region, which is a section of wavelength space that should not be included when determining the optimal y-axis plot range. The object consists of a starting wavelength, ending wavelength, and string description of what that region is.

Raises:

ValueError

utils.specutils.avoidregion.generate_avoid_regions(instrument)

Creates a list of AvoidRegion objects for use in the plotting routine, specifically designed for the given instrument.

Parameters:

instrument (str) – The instrument to generate the Avoid Region for.

2.1.2. calc_covering_fraction

utils.specutils.calc_covering_fraction.calc_covering_fraction(fig, subplots, subplot_num, optimize=True)

Calculates the ratio of pixels that contain plot data vs. background (empty) pixels by temporarily filling the background with RGB value = red and then identifying blue (plot data) pixels. This ratio is used to determine whether to make the plot lines transparent or not for readability.

Parameters:

  • fig (Figure) – The plot figure.

  • subplots (list) – The list of subplots.

  • subplot_num (int) – The index indicating which subplot is currently being examined.

  • optimize (bool) – If set to True, will use a slightly optimized version of determining the plot covering fraction. This has been tested to almost always give the same result as the non-optimized version. There has been (rare) instances where the covering fractions differed slightly, so if the preference is to have more accurate/robust covering fractions, set optimize=False! The speed benefit is on the order of 10-20%, but is largest for plots with multiple subplots.

Returns:

float – The ratio of pixels containing plot data (“blue”) vs. empty (“red”) pixels, as a percentage (0. <= p <= 100.).

utils.specutils.calc_covering_fraction.count_blue_red(buf)

Counts the number of “blue” vs. “red” pixels in the plot area.

Parameters:

buf (numpy.ndarray) – The plot pixels read into a buffer of RGB values ( one-dimensional, [r,g,b,r,g,b,…]).

Returns:

tuple – The number of blue and red pixels, respectively. Blue represent pixels that have plot data in them, red represent background pixels that do not have any plot lines going through them.

2.1.3. calc_plot_metrics

utils.specutils.calc_plot_metrics.calc_plot_metrics(instrument, wls, fls, flerrs, dqs, n_consecutive, flux_scale_factor, fluxerr_scale_factor)

Calculates a variety of plot metrics, including flux statistics, avoid regions, and optimal x- and y-axis ranges.

Parameters:

  • instrument (str) – The instrument that is being tested.

  • wls (numpy.ndarray) – The wavelengths to be plotted.

  • fls (numpy.ndarray) – The fluxes to be plotted.

  • flerrs (numpy.ndarray) – The uncertainties of the fluxes to be plotted.

  • dqs (numpy.ndarray) – The DQ flags of the spectrum to be plotted. For COS, these are the DQ_WGT bits from the header.

  • n_consecutive (int) – How many consecutive points must pass the test for the index to count as the valid start/end of the spectrum?

  • flux_scale_factor (float) – Max. allowed ratio between the flux and a median flux value, used in edge trimming.

  • fluxerr_scale_factor (float) – Max. allowed ratio between the flux uncertainty and a median flux uncertainty value, used in edge trimming.

Returns:

dict – A container for the plot metrics.

2.1.4. debug_oplot

utils.specutils.debug_oplot.debug_oplot(this_plotarea, instrument, all_wls, all_fls, all_flerrs, all_dqs, median_flux, median_fluxerr, flux_scale_factor, fluxerr_scale_factor, fluxerr_95th, oplot_percentiles=False)

Creates plots of the spectra with color-coding and special annotation to identify which points were rejected by which tests. Useful for debugging and understanding why a given plot had its plot axes defined the way it did.

Parameters:

  • this_plotarea (matplotlib.axes._subplots.AxesSubplot) – The AxesSubplot object to plot on.

  • instrument (str) – The instrument that is being tested.

  • all_wls (numpy.ndarray) – Array of wavelengths.

  • all_fls (numpy.ndarray) – Array of fluxes.

  • all_flerrs (numpy.ndarray) – Array of flux uncertainties.

  • all_dqs (numpy.ndarray) – Array of data quality flags. For COS, these are the DQ_WGT bits from the header.

  • median_flux (float) – The median flux used in determining where the best part of the spectrum is.

  • median_fluxerr (float) – The median flux uncertainty used in determining where the best part of the spectrum is.

  • flux_scale_factor (float) – Max. allowed ratio between the flux and a median flux value used in edge trimming.

  • fluxerr_scale_factor (float) – Max. allowed ratio between the flux uncertainty and a median flux uncertainty value used in edge trimming.

  • fluxerr_95th (float) – The flux uncertainty corresponding to the 95th percentile.

  • oplot_percentiles (bool) – Set this to True to overplot points where the flux uncertainties are greater than the 95th percentile. Default = False.

2.1.5. dq_has_flag

utils.specutils.dq_has_flag.dq_has_flag(dqf, flag_to_check)

Returns true/false if the given DQ value has a specific flag value set after unpacked into a 16-bit string. For example:

print dq_has_flag(48,16)
True
print dq_has_flag(40, 16)
False
Parameters:

  • dqf (int) – The DQ value.

  • flag_to_check (int) – The flag value to check if it’s set to True.

Returns:

bool – Returns True if flag_to_check is True inside dqf.

Raises:

ValueError

2.1.6. edge_trim

utils.specutils.edge_trim.edge_trim(instrument, fluxes, fluxerrs, dqs, n_consecutive, median_flux, flux_scale_factor, median_fluxerr, fluxerr_scale_factor, fluxerr_95th)

Returns start and end indexes (end indexes are negatively indexed) of the best part of the spectrum to use when defining the plot’s wavelength ranges. Returns two sets of start and end indexes: one set without taking into account DQ flags, and one set that does take into account DQ flags (since some spectra have all DQ flags set > 0).

Parameters:

  • instrument (str) – The instrument that is being tested.

  • fluxes (numpy.ndarray) – The fluxes to be plotted.

  • fluxerrs (numpy.ndarray) – The uncertainties of the fluxes to be plotted.

  • dqs (numpy.ndarray) – The DQ flags of the spectrum. For COS, these are the DQ_WGT bits from the header.

  • n_consecutive (int) – The consecutive number of fluxes that must belong to the “best” part of the spectrum for the start/end index to count.

  • median_flux (float) – The median flux, used in determining where the best part of the spectrum is.

  • flux_scale_factor (float) – Max. allowed ratio between the flux and a median flux value, used in edge trimming.

  • median_fluxerr (float) – The median flux uncertainty, used in determining where the best part of the spectrum is.

  • fluxerr_scale_factor (float) – Max. allowed ratio between the flux uncertainty and a median flux uncertainty value, used in edge trimming.

  • fluxerr_95th (float) – The flux uncertainty corresponding to the 95th percentile.

Returns:

int tuple – Indexes that define the best part of the spectrum, in the order of (start_index_nodq, end_index_nodq, start_index_withdq, end_index_withdq).

utils.specutils.edge_trim.find_good_indices(indices_arr, n_consecutive, n_fluxes, first_pass=False)

Given an array of indices, determines the start and stop indices of the best part of the spectrum based on the required number of consecutive good fluxes.

Parameters:

  • indices_arr (list) – Something

  • n_consecutive (int) – The consecutive number of fluxes that must belong to the “best” part of the spectrum for the start/end index to count.

  • n_fluxes (int) – The total number of data points in the spectrum.

  • first_pass (bool) – Used to determine if this is the first attempt to find good start and stop indices or not. The first pass normally uses only a part of the spectrum (pieces at the beginning and end), while the next pass uses the entire spectrum. If it’s not the first pass and no good start and stop indices are found, then it must return the last and first index.

Returns:

int tuple – Indices that define the best part of the spectrum (start and stop).

2.1.7. get_flux_stats

utils.specutils.get_flux_stats.get_flux_stats(fluxes, fluxerrs)

Calculates median values of the fluxes and flux uncertainties, and the 95th percentile flux uncertainty.

Parameters:

  • fluxes (numpy.ndarray) – The fluxes to be plotted.

  • fluxerrs (numpy.ndarray) – The uncertainties of the fluxes to be plotted.

Returns:

tuple – The median flux, median flux uncertainty, and the 95th percentile flux uncertainty.

2.1.8. is_bad_dq

utils.specutils.is_bad_dq.is_bad_dq(instrument, dqs)

Returns True/False whether the DQ values are from a good part of the spectrum. If the input DQs is a scalar value, the return result is also a scalar value. If the input DQs are a numpy array, the return result is also a numpy array.

Parameters:

  • instrument (str) – The instrument the DQs come from.

  • dqs (numpy.ndarray) – Array of DQ (STIS) or DQ_WGT (COS) values.

Returns:

bool or numpy.ndarray – A scalar boolean or array of booleans.

2.1.9. rms

utils.specutils.rms.rms(values, offset=0.0)

Calculates the RMS about some offset (default offset is 0.)

Parameters:

  • values (numpy.ndarray) – Array of values to compute the rms of.

  • offset (float) – Optional offset to compute the rms about. Defaults to 0.0.

Returns:

float – A scalar float containing the rms about the offset.

2.1.10. set_plot_xrange

utils.specutils.set_plot_xrange.set_plot_xrange(instrument, wavelengths, fluxes, fluxerrs, dqs, n_consecutive, flux_scale_factor, fluxerr_scale_factor, median_flux, median_fluxerr, fluxerr_95th)

Given an array of wavelengths and fluxes, returns a list of [xmin,xmax] to define an optimal x-axis plot range.

Parameters:

  • instrument (str) – The instrument that is being tested.

  • wavelengths (numpy.ndarray) – The wavelengths to be plotted.

  • fluxes (numpy.ndarray) – The fluxes to be plotted.

  • fluxerrs (numpy.ndarray) – The uncertainties of the fluxes to be plotted.

  • dqs (numpy.ndarray) – The DQ flags of the spectrum to be plotted. For COS, these are the DQ_WGT bits from the header.

  • n_consecutive (int) – How many consecutive points must pass the test for the index to count as the valid start/end of the spectrum?

  • flux_scale_factor (float) – Max. allowed ratio between the flux and a median flux value, used in edge trimming.

  • fluxerr_scale_factor (float) – Max. allowed ratio between the flux uncertainty and a median flux uncertainty value, used in edge trimming.

  • median_flux (float) – A median flux value, used in the test.

  • median_fluxerr (float) – A median flux uncertainty value, used in the test.

  • fluxerr_95th (float) – The flux uncertainty corresponding to the 95th percentile.

Returns:

list – Two-element list containing the optimal [xmin,xmax] values to define the x-axis plot range.

2.1.11. set_plot_yrange

utils.specutils.set_plot_yrange.set_plot_yrange(wavelengths, fluxes, avoid_regions=None, wl_range=None)

Given an array of wavelengths, fluxes, and avoid regions, returns a list of [ymin,ymax] to define an optimal y-axis plot range.

Parameters:

  • wavelengths (numpy.ndarray) – The wavelengths to be plotted.

  • fluxes (numpy.ndarray) – The fluxes to be plotted.

  • avoid_regions (list of STISAvoidRegion objects.) – A list of wavelength ranges to avoid when calculating optimal y-axis plot range.

  • wl_range (list) – The min. and max. wavelength that defines the x-axis plot range. The default is None, in which case the min. and max. if the input wavelength array will be used.

Returns:

list – Two-element list containing the optimal [ymin,ymax] values to define the y-axis plot range.

Note

This function makes use of an internal look-up table of wavelength regions where known contaminating emission lines or other strong UV artifacts can affect the zoom level of the plot.

2.1.12. specutilserror

exception utils.specutils.specutilserror.SpecUtilsError(value)

Bases: Exception, object

This class defines a generic Exception to use for errors raised in the SPECUTILS modules (specutils, specutils_cos, specutils_stis, etc.). It simply prints the given value when raising the exception, e.g.,

raise SpecUtilsError("Print this string")
SpecUtilsError: *** SPECUTILS ERROR: 'Print this string'

2.1.13. stitch_components

utils.specutils.stitch_components.stitch_components(input_exposure, n_consecutive, flux_scale_factor, fluxerr_scale_factor, segment_names=None)

Given a COSSpectrum or STISExposureSpectrum object, stitches each segment/order, respectively, into a contiguous array.

Parameters:

  • input_exposure (COSSpectrum or STISExposureSpectrum) – The COS segment or STIS exposure spectrum to stitch.

  • n_consecutive (int) – How many consecutive points must pass the test for the index to count as the valid start/end of the spectrum?

  • flux_scale_factor (float) – Max. allowed ratio between the flux and a median flux value, used in edge trimming.

  • fluxerr_scale_factor (float) – Max. allowed ratio between the flux uncertainty and a median flux uncertainty value, used in edge trimming.

  • segment_names (list) – List of segment names if input_exposure is a COSSpectrum object.

Returns:

dict{numpy array, numpy array, numpy array, str} – The stitched wavelengths, fluxes, flux errors, and an informational plot title in the event that all the fluxes had the DQ flag set. These are packaged in a dict.

Raises:

ValueError