README.md 4.48 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
### `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
Gregory Ashton's avatar
Gregory Ashton committed
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
`numpy` and `scipy` by default). Instructions to install miniconda/anaconda
are provided in the links.

### Dependencies

`pyfstat` makes use of a variety python modules listed as the
`imports` in the top of `pyfstat.py`. The first set are core modules (such as
`os`, `sys`) while the second set are external and need to be installed for
`pyfstat` to work properly. Please install the following widely available
modules:

* [numpy](http://www.numpy.org/)
* [matplotlib](http://matplotlib.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
  provides a useful progress bar and estimate of the remaining run-time.

For an introduction to installing modules see
[here](https://docs.python.org/3.5/installing/index.html). If you are using
`pip`, to install all of these modules, run
```
$ pip install -r /PATH/TO/THIS/DIRECTORY/requirements.txt
```
If you have installed python from conda then `pip` itself can be installed via
`conda install pip`.

In addition to these modules, you also need a working **swig-enabled**
[`lalapps`](http://software.ligo.org/docs/lalsuite/lalsuite/) with
  at least `lalpulsar`. A minimal confuration line to use when installing
`lalapps` is

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

Gregory Ashton's avatar
Gregory Ashton committed
76
77
78

### `pyfstat` installation

Gregory Ashton's avatar
Gregory Ashton committed
79
The script can be installed system wide, assuming you are in this directory, via
80
```
81
$ python setup.py install
82
```
83
84
85
86
87
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
88
89
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.
90
91
92
93

### Ephemeris installation

The scripts require a path to ephemeris files in order to use the
94
`lalpulsar.ComputeFstat` module. This can either be specified when initialising
Gregory Ashton's avatar
Gregory Ashton committed
95
96
each search (as one of the arguments), or simply by placing a file
`~/.pyfstat.conf` into your home directory which looks like
97
98
99
100
101

```
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'
```
102
here, we use the default ephemeris files provided with `lalsuite`.
103
104