From 35b898da4a6cbd9b4e8429ce97385b44b45f6e0b Mon Sep 17 00:00:00 2001 From: Gregory Ashton <gregory.ashton@ligo.org> Date: Fri, 23 Dec 2016 13:50:02 +0100 Subject: [PATCH] Update to docs --- README.md | 57 ++++++++++++++++---- docs/fully_coherent_search_using_MCMC.md | 10 ++-- docs/make_fake_data.md | 9 +++- examples/fully_coherent_search_using_MCMC.py | 4 +- examples/make_fake_data.py | 5 +- requirements.txt | 9 ++++ 6 files changed, 72 insertions(+), 22 deletions(-) create mode 100644 requirements.txt diff --git a/README.md b/README.md index 6961c63..85b6c54 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,13 @@ # PyFstat -This is a python package containing basic wrappers of the `lalpulsar` module -with capabilities to perform a variety of searches, primarily focusing on -semi-coherent glitch searches. +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. + ## Examples @@ -20,6 +25,20 @@ to have run the [script to generate fake data](examples/make_fake_data.py). ## 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 ``` $ python setup.py install @@ -29,13 +48,14 @@ was successful, run ``` $ 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 The scripts require a path to ephemeris files in order to use the `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 ``` @@ -46,17 +66,32 @@ here, we use the default ephemeris files provided with `lalsuite`. ### 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 ``` -* [emcee](http://dan.iel.fm/emcee/current/)[^1] -* [corner](https://pypi.python.org/pypi/corner/)[^1] -* [dill](https://pypi.python.org/pypi/dill)[^1] -* [tqdm](https://pypi.python.org/pypi/tqdm)[^1] (optional), if installed, this +* 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 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`. diff --git a/docs/fully_coherent_search_using_MCMC.md b/docs/fully_coherent_search_using_MCMC.md index b27a195..755b2c6 100644 --- a/docs/fully_coherent_search_using_MCMC.md +++ b/docs/fully_coherent_search_using_MCMC.md @@ -1,7 +1,7 @@ # Fully coherent search using MCMC -In this example, we will show the basics of setting up and running a MCMC -search for a fully-coherent search. This is based on the example +In this example, we will show the basics of setting up and running a +fully-coherent MCMC search. This is based on the example [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 [make_fake_data](make_fake_data.md) example. @@ -21,8 +21,8 @@ in the data, and the start and end times: F0 = 30.0 F1 = -1e-10 F2 = 0 -Alpha = 5e-3 -Delta = 6e-2 +Alpha = np.radians(83.6292) +Delta = np.radians(22.0144) tref = 362750407.0 tstart = 1000000000 @@ -30,7 +30,7 @@ duration = 100*86400 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 `Delta`). In this example, we choose a uniform box in `F0` and `F1`: diff --git a/docs/make_fake_data.md b/docs/make_fake_data.md index c4bcf52..8f896a0 100644 --- a/docs/make_fake_data.md +++ b/docs/make_fake_data.md @@ -13,14 +13,15 @@ fake data, define the Crab parameters and create an instant of the `Writer` called `data` ```python +import numpy as np from pyfstat import Writer # Define parameters of the Crab pulsar F0 = 30.0 F1 = -1e-10 F2 = 0 -Alpha = 5e-3 -Delta = 6e-2 +Alpha = np.radians(83.6292) +Delta = np.radians(22.0144) tref = 362750407.0 # Signal strength @@ -168,3 +169,7 @@ two_glitch_data = Writer( 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. + diff --git a/examples/fully_coherent_search_using_MCMC.py b/examples/fully_coherent_search_using_MCMC.py index fb4464e..4a6bdf4 100644 --- a/examples/fully_coherent_search_using_MCMC.py +++ b/examples/fully_coherent_search_using_MCMC.py @@ -11,8 +11,8 @@ tend = tstart + duration F0 = 30.0 F1 = -1e-10 F2 = 0 -Alpha = 5e-3 -Delta = 6e-2 +Alpha = np.radians(83.6292) +Delta = np.radians(22.0144) tref = .5*(tstart+tend) depth = 10 diff --git a/examples/make_fake_data.py b/examples/make_fake_data.py index e645dbd..19dd890 100644 --- a/examples/make_fake_data.py +++ b/examples/make_fake_data.py @@ -1,4 +1,5 @@ from pyfstat import Writer +import numpy as np # First, we generate data with a reasonably strong smooth signal @@ -6,8 +7,8 @@ from pyfstat import Writer F0 = 30.0 F1 = -1e-10 F2 = 0 -Alpha = 5e-3 -Delta = 6e-2 +Alpha = np.radians(83.6292) +Delta = np.radians(22.0144) tref = 362750407.0 # Signal strength diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..e4ff43e --- /dev/null +++ b/requirements.txt @@ -0,0 +1,9 @@ +numpy +matplotlib +scipy +emcee +corner +dill +tqdm + + -- GitLab