Detrending Periodic Signals (dips)

dips is an algorithm for detrending timeseries of strictly periodic signals. It does not assume any functional form for the signal or the background or the noise; it disentangles the strictly periodic component from everything else. We use it in astronomy for detrending Kepler, K2 and TESS timeseries of periodic variable stars, eclipsing binary stars, exoplanets etc. The algorithm is described in detail in Prsa et al. (2019), PASP, in review -- the reference will be updated shortly.

This repository contains a python 3 implementation of dips.

Pre-requisites

To run dips, you will need:

• python 3
• numpy
• scipy

Installation

The dips program is available from pip. To install, run pip3 install dips for a local install, or sudo pip3 install dips for a global install.

If you prefer to install dips manually, grab the tarball from github, extract it and run python3 setup.py install in the top-level dips directory (local install), or sudo python3 setup.py install in the top-level dips directory (global install).

Running dips

The dips program is run from the command line. It takes a filename with the timeseries as input and computes the disentangled synchronous and asynchronous components of the signal as output. The disentangling process is iterative and might take an appreciable amount of time, depending on data length and pdf bin size.

Run dips with:

dips.py [-h] [-V] [-b BINS] [-t0 ORIGIN] [-P PERIOD] [-l LOGFILE] [-eta TOLERANCE] [-dxk DIFFERENCE] [-xi STEP_SIZE] [-af ATTENUATION] [--allow-upstep] [--cols COLS [COLS ...]] [--disable-mp] [--initial-pdf INITIAL_PDF] [--interim-prefix INTERIM_PREFIX] [--jitter JITTER] [--output-prefix OUTPUT_PREFIX] [--renormalize] [--save-interim SAVE_INTERIM] [--yonly] finput

The arguments are summarized in the table below.

Distributed with dips (in the tarball's examples directory) are three example input files, synthetic.data, kic3953981_sap.data and kic3547874_sap.data.

To run dips on synthetic data (see http://keplerEBs.villanova.edu/includes/DPS/dps_synthetic.html how the data were created) by using 33 bins, per-bin means as the initial pdf, and with serial calculation (disabling multiprocessing), issue:

dips synthetic.data -b 33 -P 0.91 --initial-pdf mean --disable-mp

To run dips on an eclipsing binary KIC 3953981, using 101 bins, allowing the step size to increase, using per-bin data median as the initial pdf, renormalizing the pdf after each iteration, using only y-direction length and saving every 10th iteration, issue:

dips kic3953981_sap.data -b 101 -t0 54953.82253243 -P 0.49201716 --allow-upstep --initial-pdf median --save-interim 10 --interim-prefix eb --renormalize --yonly

Finally, to run dips on a heartbeat star KIC 3547874, using 200 bins, starting with a flat pdf, computing total length in the y-direction only, renormalizing the synchronous pdf to 1.0 after each iteration, and allowing the step size to increase, issue:

dips kic3547874_sap.data --cols 0 2 -t0 54989.4209 -P 19.6921722 -b 200 --yonly --initial-pdf flat --renormalize --allow-upstep

These examples should provide a basic idea of how to invoke dips.