uvotgetspec

Major functions

getSpec()

uvotpy.uvotgetspec.getSpec(RA, DEC, obsid, ext, indir='./', wr_outfile=True, outfile=None, calfile=None, fluxcalfile=None, use_lenticular_image=True, offsetlimit=None, anchor_offset=None, anchor_position=[None, None], background_lower=[None, None], background_upper=[None, None], background_template=None, fixed_angle=None, spextwidth=13, curved='update', fit_second=False, predict2nd=True, skip_field_src=False, optimal_extraction=False, catspec=None, write_RMF=False, get_curve=None, fit_sigmas=True, get_sigma_poly=False, lfilt1=None, lfilt1_ext=None, lfilt2=None, lfilt2_ext=None, wheelpos=None, interactive=True, sumimage=None, set_maglimit=None, plot_img=True, plot_raw=True, plot_spec=True, zoom=True, highlight=False, uvotgraspcorr_on=True, update_pnt=True, clobber=False, chatter=1)

Makes all the necessary calls to reduce the data.

Parameters:

ra, dec : float

The Sky position (J2000) in decimal degrees

obsid : str

The observation ID number as a String. Typically that is something like “00032331001” and should be part of your grism filename which is something like “sw00032331001ugu_dt.img”

ext : int

number of the extension to process

kwargs : dict

optional keyword arguments, possible values are:

• fit_second : bool

  fit the second order. Off since it sometimes causes problems when the orders overlap completely. Useful for spectra in top part detector

• background_lower : list

  instead of default background list offset from spectrum as list of two numbers, like [20, 40]. Distance relative to spectrum

• background_upper : list

  instead of default background list offset from spectrum as list of two numbers, like [20, 40]. Distance relative to spectrum

• offsetlimit : None,int,[center,range]

  Default behaviour is to determine automatically any required offset from the predicted anchor position to the spectrum, and correct for that. The automated method may fail in the case of a weak spectrum and strong zeroth or first order next to the spectrum. Two methods are provided:

  (1) provide a number which will be used to limit the allowed offset. If within that limit no peak is identified, the program will stop and require you to provide a manual offset value. Try small numbers like 1, -1, 3, etc..

  (2) if you already know the approximate y-location of the spectrum at the anchor x-position in the rotated small image strip around the spectrum, you can give this with a small allowed range for fine tuning as a list of two parameter values. The first value in the list must be the y-coordinate (by default the spectrum falls close to y=100 pixels), the second parameter the allowed adjustment to a peak value in pixels. For example, [105,2]. This will require no further interactive input, and the spectrum will be extracted using that offset.

• wheelpos: {160,200,955,1000}

  filter wheel position for the grism filter mode used. Helpful for forcing Vgrism or UVgrism input when both are present in the directory. 160:UV Clocked, 200:UV Nominal, 955:V clocked, 1000:V nominal

• zoom : bool

  when False, the whole extracted region is displayed, including zeroth order when present.

• clobber : bool

  When True, overwrite earlier output (see also outfile)

• write_RMF : bool

  When True, write the rmf file (will take extra time due to large matrix operations)

• use_lenticular_image : bool

  When True and a lenticular image is present, it is used. If False, the grism image header WCS-S system will be used for the astrometry, with an automatic call to uvotgraspcorr for refinement.

• sumimage : str

  Name summed image generated using sum_Extimage(), will extract spectrum from summed image.

• wr_outfile : bool

  If False, no output file is written

• outfile : path, str

  Name of output file, other than automatically generated.

• calfile : path, str

  calibration file name

• fluxcalfile : path, str

  flux calibration file name or “CALDB” or None

• predict2nd : bool

  predict the second order flux from the first. Overestimates in centre a lot.

• skip_field_src : bool

  if True do not locate zeroth order positions. Can be used if absence internet connection or USNO-B1 server causes problems.

• optimal_extraction : bool, obsolete

  Do not use.Better results with other implementation.

• catspec : path

  optional full path to the catalog specification file for uvotgraspcorr.

• get_curve : bool or path

  True: activate option to supply the curvature coefficients of all orders by hand. path: filename with coefficients of curvature

• uvotgraspcorr_on : bool enable/disable rerun of uvotgraspcorr to update the WCS keywords

• update_pnt : bool enable/disable update of the WCS keywords from the attitude file (this is done prior to running uvotgraspcorr is that is enabled)

• fit_sigmas : bool

  fit the sigma of trackwidths if True (not implemented, always on)

• get_sigma_poly : bool

  option to supply the polynomial for the sigma (not implemented)

