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

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://numpy.scipy.org/>`_ 1.3 or later
* `Scipy <http://www.scipy.org/>`_ 0.7 or later

*Optional, bundled installation:* 

With the `Enthought Python Distribution (EPD) <http://www.enthought.com/products/epd.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 package is free for academics, and downloadable `here <http://www.enthought.com/products/edudownload.php>`_. 

*Required to compile the documentation (optional):*

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

*Optional, recommended additions:*

* `iPython <http://ipython.scipy.org/moin/Download>`_
* `rtree <http://pypi.python.org/pypi/Rtree>`_ (*not included in EPD*)

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

You can install PySAL in a number of ways. We provide system-specific package installers for Windows and Mac OS X that have an intuitive look-and-feel
that most users are familiar with. We also build source distributions that self-install by invoking a single command line argument. Finally, advanced users and 
developers can use the popular version control tool **svn** to check out and use our latest code. Instructions for each of these methods follows.

Downloads
---------

Click-to-download PySAL distributions are available at `Google Code <http://code.google.com/p/pysal/downloads/list>`_.  Choose the right one for your system, or grab a source tarball or zipfile.

Instructions for Windows 
~~~~~~~~~~~~~~~~~~~~~~~~

Grab the Windows installer (ends with *.exe*) and download to your computer. Double-click to launch the installer and follow the simple wizard. You will have to select the version of Python you want the package to install with, if you have more than one version of Python on your system. You may repeat this procedure for as many versions of Python as you have on your machine. 

If you'd rather install source code, grab the zipfile (ends with *.zip*) and download to your computer. Decompress the file to a convenient location on your hard drive. Open a command shell and navigate to the decompressed PySAL folder. Type::

 python setup.py install

Instructions for Mac OS X
~~~~~~~~~~~~~~~~~~~~~~~~~

Grab the OS X installer (ends with *.dmg*) and download to your computer. Double-click to launch the installer and follow the simple wizard. This installer places PySAL into the active Python version on your system (the version that comes up when you type *python* into a terminal). 

If you'd rather install source code, grab the tarball (ends with *.tar.gz*) and download to your computer. Decompress the file to a convenient location on your hard drive. Open a terminal and navigate to the decompressed PySAL folder. Type::

 python setup.py install

Instructions for GNU/Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Grab either of the source distributions and decompress to your selected destination. Open a command shell and navigate to the decompressed PySAL folder. Type::

 python setup.py install

Development version from Subversion (SVN)
-----------------------------------------

Users and developers can grab the source code from our Subversion repository using
an svn client and the following instructions:

GNU/Linux and Mac OS X 
~~~~~~~~~~~~~~~~~~~~~~

Open a command shell, navigate to a convenient location on your hard drive, and
type::

 svn checkout http://pysal.googlecode.com/svn/trunk/ 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::

 svn update

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: '.shx', Modes: ['r', 'wb', 'w', 'rb']
 Ext: '.geoda_txt', Modes: ['r']
 Ext: '.dbf', Modes: ['r', 'w']
 Ext: '.gwt', Modes: ['r']
 Ext: '.gal', Modes: ['r', 'w']
 Ext: '.csv', Modes: ['r']
 Ext: '.wkt', Modes: ['r']
 >>> 

Windows
~~~~~~~~

To keep up to date with PySAL development, you will need an SVN client that allows you to access and 
update the code from our repository. We recommend 
`TortoiseSVN <http://tortoisesvn.tigris.org/>`_, which is free and easy to
install. The following instructions assume you are using it. There are two basic
steps. One, checkout a copy of the source code to your local drive. Two, adjust
your PYTHONPATH environment variable so that Python looks for PySAL where you
have downloaded it.

First, create a folder where you want to store PySAL's code. For the sake of this
example, we will name it ``PySALsvn`` and put it in the root folder, so the
path is::
 
 C:\PySALsvn

If for some reason you do not have access to the root directory, you can place
the PySAL source code anywhere. Adjust your paths as appropriate for the rest of
these instructions.

Right-click your PySAL folder and select 'SVN checkout' under the Tortoise menu.
A dialog will appear. The 'Checkout Directory' refers to the path to your PySAL folder
(``C:\PySALsvn`` in this case). Copy and paste the following link into the 'URL
of repository' textbox::

 http://pysal.googlecode.com/svn/trunk/

Once you click 'OK', a folder called 'pysal-read-only' will be created under
``C:\PySALsvn`` and  all the code will be downloaded to your computer.

Now tell Python 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: '.shx', Modes: ['r', 'wb', 'w', 'rb']
 Ext: '.geoda_txt', Modes: ['r']
 Ext: '.dbf', Modes: ['r', 'w']
 Ext: '.gwt', Modes: ['r']
 Ext: '.gal', Modes: ['r', 'w']
 Ext: '.csv', Modes: ['r']
 Ext: '.wkt', Modes: ['r']
 >>> 

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

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.

Troubleshooting
===============
If you experience problems when building, installing, or testing PySAL, ask for
help on the
`OpenSpace <http://geodacenter.asu.edu/support/community>`_ 
list or
browse the archives of the
`pysal-dev <http://groups.google.com/group/pysal-dev?pli=1>`_ 
google group. 

Please include the output of the following commands in your message:

1) Platform information::

    python -c 'import os,sys;print os.name, sys.platform'
    uname -a

2) Python version::
    
    python -c 'import sys; print sys.version'

3) SciPy version::

    python -c 'import scipy; print scipy.__version__'

3) NumPy version::

    python -c 'import numpy; print numpy.__version__'

4) Feel free to add any other relevant information.
   For example, the full output (both stdout and stderr) of the PySAL
   installation command can be very helpful. Since this output can be
   rather large, ask before sending it into the mailing list (or
   better yet, to one of the developers, if asked).
