diff --git a/README.md b/README.md index 6961c63adc5ecb6d8c86e5d0ad882e000a970d7d..85b6c5487617a3da6cd00ddea7fc80a80bd05218 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 b27a195fe5e80776e02438e1f636f68f0984f12e..755b2c6800d4eb24520df56dd598be51b1845a28 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 c4bcf521d2fc094675f54f243f1ddd8c2f99aaf4..8f896a0d0a5506224e7c4ea6ce603bb94f9de9d0 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 fb4464ec9de22ab5f73f53bf11d5366597c85e54..4a6bdf48e8992e884298dd423e5911bc93afecb0 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 e645dbd31facb55b5105a371513c372fe26db8ea..19dd8900d7038f5f13d04406c7ed9d88ed32c509 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 0000000000000000000000000000000000000000..e4ff43e8b353b850ff42a860100259ab20c1b75f --- /dev/null +++ b/requirements.txt @@ -0,0 +1,9 @@ +numpy +matplotlib +scipy +emcee +corner +dill +tqdm + +