Metadata-Version: 1.1
Name: discsim
Version: 1.0.0b1
Summary: Efficient coalescent simulation in continuous space
Home-page: http://pypi.python.org/pypi/discsim
Author: Jerome Kelleher
Author-email: jerome.kelleher@ed.ac.uk
License: GNU GPLv3
Description: ===================================================
        Efficient coalescent simulation in continuous space
        ===================================================
        
        Simulates the coalescent for populations evolving in a spatial 
        continuum under the extinction/recolonisation model. This 
        package is a specialisation of the `ercs <https://pypi.python.org/pypi/ercs>`_
        package, and provides a much more efficient method of 
        simulating the spatial coalescent for the disc model. 
        A very similar (but not identical) interface to ``ercs``
        is provided.
        
        
        The simulations 
        support:
                
        - A sample of ``n`` individuals with ``m`` loci at arbitrary locations on a 
          torus of diameter ``L``.
        - A fixed recombination rate between pairs of adjacent loci. 
        - An arbitrary number of classes of event occuring at fixed
          rates. 
        - Simulations in one and two dimensions.
        - Access to the locations of ancestors at any time in the past.
        - Simulations of the locations of all pedigree ancestors, as well 
          as the genetic ancestors.
        
        The ``discsim`` module supports Python 2 and 3.
        
        -------------
        Documentation
        -------------
        
        Here's a quick example for the impatient::
        
                import ercs
                import discsim
                sim = discsim.Simulator(10)
                sim.sample = [None, (3, 2), (6, 4), (7, 0)]
                sim.event_classes = [ercs.DiscEventClass(u=0.5, r=1)]
                sim.run()
                pi, tau = sim.get_history()
        
        
        Full documentation for ``discsim`` is available at 
        `<http://pythonhosted.org/discsim>`_.
        
        ------------
        Installation
        ------------
        
        *******************************
        Quick install for Debian/Ubuntu
        *******************************
        
        If you are running Debian or Ubuntu, this should get you up and running quickly::
        
                $ sudo apt-get install python-dev libgsl0-dev 
                $ sudo pip install ercs discsim
        
        For Python 3, use ``python3-dev`` and ``pip3``.
        
        ********************
        General instructions
        ********************
        
        The ``discsim`` module 
        depends on the `GNU Scientific Library <http://www.gnu.org/software/gsl/>`_,
        which must be installed before it can be built.
        Fortunately, this is straightforward on most platforms. For example, 
        on Debian or Ubuntu use::
        
                $ sudo apt-get install libgsl0-dev
        
        or on Fedora::
        
                $ sudo yum install gsl-devel
        
        GSL is available on most packaging systems; if it is not available on your
        platform, it can be installed from source.
        
        The ``discsim`` module also depends on the ``ercs`` Python module, which 
        must also be installed, using the same methods as outlined below.
        
        Once GSL has been installed we can build the ``discsim`` module using the 
        standard Python `methods <http://docs.python.org/install/index.html>`_. For 
        example, using pip we have ::
                
                $ sudo pip install discsim
        
        Or, we can manually download the package, unpack it and then run::
                
                $ python setup.py build
                $ sudo python setup.py install
        
        Most of the time this will compile and install the module without difficulty.
        
        It is also possible to download the latest development version of 
        ``discsim`` from `github <https://github.com/jeromekelleher/discsim>`_. 
        
        ******************
        Potential problems
        ******************
        
        On platforms that GSL is not available as part of the native packaging 
        system (or GSL was installed locally because of non-root access)
        there can be issues with finding the correct headers and libraries
        when compiling ``ercs`` and ``discsim``. For example, on FreeBSD we get something 
        like this::
        
                $ python setup.py build
                ... [Messages cut for brevity] ...
                In file included from _ercsmodule.c:27:
                lib/ercs.h:26:25: error: gsl/gsl_rng.h: No such file or directory
                In file included from _ercsmodule.c:27:
                lib/ercs.h:73: error: expected declaration specifiers or '...' before 'gsl_rng'
                lib/ercs.h:94: error: expected specifier-qualifier-list before 'gsl_rng'
                _ercsmodule.c: In function 'pyercs_simulate':
                _ercsmodule.c:351: error: 'ercs_t' has no member named 'pi'
                _ercsmodule.c:356: error: 'ercs_t' has no member named 'tau'
                error: command 'cc' failed with exit status 1
        
        This can be remedied by using the ``gsl-config`` program to set the 
        the ``LDFLAGS`` and ``CFLAGS`` environment variables to 
        their correct values::
                
                 $ CFLAGS=`gsl-config --cflags` LDFLAGS=`gsl-config --libs` python setup.py build
        
        *****
        Tests
        *****
        
        ``discsim`` provides some test cases to ensure that the installation has gone smoothly.
        It is a good idea to run these immediately after installation::
        
                $ python tests.py
        
        
        ****************
        Tested platforms
        ****************
        
        Discsim has been successfully built and tested on the following platforms:
        
        ================        ========        ======          ========
        Operating system        Platform        Python          Compiler
        ================        ========        ======          ========
        Debian wheezy           x86_64          2.7.3           gcc 4.7.2	
        Debian wheezy           x86_64          3.2.3           gcc 4.7.2	
        Debian squeeze          ppc64           2.6.6           gcc 4.4.5	
        Debian squeeze          ppc64           3.1.3           gcc 4.4.5	
        ================        ========        ======          ========
        
        
        
Keywords: Coalescent simulation,Continuous space
Platform: POSIX
Classifier: Programming Language :: C
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Other Environment
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: POSIX
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires: ercs
