dips

dips: detrending periodic signals


License
GPL-3.0
Install
pip install dips==0.2.0

Documentation

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 Prša, Zhang and Wells (2019), PASP 131, 8001. A new, generalized version of dips is explained in Horvat and Prša (2020), in preparation.

This repository contains a python implementation of dips.

Pre-requisites

To run dips, you will need:

  • python
  • numpy
  • scipy

Note that you will need python 3.3 or later to enable multiprocessing. All examples below assume that you have python 3.3 or later installed.

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.

Argument Usage Type Default value
-h, --help print out the help message and exit n/a n/a
-V, --version print dips version and exit n/a n/a
-b BINS, --bins BINS assign the number of synchronous pdf bins int 200
-t0 ORIGIN, --origin ORIGIN the zero-point of the timeseries float 0.0
-P PERIOD, --period PERIOD period of the synchronous signal float 1.0
-l LOGFILE, --logfile LOGFILE log file to send output to instead of screen str None
-eta TOLERANCE, --tolerance TOLERANCE tolerance for convergence float 1e-8
-dxk DIFFERENCE, --difference DIFFERENCE finite difference size for computing slopes float 2e-5
-xi STEP_SIZE, --step-size STEP_SIZE initial down-step multiplier float 1e-3
-af ATTENUATION, --attenuation ATTENUATION attenuation factor for xi float 0.9
--allow-upstep allow step size to increase during convergence bool False
--cols COL1 COL2 [COL3] a list of input columns to be parsed, starting from 0 list of ints 0 1
--disable-mp disable multiprocessing (force serial computation) bool False
--initial-pdf choice of pdf initialization ('flat', 'mean', 'median', 'random', or external filename) str 'median'
--interim-prefix filename prefix for interim results str finput
--normalize-data normalize input data by median-dividing the fluxes bool False
--output_prefix PREFIX filename prefix for saving results (PREFIX.signal, .trend, .ranges) str finput
--renormalize force pdf normalization to 1 after every iteration bool False
--save-interim STEP save intering solutions every STEP iterations int 0
--yonly use only y-distance instead of full euclidian distance bool False

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