API Reference¶

TimeSeries¶

class riptide.TimeSeries(data, tsamp, metadata=None, copy=False)¶

Container for time series data to be searched with the FFA. Use classmethods to create a new TimeSeries object.

Parameters

data (array_like) – Time series data to search.
tsamp (float) – Sampling time of data in seconds.
metadata (Metadata or dict, optional) – Optional Metadata object / dict describing the observation from which the data originate
copy (bool, optional) – If set to True, the resulting time series will hold a new copy of data, otherwise it only holds a reference to it

See also

TimeSeries.from_presto_inf: Load dedispersed data produced by PRESTO
TimeSeries.from_sigproc: Load dedispersed data produced by SIGPROC
TimeSeries.generate: Generate a noisy time series containing a fake pulsar signal

copy()¶: Returns a new copy of the TimeSeries

property data¶: numpy array holding the time series data, in float32 format.

deredden(width, minpts=101, inplace=False)¶

Subtract from the data an aproximate running median. To save time, this running median is computed on a downsampled copy of the data, then upsampled back to the original resolution and finally subtracted from the original data.

Parameters

width (float) – Width of the running median window in seconds.
minpts (int, optional) – Downsample the data so that the width of the running median window is equal to ‘minpoints’ samples. The running median will be computed on that downsampled copy of the data, and then upsampled
inplace (bool, optional) – If set to True, perform the operation in-place, otherwise, a new TimeSeries object is returned

Returns

out – The de-reddened TimeSeries, if ‘inplace’ was set to False

Return type

TimeSeries or None

downsample(factor, inplace=False)¶

Downsample data by a real-valued factor, by grouping and adding together consecutive samples (or fractions of samples).

Parameters

factor (float) – Downsampling factor
inplace (bool, optional) – If set to True, perform the operation in-place, otherwise, a new TimeSeries object is returned

Returns

out – The downsampled TimeSeries, if ‘inplace’ was set to False

Return type

TimeSeries or None

fold(period, bins, subints=None)¶

Fold TimeSeries at given period.

Parameters

period (float) – Period in seconds
bins (int) – Number of phase bins
subints (int or None, optional) – Number of desired sub-integrations. If None, the number of sub-integrations will be the number of full periods that fit in the data

Returns

folded – The folded data as a numpy array. If subints > 1, it has a shape (subints, bins). Otherwise it is a 1D array with ‘bins’ elements.

Return type

ndarray

classmethod from_binary(fname, tsamp, dtype=<class 'numpy.float32'>)¶

Create a new TimeSeries from a raw binary file, containing the time series data without any header or footer. This will work as long as the data can be loaded with numpy.fromfile().

Parameters

fname (str) – File name to load.
tsamp (float) – Sampling time of the data in seconds.
dtype (numpy data type, optional) – Data type of the file

Returns

out – TimeSeries object.

Return type

TimeSeries

classmethod from_npy_file(fname, tsamp)¶

Create a new TimeSeries from a .npy file, written with numpy.save().

Parameters

fname (str) – File name to load.
tsamp (float) – Sampling time of the data in seconds.

Returns

out – TimeSeries object.

Return type

TimeSeries

classmethod from_numpy_array(array, tsamp, copy=False)¶

Create a new TimeSeries from a numpy array (or array-like).

Parameters

array (array-like) – The time series data.
tsamp (float) – Sampling time of the data in seconds.
copy (bool, optional) – If set to True, the resulting time series will hold a new copy of ‘array’, otherwise it only holds a reference to it

Returns

out – TimeSeries object.

Return type

TimeSeries

classmethod from_presto_inf(fname)¶

Create a new TimeSeries from a .inf file written by PRESTO. The associated .dat file must be in the same directory.

Parameters: fname (str) – File name to load.
Returns: out – TimeSeries object.
Return type: TimeSeries

classmethod from_sigproc(fname, extra_keys={})¶

Create a new TimeSeries from a file written by SIGPROC’s dedisperse routine.

Parameters

fname (str) – File name to load.
extra_keys (dict, optional) –
Optional {key: type} dictionary. Use it to specify how to parse any non-standard keys that could be found in the header, or even to override the data type of standard keys.

Example:
{ ‘telescope_diameter’ : float, ‘num_trusses’: int, ‘planet_name’: str }

Returns

out – TimeSeries object.

Return type

TimeSeries

