Tools¶
Tools for signal handling.
The extensions in this module are available for users to implement custom likelihood functions, and for developers who wish to contribute to the source code.
Phase handling¶

xpsi.tools.
phase_integrator
(double exposure_time, __Pyx_memviewslice phases, __Pyx_memviewslice signal, __Pyx_memviewslice signal_phases, double phase_shift, bool allow_negative=0)¶ Integrate a signal over phase intervals.
Parameters:  exposure_time (double) – Total exposure time in seconds. The exposure time scales the integrated signal.
 phases (double[::1]) – A
numpy.ndarray
of phase interval edges in rotational cycles.  signal (double[:,::1]) – A Ccontiguous
numpy.ndarray
of signal count rates. Phase increases with column number.  signal_phases (double[::1]) – A Ccontiguous
numpy.ndarray
of phases in cycles at which the modelsignal
is evaluated on the interval[0,1]
.  phase_shift (double) – A phase shift in cycles such as on the interval
[0.5,0.5]
.  allow_negative (obj) – A boolean declaring whether to allow negative phase interpolant integrals. If the interpolant is not a Steffen spline, then the interpolant of a nonnegative function can be negative due to oscillations. For the default Akima Periodic spline from GSL, such oscillations should manifest as small relative to those present in cubic splines, for instance, because it is designed to handle a rapidly changing secondorder derivative.
Returns: A 2D
numpy.ndarray
of the phaseshifted signal integrated over phase intervals and scaled by the exposure time. Phase interval number increases with column number.

xpsi.tools.
phase_interpolator
(__Pyx_memviewslice new_phases, __Pyx_memviewslice phases, __Pyx_memviewslice signal, double phase_shift, bool allow_negative=0)¶ Interpolate a signal in phase.
Parameters:  new_phases (double[::1]) – A
numpy.ndarray
of phases in rotational cycles at which to interpolate.  signal_phases (double[::1]) – A Ccontiguous
numpy.ndarray
of phases in cycles at which the modelsignal
is evaluated on the interval[0,1]
.  signal (double[:,::1]) – A Ccontiguous
numpy.ndarray
of signal count rates. Phase increases with column number.  phase_shift (double) – A phase shift in cycles, such as on the interval
[0.5,0.5]
.  allow_negative (obj) – A boolean declaring whether to allow negative phase interpolant integrals. If the interpolant is not a Steffen spline, then the interpolant of a nonnegative function can be negative due to oscillations. For the default Akima Periodic spline from GSL, such oscillations should manifest as small relative to those present in cubic splines, for instance, because it is designed to handle a rapidly changing secondorder derivative.
Returns: A 2D
numpy.ndarray
of the phaseshifted signal interpolated at the new set of phases. Phase increases with column number. new_phases (double[::1]) – A
Energy handling¶

xpsi.tools.
energy_integrator
(size_t N_Ts, __Pyx_memviewslice signal, __Pyx_memviewslice energies, __Pyx_memviewslice energy_edges)¶ Integrate a signal over energy intervals.
Parameters:  N_Ts (size_t) – Number of OpenMP threads to spawn.
 signal (double[:,::1]) – A Ccontiguous
numpy.ndarray
of an energyresolved (specific flux) signal. Energy increases with row number.  energies (double[::1]) – A
numpy.ndarray
of the logarithms (base 10) of the energies.  energy_edges (double[::1]) – A
numpy.ndarray
of the logarithm (base 10) of the energy interval edges.
Returns: A 2D
numpy.ndarray
of the signal integrated over energy intervals. Energy interval number increases with row number.

xpsi.tools.
energy_interpolator
(size_t N_Ts, __Pyx_memviewslice signal, __Pyx_memviewslice energies, __Pyx_memviewslice new_energies)¶ Interpolate a signal in energy.
Parameters:  N_Ts (size_t) – Number of OpenMP threads to spawn.
 signal (double[:,::1]) – A Ccontiguous
numpy.ndarray
of an energyresolved (specific _signal) signal. Energy increases with row number.  energies (double[::1]) – A
numpy.ndarray
of the logarithms (base 10) of the energies at which thesignal
is resolved.  new_energies (double[::1]) – A
numpy.ndarray
of the logarithm (base 10) of the energies at which to interpolate.
Returns: A 2D
numpy.ndarray
of the signal interpolated at the new set of energies. Energy increases with row number.
Synthesis¶

xpsi.tools.
synthesise_exposure
(double exposure_time, __Pyx_memviewslice phases, components, component_phases, phase_shifts, double expected_background_counts, __Pyx_memviewslice background, allow_negative=False)¶ Synthesise Poissonian count numbers given an exposure time.
Parameters:  exposure_time (double) – Exposure time in seconds by which to scale the expected count rate
 phases (double[::1]) – A
numpy.ndarray
of phase interval edges in cycles.  components (tuple) – Component signals, each a Ccontiguous
numpy.ndarray
of signal count rates where phase increases with column number.  component_phases (tuple) – For each component, a Ccontiguous
numpy.ndarray
of phases in cycles at which the modelsignal
is evaluated on the interval[0,1]
.  phase_shift (arraylike) – Phase shifts in cycles, such as on the interval
[0.5,0.5]
, for the component signals.  expected_background_counts (double) – The total expected number of background counts to set the background normalisation (given the exposure time).
 background (double[:,::1]) – A Ccontiguous
numpy.ndarray
of background expected counts, whose shape matches the number of channels in each element ofcomponents
and the number of phase intervals constructed fromphases
.
Returns: A tuple
(2D ndarray, 2D ndarray, double)
. The first element is the expected count numbers in joint phasechannel intervals. The second element is a stochastic realisation of those count numbers. The last element is the required normalisation of the background.

xpsi.tools.
synthesise_given_total_count_number
(__Pyx_memviewslice phases, double expected_star_counts, components, component_phases, phase_shifts, double expected_background_counts, __Pyx_memviewslice background, allow_negative=False)¶ Synthesise Poissonian count numbers given expected target source counts.
Parameters:  phases (double[::1]) – A
numpy.ndarray
of phase interval edges in cycles.  expected_star_counts (float) – Total number of expected counts from the star (the target source) to require.
 expected_background_stars (float) – Total number of expected background counts to require.
 components (tuple) – Component signals, each a Ccontiguous
numpy.ndarray
of signal count rates where phase increases with column number.  component_phases (tuple) – For each component, a Ccontiguous
numpy.ndarray
of phases in cycles at which the modelsignal
is evaluated on the interval[0,1]
.  phase_shift (arraylike) – Phase shifts in cycles, such as on the interval
[0.5,0.5]
, for the component signals.  expected_background_counts (double) – The total expected number of background counts to set the background normalisation (given the exposure time).
 background (double[:,::1]) – A Ccontiguous
numpy.ndarray
of background expected counts, whose shape matches the number of channels in each element ofcomponents
and the number of phase intervals constructed fromphases
.  allow_negative (obj) – A boolean or an array of booleans, one per component, declaring whether to allow negative phase interpolant integrals. If the interpolant is not a Steffen spline, then the interpolant of a nonnegative function can be negative due to oscillations. For the default Akima Periodic spline from GSL, such oscillations should manifest as small relative to those present in cubic splines, for instance, because it is designed to handle a rapidly changing secondorder derivative.
Returns: A tuple
(2D ndarray, 2D ndarray, double, double)
. The first element is the expected count numbers in joint phasechannel intervals. The second element is a stochastic realisation of those count numbers. The third element is the required exposure time. The last element is the required normalisation of the background. phases (double[::1]) – A