Installing Trackpy

For Python Novices

Installation is simple on Windows, OSX, and Linux, even for Python novices.

1. Get Scientific Python

To get started with Python on any platform, download and install Anaconda. It comes with the common scientific Python packages built in.

2. Install trackpy

Open a command prompt. On Windows, you can use the “Anaconda Command Prompt” installed by Anaconda or Start > Applications > Command Prompt. On a Mac, look for Applications > Utilities > Terminal. Type these commands:

conda update conda
conda install -c conda-forge trackpy
conda install -c conda-forge pims

The above installs trackpy and all its requirements, plus the recommended PIMS package that simplifies image-reading, and that is used in the trackpy tutorials.

3. Try it out!

Finally, to try it out, type

jupyter notebook

Note

For older Python versions, use ipython notebook

This will automatically open a browser tab, ready to interpret Python code. To get started, check out the links to tutorials at the top of this document.

Updating Your Installation

Before updating to a new version of trackpy, be sure to read the release notes for a list of new features and any changes that may affect your existing analysis code.

Latest Stable Release

The code is under active development. To update to the latest stable release, run this in the command prompt:

conda update -c conda-forge trackpy

Latest Version Under Development

The master branch on GitHub contains the latest tested development code. Sometimes this branch will be compatible with the very latest versions of other packages (especially pandas or scipy) weeks or months before a new stable version is released. Code in this branch has already been thoroughly tested.

You can easily install a recent build by downloading the source from GitHub:

pip install https://github.com/soft-matter/trackpy/archive/master.zip

If you plan to edit the code yourself, you should use git and pip as explained below.

Using environments

Some users often like to separate Python instances into environments, so that each project can have its own set of packages. Create a trackpy-dedicated environment with the name softmatter as follows:

conda create --name softmatter trackpy nb_conda

The nb_conda is optional, but we added it to ensure that Jupyter sees this environment as well. You can switch to the environment from within Jupyter in the Kernels menu. To access the environment on the commandline, type the following:

source activate softmatter

On Windows systems, leave out the source. You can go back to the root conda environment by activating root.

More Information for Experienced Python Users

Archlinux

Package is available for Archlinux on AUR: Python 3

pip

We strongly recommend using conda to install trackpy, as described above, but pip is also supported. In general, you can use the latest version of each dependency. If you wish to override trackpy’s minimum version requirements, you may find that trackpy still runs your analysis code with older versions of dependencies.

Essential Dependencies:

You will also want to install the pims package that simplifies image-reading, and that is used in the trackpy tutorials. The remaining optional dependencies, listed below, are strongly recommended but can be challenging to install yourself, hence our recommendation that you use Anaconda.

Manual installation

If you want to be able to edit the code yourself, you can install the package manually. First, make sure you have git version management software installed. Go to a folder where you want to have your source code, then:

git clone https://github.com/soft-matter/trackpy
cd trackpy
python setup.py develop

We welcome any contribution to the trackpy source code, so feel free to send in your contributions on Github! To do so, make an account, fork trackpy and create a local copy using:

git clone https://github.com/<your_account>/trackpy

Now you have a local copy of the code which you can edit, but don’t start editing right away as you are currently on the master branch. We think it is good practice to keep your master branch mirroring the upstream trackpy version, so first create a new branch and push it to the remote as follows:

git branch fix-something
git push --set-upstream origin fix-something

Now you can edit your code in any way you like, commit your changes, and push them again to the remote.

Before sending in your code, please consult our guidelines. Also, see here for getting started using git.

Optional Dependencies

These are strongly recommended to make using trackpy more convenient and faster:

  • The PIMS package simplifies image-reading,

    and is used in the trackpy tutorials.

  • PyTables for saving results in an HDF5 file.

    This is included with Anaconda.

  • numba for accelerated feature-finding and linking.

    This is included with Anaconda and Canopy. Installing it any other way is difficult; we recommend sticking with one of these.

  • Pillow or PIL for some display routines.

    This is included with Anaconda.

PIMS has its own optional dependencies for reading various formats. You can read what you need for each format here on PIMS’ README.