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 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 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 modelsignal
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 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, 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 modelsignal
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 ofcomponents
and the number of phase intervals constructed fromphases
.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 modelsignal
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 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 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.