classmethod generate(length, tsamp, period, phi0=0.5, ducy=0.02, amplitude=10.0, stdnoise=1.0)¶

Generate a time series containing a periodic signal with a von Mises pulse profile, and some background white noise (optional).

Parameters

length (float) – Length of the data in seconds.
tsamp (float) – Sampling time in seconds.
period (float) – Signal period in seconds
phi0 (float, optional) – Initial pulse phase in number of periods
ducy (float, optional) – Duty cycle of the pulse, i.e. the ratio FWHM / Period
amplitude (float, optional) –
True amplitude of the signal as defined in the reference paper. The expectation of the S/N of the generated signal is

S/N_true = amplitude / stdnoise,

assuming that a matched filter with the exact shape of the pulse is employed to measure S/N (here: von Mises with given duty cycle). riptide employs boxcar filters in the search, which results in a slight S/N loss. See the reference paper for details. A further degradation will be observed on bright signals, because they bias the estimation of the mean and standard deviation of the noise in a blind search.
stdnoise (float, optional) – Standard deviation of the background noise (default: 1.0). If set to 0, a noiseless signal is generated.

Returns

tseries – Output time series.

Return type

ndarray (1D, float)

property length¶: Length of the data in seconds

normalise(inplace=False)¶

Normalise to zero mean and unit variance. if ‘inplace’ is False, a new TimeSeries object with the normalized data is returned.

Parameters: inplace (bool, optional) – If set to True, perform the operation in-place, otherwise, a new TimeSeries object is returned
Returns: out – The normalised TimeSeries, if ‘inplace’ was set to False
Return type: TimeSeries or None

property nsamp¶: Number of samples in the data.

property tobs¶: Length of the data in seconds. Alias of property ‘length’.

property tsamp¶: Sampling time in seconds.

ffa_search¶

riptide.ffa_search(tseries, period_min=1.0, period_max=30.0, fpmin=8, bins_min=240, bins_max=260, ducy_max=0.2, wtsp=1.5, deredden=True, rmed_width=4.0, rmed_minpts=101, already_normalised=False)¶

Run a FFA search of a single TimeSeries object, producing its periodogram.

Parameters

tseries (TimeSeries) – The time series object to search
period_min (float) – Minimum period to search in seconds
period_max (float) – Maximum period to search in seconds
fpmin (int) – Minimum number of signal periods that must fit in the data. In other words, place a cap on period_max equal to DATA_LENGTH / fpmin
bins_min (int) – Minimum number of phase bins in the folded data. Higher values provide better duty cycle resolution. As the code searches longer trial periods, the data are iteratively downsampled so that the number of phase bins remains between bins_min and bins_max
bins_max (int) – Maximum number of phase bins in the folded data. Must be strictly larger than bins_min, approx. 10% larger is a good choice
wtsp (float) – Multiplicative factor between consecutive boxcar width trials. The smallest width is always 1 phase bin, and the sequence of width trials is generated with the formula: W(n+1) = max( floor(wtsp x W(n)), W(n) + 1 ) wtsp = 1.5 gives the following sequence of width trials (in number of phase bins): 1, 2, 3, 4, 6, 9, 13, 19 …
ducy_max (float) – Maximum duty cycle to optimally search. Limits the maximum width of the boxcar matched filters applied to any given profile. Example: on a 300 phase bin profile, ducy_max = 0.2 means that no boxcar filter of width > 60 bins will be applied
deredden (bool) – Subtract red noise from the time series before searching
rmed_width (float) – The width of the running median filter to subtract from the input data before processing, in seconds
rmed_minpts (int) – The running median is calculated of a time scrunched version of the input data to save time: rmed_minpts is the minimum number of scrunched samples that must fit in the running median window Lower values make the running median calculation less accurate but faster, due to allowing a higher scrunching factor
already_normalised (bool) – Assume that the data are already normalised to zero mean and unit standard deviation

Returns

ts (TimeSeries) – The de-reddened and normalised time series that was actually searched
pgram (Periodogram) – The output of the search, which contains among other things a 2D array representing S/N as a function of trial period and trial width.

find_peaks¶

riptide.find_peaks(pgram, smin=6.0, segwidth=5.0, nstd=6.0, minseg=10, polydeg=2, clrad=0.1)¶

Identify significant peaks in a periodogram using a dynamically fitted S/N selection threshold. The fitting involves the following procedure for each pulse width trial separately:

