uvotio

Major functions

fileinfo()

uvotpy.uvotio.fileinfo(filestub, ext, lfilt1=None, directory='./', chatter=0, wheelpos=None, twait=40.0)

finds files for spectrum, matching attitude and lenticular images uncompresses gzipped files if found

Parameters:

filestub : str

the base of the file name, with the Swift project convention, consisting of “sw” + the OBSID, i.e., “sw00032301001”

ext : int

the number of the extension of the grism file to match

kwargs : dict

• lfilt1 : str, optional

name of first lenticular filter used. Must be one of ‘uvw2’, ‘uvm2’,’uvw1’,’u’,’b’,’v’,’wh’

• directory : path, str

path for directory. This is the directory with the grism file.

• chatter : int

verbosity

• twait : float

The maximum time allowed between begin and end of matched exposures of grism-lenticular filter, for each match.

• wheelpos : imt

If given, use to discriminate between UV and Visual grisms.

Returns:

specfile, attfile: str

filename of spectrum, the attitude file name.

lfilt1, lfilt2 : str

lenticular filter file name before the grism exposure or None, and the file name of the lenticular filter following the grism

lfilt1_ext,lfilt2_ext : int

extension number for each lenticular filter matching exposure

rate2flux()

uvotpy.uvotio.rate2flux(wave, rate, wheelpos, bkgrate=None, pixno=None, co_sprate=None, co_bgrate=None, arf1=None, arf2=None, effarea1=None, effarea2=None, spectralorder=1, anker=None, test=None, msg='', respfunc=False, swifttime=None, option=1, fudgespec=1.0, frametime=0.0110329, debug=False, chatter=1)

Convert net count rate to flux

WARNING: dependent on the parameters passed, the old CALDB (<=2012)

OR the new flux calibration will be used. Since 10SEP2012 the coi-factor is included in the calculation of the flux and the effective area. A coi-correction is still made when using the old CALDB which will be inconsistent to that calculated in the writeSpectrum() which makes the output file.

many of the parameters are needed to calculate the coi-factor

Parameters:

wave : float ndarray

wavelength in A

rate, bkrate : float ndarray

net and background count rate/bin in spectrum, aperture corrected

co_sprate, co_bgrate : ndarray

total of spectrum+background and background rate/bin for the coincidence area of constant width (default set to 16 pixels)

wheelpos : int

filter wheel position

pixno : ndarray

pixel coordinate (zero = anchor; + increasing wavelengths)

co_sprate, cp_bgrate : ndarray

rates for calculating the coincidence loss

arf1, arf2 : path or “CALDB”, optional

effarea1, effarea2 : FITS HDU[, interpolating function]

result from a previous call to readFluxCalFile() for first or second order

spectralorder : int

the spectral order of the spectrum, usually =1

trackwidth : float

width of the spectral extraction used in units of sigma

anker : list

anchor detector coordinate positions (pix) as a 2-element numpy array

frametime : float

the frame time for the image is required for the coi-correction

swifttime : int

swift time of observation in seconds for calculating the sensitivity loss

debug : bool

for development

chatter : int

verbosity (0..5)

respfunc : bool

return the response function (used by writeSpectrum())

Returns:

(flux, wave, coi_valid) : tuple

coi-corrected flux type interp1d, array wave, and matching boolean array for points not too bright for coincidence loss correction

Notes

2013-05-05 NPMKuin - adding support for new flux calibration files; new kwarg 2014-02-28 fixed. applying fnorm now to get specrespfunc, pass earlier effective area 2014-04-30 NPMK changed coi_func parameters (option=1,fudgespec=1.322,frametime,coi_length=29)

readFluxCalFile()

uvotpy.uvotio.readFluxCalFile(wheelpos, anchor=None, option='default', spectralorder=1, arf=None, msg='', chatter=0)

Read the new flux calibration file, or return None.

Parameters:

wheelpos : int, required

the position of the filterwheel

kwargs: dict

• anchor : list, optional coordinate of the anchor

• option : str option for output selection:

  option==”default” + anchor==None: old flux calibration option==”default” + anchor : nearest flux calibration + model extrapolation option==”nearest” : return nearest flux calibration option==”model” : model

