Update to docs

README.md

 # 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`.
 

docs/fully_coherent_search_using_MCMC.md

 # 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`:
 

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.
+

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

examples/make_fake_data.py

 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

requirements.txt

+numpy
+matplotlib
+scipy
+emcee
+corner
+dill
+tqdm
+
+