<commit_before>.. _installation:

================
Installing PySAL
================

.. contents::

Prerequisites
=============


Before installing PySAL, make sure the following libraries are properly
installed on your machine:


* `Python <http://www.python.org/>`_ 2.5 or later
* `Numpy <http://new.scipy.org/download.html>`_ 1.3 or later
* `Scipy <http://new.scipy.org/download.html>`_ 0.7 or later


*Optional, bundled installation:* 

The Anaconda Python distribution ships with PySAL (version 1.5 as of June 3,
2013). Opting for this distro means you don't have to read any further!
Check it out at http://continuum.io/downloads.html

With the `Enthought Python Distribution (EPD Free) <http://www.enthought.com/products/epd_free.php>`_, 
you will install all of PySAL's required dependencies, as well as iPython and a lot more, rather than installing dependencies one by one.
The full-blown EPD package is free for academics, and downloadable `here <http://www.enthought.com/products/edudownload.php>`_. 

* Optional, tools to compile our documentation:*

* `Sphinx <http://sphinx.pocoo.org/>`_
* `numpydoc <http://pypi.python.org/pypi/numpydoc/0.4>`_  extension to Sphinx (*not included in EPD*)

*Optional, recommended additions:*

* `iPython <http://ipython.scipy.org/moin/Download>`_

Getting PySAL
=============

PySAL is available on the `Python Package Index
<http://pypi.python.org/pypi/PySAL>`_, which means it can be
downloaded and installed manually or from the command line using easy_install or pip, as
follows::

 $ pip install pysal
 #or
 $ easy_install pysal

Alternatively, grab the source distribution (.tar.gz) and decompress it to your selected destination. Open a command shell and navigate to the decompressed PySAL folder. Type::

 $ python setup.py install

You may not want to install the latest version in place of the last stable
release. If that is the case, you can use the 'develop' subcommand to
install PySAL in development mode. This option builds the modules in place 
and modifies sys.path to include the code. The advantage of this method is that
you get the latest and greatest code but don't have to muck about with
setting or re-setting *NIX environment variables.

  $ python setup.py develop


Development version on GitHub 
-----------------------------

Developers can checkout PySAL using **git**::

 $ git clone https://github.com/pysal/pysal.git pysal


This will create a folder called 'pysal' containing the source
code in trunk. This will allow you to easily update any change
to the developer code base by running::

 $ git pull

Since PySAL is in active development, changes are made frequently. For that
reason, we recommend you 'tell' Python to look for PySAL in that folder
rather than properly install it as a package. You can do this by adding the
PySAL folder to the PYTHONPATH, a UNIX environment variable. 
To do that, create or edit your command shell profile (.bash_profile if using
BASH) and add the following line, substituting where appropriate::


 $ export PYTHONPATH=${PYTHONPATH}:"/path_to_desired/folder/pysal/"

Save and quit the file, then source it as follows::

 $ source ~/.bash_profile

You are all set. To test your setup, start a Python session and type::

 >>> import pysal; pysal.open.check()

Your terminal should reply with the following::

 PySAL File I/O understands the following file extensions:
 Ext: '.shp', Modes: ['r', 'wb', 'w', 'rb']
 Ext: '.mtx', Modes: ['r', 'w']
 Ext: '.swm', Modes: ['r', 'w']
 Ext: '.mat', Modes: ['r', 'w']
 Ext: '.shx', Modes: ['r', 'wb', 'w', 'rb']
 Ext: '.stata_text', Modes: ['r', 'w']
 Ext: '.geoda_txt', Modes: ['r']
 Ext: '.dbf', Modes: ['r', 'w']
 Ext: '.dat', Modes: ['r', 'w']
 Ext: '.gwt', Modes: ['r']
 Ext: '.gal', Modes: ['r', 'w']
 Ext: '.arcgis_text', Modes: ['r', 'w']
 Ext: '.wk1', Modes: ['r', 'w']
 Ext: '.arcgis_dbf', Modes: ['r', 'w']
 Ext: '.geobugs_text', Modes: ['r', 'w']
 Ext: '.csv', Modes: ['r']
 Ext: '.wkt', Modes: ['r']
 >>>


