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, double[::1] phases, double[:, ::1] signal, double[::1] 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(double[::1] new_phases, double[::1] phases, double[:, ::1] 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, double[:, ::1] signal, double[::1] energies, double[::1] 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, double[:, ::1] signal, double[::1] energies, double[::1] 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, double[::1] phases, components, component_phases, phase_shifts, double expected_background_counts, double[:, ::1] background, allow_negative=False, gsl_seed=None)

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]. Typically this is more finely spaced than the resulting synthesised data.
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 (i.e. one element fewer than phase interval edges) constructed from phases.
gsl_seed (int) – Seed number for adding random noise to the data. If not specified, seed is based on the clock time.

Returns:

A tuple (2D ndarray, 2D ndarray, double). The first element is the expected count numbers in joint phase-channel intervals. Note those are intervals, not edges. 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(double[::1] phases, double expected_star_counts, components, component_phases, phase_shifts, double expected_background_counts, double[:, ::1] background, allow_negative=False, gsl_seed=None)

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]. Typically this is more finely spaced than the resulting synthesised data.
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 (i.e. one element fewer than phase interval edges) 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.
gsl_seed (int) – Seed number for adding random noise to the data. If not specified, seed is based on the clock time.

Returns:

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