uvotspec

Major functions

adjust_wavelength_manually()

uvotpy.uvotspec.adjust_wavelength_manually(file=None, openfile=None, openplot=None, ylim=[None, None], ions=['HI', 'HeII'], reference_spectrum=None, recalculate=True, figno=None)

manually adjust the wavelength scale

Parameters:

file : path

extracted spectral data (i.e., after running uvotgetspec.getSpec()

fileopen : filehandle

opened spectral data file

openplot : axis

axis instance to use

ylim : list(2)

list of length 2 with limits of the Y-axis or None

ions : list

list of ions to use for annotation valid ions are spdata.keys()

reference_spectrum : astropy.table.table.Table

column 1: wavelength, column 2: flux

recalculate : bool

when set, use wavelength shift to determine shift of pixno array and use dispersion to recalculate the wavelengths

Notes

The header will be updated with the value of the wavelength shift The wavelengths in the second extension lambda column will be shifted. The response file will need to be recreated separately.

Returns the figure instance

flag_bad_manually()

uvotpy.uvotspec.flag_bad_manually(file=None, openfile=None, openplot=None, ylim=[None, None])

manually flag bad parts of the spectrum

Parameters:

file : path

extracted spectral data (i.e., after running uvotgetspec.getSpec()

openfile : filehandle

openplot : matplotlib.figure

figure handle

ylim : list

limits y-axis

Notes

returns ax:axes instance, fig:figure instance, [f:fits file handle if passed with openfile]

The data quality flag of flagged pixels will be set to “bad” The header will be updated with the value of the wavelength shift

plot_spectrum()

uvotpy.uvotspec.plot_spectrum(ax, spectrumfile, errbars=False, errhaze=False, hazecolor='grey', hazealpha=0.2, flag='all', ylim=[6e-15, 9e-13], speccolor='g', plot_quality=True, quality_marker='x', qual_flags=['bad', 'weakzeroth', 'zeroth', 'overlap', 'too_bright', 'first'], qualcolors=['c', 'g', 'y', 'm', 'b', 'r', 'k'], qualalpha=0.2, quallegend={'weakzeroth': True, 'zeroth': True, 'overlap': True, 'bad': True, 'too_bright': True, 'first': True}, chatter=0)

make a quick plot of a PHA/summed spectrum

Parameters:

ax : matplotlib.axes.AxesSubplot instance

The spectrum will be drawn in ‘ax’

spectrumfile: path

the full filename of the spectrum

ylim : list

y-axis limits

speccolor : color

errbars: bool

if False, draw spectrum with optional error as a haze (see errhaze, hazecolor, hazealpha) if True, draw data with error bars

errhaze, hazecolor, hazealpha : bool, string, float

parameters to control the display of the error region around the spectrum

flag: one of quality_flags()

for PHA spectrum: plot data excluding this flag e.g., ‘all’ include only ‘good’ data (no flag set)

plot_quality : bool

(only for PHA files)

quality_marker : plot string character or None

if None, plot with color shading, otherwise, plot symbol

qualflag,qualcolors,qualalpha : list, list, float

(only for PHA files) parameters passed to plotquality - qualflag is a list of flags (from uvotgetspec.quality_flags().keys()) - qualcolors is a list of colors for the shading of the regions by quality - qualalpha is the alpha factor for the shading - quallegend (for each flag, add to legend)

chatter: int (0...5)

verbosity

If a summed spectrum is presented, it needs to be FITS

generated using the uvotspec.sum_PHAspectra() program.

plotquality()

uvotpy.uvotspec.plotquality(ax, w, quality, flux=None, flag=['bad', 'weakzeroth', 'zeroth', 'too_bright'], colors=['c', 'y', 'm', 'b', 'r', 'g', 'k'], alpha=0.2, quallegend={'weakzeroth': True, 'zeroth': True, 'overlap': True, 'bad': True, 'too_bright': True, 'first': True}, marker='x', chatter=0)

mark up plot with data quality either add vertical greyscale regions in plot for each

quality flag (when marker=None)

or plot a symbol ‘marker’ on each data point

Parameters:

ax : matplotlib.axes.Axes instance

w : array

x-axis values

quality : array

flux : array

flux values quality flags matching x-axis points

flag : list of strings

each list value must be one of the valid keys from quality_flags()

colors : array

color values

alpha : float

alpha value for transparency

marker : nonetype or plot character string

if None then plot grey scale regions, otherwise, plot marker on bad data requires flux array

sum_PHAspectra()

uvotpy.uvotspec.sum_PHAspectra(phafiles, outfile=None, ignore_flags=False, use_flags=['bad'], interactive=False, figno=14, ylim=[-2e-15, 5e-13], flag_bad_areas=False, exclude_wave=[], adjust_wavelengths=False, wave_shifts=[], objectname='unknown', object_position=None, wave_adjust_method=1, exclude_method=1, chatter=1, clobber=True)

Read a list of phafiles. Sum the spectra after applying optional wave_shifts. The sum is weighted by the errors.

Parameters:

phafiles : list

list of filenames

outfile : str

name for output file. If “None” then write to ‘sumpha.txt’, if ending in ‘.fit’ or ‘.fits’ a fits file will be written.

flag_bad_areas : bool [optional]

interactively select areas of each spectrum not to include in each spectrum

adjust_wavelengths : bool [optional]

interactively select a wavelength shift for each spectrum to apply before summing the spectra

ylim : list [optional]

force limits of Y-axis figure (interactive)

figno : int, or list [optional]

numbers for figures or (if only one) the start number of figures (interactive)

wave_shifts : list [optional]

list of shifts to add to the wavelength scale; same length as phafiles

exclude_wave : list [optional]

list of lists of exclude regions; same length as pha files; one list per file for an indivisual file the the list element is like [[1600,1900],[2700,2750],]

ignore_flags : bool [optional]

if True, do not automatically convert flagged sections of the spectrum to exclude_wave regions, if False, use the quality flags from “use_flags”

use_flags : list [optional]

list of flags (except - ‘good’) to exclude. Valid keyword values for the flags are defined in quality_flags(),

objectname : str [optional]

name of the object. This will be entered as a keyword in the summed_spectrum fits file.

object_position: astropy.coordinates [optional]

Returns:

debug information when outfile=None.

Notes

Two figures are shown, one with flux for all spectra after shifts, one with broad sum of counts in a region which includes the spectrum, unscaled, not even by exposure.

** not yet implemented: selection on flags using use-flags ** smooth each spectrum, correlate for shift [all quality=’good’ data points]

BUGS: the quality is not read from the file into exclusion sets at the moment

Key functions

apply_shift()

uvotpy.uvotspec.apply_shift(file, delwav, recalculate=False)

apply a given wavelength shift in A

check_flag()

uvotpy.uvotspec.check_flag(quality, flag, chatter=0)

return a logical array where the elements are True if flag is set

complement_of_ranges()

uvotpy.uvotspec.complement_of_ranges(ranges, rangestart=0, rangeend=None)

given a list of exclusion ranges, compute the complement

Parameters:

range : list

the range list consists of elements that each specify a bad range in the spectrum. The complement needs also the start and end of the whole range in order to add the leading and trailing complement ranges.

rangestart, rangeend : int

start and end index of the wavelenght array. Usually that is 0, len(wave)

plot_line_ids()

uvotpy.uvotspec.plot_line_ids(ax, ylower=None, ion='HI', color='k', dash=[0.07, 0.1], fontsize=8, spdata={'HI': [{'wavevac': 1215.67, 'transition': '1s-2', 'name': 'Ly-alpha', 'label': 'Ly$\\alpha$'}, {'wavevac': 1025.722, 'transition': '1s-3', 'name': 'Ly-beta', 'label': 'Ly$\\beta$'}, {'wavevac': 972.537, 'transition': '1s-4', 'name': 'Ly-gamma', 'label': 'Ly$\\gamma$'}, {'wavevac': 912.3, 'transition': '1s-40', 'name': 'Ly-limit', 'label': 'Ly-limit'}, {'wavevac': 6564.63, 'transition': '2-3', 'name': 'H-alpha', 'label': 'H$\\alpha$'}, {'wavevac': 4862.69, 'transition': '2-4', 'name': 'H-beta', 'label': 'H$\\beta$'}, {'wavevac': 4341.69, 'transition': '2-5', 'name': 'H-gamma', 'label': 'H$\\gamma$'}, {'wavevac': 4102.899, 'transition': '2-6', 'name': 'H-delta', 'label': 'H$\\delta$'}, {'wavevac': 3971.202, 'transition': '2-7', 'name': 'H-epsilon', 'label': 'H$\\epsilon$'}, {'wavevac': 3890.16, 'transition': '2-8', 'name': 'H-6', 'label': 'H6'}, {'wavevac': 3836.485, 'name': 'H-7', 'label': 'H7'}, {'wavevac': 3656, 'transition': '2s-40', 'name': 'H-limit', 'label': 'Ba-limit'}, {'wavevac': 18756.096, 'transition': '3-4', 'name': 'Pa-alpha', 'label': 'Pa$\\alpha$'}, {'wavevac': 12821.576, 'transition': '3-5', 'name': 'Pa-beta', 'label': 'Pa$\\beta$'}, {'wavevac': 10941.082, 'transition': '3-6', 'name': 'Pa-gamma', 'label': 'Pa$\\gamma$'}, {'wavevac': 10052.123, 'transition': '3-7', 'name': 'Pa-delta', 'label': 'Pa$\\delta$'}, {'wavevac': 9548.587, 'transition': '3-8', 'name': 'Pa-5', 'label': 'Pa5'}, {'wavevac': 8252.2, 'transition': '3s-40', 'name': 'Pa-limit', 'label': 'Pa-limit'}], 'HeI': [{'wavevac': 7067.14, 'transition': '1s2p 3Po-1s3s 3S ', 'label': u'HeI'}, {'wavevac': 6679.9956, 'transition': '1s2p 1Po-1s3d 1D ', 'label': u'HeI'}, {'wavevac': 5877.249, 'transition': '1s2p 3Po-1s3d 3D ', 'label': u'HeI'}, {'wavevac': 5017.0772, 'transition': '1s2s 1S -1s3p 1Po', 'label': u'HeI'}, {'wavevac': 4472.735, 'transition': '1s2s 3Po-1s4d 4D ', 'label': u'HeI'}, {'wavevac': 3889.75, 'transition': '1s2s 3S -1s3p 3Po', 'label': u'HeI'}, {'wavevac': 3188.667, 'transition': '1s2s 3S -1s4p 3Po', 'label': u'HeI'}, {'wavevac': 3014.59, 'transition': '2p2 3P -2p3d 3Do', 'label': u'HeI'}, {'wavevac': 2945.967, 'transition': '1s2s 3S -1s5p 3Po', 'label': u'HeI'}, {'wavevac': 2819.0, 'label': u'HeI'}, {'wavevac': 2578.4, 'label': u'HeI'}, {'wavevac': 584.334, 'transition': '1s2 1S -1s1p 1Po', 'label': u'HeI'}], 'nova': [{'wavevac': 1750, 'transition': '', 'label': u'N III]'}, {'wavevac': 1810, 'transition': '', 'label': 'Si II'}, {'wavevac': 1862.3, 'transition': '', 'label': u'Al III]'}, {'wavevac': 1908.7, 'transition': '', 'label': u'C III]'}, {'wavevac': 2143, 'transition': '', 'label': u'N II]'}, {'wavevac': 2297, 'transition': '', 'label': u'C III'}, {'wavevac': 2325.4, 'transition': '', 'label': u'C II'}, {'wavevac': 2335.4, 'transition': '', 'label': u'Si II'}, {'wavevac': 2332.1, 'transition': '', 'label': u'[O III]'}, {'wavevac': 2471.0, 'transition': '', 'label': u'O II]'}, {'wavevac': 2796.4, 'transition': '', 'label': u'Mg II'}, {'wavevac': 2803.5, 'transition': '', 'label': u'Mg II'}, {'wavevac': 2937.4, 'transition': '', 'label': u'Mg II*'}, {'wavevac': 3130.0, 'transition': '', 'label': u'O III*'}, {'wavevac': 3345.8, 'transition': '', 'label': u'[Ne V]'}, {'wavevac': 3425.9, 'transition': '', 'label': u'[Ne V]'}, {'wavevac': 3727, 'transition': '', 'label': u'[O III]'}, {'wavevac': 3869, 'transition': '', 'label': u'[Ne III]'}, {'wavevac': 3968, 'transition': '', 'label': u'[Ne III]'}, {'wavevac': 4363, 'transition': '', 'label': u'[O III]'}, {'wavevac': 4636, 'transition': '', 'label': u'N III*'}, {'wavevac': 4643, 'transition': '', 'label': u'N III*'}, {'wavevac': 4648.7, 'transition': '', 'label': u'C III*'}, {'wavevac': 4651.2, 'transition': '', 'label': u'O III*'}, {'wavevac': 4959, 'transition': '', 'label': u'[O III]'}, {'wavevac': 5007, 'transition': '', 'label': u'[O III]'}, {'wavevac': 5755, 'transition': '', 'label': u'[N II]'}], 'HeII': [{'wavevac': 6562.0, 'transition': '4 - 6', 'label': u'HeII'}, {'wavevac': 5411.5, 'transition': '4 - 7', 'label': u'HeII'}, {'wavevac': 4687.1, 'transition': '3 - 4', 'label': u'HeII'}, {'wavevac': 3203.95, 'transition': '3 - 5', 'label': u'HeII'}, {'wavevac': 2734.13, 'transition': '3 - 6', 'label': u'HeII'}, {'wavevac': 2511.2, 'transition': '3 - 7', 'label': u'HeII'}, {'wavevac': 2385.4, 'transition': '3 - 8', 'label': u'HeII'}, {'wavevac': 1640.47, 'transition': '2 - 3', 'label': u'HeII'}, {'wavevac': 1215.17, 'transition': '2 - 4', 'label': u'HeII'}, {'wavevac': 1025.3, 'transition': '2 - 6', 'label': u'HeII'}]})

add the line ids to the plot

Parameters:

ax : plot handle

ylower : float

y-level where the bottom of the line should be

ion : [‘HI’,’HeI’,’HeII’,]

key to the ion to be plotted one at a time

spdata : dict

dictionary of lines

dash : [scale_factor, offset_text ]

dash line from ylower to ylower+scale_factor text from ylower+offset The default is fine for linear axes, but for log axis, it fails

try for a log scale.a scale_factor that is sized by the log scale from ylower to ylower+scale_factor (so if ylower is 2x** and scale_factor=0.1, the line will go from 2-3x**.

fontsize

: int

font size

quality_flags_to_ranges()

uvotpy.uvotspec.quality_flags_to_ranges(quality, chatter=0)

given wavelength and quality flag arrays, reduce the quality to ranges of a certain quality (except for “good” = 0.)

Parameters:

wave : array

x-axis values

quality : array

quality flags matching x-axis points

Returns:

quality_ranges : dict

a dictionary of ranges for each flag except ‘good’