Signal

Instances of Signal are objects which define the generative relationship between the pulse and X-ray photon data. That is, the parametrised sampling distribution of the photon data is defined.

class xpsi.Signal.Signal(data, instrument, background=None, interstellar=None, support=None, photosphere_prefix=None, cache=False, bounds=None, values=None, stokes='I', min_channel=0, max_channel=-1, tolerance=0.0, *args, **kwargs)

Bases: ParameterSubspace

A signal is constituted by some X-ray dataset, a model instrument with which that data was acquired, a model background, and an object for modelling interstellar processes.

The methods in this class must transform incident specific flux signals into a structure congruent to that of the data for the purpose of evaluation of the custom likelihood implemented via subclassing.

Parameters:

• data (obj) – An instance of Data.

• instrument (obj) – An instance of Instrument.

• background (obj) – If not None, an instance of Background. It is assumed if one constructs a model using instances of Background that the background needs to be registered by a model instrument. If None, it is still possible for one to define and use background parameters in a custom subclass of Signal. In particular, background parameters for some model which directly specifies background contribution in units of count/s per output channels. These background parameters can even be the counts/s in output channels.

• interstellar (obj) – If not None, an instance of Interstellar. To be applied to the incident signal as a callable that modifies the signal in place.

• photosphere_prefix (str) – The str prefix of the photosphere object with which this signal object is associated.

• cache (bool) – Cache intermediary signals during likelihood evalation? When performing post-processing, this needs to be activated for full functionality of the PostProcessing module. For likelihood function evaluation during sampling, caching should be deactivated because it is not used. It might be useful to activate caching also when preparing a model for a sampling application, to check the likelihood function works as intended.

• store (bool) – Deprecated. You can use this or cache, which has the same effect.

• stokes (str) – Define the type of the signal. Options are Stokes “I” (default), “Q”, “U”, “Qn” (Q/I), and “Un” (U/I).

abstractmethod __call__(**kwargs)

Compute the logarithm of the likelihood and store it as a property.

The keyword arguments currently communicated by an Likelihood instance are as follows.

Parameters:

• threads (int) – Number of OpenMP threads to use for likelihood evaluation. This argument can be ignored if not required.

• llzero (float) – The minimum log-likelihood setting for MultiNest. Points whose log-likelihood is lower than this value are ignored.

property background

Get the instance of Background.

property background_signal

Get stored background.

property bolometric_chi2

Return the bolometric chi2 value for the current likelihood value.

property caching_target_names

Just return the names of the caching targets.

property caching_targets

Get a dictionary of model objects for caching.

Called by the post-processing module.

Raises:

AttributeError – If a property is not set in methods of a subclass, or if the self.store property is not True.

create_energy_array(rel_num_energies=10.0)

Get a (finer) array of energies spanning instrument waveband.

Useful for getting an appropriately bounded and spaced set of energies for signal interpolation.

Parameters:

rel_num_energies (float) – The number of energies desired as a fraction of the number of energies implemented for incident signal integration.

property data

Get the stored data object.

property energy_edges

Get a numpy.ndarray of energy edges.

execute_custom_cache_instructions()

Subclass and overwrite to specify custom cache objects.

The default cached objects, when cache mode is activated, are handled in the register() method.

property incident_flux_signals

Get the incident flux signal components.

These signals are integrated over a set of energy intervals spanning the instrument waveband.

property incident_specific_flux_signals

Get the incident signal components.

property instrument

Get the instance of Instrument.

property interstellar

Get the instance of Interstellar.

property isI

…

property isQ

…

property isQn

…

property isU

…

property isUn

…

property loglikelihood

Return the logarithm of the likelihood.

Raises:

AttributeError – If property not set in methods of a subclass.

property original_data

Get the a copy of the original instance of Data.

register(signals, threads=1, reset=True)

Register an incident signal by operating with the response matrix.

A numpy.ndarray is stored as an instance attribute containing source signal for each output channel in units of counts cm^2/s (assuming instrument effective area units are cm^2).

property shifts

Returns the hot region phase plus the instrument phase-shift.

property signals

Get the stored channel-by-channel signal components.

synthesise(exposure_time=None, expected_source_counts=None, data_BKG=None, expected_background_counts=None, format='TXT', instrument_name=None, backscal_ratio=1.0, name='synthetic', directory='./', seed=None, save_background=True, **kwargs)

Synthesise data set in FITS format that can be used in input of X-PSI. Data can be synthesised with or without background.

Parameters:

• exposure_time (float) – Exposure time in seconds.

• expected_source_counts (float) – Total expected number of source counts.

• data_BKG (array) – One (or two) dimensional array of expected phase-averaged (phase-resolved) background counts in the background extraction region. It must be None if using the signal._background.

• expected_background_counts (float) – Total expected number of background counts.

• format (str) – Format of the output file. Can be either TXT or FITS.

• instrument_name (str) – Instrument name to be written to the header. Can be None for txt format. Beware that it must be the same as the one in the background and response files.

• backscal_ratio (float) – Ratio of the backscal parameters of the background to the source one. This is used to rescale the background counts to be extracted from a similar area as the source ones. If the input background is considered from the same region as the source, set it to 1.

• name (str) – Base name of synthetic data files.

• directory (str) – Directory in which to write the synthetic data files.

• seed (int) – Random seed for the pseudo-random number generator.

• save_background (bool) – If True, the synthetic background is saved in the FITS file. If False, it is not saved. For NICER for instance, it does not need to be saved as it is unknown.

class xpsi.Signal.LikelihoodError

Bases: xpsiError

Raised if there is a problem with the value of the log-likelihood.

xpsi.Signal.construct_energy_array(num_energies, signals, max_energy=None)

Construct an array of photon energies for integration.

Parameters:

• num_energies (int) – Number of energies, distributed over union of wavebands covered by instruments that registered the data signals.

• signals (list) – An unordered list of Signal instances.