Spectrum

class xspec.Spectrum(dataFile)

Spectral data class.

Methods

  • __init__
  • dummyrsp
  • ignore
  • ignoredString
  • notice
  • noticedString
  • show

Attributes ((*) = get-only)

  • areaScale*
  • background
  • backScale*
  • cornorm
  • correction
  • dataGroup*
  • energies*
  • eqwidth*
  • exposure*
  • fileName*
  • flux*
  • ignored*
  • index*
  • isPoisson*
  • lumin*
  • multiresponse
  • noticed*
  • rate*
  • response
  • values*
  • variance*
__init__(dataFile)

Construct a Spectrum object.

Read in a spectrum and any associated background, response and arf files. Spectrum is automatically added to the AllData container.

Args:
dataFile: Spectral data filename [string].
dummyrsp(lowE=None, highE=None, nBins=None, scaleType=None, chanOffset=None, chanWidth=None, sourceNum=1)

Create a dummy response for this spectrum only.

Args (all are optional):

lowE: Input response energy lower bound, in keV. [float]

highE: Input response energy higher bound, in keV. [float]

nBins: Number of bins into which the energy range is divided. [int]

scaleType: ‘log’ or ‘lin’. [string]

chanOffset: Starting value of dummy channel energies. [float]

chanWidth: Energy width of the channel bins. [float]

If chanWidth is set to 0, the dummy response can only be used for evaluating model arrays, and not for fitting to spectra.

sourceNum: Optional source number for the dummy response. [int]

Examples:

# All values are optional, use keywords to enter values
# non-consecutively.  Unspecified values revert to the
# current defaults.
s = Spectrum("dataFile.pha")
s.dummyrsp(.3, 30., 100, chanWidth=.5)
s.dummyrsp(highE = 50., sourceNum = 2)
s.dummyrsp(.1,10.,100,"lin",.0, 1.0, 1)

Initial defaults: lowE = .1, highE = 50., nBins = 50, scaleType = “log” chanOffset = .0, chanWidth = .0, sourceNum = 1

The defaults for lowE, highE, nBins, scaleType, and chanOffset will be modified for each explicit new entry. chanWidth always defaults to 0 and sourceNum always defaults to 1.

To remove the spectrum’s dummy response(s) and restore actual responses (if any), call AllData.removeDummyrsp().

ignore(ignoreRange)

Ignore a range of the spectrum by channels or energy/wavelengths.

Args:

ignoreRange: String specifying the channel range to ignore.

This follows the same syntax as used in the standard Xspec “ignore” command. If the numbers are floats rather than ints, they will be treated as energies or wavelengths (depending on the Plot settings).

Note that “bad” will not work from here, as it can only be applied to ALL of the loaded spectra.

To apply range(s) to multiple spectra, use the AllData ignore function.

ignoredString()

Return a string of ignored channel ranges.

This produces a string in compact (hyphenated) form, which can be used as input to a subsequent ‘ignore’ command. Example:

If ignored channels are [1,3,4,5,7], this function will output “1 3-5 7”.
notice(noticeRange)

Notice a range of the spectrum by channels or energy/wavelengths.

Args:

noticeRange: String specifying the channel range to notice.

This follows the same syntax as used in the standard Xspec “notice” command. If the numbers are floats rather than ints, they will be treated as energies or wavelengths (depending on the Plot settings). If the string is “all”, it will notice all channels in spectrum.

To apply range(s) to multiple spectra, use the AllData notice function.

noticedString()

Return a string of noticed channel ranges.

This produces a string in compact (hyphenated) form, which can be used as input to a subsequent ‘notice’ command. Example:

If noticed channels are [1,3,4,5,7], this function will output “1 3-5 7”.
show()

Display information for this Spectrum object

areaScale

The Spectrum area scaling factor.

This is either a single float (if file stores it as a keyword), or a tuple of floats (if file stores column).

backScale

The Spectrum background scaling factor.

This is either a single float (if file stores it as a keyword), or a tuple of floats (if file stores column).

background

Get/Set the spectrum’s background.

Get:
Returns the Background object associated with the Spectrum. If Spectrum has no background object, this will raise an Exception.
Set:
Supply a background filename [string]. This will become the new background to the Spectrum object, and any previously existing background will be removed. If string is empty, all whitespace, or the Python None variable, the background (if any) will be removed.
cornorm

Get/Set the normalization of a spectrum’s correction file. [float]

correction

Get/Set the correction file.

Get:
Returns the Spectrum’s current correction information as an object of class Background. This raises an Exception if Spectrum has no correction.
Set:
Enter the filename string for the new correction. This will remove any previously existing correction. Returns the new correction info as an object of class Background. If string is “none”, empty, or all whitespace, the current correction will be removed and this will return None.
dataGroup

The data group to which the spectrum belongs [int].

energies

Tuple of pairs of floats (also implemented as tuples) giving the E_Min and E_Max of each noticed channel.

eqwidth

Tuple of 3 floats containing the results of the most recent eqwidth calculation for this spectrum (performed with the AllModels.eqwidth method).

The results are stored as:

[0] - eqwidth calculation

[1] - eqwidth error lower bound

[2] - eqwidth error upper bound

The error bounds will be 0.0 if no error calculation was performed, and all will be 0.0 if eqwidth wasn’t performed for this spectrum.

exposure

The exposure time keyword value [float].

fileName

The spectrum’s file name [string].

flux

A tuple containing the results of the most recent flux calculation for this spectrum.

The tuple values are: (value, errLow, errHigh (in ergs/cm^2), value, errLow, errHigh (in photons)) for each model applied to the spectrum.

ignored

A list of the currently ignored (1-based) channel numbers.

index

The spectrum’s current index number within the AllData container [int].

isPoisson

Boolean flag, true if spectrum has Poisson errors.

lumin

Similar to flux, the results of the most recent luminosity calculation.

multiresponse

Get/Set detector response ARRAY elements when using multiple sources.

This is for use only when assigning multiple responses to a spectrum, for multi-source/multi-model analysis. For standard single-source analysis, use the response attribute instead.

You must provide an array index for all multiresponse get/set operations. Note that array indices ARE 0-BASED, so multiresponse[0] corresponds to source 1. Examples:

# Get the response assigned to source 1.
# This particular call is the same as doing
# "r1 = s.response"
r1 = spec.multiresponse[0]

# Get the response for the second source.
# Can only do this with multiresponse.
r2 = spec.multiresponse[1]

# Define a third source by adding a new response:
spec.multiresponse[2] = "myResp3.pha"

# Now remove the response for the second source:
spec.multiresponse[1] = None
noticed

A list of the currently noticed (1-based) channel numbers.

rate

A tuple containing the total Spectrum rates in counts/sec.

The tuple consists of:

[0] - current net rate (w/ background subtracted),

[1] - net rate variance,

[2] - total rate (without background),

[3] - predicted model rate

response

Get/Set the detector response.

Use this for standard SINGLE-SOURCE analysis. To add other responses for multi-source and multi-model analysis, use the multiresponse attribute.

Get:
Returns a Response object, or raises an Exception if none exists
Set:
Supply a response filename string. To remove a response, supply an empty string or None.
values

Tuple of floats containing the spectrum rates for noticed channels in counts/cm^2-sec.

variance

Tuple of floats containing the variance of each noticed channel.