Major functions


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


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


  • 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.


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


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


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())


(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


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)


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

Read the new flux calibration file, or return None.


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)


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


2013-05-05 NPMKuin


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


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)


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


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.


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


Writes the output file only.


Output file composition

For details, see the output file format description.

wheelpos, filter, orders, author


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


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.


the new effective area file with file name something like:



  • 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.


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


rmffile : path, str

file name output file

: ndarray

mid-wavelengths of the bins in the spectrum

: ndarray [default None]

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

: int

filter wheel position

: ndarray

dispersion coefficients

: 2-element list

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

: 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

: [‘001’,‘003’]

version number of the LSF file to be used.

: int


: bool

if true overwrite output file if it already exists


Writes the RMF file


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


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.


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


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.


Will be superseded by readFluxCalFile


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

Interpolate model to get normalized flux.


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)


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


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

conversion of units

Returns:The photon wavelength in angstroms


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

conversion of units

Returns:The photon wavelength in angstroms


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.


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



writes RMF file


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