• lfilt1, lfilt2 : str

  name if the lenticular filter before and after the grism exposure (now supplied by fileinfo())

• lfilt1_ext, lfilt2_ext : int

  extension of the lenticular filter (now supplied by fileinfo())

• plot_img : bool

  plot the first figure with the det image

• plot_raw : bool

  plot the raw spectrum data

• plot_spec : bool

  plot the flux spectrum

• highlight : bool

  add contours to the plots to highlight contrasts

• chatter : int

  verbosity of program

• set_maglimit : int

  specify a magnitude limit to seach for background sources in the USNO-B1 catalog

• background_template : numpy 2D array

  User provides a background template that will be used instead determining background. Must be in counts. Size and alignment must exactly match detector image.

Returns:

None, (give_result=True) compounded data (Y0, Y1, Y2, Y3, Y4) which

are explained in the code, or (give_new_result=True) a data dictionary.

Notes

Quick Start

getSpec(ra,dec,obsid, ext,) should produce plots and output files

Which directory?

The program needs to be started from the CORRECT data directory. The attitude file [e.g., “sw<OBSID>pat.fits” ]is needed! A link or copy of the attitude file needs to be present in the directory or ”../../auxil/” directory as well.

Global parameters

These parameters can be reset, e.g., during a (i)python session, before calling getSpec.

• trackwidth : float width spectral extraction in units of sigma. The default is trackwidth = 2.5 The alternative default is trackwidth = 1.0 which gives better results for weak sources, or spectra with nearby contamination. However, the flux calibration and coincidence-loss correction give currently inconsistent results. When using trackwidth=1.0, rescale the flux to match trackwidth=2.5 which value was used for flux calibration and coincidence-loss correction.
• give_result : bool set to False since a call to getSpec with this set will return all the intermediate results. See returns

When the extraction slit is set to be straight curved="straight" it cuts off the UV part of the spectrum for spectra located in the top left and bottom right of the image.

Key functions

coi_func()

uvotpy.uvotgetspec.coi_func(pixno, wave, countrate, bkgrate, frametime=0.0110329, background=False, wheelpos=160, area=414, option=1, fudgespec=1.0, coi_length=29, sig1coef=[], trackwidth=0.0, sigma1_limits=[2.6, 4.0], ccc=[], ccb=[], ca=[], cb=[], debug=False, chatter=5)

Compute the coincidence loss correction factor to the (net) count rate as a function of wavelength

Parameters:

pixno : array-like

pixel number with origen at anchor

wave : array-like

wavelength in A, must be monotonically increasing

countrate : array-like

input total count rate for the coi aperture (default coi_width pixels wide)

bkgrate : array-like

background rate for the coi aperture (default coi_width pixels wide)

kwargs : dict

• frametime : float

  CCD frame time in seconds

• option : int

  . option = 1

  : (default) classic coi-loss, for box 16 pixels wide,

  414 pix^2 area

• background : bool

  if the background is True an interpolated function for the coi correction factor in the background count rate is returned

  if the background is False an interpolated function for the coi correction factor in the net target count rate is returned

• wheelpos

  : [160,200,955,1000]

  filter wheel position, one of these values.

Returns:

coi_func : scipy.interpolate.interpolate.interp1d

if background is True an interpolated function for the coi correction factor in the background count rate while if background is False an interpolated function for the coi correction factor in the net target count rate is returned

v

: bool

only for spectrum. v=True points are valid, False points mean observed rate per frame is too large.

Notes

defaults to the background coincidence loss equivalent to an area of “area=414” sub-pixels.

Both the sprate and bgrate are required, as the points in sprate that are not valid are used to mask the bgrate.

• 2012-03-21 NPMK initial version

• 2014-06-02 NPMK start using a fixed coi-area,remove old options,

  change meaning parameters

• 2014-07-23 NPMK use calibrated values of coi-box and factor

findBackground()

uvotpy.uvotgetspec.findBackground(extimg, background_lower=[None, None], background_upper=[None, None], yloc_spectrum=100, smo1=None, smo2=None, chatter=2)

Extract the background from the image slice containing the spectrum.

Parameters:

extimg : 2D array

image containing spectrum. Dispersion approximately along x-axis.

background_lower : list

distance in pixels from yloc_spectrum of the limits of the lower background region.

background_upper : list

distance in pixels from yloc_spectrum of the limits of the upper background region.

yloc_spectrum : int

pixel Y location of spectrum

smo1 : float

smoothing parameter passed to smoothing spline fitting routine. None for default.

smo2 : float

smoothing parameter passed to smoothing spline fitting routine. None for default.

chatter : int

verbosity

Returns:

