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:
Python 3
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.
PIMS has its own optional dependencies for reading various formats. You can read what you need for each format here on PIMS’ README.