Cut the frequency range covered by the periodogram in segments of length 1 / T_obs
Get the median S/N ‘m’ and robust S/N standard deviation ‘s’ of each segment. The dynamic selection threshold for that segment should be t = m + nstd x s
Fit a polynomial in log(f) to the control points (f_i, t_i) thus obtained
Any point whose S/N exceeds both the dynamic threshold and the value ‘smin’ are considered significant
Cluster these points. Two points are in the same peak if their trial frequencies are within clrad / T_obs of each other. All such clusters constitute a Peak.

Parameters

pgram (Periodogram) – Input periodogram to search for peaks
smin (float, optional) – Minimum S/N that a peak must exceed, in addition to having to exceed the dynamic selection threshold
segwidth (float, optional) – Width of a frequency segment in units of 1 / T_obs
nstd (float, optional) – See above for an explanation
minseg (float, optional) – Minimum number of segments below which only a static selection threshold is applied
polydeg (float, optional) – Degree of polynomial in log(f)
clrad (float, optional) – Clustering radius in frequency space, in units of 1 / T_obs

Returns

peaks (list) – List of Peak objects
polycos (dict) – Dictionary of polynomial coefficients {iw: polyco} where ‘iw’ is the width trial index, and ‘polyco’ a list of polynomial coefficients in log(f). These can be passed to np.poly1d

Periodogram¶

class riptide.Periodogram(widths, periods, foldbins, snrs, metadata=None)¶

Stores the raw output of the FFA search of a time series.

widths¶

Sequence of pulse width trials, in number of phase bins

Type: ndarray

periods¶

Sequence of trial periods in seconds

Type: ndarray

foldbins¶

Sequence with the same length as periods, containing the exact number of phase bins with which the data were folded for each particular trial period.

Type: ndarray

snrs¶

Two dimensional array with shape (num_periods, num_widths) containing the S/N as a function of trial pulse width and period.

Type: ndarray

display(iwidth=None, figsize=(20, 5), dpi=100)¶: Display a plot S/N versus trial period. Creates a matplotlib figure, calls plot() and pyplot.show().

property freqs¶: Sequence of trial frequencies in Hz, in decreasing order

plot(iwidth=None)¶

Make a S/N versus trial period plot in the current matplotlib figure.

Parameters: iwidth (int or None, optional) – Display only the data for this specific pulse width trial index. If None, for each trial period, plot the highest S/N across all trial pulse widths.

property tobs¶: Length in seconds of the TimeSeries that was searched

Candidate¶

class riptide.Candidate(params, tsmeta, peaks, subints)¶

Final data product of the riptide pipeline

params¶

Dictionary with best-fit parameters of the signal: period, freq, dm, width, ducy, snr

Type: dict

tsmeta¶

Metadata of the TimeSeries object (DM trial) in which the Candidate was found to have the highest S/N, and from which it was folded

Type: Metadata

peaks¶

A pandas DataFrame with the attributes of the periodogram peaks associated to the Candidate

Type: pandas.DataFrame

subints¶

A two-dimensional numpy array with shape (num_subints, num_bins) containing the folded sub-integrations

Type: ndarray

profile¶

Folded profile as a one-dimensional numpy array, normalised such that the background noise standard deviation is 1, and the mean of the profile is zero

Type: ndarray

dm_curve¶

Tuple of numpy arrays (dm, snr) containing respectively the sequence of DM trials, and corresponding best S/N value across all trial widths

Type: tuple

classmethod from_dict(items)¶: De-serialize from dictionary

classmethod from_pipeline_output(ts, peak_cluster, bins, subints=1)¶

Method used by the pipeline to produce a candidate from intermediate data products.

subints can be an int or None. None means pick the number of subints that fit inside the data.

If ‘subints’ is too large to fit in the data, then this function will call TimeSeries.fold() with subints=None.

plot(figsize=(18, 4.5), dpi=80)¶

Create a plot of the candidate

Parameters

figsize (tuple) – figsize argument passed to plt.figure()
dpi (int) – dpi argument passed to plt.figure()

Returns

fig

Return type

matplotlib.Figure

savefig(fname, **kwargs)¶: Create a plot of the candidate and save it as PNG under the specified file name. Accepts the same keyword arguments as plot().

show(**kwargs)¶: Create a plot of the candidate and display it. Accepts the same keyword arguments as plot().

