Spectrum

class xspec.Spectrum(dataFile, backFile='USE_DEFAULT', respFile='USE_DEFAULT', arfFile='USE_DEFAULT')

Spectral data class.

Methods

  • __init__

  • dummyrsp

  • fileinfo

  • 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

  • responsesUsed*

  • statistic*

  • values*

  • variance*

  • xflt*

__init__(dataFile, backFile='USE_DEFAULT', respFile='USE_DEFAULT', arfFile='USE_DEFAULT')

Construct a Spectrum object.

Read in a spectrum and any associated background, response and arf files. The only required argument is the dataFile name. By default, it will also read in all associated files as given by the keywords stored in the data file.

You may override the default associated files with additional optional arguments. These may also be changed at a later time with Spectrum's background and response attributes (and Response's arf attribute).

Note that PyXspec will always first try to load the associated files as given by the dataFile's internal keywords. Then it replaces them with the specified optional argument file names.

The Spectrum object is automatically added to the AllData container.

Args:

dataFile: Spectral data filename [string].

Optional Args:

backFile: Background filename [string].

respFile: Response filename [string].

arfFile: Arf filename [string].

These may be used to override the filenames given by the keywords stored in the spectral data file. If they are blank or the Python None variable, the corresponding default file will be removed with no replacement,

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

fileinfo(keyword)

Return the value of a particular keyword in the SPECTRUM extension.

Args:

keyword: Name of the keyword

The value is returned as a string.

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

property 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).

property 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).

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

property cornorm

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

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

property dataGroup

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

property energies

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

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

property exposure

The exposure time keyword value [float].

property fileName

The spectrum's file name [string].

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

property ignored

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

property index

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

property isPoisson

Boolean flag, true if spectrum has Poisson errors.

property lumin

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

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

property 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
property noticed

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

property 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 uncertainty,

[2] - total rate (without background),

[3] - predicted model rate

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

property responsesUsed

Return a list of detector slot numbers with currently assigned responses.

The values returned are 0-based ([0] = source 1, [1] = source 2, etc.) If no responses are assigned to spectrum, the list will be empty.

property statistic

Spectrum's contribution to the total fit statistic [float].

property values

Tuple of floats containing the spectrum rates for noticed channels in counts/sec.

property variance

Tuple of floats containing the variance of each noticed channel.

property xflt

XFLT key-value pairs returned as a tuple of tuples