• spectralorder

  : int

  spectral order (1, or 2)

• arf: path

  fully qualified path to a selected response file

• msg: str

  buffer message list (to add to)

Returns:

None if not (yet) supported

option == ‘model’ returns the (astropy/pyfits) fits HDU (header+data) of the model

option == ‘nearest’

returns the fits HDU of the nearest calfile

option == ‘default’ and anchor == None:

returns the fits HDU of the nearest calfile

option == ‘default’ and anchor position given (in detector coordinates)

returns the fits HDU and an interpolating function fnorm(wave in A) for the flux correction

msg : string comments separated by

Notes

2013-05-05 NPMKuin

sensitivityCorrection()

uvotpy.uvotio.sensitivityCorrection(swifttime, wave=None, sens_rate=0.01, wheelpos=0)

give the sensitivity correction factor Actual flux = observed flux(date-obs) times the sensitivity correction

Parameters:

swifttime : float

time of observation since 2005-01-01 00:00:00 in seconds, usually TSTART

sens_rate : float

the yearly percentage loss in sensitivity

wave : array, optional

the wavelength for (future) in case sensitivity(time, wavelength)

Notes

A 1%/year decay rate since 2005-01-01 has been assumed and the length of the mean Gregorian year was used

writeSpectrum()

uvotpy.uvotio.writeSpectrum(ra, dec, filestub, ext, Y, fileoutstub=None, arf1=None, arf2=None, fit_second=True, write_rmffile=True, used_lenticular=True, fileversion=2, calibration_mode=True, history=None, chatter=1, clobber=False)

Write a standard UVOT output file - Curved extraction only, not optimal extraction.

Parameters:

ra,dec : float, float

position in decimal degrees

filestub : str

“sw” + obsid

ext : int

extension number

Y : tuple

compound variable with spectral data from uvotgetspec

Returns:

Writes the output file only.

Notes

Output file composition

For details, see the output file format description.

wheelpos, filter, orders, author

writeEffAreaFile()

uvotpy.uvotio.writeEffAreaFile(wheelpos, spectralorder, wave, specresp, specresp_err=None, anker=None, dxy_anker=None, fileversion='999', todir='./', rebin=True, clobber=False)

create an ARF file

Parameters:

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

spectralorder: int, {1,2}

wave: ndarray

wavelengths in Angstrom

specresp: ndarray

effective area (EA) in cm^2 for each wave

specresp_err: ndarray

1-sigma EA error (random + systematic)

anker: list, ndarray[2]

2-element array with position in det coordinates of EA

dxy_anker: list,ndarray[2]

EA determined for box [anker[0]+/-dxy_anker[0], anker[1]+/-dxy_anker[1]]

fileversion: str

version for this EA (spectral response) file.

todir: path

directory to place the file into

rebin : bool

When true (old behaviour) bin 1 A in wavelength When False, make one bin for each point in array wave.

Returns:

the new effective area file with file name something like:

‘swugu0160_ax1100ay1100_dx150dy150_o1_20041120v001.arf’

Notes

• Modified 15-SEP-2012 by Paul Kuin.

With only wheelpos, spectralorder, wave, specresp input, the output file conforms to the HEASARC approved response file. The additional keywords and error column have not been approved as of 15 September 2012.

• Modified 13 Feb 2013 by Paul Kuin

Added futher keyword COIAWARE to discriminate between the old and new effective areas and changed comments after keywords to be more descriptive.

• Modified 5 March 2013 by Paul Kuin

header edited

• Renamed 28 Dec 2013

first extension assumed 1-spaced wavelengths. Relaxed to allow variable wavelengths.

• changed to reflect use of full coi-solution 2014-08-20. Paul Kuin
• added no rebinning as option. It actually will rebin slightly by calculating the minimum value of the bin from the distance of its neighbors, and the maximum value is chosen to have no gaps between bins.

write_rmf_file()

uvotpy.uvotio.write_rmf_file(rmffilename, wave, wheelpos, disp, flux=None, anchor=[1000, 1000], spectralorder=1, effarea1=None, effarea2=None, lsfVersion='001', msg='', chatter=1, clobber=False)

Write the RMF file for the first order spectrum

Parameters:

