Skip to content

Commit

Permalink
Docs: updated installation instructions
Browse files Browse the repository at this point in the history
  • Loading branch information
@tritemio
tritemio committed Jan 20, 2015
1 parent 176ca34 commit 3b2ba44
Show file tree
Hide file tree
Showing 6 changed files with 273 additions and 230 deletions.
30 changes: 15 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ FRETBursts
[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.12784.png)](http://dx.doi.org/10.5281/zenodo.12784)
[![Build Status](https://travis-ci.org/tritemio/FRETBursts.svg?branch=master)](https://travis-ci.org/tritemio/FRETBursts)

> *Quick links: [Reference documentation](http://fretbursts.readthedocs.org/en/latest/index.html), [FRETBursts tutorials](https://github.com/tritemio/FRETBursts_notebooks)*
> *Quick links: [Reference documentation](http://fretbursts.readthedocs.org/), [FRETBursts tutorials](https://github.com/tritemio/FRETBursts_notebooks)*
Project description
-------------------
Expand Down Expand Up @@ -101,12 +101,12 @@ to ensure robustness and reproducibility of the results. For example,
when loading FRETBursts in an ipython notebook, the current commit ID is always
displayed and saved.

We provide a [list of tutorials](#how-to-use) (IPython notebooks) that can be
viewed online, edited and re-executed. The
[reference documentation](http://fretbursts.readthedocs.org/en/latest/)
We provide a [list of tutorials](#getting-started) (IPython notebooks) that
can be viewed online, edited and re-executed. The
[reference documentation](http://fretbursts.readthedocs.org/)
is generated by Sphinx extracting the docstrings from the source code.

###External resources
### External resources

For a comprehensive tutorial on using python for scientific computing:

Expand All @@ -119,21 +119,21 @@ rich text, math and graphics with (live) code. For more info please visit:
* [Notebook examples](http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/Notebook/Index.ipynb)
* [A gallery of interesting IPython Notebooks](https://github.com/ipython/ipython/wiki/A-gallery-of-interesting-IPython-Notebooks)

##Installation
## Installation

Briefly, the installation requires installing a scientific python distribution
(such as [Continuum Anaconda](https://store.continuum.io/cshop/anaconda/))
and then installing the `fretbursts` python package (`pip install fretbursts==0.4rc5`).
and then installing the `fretbursts` python package.

A detailed description of different installation options can be found in:
For detailed installation instructions see:

* [FRETBursts documentation: Getting started](http://fretbursts.readthedocs.org/en/latest/getting_started.html)

## Getting started

##How to use
The official FRETBursts documentation is built and hosted by ReadTheDocs:

* [FRETBursts Documentation](http://fretbursts.readthedocs.org/en/latest/)
* [FRETBursts Documentation](http://fretbursts.readthedocs.org/)

We provide a list of IPython notebooks showing typical workflows
for smFRET analysis and illustrating FRETBursts functionalities.
Expand All @@ -153,13 +153,13 @@ repository.
> [notebooks folder](https://github.com/tritemio/FRETBursts/tree/master/notebooks).
We provide a public dataset [1] to test and demonstrate FRETBursts
functionalities. These dataset files will be downloaded when running
the tutorials.
functionalities. These dataset files will be automatically downloaded
when running the tutorials.

[1] A. Ingargiola, S. Chung (2014): smFRET example datasets for the FRETBursts
software. [DOI 10.6084/m9.figshare.1019906](http://dx.doi.org/10.6084/m9.figshare.1019906)

##Development
## Development

The documentation is built using [Sphinx](http://sphinx-doc.org/) (1.2.2 or
later) and the [napoleon extension](https://pypi.python.org/pypi/sphinxcontrib-napoleon).
Expand All @@ -172,11 +172,11 @@ Notebooks that execute the unit tests can be found in
In the same folder a notebook for regression testing is provided.


##Acknowledgements
## Acknowledgements

This work was supported by NIH grants R01 GM069709 and R01 GM095904.

##License and Copyrights
## License and Copyrights

FRETBursts - A bursts analysis toolkit for single and multi-spot smFRET data.

Expand Down
29 changes: 29 additions & 0 deletions docs/source/dependencies.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
FRETBursts Dependencies
=======================

For documentation purposes, this is the list of dependencies to run FRETBursts:

- Python 2.7
- Numpy 1.6 or newer
- Scipy 0.13 or newer
- Matplotlib 1.3 or newer, with QT4 backend (either PyQT4 or PySide).
- IPython 1.x (2.x recommended)
- PyTables 3.x. To load/save the :ref:`Photon-HDF5 <hdf5-format>`.
- lmfit 0.8 or newer, used for flexible histogram fitting.
- Pandas, currently used just for nice table representations.

If you want to compile the cython extensions (optional) you also need:

- cython 0.20 or newer.
- a C compiler

For developing FRETBursts you should also install

- sphinx 1.2.2 with the napoleon extension (sphinxcontrib-napoleon) to
build this documentation.
- pytest to execute the unit tests.

Note that, unless you know what you are doing, you should never install these
dependencies manually. Use a scientific python distribution like
`Continuum Anaconda <https://store.continuum.io/cshop/anaconda/>`__
instead.
1 change: 1 addition & 0 deletions docs/source/getting_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,5 @@ Getting started

installation
notebook_workflow
dependencies

225 changes: 42 additions & 183 deletions docs/source/installation.rst
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,52 @@
Installation
============
.. _installation:

FRETBursts can be installed as a standard python package or can be executed
from the source folder.
FRETBursts Installation
=======================

In both cases, installing a scientific python distribution is needed.
FRETBursts can be installed as a standard python package (either via PIP
or conda).

In any case, to easily install the different dependencies, you need to
install a **scientific python distribution**.

After installing FRETBursts, it is recommended that you download the
`FRETBursts notebooks <https://github.com/tritemio/FRETBursts_notebooks/archive/master.zip>`__
to get started. See :ref:`running_fretbursts`.


.. _package_install:

Quick: Package installation
---------------------------
Package installation (PIP)
--------------------------

This is the preferred method if you are just starting with FRETBursts.

Start by installing `Continuum Anaconda <https://store.continuum.io/cshop/anaconda/>`__
python distribution (free version).

Then you can install latest FRETBursts release with through PIP::

pip install fretbursts --upgrade

Use the previous command every time you want to upgrade to the latest stable
release.

Package installation (conda)
----------------------------

If you prefer installing FRETBursts through `conda` (the Anaconda package
manager), you need to add the FRETBursts channel::

conda config --add channels tritemio

If you are just starting with FRETBursts this is the preferred installation
method.
and then install FRETBursts with::

To install the latest stable release type::
conda install fretbursts

pip install fretbursts==0.4rc5 --upgrade
Install from GitHub (development)
---------------------------------

To install the latest version from GitHub, type::
You can install the latest development version from GitHub with::

pip install git+git://github.com/tritemio/FRETBursts.git

Expand All @@ -32,25 +59,12 @@ The optimized C extensions are installed in both cases. Make sure that
the dependencies `lmfit` and `seaborn` have been installed. If not
just install them with::

pip install lmfit==0.8.1 seaborn

After installation, FRETBurst can be imported with::

from fretbursts import *

this will also import numpy (as `np`) and matplolib.pyplot (as `plt`).
Alternatively you can import FRETBursts in its own namespace with::

import fretbursts as fb

For more info on running FRETBursts refer to the
`tutorials <https://github.com/tritemio/FRETBursts_notebooks>`_.

pip install lmfit seaborn

.. _source_install:

Quick: Source installation
--------------------------
Source installation (development)
---------------------------------

To perform a "source installation", i.e. executing FRETBursts from the source
folder, download the code from GitHub, and execute the ipython notebook
Expand All @@ -66,158 +80,3 @@ folder you can load/import FRETBursts with::

A copy of `load_fretbursts.py` can be found under `notebooks` in the
source tree.


Source installation description (long)
======================================

Windows: Source installation with SourceTree
---------------------------------------------

If you are not familiar with Python and Git and you are using MS Windows
follow these steps:

1. Install `Continuum Anaconda <https://store.continuum.io/cshop/anaconda/>`__
(a scientific python distribution).

2. Install `SourceTree <http://www.sourcetreeapp.com/>`__ (GUI for Git).

3. Download FRETBursts using SourceTree (see below :ref:`download_fretbursts`).

4. Open FRETBursts folder, enter the `notebooks` folder and double-click
"Launch IPython Notebook Here.bat".

5. A new browser windows will open. Click on `FRETBursts Installation`
and run the notebook. Follow the instruction there to run the
tutorial notebooks.

For more info and customizations continue reading.


Installing Python for scientific computing
------------------------------------------

On all the main platforms, the easiest way to install python and all
the scientific packages is using a python distribution like
`Continuum Anaconda <https://store.continuum.io/cshop/anaconda/>`__ or
`Enthought Canopy <https://www.enthought.com/products/canopy/>`__. Both
distributions include, in the free version, all the needed software (and much
more).

A pure-python dependency, lmfit, is not in Anaconda and is installed
during FRETBursts python package installation
or when running the Installation notebook.

FRETBursts has been tested on Anaconda 1.9 or newer.

Manual Dependencies
^^^^^^^^^^^^^^^^^^^

If you prefer a manual installation, FRETBursts dependencies are:

- Python 2.7
- Numpy/Scipy (any version from 2013 on)
- Matplotlib (1.3.x or greater) with QT4 backend (either PyQT4 or PySide).
- IPython 1.x (2.x recommended)
- PyTables 3.x (optional). To load/save the :ref:`Photon-HDF5 <hdf5-format>`.
- lmfit: (version 0.8 or higher) for powerful and user-friendly fitting
- Pandas (optional) currently used only by the fitting framework
- a modern browser (Chrome or Firefox suggested)

For developing FRETBursts you should also install

- sphinx 1.2.2 with the napoleon extension (sphinxcontrib-napoleon)
to build this documentation.
- pytest to execute the unit tests.

Installing Git (optional)
-------------------------

FRETBursts uses `Git <http://git-scm.com/>`__ as revision control
system. Even if not necessary, we strongly recommend installing it because
FRETBursts notebooks can keep track of the FRETBursts software revision.
Furthermore, Git will make easy downloading future updates.

Unless you are familiar with Git it is preferable to install a graphical
interface like `SourceTree <http://www.sourcetreeapp.com/>`__.

On **Windows**, install SourceTree and, when asked, select the
single-user installation and choose to download the embedded Git.
Alternatively, for an independent system-wide Git installation,
download the windows binaries from the
`Git Homepage <http://git-scm.com/downloads>`__.

On **Mac OSX**, install SourceTree and configure it to use a system-wide
Git installation. Git can be installed system-wide using the
`homebrew <http://brew.sh/>`__ package manager.

On **Linux** Git is easily installed and usually comes with the **gitk**
graphical interface.


.. _download_fretbursts:

Obtaining FRETBursts sources
----------------------------

You can download a simple ZIP-ball containing FRETBursts by clicking on
**Download ZIP** on
`FRETBursts Homepage <https://github.com/tritemio/FRETBursts>`__ on GitHub.

However the preferred way is downloading FRETBursts through Git by
"cloning FRETBursts" (you will download the full history).
To clone the FRETBursts from the command line type::

git clone https://github.com/tritemio/FRETBursts.git

When using SourceTree, click on *Clone/New* -> *Clone Repository* and paste
the `clone URL <https://github.com/tritemio/FRETBursts.git>`_
in *Source Path/URL*.


.. _install_notebook:

Configure FRETBursts to run from the source tree
------------------------------------------------

To run FRETBursts from the source folder (instead of installing the python
package) you first need to run the "FRETBursts Installation" notebook
that will create a configuration file (storing the sources path) and
install some dependencies.

To run the FRETBursts Installation notebook:

- On windows, click on "Launch IPython Notebook Server Here.bat" (inside the
notebooks folder) and then click on "FRETBursts Installation".

- On the other platforms::

cd notebook_folder
ipython notebook

.. Note ::
Once the configuration is done, you can load FRETBursts in any notebook
by running `%run load_fretbursts`. Note that you need a copy of the
`load_fretbursts.py <https://github.com/tritemio/FRETBursts/blob/master/notebooks/load_fretbursts.py>`_
script in the notebook folder.
C compiler: manual installation
-------------------------------

Some core FRETBursts functions have a :ref:`cython version <fretbursts_cython>`
for higher execution speed. The cython functions require a C compiler that is
already installed when installing the Anaconda distribution.

The following paragraphs may be useful for users wanting to
manually install a C compiler.

On **Linux** the preferred compiler is GNU GCC, that is already installed (or
easily installed) in all the major distributions.
On **Windows**, the MS Visual Studio compiler is preferred. To install
it search on internet for the files VS2008ExpressWithSP1ENUX1504728.iso
and GRMSDKX\_EN\_DVD.iso.

On **Mac OSX** you should install the LLVM compiler included in Xcode.

0 comments on commit 3b2ba44

Please sign in to comment.