Data

Instances of Data are X-ray photon data containers.

class xpsi.Data.Data(counts, channels, phases, first, last, exposure_time)[source]

A container for event data.

The working assumption is that the sampling distribution of this event data can be written in terms of a set of channel-by-channel count-rate signals. The instrument associated with this data in an instance of Signal must transform incident signals into a structure congruent to that of the event data. The attributes and methods of this class and any derived classes must therefore store information required for this operation.

The initialiser assigns observation settings to attributes which are required for the treating the incident specific flux signals using the model instrument. The body of the initialiser may be changed, but to ensure inter-module compatibility, only the phase handling should really be modified, for instance if you want to implement an unbinned likelihood function with respect to phase; the phase bins defined in this concrete implementation are only used by a custom implementation of the likelihood function (i.e., by a subclass of xpsi.Signal), and not by the other concrete classes used to construct the likelihood callable. The initialiser can also be extended if appropriate using a call to super().__init__. Specialist constructors can be defined in a subclass using the @classmethod decorator, for instance to load event data from disk into a compatible data structure in memory; an example of this may be found below.

Note

You can subclass in order to tailor the handling of the event data, for instance to implement a likelihood functions for unbinned event data.

Parameters:

counts (ndarray[n,m]) – A ndarray of count numbers. The columns must map to the phase intervals given by phases. The rows of the array map to some subset of instrument channels.
channels (ndarray[n]) – Instrument channel numbers which must be equal in number to the first dimension of the matrix: the number of channels must 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). It is advisable that these numbers are the actual instrument channel numbers so that plots generated by the post-processing module using these labels are clear.
phases (ndarray[m+1]) – A ndarray of phase interval edges, where events are binned into these same intervals in each instrument channel.
first (int) – The index of the first row of the loaded response matrix containing events (see note below).
last (int) – The index of the last row of the loaded response matrix containing events (see note below).

Note

The counts matrix rows must span a contiguous subset of the rows of the loaded response matrix, but in general can span an arbitrary subset and order of instrument channels. Note that the first and last+1 numbers are used to index the loaded instrument response matrix. Therefore, if you load only a submatrix of the full instrument response matrix, these indices must be appropriate for the loaded submatrix, and must not be the true channel numbers (this information is instead loaded in the xpsi.Instrument). Of course, in all sensible usage patterns the order of the instrument channels, when mapped to matrix rows, will be such that channel number increases with matrix row number monotonically because, then the nominal event energy increases monotonically with row number, which is important for visualisation of data and model (because spatial order matches energy order and correlations in space can be discerned easily). However, there could in principle be channel cuts that mean an increment of more than one channel between matrix adjacent rows, and the response matrix needs to be manipulated before or during a custom loading phase such that its rows match the channel numbers assigned to the counts matrix rows.

Parameters:: exposure_time (float) – The exposure time, in seconds, to acquire this set of event data.

property channels: Get the array of channels that the event data spans.

property exposure_time: Get the total exposure time in seconds.

property index_range: Get a 2-tuple of the bounding response-matrix row indices.

classmethod phase_bin__event_list(path, channels, phases, channel_column, phase_column=None, phase_averaged=False, phase_shift=0.0, channel_edges=None, skiprows=1, eV=False, dtype=<class 'numpy.int32'>, *args, **kwargs)[source]

Load a phase-folded event list and bin the events in phase.

Parameters:

path (str) – Path to event list file containing two columns, where the first column contains phases on the unit interval, and the second column contains the channel number.
channels (ndarray[n]) – An (ordered) subset of instrument channels. It is advisable that these channels are a contiguous subset of instrument channels, but this not a strict requirement if you are comfortable with the handling the instrument response matrix and count number matrix to match in row-to-channel definitions.
phases (list) – An ordered sequence of phase-interval edges on the unit interval. The first and last elements will almost always be zero and unity respectively.
phase_shift (float) – A phase-shift in cycles to be applied when binning the events in phase.
phase_column (int) – The column in the loaded file containing event phases.
phase_averaged (bool) – Is the event data phase averaged?
channel_column (int) – The column in the loaded file containing event channels.
channel_edges (ndarray[n+1]) – The nominal energy edges of the instrument channels, assumed to be contiguous if binning event energies in channel number.
skiprows (int) – The number of top rows to skip when loading the events from file. The top row of couple of rows will typically be reserved for column headers.
eV (bool) – Are event energies in eV, instead of channel number?
dtype (type) – The type of the count data. Sensible options are numpy.int (the default) or a numpy floating point type. The choice here only matters when executing custom likelihood evaluation code, which might expect a type without checking or casting.

property phases: Get the phases.