Windows
~~~~~~~~

To keep up to date with PySAL development, you will need a Git client that allows you to access and 
update the code from our repository. We recommend 
`GitHub Windows <http://windows.github.com/>`_.

After using GitHub Windows to install a local copy of PySAL, you need to tell
your Python distribution where to find PySAL.  There are several ways to do this. Here we
will use a simple one that requires you to create a text file
called ``sitecustomize.py`` in the
``site-packages`` folder of your Python distribution. That path looks more or
less like this::
 
 C:\PythonXX\Lib\site-packages\sitecustomize.py

,where XX corresponds to the version of the Python distribution you are using
(25 for 2.5, for example).
Edit ``sitecustomize.py`` with the following two lines of text::

 import sys
 sys.path.append("C:/PySALsvn/pysal-read-only")
 
Save and close the file.
You are all set.  To test your setup, start a Python session and type::

 >>> import pysal; pysal.open.check()

Your terminal should reply with the following::


 PySAL File I/O understands the following file extensions:
 Ext: '.shp', Modes: ['r', 'wb', 'w', 'rb']
 Ext: '.mtx', Modes: ['r', 'w']
 Ext: '.swm', Modes: ['r', 'w']
 Ext: '.mat', Modes: ['r', 'w']
 Ext: '.shx', Modes: ['r', 'wb', 'w', 'rb']
 Ext: '.stata_text', Modes: ['r', 'w']
 Ext: '.geoda_txt', Modes: ['r']
 Ext: '.dbf', Modes: ['r', 'w']
 Ext: '.dat', Modes: ['r', 'w']
 Ext: '.gwt', Modes: ['r']
 Ext: '.gal', Modes: ['r', 'w']
 Ext: '.arcgis_text', Modes: ['r', 'w']
 Ext: '.wk1', Modes: ['r', 'w']
 Ext: '.arcgis_dbf', Modes: ['r', 'w']
 Ext: '.geobugs_text', Modes: ['r', 'w']
 Ext: '.csv', Modes: ['r']
 Ext: '.wkt', Modes: ['r']
 >>>


Known Issues
============

1.5 install fails with scipy 11.0 on Mac OS X
---------------------------------------------

Running `python setup.py install` results in::

	from _cephes import *
	ImportError:
	dlopen(/Users/serge/Documents/p/pysal/virtualenvs/python1.5/lib/python2.7/site-packages/scipy/special/_cephes.so,
	2): Symbol not found: _aswfa_
	  Referenced from:
	  /Users/serge/Documents/p/pysal/virtualenvs/python1.5/lib/python2.7/site-packages/scipy/special/_cephes.so
	    Expected in: dynamic lookup

This occurs when your scipy on Mac OS X was complied with gnu95 and not
gfortran.  See `this thread <http://mail.scipy.org/pipermail/scipy-user/2010-November/027548.html>`_ for possible solutions.

weights.DistanceBand failing
----------------------------

This occurs due to a bug in scipy.sparse prior to version 0.8. If you are running such a version see `Issue 73 <http://code.google.com/p/pysal/issues/detail?id=73&sort=milestone>`_ for a fix.

doc tests and unit tests under Linux
------------------------------------<commit_msg>simplified install instructions<commit_after>.. _installation:

================
Installing PySAL
================

.. contents::

Prerequisites
=============


Before installing PySAL, make sure the following libraries are properly
installed on your machine:


* `Python <http://www.python.org/>`_ 2.5 or later
* `Numpy <http://new.scipy.org/download.html>`_ 1.3 or later
* `Scipy <http://new.scipy.org/download.html>`_ 0.7 or later


*Optional, bundled installation:* 

The Anaconda Python distribution ships with PySAL. 
Check it out `here <http://continuum.io/downloads.html>`_.

With the `Enthought Python Distribution (EPD Free) <http://www.enthought.com/products/epd_free.php>`_, 
you will install all of PySAL's required dependencies, as well as iPython and a lot more, rather than installing dependencies one by one.
The full-blown EPD package is free for academics, and downloadable `here <http://www.enthought.com/products/edudownload.php>`_. 

