Folding time series

PyAstronomy.pyasl.foldAt(time, period, T0=0.0, getEpoch=False)

Fold time series with a particular period.

Calculate the phase, P, from time, period, and reference point, T0, according to

P = (time - T0)/period - [(time-T0)/period].

Here, square brackets indicate Gaussian brackets (i.e., the floor function), and the phase is a number between 0 and 1 by definition (and not between 0 and 2pi).

Optionally, also the epoch, E, can be returned, which is an integer corresponding to the second term in the above equation. For any point of the series, therefore, the following relation applies

time = T0 + (E+P) * period .

Of course the series to be folded does not necessarily have to be a time series although this particular example guides the naming convention here.

Parameters:
time : array

The time stamps.

period : float

The period to fold with (same units as time stamps).

T0 : float

Time reference point. The point T0 as well as all points T0+n*period with integer n are mapped to phase zero. Default is 0.0.

getEpoch : boolean, optional

If True, an array holding the epoch for every point in time will be returned; the default is False. Note that the first epoch, corresponding to times between T0 and T0+per, is 0.

Returns:
Phases : array

The (unsorted) phase array pertaining to the input time axis.

Epoch : array, optional

An array holding the epoch for every given point in time. The counting starts at zero. Only returned if getEpoch is True.

Folding example

from PyAstronomy.pyasl import foldAt
import matplotlib.pylab as plt
import numpy as np

# Generate some data ...
time = np.random.random(1000) * 100.
flux = 0.05 * np.sin(time*(2.*np.pi/21.5) + 15)
# ... and add some noise
flux += np.random.normal(0, 0.02, len(flux))

# Obtain the phases with respect to some
# reference point (in this case T0=217.4)
phases = foldAt(time, 21.5, T0=217.4)

# Sort with respect to phase
# First, get the order of indices ...
sortIndi = np.argsort(phases)
# ... and, second, rearrange the arrays.
phases = phases[sortIndi]
flux = flux[sortIndi]

# Plot the result
plt.plot(phases, flux, 'bp')
plt.show()