rmffile : path, str

file name output file

wave

: ndarray

mid-wavelengths of the bins in the spectrum

flux

: ndarray [default None]

used to omit channels of invalid (NaN) or negative flux values from the response file

wheelpos

: int

filter wheel position

disp

: ndarray

dispersion coefficients

anchor

: 2-element list

The anchor position is used to select the correct effective area (important for the clocked grism modes).

spectralorder

: 1

** Do not change ** Only for the first order the RMF can currently be computed.

effarea1, effarea2

: hdu, interpolating function

do not use unless you know what you’re doing

lsfVersion

: [‘001’,‘003’]

version number of the LSF file to be used.

chatter

: int

verbosity

clobber

: bool

if true overwrite output file if it already exists

Returns:

Writes the RMF file

Notes

The count rate has been corrected for coincidence loss (version 2 SPECTRUM extension). The spectral response varies in the clocked grisms, is nearly constant in the nominal grisms. Therefore, in the clocked grisms, the rmf file needs to be created specifically for the specific spectrum.

The rmf files have also energy bins corresponding to the wavelength bins in the spectrum. These also show some variation from spectrum to spectrum.

The line spread function from the uv grism at default position is currently used for all computations. Since the RMF file encodes also the effective area, this version presumes given anchor position.

2014-02-27 code cleaned up. Speed depends on number of points 2015-02-02 versioning lsf introduced; changed instrument FWHM values 2015-02-04 error found which affects the longer wavelengths (> 3500A) 2015-02-04 verified the LSF with a calibration spectrum, which shows

instrumental broadening of 10+-1 Angstrom and at long wavelengths (6560) the same broadening predicted by the Zemax optical model.

2015-02-09 There was a major overhaul of this routine, which is now

much improved.

2015-02-13 remove trimming of channels

Key functions

XYSpecResp()

uvotpy.uvotio.XYSpecResp(wheelpos=None, spectralorder=1, anker=[1129, 1022], test=None, chatter=0)

the spectral response based on the position of the anchor of the spectrum. Depends on the grism mode via ‘wheelpos’ and the spectral order.

Parameters:

wheelpos : int

kwargs : dict

• spectralorder

  : int

  order of the spectrum

• anker

  : list

  position in detector coordinates (pixels)

• test

  : any

  if not None then get the response at the boresight

Returns:

An interpolating function for the spectral response

based on the position (Xank,Yank) of the anchor of the spectrum.

Depends on the grism mode via ‘wheelpos’ and the spectral order.

Notes

Will be superseded by readFluxCalFile

getZmxFlux()

uvotpy.uvotio.getZmxFlux(x, y, model, ip=1)

Interpolate model to get normalized flux.

Parameters:

x, y : float

anchor coordinate x,y to find an interpolated solution to the model

model : fits structure

binary table extension (header + data) fields are wave, xpix, ypix, flux

ip : int

The order of the interpolation (1=linear, 2=quadratic, 3=cubic)

Returns:

flux interpolated at (x,y) in (xpix, ypix) as function of wave

kev2angstrom()

uvotpy.uvotio.kev2angstrom(E, unit='keV')

conversion of units

Returns:The photon wavelength in angstroms

angstrom2kev()

uvotpy.uvotio.kev2angstrom(E, unit='keV')

conversion of units

Returns:The photon wavelength in angstroms

updateResponseMatrix()

uvotpy.uvotio.updateResponseMatrix(rmffile, C_1, clobber=True, lsffile='zemaxlsf', chatter=0)

modify the response matrix lineprofiles using the zemax model prediction from zemaxlsf.fit In addition the zemax profile is broadened by the instrumental broadening of 2.7 pixels.

Parameters:

rmffile : path, str

The rmffile is updated by default

C_1: ndarray

The dispersion C_1 is used to convert pixels to angstroms.

kwargs : dict

• lsffile : path

  The lsffile is in the $UVOTPY/calfiles directory

• clobber : bool

  overwrite output.

• chatter : int

  verbosity

Returns:

writes RMF file

Notes

The same algorithm was implemented in the write_rmf_file() routine which does not need the input rmf file produced by the “Ftool” rmfgen. write_rmf_file was rewritten 2015-02-08