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 C-contiguous numpy.ndarray of signal count rates. Phase increases with column number.
  • signal_phases (double[::1]) – A C-contiguous numpy.ndarray of phases in cycles at which the model signal 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 non-negative 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 second-order derivative.
Returns:

A 2D numpy.ndarray of the phase-shifted 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 C-contiguous numpy.ndarray of phases in cycles at which the model signal is evaluated on the interval [0,1].
  • signal (double[:,::1]) – A C-contiguous 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 non-negative 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 second-order derivative.
Returns:

A 2D numpy.ndarray of the phase-shifted signal interpolated at the new set of phases. Phase increases with column number.

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 C-contiguous numpy.ndarray of an energy-resolved (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 C-contiguous numpy.ndarray of an energy-resolved (specific _signal) signal. Energy increases with row number.
  • energies (double[::1]) – A numpy.ndarray of the logarithms (base 10) of the energies at which the signal 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 C-contiguous numpy.ndarray of signal count rates where phase increases with column number.
  • component_phases (tuple) – For each component, a C-contiguous numpy.ndarray of phases in cycles at which the model signal is evaluated on the interval [0,1].
  • phase_shift (array-like) – 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 C-contiguous numpy.ndarray of background expected counts, whose shape matches the number of channels in each element of components and the number of phase intervals constructed from phases.
Returns:

A tuple (2D ndarray, 2D ndarray, double). The first element is the expected count numbers in joint phase-channel 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 C-contiguous numpy.ndarray of signal count rates where phase increases with column number.
  • component_phases (tuple) – For each component, a C-contiguous numpy.ndarray of phases in cycles at which the model signal is evaluated on the interval [0,1].
  • phase_shift (array-like) – 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 C-contiguous numpy.ndarray of background expected counts, whose shape matches the number of channels in each element of components and the number of phase intervals constructed from phases.
  • 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 non-negative 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 second-order derivative.
Returns:

A tuple (2D ndarray, 2D ndarray, double, double). The first element is the expected count numbers in joint phase-channel 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.