README.md 4.19 KB
Newer Older
1
2
# PyFstat

Gregory Ashton's avatar
Gregory Ashton committed
3
4
5
6
7
8
9
10
This is a python package providing an interface to perform F-statistic based
continuous gravitational wave (CW) searches. At its core, this is a simple
wrapper of selected tools in
['lalpulsar'](http://software.ligo.org/docs/lalsuite/lalpulsar/). The general
idea is to allow easy scripting of new search pipelines, we focus
primarily on interfacing the CW routines with
[emcee](http://dan.iel.fm/emcee/current/) a python MCMC sampler.

11

12
13
## Examples

14
15
16
17
We include a variety of example search scripts [here](examples), for each
example there is also a more descriptive write-up containing examples of the
output which we list below. Before running any of the search examples, be sure
to have run the [script to generate fake data](examples/make_fake_data.py).
18
19

* [Making fake data with and without glitches](docs/make_fake_data.md)
20
21
22
23
* [Fully-coherent MCMC search](docs/fully_coherent_search_using_MCMC.md)
* [Fully-coherent MCMC search on data containing a single glitch](docs/fully_coherent_search_using_MCMC_on_glitching_data.md)
* [Semi-coherent MCMC glitch-search on data containing a single glitch](docs/semi_coherent_glitch_search_using_MCMC_on_glitching_data.md)
* [Semi-coherent MCMC glitch-search on data containing two glitches](docs/semi_coherent_glitch_search_with_two_glitches_using_MCMC_on_glitching_data.md)
24
* [Semi-coherent Follow-Up MCMC search (dynamically changing the coherence time)](docs/follow_up.md)
25

26
27
## Installation

Gregory Ashton's avatar
Gregory Ashton committed
28
29
30
31
32
33
34
35
36
37
38
39
40
41
### `python` installation
The scripts are written in `python 2.7+` and therefore require a working
`python` installation. While many systems come with a system wide python
installation, it can often be easier to manage a user-specific python
installation. This way one does not require root access to install or remove
modules. One method to do this, is to use the `conda` system, either through
the stripped down [miniconda](http://conda.pydata.org/miniconda.html)
installation, or the full-featured
[anaconda](https://www.continuum.io/downloads) (these are essentially the
same, but the `anaconda` version installs a variety of useful packages such as
`numpy` and `scipy` by default.

### `pyfstat` installation

42
43
The script can be installed system wide via
```
44
$ python setup.py install
45
```
46
47
48
49
50
or simply add this directory to your python path. To check that the installation
was successful, run
```
$ python -c 'import pyfstat'
```
Gregory Ashton's avatar
Gregory Ashton committed
51
52
if no error message is output, then you have installed `pyfstat`. Note that
the module will be installed to whichever python executable you call it from.
53
54
55
56

### Ephemeris installation

The scripts require a path to ephemeris files in order to use the
57
`lalpulsar.ComputeFstat` module. This can either be specified when initialising
Gregory Ashton's avatar
Gregory Ashton committed
58
each search, or more simply by placing a file `~/.pyfstat.conf` into your home
59
60
61
62
63
64
directory which looks like

```
earth_ephem = '/home/<USER>/lalsuite-install/share/lalpulsar/earth00-19-DE421.dat.gz'
sun_ephem = '/home/<USER>/lalsuite-install/share/lalpulsar/sun00-19-DE421.dat.gz'
```
65
here, we use the default ephemeris files provided with `lalsuite`.
66
67
68

### Dependencies

Gregory Ashton's avatar
Gregory Ashton committed
69
70
71
72
73
74
75
The installation above will complete succesfully without the following
dependencies, but you will subsequently find various `ImportError` messages
when running `pyfstat` scripts if you haven't installed the following modules.

* swig-enabled [`lalapps`](http://software.ligo.org/docs/lalsuite/lalsuite/) with
  at least `lalpulsar`. A minimal confuration line to use when installing
`lalapps` is
76
77

```
78
$ ./configure --prefix=${HOME}/lalsuite-install --disable-all-lal --enable-lalpulsar --enable-lalapps --enable-swig
79
80
```

Gregory Ashton's avatar
Gregory Ashton committed
81
82
83
84
85
86
87
88
* If using the MCMC tools, you will need to install the following python
  modules
  * [numpy](http://www.numpy.org/)
  * [scipy](https://www.scipy.org/)
  * [emcee](http://dan.iel.fm/emcee/current/)
  * [corner](https://pypi.python.org/pypi/corner/)
  * [dill](https://pypi.python.org/pypi/dill)
  * [tqdm](https://pypi.python.org/pypi/tqdm)(optional), if installed, this
89
  provides a useful progress bar and estimate of the remaining run-time.
90

Gregory Ashton's avatar
Gregory Ashton committed
91
92
93
94
95
96
  To install all of these modules, run
```
$ pip install -r /PATH/TO/THIS/DIRECTORY/requirements.txt
```
  where `pip` is the python package installer, if you have installed python
  from conda then it can be installed via `conda install pip`.
97