* Optional, tools to compile our documentation:*

* `Sphinx <http://sphinx.pocoo.org/>`_
* `numpydoc <http://pypi.python.org/pypi/numpydoc/0.4>`_  extension to Sphinx (*not included in EPD*)

*Optional, recommended additions:*

* `iPython <http://ipython.scipy.org/moin/Download>`_

Getting PySAL
=============

PySAL is available on the `Python Package Index
<http://pypi.python.org/pypi/PySAL>`_, which means it can be
downloaded and installed manually or from the command line using easy_install or pip, as
follows::

 $ pip install pysal
  - or -
 $ easy_install pysal

Alternatively, grab the source distribution (.tar.gz) and decompress it to your selected destination. Open a command shell and navigate to the decompressed PySAL folder. Type::

 $ python setup.py install

Windows users can download a graphical installer from
`Sourceforge <http://sourceforge.net/projects/pysal/files/?source=navbar>`_.

Development version on GitHub 
-----------------------------

Developers can checkout PySAL using **git**::

 $ git clone https://github.com/pysal/pysal.git pysal

This will create a directory called 'pysal' containing the source
code.
Open a command shell and navigate to the cloned PySAL
directory. Type::

 $ python setup.py develop

The 'develop' subcommand builds the modules in place 
and modifies sys.path to include the code.
The advantage of this method is that you get the latest code 
but don't have to fuss with editing system environment variables.

To test your setup, start a Python session and type::

 >>> import pysal

Keep up to date with PySAL development by 'pulling' the latest
changes::

 $ git pull

Windows
~~~~~~~~

To keep up to date with PySAL development, you will need a Git client that allows you to access and 
update the code from our repository. We recommend 
`GitHub Windows <http://windows.github.com/>`_ for a more graphical client, or
`Git Bash <https://code.google.com/p/msysgit/downloads/list?q=label:Featured>`_ for a
command line client. This one gives you a nice Unix-like shell with
familiar commands. Here is `a nice tutorial
<http://openhatch.org/missions/windows-setup/>`_ on getting going with Open
Source software on Windows. 

After cloning PySAL, install it in develop mode so Python knows where to find it. 

Open a command shell and navigate to the cloned PySAL
directory. Type::

 $ python setup.py develop

To test your setup, start a Python session and type::

 >>> import pysal

Keep up to date with PySAL development by 'pulling' the latest
changes::

 $ git pull


Known Issues
============

1.5 install fails with scipy 11.0 on Mac OS X
---------------------------------------------

Running `python setup.py install` results in::

	from _cephes import *
	ImportError:
	dlopen(/Users/serge/Documents/p/pysal/virtualenvs/python1.5/lib/python2.7/site-packages/scipy/special/_cephes.so,
	2): Symbol not found: _aswfa_
	  Referenced from:
	  /Users/serge/Documents/p/pysal/virtualenvs/python1.5/lib/python2.7/site-packages/scipy/special/_cephes.so
	    Expected in: dynamic lookup

This occurs when your scipy on Mac OS X was complied with gnu95 and not
gfortran.  See `this thread <http://mail.scipy.org/pipermail/scipy-user/2010-November/027548.html>`_ for possible solutions.

weights.DistanceBand failing
----------------------------

This occurs due to a bug in scipy.sparse prior to version 0.8. If you are running such a version see `Issue 73 <http://code.google.com/p/pysal/issues/detail?id=73&sort=milestone>`_ for a fix.

doc tests and unit tests under Linux
------------------------------------
{'fraction_non_alphanumeric': 0.1505194920522156, 'fraction_numerical': 0.008258591599325104, 'mean_word_length': 3.747892074198988, 'pattern_counts': {'":': 0, '<': 31, '<?xml version=': 0, '>': 49, 'https://': 3, 'lorem ipsum': 0, 'www.': 6, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 20, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3725181', 'n_tokens_mistral': 3690, 'n_tokens_neox': 3459, 'n_words': 1379}