==========
Python-dna
==========

Python dna provide classes and functions for molecular biology using python.
Notably, PCR, cut and paste cloning and homologous recombination between linear
DNA fragments are supported. Most functionality is implemented as methods for
the double stranded DNA sequence record class "Drecord", which is a subclass of
the `Biopython <http://biopython.org/wiki/Main_Page>`_. SeqRecord class.

Python-DNA might be useful to automate the simulation of
`sub cloning <http://en.wikipedia.org/wiki/Subcloning>`_ experiments using
python. This could be helpful to generate examples for teaching purposes. Read
the `documentation <https://python-dna.readthedocs.org/en/latest/>`_ or the
`cookbook <https://pydna.googlecode.com/files/cookbook.zip>`_ with example files
for further information.

Python-dna was designed to semantically imitate how sub cloning experiments are
typically documented in Scientific literature. Python-dna code describing a
sub cloning is reasonably compact and meant to be easily readable.

One use case for Python-dna is to create a sort of executable documentation
describing a subcloning experiment. The Python-dna code unambiguously describe
a sub cloning experiment, and can be executed to yield the sequence of the
of the resulting DNA molecule.

Please post a message in the google group "Python-dna" at
https://groups.google.com/forum/?fromgroups#!forum/python-dna
if you have problems, questions or comments.

Feedback is very welcome!

Typical usage at the command line could look like this::

    >>> import pydna
    >>> seq = pydna.Dseq("GGATCCAAA","TTTGGATCC",ovhg=0)
    >>> seq
    Dseq(-9)
    GGATCCAAA
    CCTAGGTTT
    >>> from Bio.Restriction import BamHI
    >>> a,b = seq.cut(BamHI)
    >>> a
    Dseq(-5)
    G
    CCTAG
    >>> b
    Dseq(-8)
    GATCCAAA
        GTTT
    >>> a+b
    Dseq(-9)
    GGATCCAAA
    CCTAGGTTT
    >>> b+a
    Dseq(-13)
    GATCCAAAG
        GTTTCCTAG
    >>> b+a+b
    Dseq(-17)
    GATCCAAAGGATCCAAA
        GTTTCCTAGGTTT
    >>> b+a+a
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "/usr/local/lib/python2.7/dist-packages/pydna/dsdna.py", line 217, in __add__
        raise TypeError("sticky ends not compatible!")
    TypeError: sticky ends not compatible!
    >>>

NEWS
====

=======   ========== =============================================================
version   date       comment
=======   ========== =============================================================
0.1.2     2013-04-09 Corrected an error in setup.py that prevented installation
                     of the py_rstr_max sub package. Several additional unit tests
                     were added. An error in the homologous recombination function
                     was corrected.

0.1.1     2013-03-30 Removed the filtering option in the inititalization of
                     Drecord objects. The linear and circular properties of Dseq
                     and Drecord objects are now read only properties.

0.1.0     2013-03-24 New python script "findsubstrings_suffix_arrays_python.py"
                     replaces the cython script find_sub_strings.pyd. The new
                     python script is nearly as fast as the cython script, but
                     does not require a c compiler to build.

0.0.9     2013-03-10 Docs updated http://python-dna.readthedocs.org/en/latest/
                     drecord renamed Drecord
                     dseq renamed Dseq
                     to better comply with Python coding standards

0.0.8     2013-01-17 This version builds and passes all tests.
                     An updated cookbook added showing examples of
                     assembly by restriction/ligation and
                     homologous recombination. Look in folder docs/ in the source
                     distribution or download from
                     `here <http://pydna.googlecode.com/files/pydna_cookbook.zip>`_.

0.0.7     2013-01-15 This version does not pass all tests due
                     to an error in a c extension. Use the
                     newer version.

0.0.6     2013-01-10 The windows installer of this version probably works.
                     The source installations probably not, due to errors in
                     the packaging scripts. Do not use this version,
                     as the later ones provide the same functions.
=======   ========== =============================================================

System Requirements
===================

- `Python 2.7 <http://www.python.org>`_.

- `NumPy >= 1.6.1 <http://pypi.python.org/pypi/numpy>`_.

- `Biopython >= 1.60 <http://pypi.python.org/pypi/biopython>`_.

- `networkx >= 1.7 <http://pypi.python.org/pypi/networkx>`_.

- `distribute >= 0.6.34 <http://pypi.python.org/pypi/distribute>`_.

Python 2.x
----------

Versions other than 2.7 has not been tried with this software.
Version 2.7.3 was used to build the distribution.

Python 3.x
----------

This code has not been tried with python 3.

Installation
============

Source
------

You need to install the dependencies listed above.
If you are using Windows, you need to have a C compiler installed.
The free MS visual studio 2008 express can be used.

Open the Python-dna source code directory (containing the setup.py file) in
terminal and type:

    sudo python setup.py install <enter>

If you need to do additional configuration, e.g. changing the base
directory, please type `python setup.py`, or see the documentation for
Setuptools.


Binary distribution
-------------------

A `Binary installer <http://pypi.python.org/pypi/python-dna/#downloads>`_ for 32 bit editions of MS Windows XP and 7 are provided.

The installer has been tested on succesfully on both.

The dependencies have to be installed from source or using binary installers
for 32 bit windows.

This is a list of locations of binary installers:

- Python          <http://www.python.org/download/>
- NumPy           <http://sourceforge.net/projects/numpy/files/NumPy/>
- Biopython       <http://biopython.org/wiki/Download>
- networkx        <http://www.lfd.uci.edu/~gohlke/pythonlibs/#networkx>


Source Code Repository
----------------------

pydna is hosted by google code:

http://code.google.com/p/pydna/


Distribution Structure
======================

README.txt          -- This file.

NEWS.txt            -- Release notes and news

LICENSE.txt         -- What you can do with the code.

MANIFEST.in         -- Tells distutils what files to distribute

setup.py            -- Installation file.

setup_build.py      -- Building from Cython source (not needed for install)

distribute_setup.py -- Bootstrap distribute installation for version 0.6.34 which will pretend to be setuptools 0.6c11

run_tests.py        -- run tests by "python run_tests.py"<enter>

pydna/              -- The actual code.

docs/                -- Documentation.

scripts/            -- Miscellaneous perhaps useful scripts

tests/              -- Testing code