Instrument¶
Instances of Instrument
are objects representing a model
instrument.

class
xpsi.Instrument.
Instrument
(matrix, energy_edges, channels, channel_edges=None, *args, **kwargs)[source]¶ Bases:
xpsi.ParameterSubspace.ParameterSubspace
Base class for astronomical Xray instruments onboard space telescopes.
The body of the initialiser must not be changed to ensure intermodule compatibility, but can be extended if appropriate using a call to
super().__init__
. Specialist constructors can be defined in a subclass using the@classmethod
decorator.Parameters:  matrix (ndarray[p,q]) – A \(p \times q\) matrix which is the product of a redistribution
matrix and effective area vector. The input energy intervals must
increase along the columns of
matrix
, and the output channels must increase along the rows ofmatrix
. The units of the elements must be that of an effective area (\(cm^2\)). Generally there will be some available calibration product, and deviations from this nominal response model will be parametrised. So here load some nominal response matrix.  energy_edges (ndarray[q+1]) – Energy edges in keV of the instrument energy intervals which must be
congruent to the first dimension of the
matrix
: the number of edges must be \(q + 1\). The edges must be monotonically increasing. These edges will correspond to the nominal response matrix and any deviation from this matrix (see above).  channels (ndarray[p]) – Instrument channel numbers which must be equal in number to the number
of rows of the
matrix
. The number of channels must therefore be \(p\). These channels will correspond to the nominal response matrix and any deviation from this matrix (see above). In common usage patterns, the channel numbers will increase monotonically with row number, and usually increment by one (but this is not necessary).
Note
That these channel numbers are not used to index the loaded instrument (sub)matrix. The
xpsi.Data.index_range
property returns bounding row numbers that index the loaded instrument response (sub)matrix in order to operate on an incident signal flux. The channel array contained inxpsi.Data.channels
must be a contiguous (ordered) subset of the channel array loaded here.Note
The dimensions of the response matrix need not be equal, but it is required that the number of input intervals be greater than or equal to the number of output channels – i.e., \(p \leq q\). If \(p < q\) then it is implied that subsets of adjacent output channels are effectively grouped together.
Parameters:  channel_edges (ndarray[p+1]) – The channel (energy) edges of the instrument, in keV. The array must
be congruent to the zeroth dimension of the
matrix
: the number of edges must be \(p + 1\). The edges must be monotonically increasing. These edges will correspond to the nominal response matrix and any deviation from this matrix (see above).  args (tuple) – Container of parameter instances.
 kwargs (dict) – If you want to prefix parameters of an instance of this instrument subspace with an identifier, pass it as keyword argument and it will find its way to the base class.

__call__
(signal, irange, orange)[source]¶ Register an incident signal.
Parameters:  signal (ndarray[m,n]) – An \(m \times n\) matrix, where input energy interval
increments along rows, and phase increases along columns. The
number of rows, \(m\), must equal the number of columns of
matrix
: \(m=q\).  irange (arraylike) – Indexable object with two elements respectively denoting the
indices of the first and last input intervals. The response
matrix
matrix
must be indexable with these numbers, i.e., they must satisfy \(indx < q\).  orange (arraylike) – Indexable object with two elements respectively denoting the
indices of the first and last output channels. The response
matrix
matrix
must be indexable with these numbers, i.e., they must satisfy \(indx < p\).
Returns: ndarray[p,n] containing the registered signal.
Note
The product of the most recent operation is stored as the property
cached_signal
. signal (ndarray[m,n]) – An \(m \times n\) matrix, where input energy interval
increments along rows, and phase increases along columns. The
number of rows, \(m\), must equal the number of columns of

cached_signal
¶ Get the cached registered signal.

channel_edges
¶ Get the channel (energy) edges of the instrument, in keV.
A
numpy.ndarray
of edges of the registered energy intervals labelled as channels defined in the data space. This is relevant when there is a detectorbydetector gain scale applied to event data (such as for NICER instrument calibration products), meaning that the redistribution matrix is effectively shared by detectors and the channels across detectors can share an energy scale definition.An incident photon of given energy then has a registeredenergy distribution that generally peaks in the vicinity of the true photon energy. The resdistribution matrix will have some energy resolution (along with other features such as shelves). With thanks to Paul S. Ray for explaining the choice to calibrate in this manner.
Note
If you made a channel cut that results in a noncontiguous subset of channels, you will need to overwrite the setter method because the checks will fail.

channels
¶ Get the array of channels corresponding to rows of the matrix.
The matrix being the loaded instrument response (sub)matrix.

construct_matrix
()[source]¶ Construct the response matrix if it is parameterised.
If customising, do operations to calculate a matrix, and return it. You can access parameters (free, fixed, and derived) via the container access
self[<name>]
.If the instrument operation is fixed, you might not need to subclass, because the default behaviour is to return the nominal response you loaded. If for some reason the matrix you loaded is to be modified in some fixed manner, possibly as a function of some custom fixed parameters that you defined, you would also have to subclass and provide the correct implementation of this method.

energy_edges
¶ Get the energy edges of the instrument, in keV.
A
numpy.ndarray
of edges of the input energy intervals which map to channels defined in the data space.

matrix
¶ Get the reference response matrix.
In common usage patterns there will be some fiducial or nominal response matrix that either defines fixed instrument operation or is a basis for parametrised deviations. This matrix is usually a calibration product distributed by an instrument calibration team.
A matrix of dimension \(p \times q\). Here \(p\) must be the number of input energy intervals, and \(q \geq p\) the number of output channels.
Note
The attribute
matrix
must be assigned, and it must be anumpy.ndarray
for use withnumpy.dot()
(even if the matrix is sparse to some degree).
 matrix (ndarray[p,q]) – A \(p \times q\) matrix which is the product of a redistribution
matrix and effective area vector. The input energy intervals must
increase along the columns of

class
xpsi.Instrument.
ResponseError
[source]¶ Bases:
xpsi.global_imports.xpsiError
Raised if there is a problem with the input response matrix.