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', *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).

abstract __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 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 fast_energies

Get coarse array of energies for fast-mode likelihood evals.

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.

register(signals, fast_mode=False, threads=1)

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(phase_shifts, directory, **kwargs)

Synthesise signal data according to the generative model.

Parameters:

• phase_shifts (iterable) – Container of phase shift Parameter instances, one per hot region, communicated by the likelihood object from the star object. The order is equal to the order of the hot region objects stored in photosphere.hot.objects.

• directory (str) – Path to directory in which to write synthetic data. It is recommended that the prefix of the signal appears in the filename.

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

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.