dips 0.2.0

消去周期信号趋势 (dips)
==================================

_dips_ 是一个用于消去严格周期信号时间序列的算法。它不对信号、背景或噪声的函数形式做出任何假设；它将严格周期性分量与其他所有内容分开。我们在天文学中使用它来消去 _Kepler_、_K2_ 和 _TESS_ 的周期性变量星、食双星、系外行星等时间序列。该算法在 Prsa 等人 (2019) 的 PASP 文章中有详细描述，正在审查中——参考文献将很快更新。

此存储库包含 _dips_ 的 Python 实现。

先决条件
--------------

要运行 _dips_，您需要

* python
* numpy
* scipy

请注意，您需要 Python 3.3 或更高版本才能启用多进程。以下所有示例都假设您已安装 Python 3.3 或更高版本。

安装
------------

`dips` 程序可通过 pip 获取。要安装，请运行 `pip3 install dips` 进行本地安装，或 `sudo pip3 install dips` 进行全局安装。

如果您喜欢手动安装 `dips`，请从 GitHub 下载 tarball，解压它，并在 `dips` 目录的顶层运行 `python3 setup.py install`（本地安装），或在 `dips` 目录的顶层运行 `sudo python3 setup.py install`（全局安装）。

运行 _dips_
--------------

“_dips_”程序通过命令行运行。它接受一个包含时间序列的文件名作为输入，并计算信号的解耦同步和非同步成分作为输出。解耦过程是迭代的，可能需要相当长的时间，具体取决于数据长度和PDF分箱大小。

使用以下命令运行 _dips_：

`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`

以下表格总结了这些参数。

| 参数 | 用法 | 类型 | 默认值 |
|----------|-------|------|---------------|
| -h, --help | 打印帮助信息并退出 | n/a | n/a |
| -V, --version | 打印 _dips_ 版本并退出 | n/a | n/a |
| -b BINS, --bins BINS | 分配同步PDF分箱的数量 | int | 200 |
| -t0 ORIGIN, --origin ORIGIN | 时间序列的零点 | float | 0.0 |
| -P PERIOD, --period PERIOD | 同步信号周期 | float | 1.0 |
| -l LOGFILE, --logfile LOGFILE | 输出日志文件到屏幕以外的文件 | str | None |
| -eta TOLERANCE, --tolerance TOLERANCE | 收敛容忍度 | float | 1e-8 |
| -dxk DIFFERENCE, --difference DIFFERENCE | 计算斜率的有限差分大小 | float | 2e-5 |
| -xi STEP_SIZE, --step-size STEP_SIZE | 初始下步乘数 | float | 1e-3 |
| -af ATTENUATION, --attenuation ATTENUATION | xi 的衰减因子 | float | 0.9 |
| --allow-upstep | 允许收敛过程中步长增加 | bool | False |
| --cols COL1 COL2 [COL3] | 要解析的输入列列表，从0开始 | list of ints | 0 1 |
| --disable-mp | 禁用多进程（强制串行计算） | bool | False |
| --initial-pdf INITIAL_PDF | PDF初始化选择（'flat', 'mean', 'median', 'random' 或外部文件名） | str | 'median' |
| --interim-prefix INTERIM_PREFIX | 中间结果的文件名前缀 | str | finput |
| --normalize-data | 通过中值除以通量归一化输入数据 | bool | False |
| --output_prefix PREFIX | 保存结果的文件名前缀（PREFIX.signal, .trend, .ranges） | str | finput |
| --renormalize | 在每次迭代后强制PDF归一化到1 | bool | False |
| --save-interim STEP | 每STEP次迭代保存中间解 | int | 0 |
| --yonly | 仅使用y距离而不是欧几里得距离 | bool | False |

_dips_（在tarball的`examples`目录中）附带三个示例输入文件，`synthetic.data`，`kic3953981_sap.data` 和 `kic3547874_sap.data`。

要通过使用33个分箱、每分箱均值为初始PDF和使用串行计算（禁用多进程）在合成数据上运行 _dips_（请参阅[此处](http://keplerEBs.villanova.edu/includes/DPS/dps_synthetic.html)了解数据是如何创建的），请执行以下操作：

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

要在食双星 [KIC 3953981](http://keplerEBs.villanova.edu/overview/?k=3953981) 上运行 _dips_，使用101个分箱，允许步长增加，使用每分箱数据中值作为初始PDF，每次迭代后重置PDF，仅使用y方向长度并每10次迭代保存一次，请执行以下操作：

```bash
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
```

最后，要在脉动星 [KIC 3547874](http://keplerEBs.villanova.edu/overview/?k=3547874) 上运行 _dips_，使用200个分箱，从平坦PDF开始，仅计算y方向的总长度，每次迭代后将同步PDF重置为1.0，并允许步长增加，请执行以下操作：

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

这些示例应提供如何调用 _dips_ 的基本概念。