to_dict()¶: Convert to dictionary for serialization

Save / Load data¶

Most objects in riptide can be converted to/from JSON via their to_dict() and from_dict() methods. This includes in particular riptide.TimeSeries, riptide.Periodogram, and riptide.Candidate. It is also possible to save / load a list of such objects, a dictionary containing such objects, and any other composition that is JSON-serializable.

riptide.load_json(fname)¶: Load a JSON file containing a riptide object (or list/dict/composition thereof)

riptide.save_json(fname, obj, **kwargs)¶: Save riptide object (or list/dict/composition thereof) to a JSON file. Any keyword arguments are passed to json.dumps().

Kernel Functions¶

riptide.libffa.boxcar_snr(data, widths, stdnoise=1.0)¶

Compute the S/N ratio of pulse profile(s) for a range of boxcar width trials.

Parameters

data (ndarray) – Input profile(s). Can be of any shape, but the last axis must be pulse phase.
widths (ndarray, 1D) – Trial pulse widths, expressed in number of phase bins.
stdnoise (float) – Standard deviation of the background noise in all profiles.

Returns

snr – Output with the same shape as data, with an additional axis which represents trial pulse width index.

Return type

ndarray

riptide.libffa.ffa1(data, p)¶

Compute the FFA transform of a one-dimensional input (time series) at base period p

Parameters

data (ndarray (1D)) – Input time series data. If N is the total number of samples in the data, the last N % p samples are ignored, as they do not form a complete pulse period
p (int) – Base period of the transform, in number of samples

Returns

transform – The FFA transform of ‘data’, as a float32 2D array of shape (m, p), where m is the number of complete pulse periods in the data

Return type

ndarray (2D)

See also

ffafreq: trial frequencies in the output transform
ffaprd: trial periods in the output transform

riptide.libffa.ffa2(data)¶

Compute the FFA transform of a two-dimensional input

Parameters: data (ndarray (2D)) – Input time series data in two-dimensional form with shape (m, p), where m is the number of signal periods and p the number of phase bins.
Returns: transform – The FFA transform of ‘data’, as a float32 2D array of shape (m, p)
Return type: ndarray (2D)

See also

ffafreq: trial frequencies in the output transform
ffaprd: trial periods in the output transform

riptide.libffa.ffafreq(N, p, dt=1.0)¶

Returns the trial frequencies that correspond to every folded profile in the FFA output.

Parameters

N (int) – Total number of samples in the input data
p (int) – Base period of the FFA transform in number of samples
dt (float, optional) – Sampling time

Returns

freqs – Array with m elements containing the sequence of trial frequencies in the FFA output

Return type

ndarray

riptide.libffa.ffaprd(N, p, dt=1.0)¶

Returns the trial periods that correspond to every folded profile in the FFA output.

Parameters

N (int) – Total number of samples in the input data
p (int) – Base period of the FFA transform in number of samples
dt (float, optional) – Sampling time

Returns

periods – Array with m elements containing the sequence of trial periods

Return type

ndarray

riptide.running_medians.fast_running_median(data, width_samples, min_points=101)¶

Compute an approximate running median of data over large window sizes. The idea is to downsample the data (if necessary), call running_median() on it and linearly interpolate it back to the original resolution.

Parameters

data (ndarray) – Input data
width (int) – Required width of the running median window in number of samples
min_points (int) – The running median is calculated of a time scrunched version of the input data to save time: min_points is the minimum number of scrunched samples that must fit in the running median window. Lower values make the running median calculation less accurate but faster, due to allowing a higher scrunching factor. NOTE: ‘min_points’ must be an odd number.

See also

running_median: an exact running median but slower for large window sizes

riptide.running_medians.running_median(x, width_samples)¶

Computes the running median of data with the specified window size.

Parameters

x (ndarray) – One dimensional input data.
width_samples (int) – The width of the running median window in number of elements. It must be an odd number smaller than the input data length, otherwise ValueError is raised.

Returns

rmed – The running median of ‘x’.

Return type

ndarray

Notes

The C++ running median code internally pads both ends of the arrray with the edge values.

If the input array is not contiguous in memory, a temporary contiguous copy is made and passed to the C++ function (which only accepts C-contiguous arrays). Otherwise no performance hit is incurred.

See also

fast_running_median: an approximate running median that runs much faster with large window sizes (> 100 elements).