bg : float

mean background

bg1, bg2 : 1D arrays

bg1 = lower background; bg2 = upper background inherits size from extimg.shape x-xoordinate

bgsig : float

standard deviation of background

bgimg : 2D array

image of the background constructed from bg1 and/or bg2

bg_limits_used : list, length 4

limits used for the background in the following order: lower background, upper background

(bg1_good, bg1_dis, bg1_dis_good, bg2_good, bg2_dis, bg2_dis_good, bgimg_lin) : tuple

various other background measures

Notes

Global parameter

• background_method : {‘boxcar’,’splinefit’}

The two background images can be computed 2 ways:

1. ‘splinefit’: sigma clip image, then fit a smoothing spline to each

   row, then average in y for each background region

2. ‘boxcar’: select the background from the smoothed image created

   by method 1 below.

3. ‘sigmaclip’: do sigma clipping on rows and columns to get column

   profile background, then clip image and mask, interpolate over masked bits.

extimg is the image containing the spectrum in the 1-axis centered in 0-axis ank is the position of the anchor in the image

I create two background images:

1. split the image strip into 40 portions in x, so that the background variation is small compute the mean sigma clip (3 sigma) each area to to the local mean replace out-of-image pixels with mean of whole image (2-sigma clipped) smooth with a boxcar by the smoothing factor
2. compute the background in two regions upper and lower linearly interpolate in Y between the two regions to create a background image

bg1 = lower background; bg2 = upper background

smo1, smo2 allow one to relax the smoothing factor in computing the smoothing spline fit

get_radec()

uvotpy.uvotgetspec.get_radec(file='radec.usno', objectid=None, tool='astropy', chatter=0)

Read the decimal ra,dec from a file or look it up using the objectid name from CDS

Parameters:

file: str, optional

path, filename of ascii file with just the ra, dec position in decimal degrees

objectid : str, optional

name of object that is recognized by the (astropy.coordinates/CDS Sesame) service if not supplied a file name is required

tool : str

name tool to use; either ‘astropy’ or ‘cdsclient’

chatter : int

verbosity

Returns:

ra,dec : float

Position (epoch J2000) in decimal degrees

makeXspecInput()

uvotpy.uvotgetspec.makeXspecInput(lamdasp, countrate, error, lamda_response=None, chatter=1)

Convert the count rate spectrum per pixel into a spectrum on the given bins of the response function.

Parameters:

lamdasp : array

wavelengths spectrum

countrate : array

count rates at wavelengths

error : array

errors at wavelengths

kwargs : dict

• lamda_response : array

  the wavelength for the response bins

• chatter : int

  verbosity

Returns:

lambda : array

wavelengths of the bins

countrate : array

count rate in the bins

error : array

errors in the bins

Notes

errors are summed as sqrt( sum (errors**2 ) )

plan_obs_using_mags()

uvotpy.uvotgetspec.plan_obs_using_mags(S2N=3.0, lentifilter=None, mag=None, bkgrate=0.16, coi=False, obsfile=None, grism='uv')

Tool to compute the grism exposure time needed to get a certain S/N in the filterband given observed magnitude in lentifilter.

Parameters:

S2N : float

signal to noise desired

lentifilter : str, {‘uvw2’,’uvm2’,’uvw1’,’u’,’b’,’v’}, optional if obsfile given

lenticular filter in which a magnitude is available

mag : float, optional if obsfile given

measured magnitude in lentifilter.

bkgrate : float

the count rate in the background. This parameter determines for weak spectra to a large extent what exposure time is required.

coi : bool

apply coincidence-loss correction ? not yet implemented

obsfile : path, str, optional if lentifilter,`mag` given

ascii filename with two columns wave, flux or a fits file with the spectrum in the second extension

grism : str, {‘uv’}

Returns:

An estimate of the required exposure time is printed

Notes

Lentifilter should be one of: uvw2, uvm2, uvw1, u, b, v

Assumed source is faint - no coi (can later add coi)

The exposure time will ramp up quickly once the target gets too faint. The background in the clocked uv grism varies and can be lower, like 0.06 depnding of where the spectrum is put on the detector. So we could update this program at some point with the uv clocked background variation in it. Typically background values are below 0.1 c/s/arcsec. Higher backgrounds are found in crowded fields.

If obsfile is given, then calculate the magnitudes using the spectrum from the obsfile

TO DO: V grism placeholder

• 16 April 2012, initial version, Paul Kuin

spec_curvature()

uvotpy.uvotgetspec.spec_curvature(wheelpos, anchor, order=1)

Find the coefficients of the polynomial for the curvature.

