# 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]`.

• 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`.

• 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. 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]`.

• 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.

• 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. 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.