Commit 35b898da authored by Gregory Ashton's avatar Gregory Ashton
Browse files

Update to docs

parent 98327cb4
# PyFstat # PyFstat
This is a python package containing basic wrappers of the `lalpulsar` module This is a python package providing an interface to perform F-statistic based
with capabilities to perform a variety of searches, primarily focusing on continuous gravitational wave (CW) searches. At its core, this is a simple
semi-coherent glitch searches. 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.
## Examples ## Examples
...@@ -20,6 +25,20 @@ to have run the [script to generate fake data](examples/make_fake_data.py). ...@@ -20,6 +25,20 @@ to have run the [script to generate fake data](examples/make_fake_data.py).
## Installation ## Installation
### `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
The script can be installed system wide via The script can be installed system wide via
``` ```
$ python setup.py install $ python setup.py install
...@@ -29,13 +48,14 @@ was successful, run ...@@ -29,13 +48,14 @@ was successful, run
``` ```
$ python -c 'import pyfstat' $ python -c 'import pyfstat'
``` ```
if no error message is output, then you have installed `pyfstat`. 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.
### Ephemeris installation ### Ephemeris installation
The scripts require a path to ephemeris files in order to use the The scripts require a path to ephemeris files in order to use the
`lalpulsar.ComputeFstat` module. This can either be specified when initialising `lalpulsar.ComputeFstat` module. This can either be specified when initialising
each search, or more simply by placing a file `~/pyfstat.conf` into your home each search, or more simply by placing a file `~/.pyfstat.conf` into your home
directory which looks like directory which looks like
``` ```
...@@ -46,17 +66,32 @@ here, we use the default ephemeris files provided with `lalsuite`. ...@@ -46,17 +66,32 @@ here, we use the default ephemeris files provided with `lalsuite`.
### Dependencies ### Dependencies
* swig-enabled lalpulsar, a minimal configuration is given by 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
``` ```
$ ./configure --prefix=${HOME}/lalsuite-install --disable-all-lal --enable-lalpulsar --enable-lalapps --enable-swig $ ./configure --prefix=${HOME}/lalsuite-install --disable-all-lal --enable-lalpulsar --enable-lalapps --enable-swig
``` ```
* [emcee](http://dan.iel.fm/emcee/current/)[^1] * If using the MCMC tools, you will need to install the following python
* [corner](https://pypi.python.org/pypi/corner/)[^1] modules
* [dill](https://pypi.python.org/pypi/dill)[^1] * [numpy](http://www.numpy.org/)
* [tqdm](https://pypi.python.org/pypi/tqdm)[^1] (optional), if installed, this * [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. provides a useful progress bar and estimate of the remaining run-time.
[^1]: Most easily installed using either `conda` or `pip`. 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`.
# Fully coherent search using MCMC # Fully coherent search using MCMC
In this example, we will show the basics of setting up and running a MCMC In this example, we will show the basics of setting up and running a
search for a fully-coherent search. This is based on the example fully-coherent MCMC search. This is based on the example
[fully_coherent_search_using_MCMC.py](../example/fully_coherent_search_using_MCMC.py). [fully_coherent_search_using_MCMC.py](../example/fully_coherent_search_using_MCMC.py).
We will run the search on the `basic` data generated in the We will run the search on the `basic` data generated in the
[make_fake_data](make_fake_data.md) example. [make_fake_data](make_fake_data.md) example.
...@@ -21,8 +21,8 @@ in the data, and the start and end times: ...@@ -21,8 +21,8 @@ in the data, and the start and end times:
F0 = 30.0 F0 = 30.0
F1 = -1e-10 F1 = -1e-10
F2 = 0 F2 = 0
Alpha = 5e-3 Alpha = np.radians(83.6292)
Delta = 6e-2 Delta = np.radians(22.0144)
tref = 362750407.0 tref = 362750407.0
tstart = 1000000000 tstart = 1000000000
...@@ -30,7 +30,7 @@ duration = 100*86400 ...@@ -30,7 +30,7 @@ duration = 100*86400
tend = tstart = duration tend = tstart = duration
``` ```
Now, we need to specify out prior. This is a dictionary containing keys for Now, we need to specify our prior. This is a dictionary containing keys for
each variable (in the `MCMCSearch` these are `F0`, `F1`, `F2`, `Alpha`, and each variable (in the `MCMCSearch` these are `F0`, `F1`, `F2`, `Alpha`, and
`Delta`). In this example, we choose a uniform box in `F0` and `F1`: `Delta`). In this example, we choose a uniform box in `F0` and `F1`:
......
...@@ -13,14 +13,15 @@ fake data, define the Crab parameters and create an instant of the `Writer` ...@@ -13,14 +13,15 @@ fake data, define the Crab parameters and create an instant of the `Writer`
called `data` called `data`
```python ```python
import numpy as np
from pyfstat import Writer from pyfstat import Writer
# Define parameters of the Crab pulsar # Define parameters of the Crab pulsar
F0 = 30.0 F0 = 30.0
F1 = -1e-10 F1 = -1e-10
F2 = 0 F2 = 0
Alpha = 5e-3 Alpha = np.radians(83.6292)
Delta = 6e-2 Delta = np.radians(22.0144)
tref = 362750407.0 tref = 362750407.0
# Signal strength # Signal strength
...@@ -168,3 +169,7 @@ two_glitch_data = Writer( ...@@ -168,3 +169,7 @@ two_glitch_data = Writer(
two_glitch_data.make_data() two_glitch_data.make_data()
``` ```
So, having run `$ python make_fake_data.py` (from the `examples` directory), we
will see that in the sub-directory `examples/data/` there are three `.sft`
files. These will be used throughout the other examples.
...@@ -11,8 +11,8 @@ tend = tstart + duration ...@@ -11,8 +11,8 @@ tend = tstart + duration
F0 = 30.0 F0 = 30.0
F1 = -1e-10 F1 = -1e-10
F2 = 0 F2 = 0
Alpha = 5e-3 Alpha = np.radians(83.6292)
Delta = 6e-2 Delta = np.radians(22.0144)
tref = .5*(tstart+tend) tref = .5*(tstart+tend)
depth = 10 depth = 10
......
from pyfstat import Writer from pyfstat import Writer
import numpy as np
# First, we generate data with a reasonably strong smooth signal # First, we generate data with a reasonably strong smooth signal
...@@ -6,8 +7,8 @@ from pyfstat import Writer ...@@ -6,8 +7,8 @@ from pyfstat import Writer
F0 = 30.0 F0 = 30.0
F1 = -1e-10 F1 = -1e-10
F2 = 0 F2 = 0
Alpha = 5e-3 Alpha = np.radians(83.6292)
Delta = 6e-2 Delta = np.radians(22.0144)
tref = 362750407.0 tref = 362750407.0
# Signal strength # Signal strength
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment