Installation

Requirements

Scikit-Beam has the following strict requirements:

Scikit-Beam also depends on other packages for optional features:

  • h5py: To read/write Table objects from/to HDF5 files.

However, note that these only need to be installed if those particular features are needed. Scikit-beam will import even if these dependencies are not installed.

Installing Scikit-Beam

Using pip

To install Scikit-Beam with pip, simply run:

pip install --no-deps scikit-beam

Warning

Users of the Anaconda python distribution should follow the instructions for Anaconda python distribution.

Note

You will need a C compiler (e.g. gcc or clang) to be installed (see Building from source below) for the installation to succeed.

Note

The --no-deps flag is optional, but highly recommended if you already have Numpy installed, since otherwise pip will sometimes try to “help” you by upgrading your Numpy installation, which may not always be desired.

Note

If you get a PermissionError this means that you do not have the required administrative access to install new packages to your Python installation. In this case you may consider using the --user option to install the package into your home directory. You can read more about how to do this in the pip documentation.

Alternatively, if you intend to do development on other software that uses Scikit-Beam, such as an affiliated package, consider installing Scikit-Beam into a virtualenv.

Do not install Scikit-Beam or other third-party packages using sudo unless you are fully aware of the risks.

Anaconda python distribution

Scikit-Beam is installed by default with Anaconda. To update to the latest version run:

conda update scikit-beam

Note

There may be a delay of a day or two between when a new version of Scikit-Beam is released and when a package is available for Anaconda. You can check for the list of available versions with conda search scikit-beam.

Note

Attempting to use pip to upgrade your installation of Scikit-Beam may result in a corrupted installation.

Binary installers

Binary installers are available on Windows for Python 2.6, 2.7, and >= 3.3 at PyPI.

Testing an installed Scikit-Beam

The easiest way to test your installed version of scikit-beam is running correctly is to use the scikit-beam.test() function:

import skbeam
skbeam.test()

The tests should run and print out any failures, which you can report at the Scikit-Beam issue tracker.

Note

This way of running the tests may not work if you do it in the scikit-beam source distribution. See Testing a source code build of scikit-beam for how to run the tests from the source code directory, or Running Tests for more details.

Note

Running the tests this way is currently disabled in the IPython REPL due to conflicts with some common display settings in IPython. Please run the Scikit-beam tests under the standard Python command-line interpreter.

Building from source

Prerequisites

You will need a compiler suite and the development headers for Python and Numpy in order to build Scikit-beam. On Linux, using the package manager for your distribution will usually be the easiest route, while on MacOS X you will need the XCode command line tools.

The instructions for building Numpy from source are also a good resource for setting up your environment to build Python packages.

You will also need Cython (v0.15 or later) and jinja2 (v2.7 or later) installed to build from source, unless you are installing a numbered release. (The releases packages have the necessary C files packaged with them, and hence do not require Cython.)

Note

If you are using MacOS X, you will need to the XCode command line tools. One way to get them is to install XCode. If you are using OS X 10.7 (Lion) or later, you must also explicitly install the command line tools. You can do this by opening the XCode application, going to Preferences, then Downloads, and then under Components, click on the Install button to the right of Command Line Tools. Alternatively, on 10.7 (Lion) or later, you do not need to install XCode, you can download just the command line tools from https://developer.apple.com/downloads/index.action (requires an Apple developer account).

Obtaining the source packages

Source packages

The latest stable source package for Scikit-beam can be downloaded here.

Development repository

The latest development version of Scikit-beam can be cloned from github using this command:

git clone git://github.com/scikit-beam/scikit-beam.git

Note

If you wish to participate in the development of Scikit-beam, see Developer Documentation. This document covers only the basics necessary to install Scikit-beam.

Building and Installing

Scikit-beam uses the Python distutils framework for building and installing and requires the distribute extension–the later is automatically downloaded when running python setup.py if it is not already provided by your system.

If Numpy is not already installed in your Python environment, the scikit-beam setup process will try to download and install it before continuing to install scikit-beam.

To build Scikit-beam (from the root of the source tree):

python setup.py build

To install Scikit-beam (from the root of the source tree):

python setup.py install

Troubleshooting

If you get an error mentioning that you do not have the correct permissions to install Scikit-beam into the default site-packages directory, you can try installing with:

python setup.py install --user

which will install into a default directory in your home directory.

External C libraries

The Scikit-beam source ships with the C source code of a number of libraries. By default, these internal copies are used to build Scikit-beam. However, if you wish to use the system-wide installation of one of those libraries, you can pass one or more of the --use-system-X flags to the setup.py build command.

For example, to build Scikit-beam using the system libexpat, use:

python setup.py build --use-system-expat

To build using all of the system libraries, use:

python setup.py build --use-system-libraries

To see which system libraries Scikit-beam knows how to build against, use:

python setup.py build --help

As with all distutils commandline options, they may also be provided in a setup.cfg in the same directory as setup.py. For example, to use the system libexpat, add the following to the setup.cfg file:

[build]
use_system_expat=1

The required version of setuptools is not available

If upon running the setup.py script you get a message like

The required version of setuptools (>=0.9.8) is not available, and can’t be installed while this script is running. Please install a more recent version first, using ‘easy_install -U setuptools’.

(Currently using setuptools 0.6c11 (/path/to/setuptools-0.6c11-py2.7.egg))

this is because you have a very outdated version of the setuptools package which is used to install Python packages. Normally Scikit-beam will bootstrap newer version of setuptools via the network, but setuptools suggests that you first uninstall the old version (the easy_install -U setuptools command).

However, in the likely case that your version of setuptools was installed by an OS system package (on Linux check your package manager like apt or yum for a package called python-setuptools), trying to uninstall with easy_install and without using sudo may not work, or may leave your system package in an inconsistent state.

As the best course of action at this point depends largely on the individual system and how it is configured, if you are not sure yourself what do please ask on the Scikit-beam mailing list.

The Windows installer can’t find Python in the registry

This is a common issue with Windows installers for Python packages that do not support the new User Access Control (UAC) framework added in Windows Vista and later. In particular, when a Python is installed “for all users” (as opposed to for a single user) it adds entries for that Python installation under the HKEY_LOCAL_MACHINE (HKLM) hierarchy and not under the HKEY_CURRENT_USER (HKCU) hierarchy. However, depending on your UAC settings, if the Scikit-beam installer is not executed with elevated privileges it will not be able to check in HKLM for the required information about your Python installation.

In short: If you encounter this problem it’s because you need the appropriate entries in the Windows registry for Python. You can download this script and execute it with the same Python as the one you want to install Scikit-beam into. For example to add the missing registry entries to your Python 2.7:

C:\>C:\Python27\python.exe C:\Path\To\Downloads\win_register_python.py

Building documentation

Note

Building the documentation is in general not necessary unless you are writing new documentation or do not have internet access, because the latest (and archive) versions of scikit-beam’s documentation should be available at docs.scikit-beam.org .

Building the documentation requires the Scikit-beam source code and some additional packages:

  • Sphinx (and its dependencies) 1.0 or later

  • Graphviz

  • Scikit-beam-helpers (Scikit-beam and most affiliated packages include this as a submodule in the source repository, so it does not need to be installed separately.)

  • WCSAxes

Note

Sphinx also requires a reasonably modern LaTeX installation to render equations. Per the Sphinx documentation, for the TexLive distribution the following packages are required to be installed:

  • latex-recommended

  • latex-extra

  • fonts-recommended

For other LaTeX distributions your mileage may vary. To build the PDF documentation using LaTeX, the fonts-extra TexLive package or the inconsolata CTAN package are also required.

There are two ways to build the Scikit-beam documentation. The most straightforward way is to execute the command (from the scikit-beam source directory):

python setup.py build_docs

The documentation will be built in the docs/_build/html directory, and can be read by pointing a web browser to docs/_build/html/index.html.

The LaTeX documentation can be generated by using the command:

python setup.py build_docs -b latex

The LaTeX file Scikit-beam.tex will be created in the docs/_build/latex directory, and can be compiled using pdflatex.

The above method builds the API documentation from the source code. Alternatively, you can do:

cd docs
make html

And the documentation will be generated in the same location, but using the installed version of Scikit-beam.

Testing a source code build of scikit-beam

The easiest way to test that your Scikit-beam built correctly (without installing scikit-beam) is to run this from the root of the source tree:

python run_tests.py

There are also alternative methods of Running Tests.