Parameters:

wheelpos : int, {160,200,955,1000}

grism filter position in filter wheel

anchor : list, array

anchor position in detector coordinates (pixels)

order : int

the desired spectral order

Returns:

Provides the polynomial coefficients for y(x).

Notes

The curvature is defined with argument the pixel coordinate in the dispersion direction with reference to the the anchor coordinates in det-img coordinates. The polynomial returns the offset normal to the dispersion.

• 2011-03-07 Paul Kuin, initial version
• 2011-08-02 fixed nominal coefficients order=1

spectrumpixshift()

uvotpy.uvotgetspec.spectrumpixshift(w1, spec1, w2, spec2, wmin=None, wmax=None, spectrum=False, delwav=False, chatter=0)

Accurately determine relative wavelength/pixel shift between 2 spectra.

Parameters:

w1,spec1, w2,spec2 : array-like

wavelength, spectrum pairs

kwargs : dict

• wmin,wmax: float

limits to region to use

• spectrum : bool

resample 2nd spectra and return second spectrum shifted

• delwav : bool
• chatter : int

verbosity

Returns:

k : int

shift in pixels. option spectrum False, for option delwav False

delwav : float

shift in angstroms. For option spectrum False, option delwav True

k, (w1,s2) : int, tuple

pixel shift, tuple of wave, flux for second spectrum shifted and resampled on wavelength first spectrum for option spectrum True

Notes

k ~ 1/6 pixel [option: resample 2nd spectra ]

sum_Extimage()

uvotpy.uvotgetspec.sum_Extimage(pha_file_list, sum_file_name='extracted_image_sum.fit', mode='create', ankerlist=None, plotimage=True, correlate=True, correlate_wavewindow=[None, None], figno=20, shiftlist=[], clobber=False, chatter=1)

This routine will create/update/read a summed extracted image.

Parameters:

pha_file_list : list

list of PHA filenames written by calls of getSpec

kwargs : dict

• sum_file_name : str

  file name for sum

• mode : str, {‘create’,’read’}

  when ‘create’ make the sum file; when ‘read’ read the sum file

• ankerlist : list, optional

  list of anchor positions

• plotimage : bool, optional

  make a plot of the image

• correlate : bool, optional

  try to determine shifts by correlating the image

• correlate_wavewindow : list

  when correlate True then use only the part of the spectrum within [wavemin, wavemax]

• figno : int, optional

  figure number to use

• shiftlist : list, optional

  list of shifts to apply

• clobber : bool

  write over existing file

• chatter : int

  verbosity

Returns:

When option=read the following are returned:

- sumimg : 2D array

summed image

- expmap : 2D array

exposure map for each pixel in summed image

- exposure : float

exposure time (maximum)

- wheelpos : int

grism wheel position

- C_1, C_2 : list

dispersion coefficients

- dist12 : float

distance in pixels between the first and second order anchors

- anker : list

anchor position in summed image

- coefficients : tuple

(coef0,coef1,coef2,coef3,sig0coef,sig1coef,sig2coef,sig3coef) curvature and sigma coefficients for the summed image

- hdr : fits header

Notes

The anchor point, by default, will be at point [100,500]

mode = ‘create’ <make new sum file>, ‘read’ <read sum file>

The anchor position in the pha_file will need to be passed via ankerlist or be given as keyword ANKXIMG, ANKYIMG in the header of the PHA file (it is).

when correlate_wavewindow = [none,none] nothing is done

= [2300,4000] wavelength range where to do cross correlation on flux to generate corrections to ankx

shiftlist = [None, 0, -2, None ] can be used to force the shifts (in pix)

of the given number in the list of spectra (here assumed to be four. List length must equal pha_file_list length.

Example:

phafiles = [‘sw00032150003ugu_1_pha.fits’,’sw00032150003ugu_2_pha.fits’, ‘sw00032150003ugu_3_pha.fits’, ‘sw00032150003ugu_4_pha.fits’, ‘sw00032150003ugu_5_pha.fits’, ‘sw00032150003ugu_6_pha.fits’, ‘sw00032150003ugu_7_pha.fits’, ‘sw00032150003ugu_8_pha.fits’, ‘sw00032150003ugu_9_pha.fits’, ‘sw00032150003ugu_10_pha.fits’, ‘sw00032150003ugu_11_pha.fits’, ‘sw00032150003ugu_12_pha.fits’, ‘sw00032150003ugu_13_pha.fits’]

uvotgetspec.sumimage( phafiles, mode=’create’,chatter=1,clobber=True)

Paul Kuin 2011 (MSSL/UCL)