Walkthrough¶

This notebook follows an example trackpy project from start to finish. We take video of micron-sized particles diffusing in water, track them, and analyze the trajectories to obtain the viscosity of water.

At the bottom of the notebook, we very briefly survey the more advanced features of trackpy. Browse the rest of the documentation to learn more.

Scientific IPython Setup¶

We need Python's plotting library, matplotlib. Your environment might load matplotlib automatically, but for this tutorial I'll load it explicitly using this convention. If you are unfamiliar with matplotlib, do the same as I do here, and everything that follows will work without modification.

We also might want to use scientific Python libraries. Finally, we'll import trackpy itself and its sister project, pims.

We use the alias tp for brevity.

Step 1: Read the Data¶

Obtaining the sample data¶

You can try the methods below on your own data, or you can download this notebook and all of the sample movies from the trackpy-examples repository. It's simplest to download a ZIP file of everything using this link and unzip it on your computer.

Opening images or video¶

To get our data into Python, we use our sister project, PIMS (Python Image Sequence). PIMS makes it easy and convenient to load and process video data from many formats with one consistent interface.

Using PIMS, trackpy can read:

• a directory or zipfile of sequential images
• a multi-frame TIFF file
• a video (AVI, MOV, etc.)
• specialty formats used in microscopy and scientific video capture:
  • Cine, NorPix seq
  • LSM
  • Files supported by Bioformats
  • ND2 using PIMS_ND2

(Some of the formats require some extra dependencies. For a complete list, see the README page for PIMS, or the installation instructions in the documentation.)

For many formats, using pims.open just works. Since these images are in color, we also need to set up a pipeline to convert each image to grayscale when it is read.

We can access any frame like frames[frame_number]. The image is represented as a numpy array of intensities. If you're using the Anaconda distribution of Python, these should be in the range [0, 255]. If you have a more custom environment they may be in the range [0, 1], in which case you'll have to experiment with the minmass parameters below.

In an IPython notebook, the frame is represented directly by displaying the image.

Alternatively, to make a proper plot with axes and control over scaling, use matplotlib's imshow() method.

Frames behave like numpy arrays, but with a few extra properties.

Step 2: Locate Features¶

Start with just the first frame. Estimate the size of the features (in pixels). The size must be an odd integer, and it is better to err on the large side, as we'll see below. We estimate 11 pixels.

The algorithm looks for bright features; since the features in this set of images are dark, we set invert=True.

locate returns a spreadsheet-like object called a DataFrame. It lists

• each feature's position,
• various characterizations of its appearance, which we will use to filter out spurious features,
• the "signal" strength and an estimate of uncertainty, both derived from this paper

More information about DataFrames may be found in the pandas documentation. DataFrames can easily be exported to formats like CSV, Excel, SQL, HDF5, etc.

Refine parameters to elminate spurious features¶

Many of these circles are clearly wrong; they are fleeting peaks in brightness that aren't actually particles. Rejecting them often improves results and speeds up feature-finding. There are many ways to distinguish real particles from spurious ones. The most important way is to look at total brightness ("mass").

We can then specify the minmass parameter. If your image is especially noisy, you may also find the threshold parameter useful.

There are more options for controling and optimizing feature-finding. You can review them in the documentation, where the most comprehensive description is in the API reference. Or, pull them up as you work by typing tp.locate? into IPython.

Check for subpixel accuracy¶

As Eric Weeks points out in his related tutorial, a quick way to check for subpixel accuracy is to check that the decimal part of the x and/or y positions are evenly distributed. Trackpy provides a convenience plotting function for this called subpx_bias:

If we use a mask size that is too small, the histogram often shows a dip in the middle.

Locate features in all frames¶

Or, to start, just explore a subset of the frames.

We'll locate features in the first 300 frames from this video. We use tp.batch, which calls tp.locate on each frame and collects the results.

As each frame is analyzed, tp.batch reports the frame number and how many features were found. If this number runs unexpectedly low or high, you may wish to interrupt it and try different parameters.

If your images are small, you may find that printing this number actually slows down batch significantly! In that case you can run tp.quiet() to turn it off.

Step 3: Link features into particle trajectories¶

We have the locations of the particles in each frame. Next we'll track particles from frame to frame, giving each one a number for identification.

First, we must must specify a maximum displacement, the farthest a particle can travel between frames. We should choose the smallest reasonable value because a large value slows computation time considerably. In this case, 5 pixels is reasonable.

Second, we allow for the possibility that a particle might be missed for a few frames and then seen again. (Perhaps its "mass" slipped below our cutoff due to noise in the video.) Memory keeps track of disappeared particles and maintains their ID for up to some number of frames after their last appearance. Here we use 3 frames.

The result is the features DataFrame f with an additional column, particle, identifying each feature with a label. We denote this new DataFrame t.

Filter spurious trajectories¶

We have more filtering to do. Ephemeral trajectories — seen only for a few frames — are usually spurious and never useful. The convenience function filter_stubs keeps only trajectories that last for a given number of frames.

We can also filter trajectories by their particles' appearance. At this stage, with trajectories linked, we can look at a feature's "average appearance" throughout its trajectory, giving a more accurate picture.

The particles with especially low mass, or that are especially large or non-circular (eccentric), are probably out of focus or aggregated, respectively. It is best to experiment by trial and error, filtering out regions of mass-size space and looking at the results using tp.annotate. In the end, we need to separate the good particles from the spurious ones, and it doesn't matter how we get it done.

Trace the trajectories using plot_traj():

Remove overall drift¶

Compute the overall drifting motion, which we will subtract away, adopting the reference frame of the particles' average position.

With the overall drifting motion subtracted out, we plot the trajectories again. We observe nice random walks.

Step 4: Analyze trajectories¶

Trackpy includes several functions to help with some common analyses for particle trajectories. (See the "Static Analysis" and "Motion Analysis" sections of the API reference.)

Here, we can show that these data are consistent with colloidal particles undergoing Brownian motion in water.

Mean Squared Displacement of Individal Probes¶

Compute the mean squared displacement (MSD) of each particle using the imsd function, and plot MSD vs. lag time.

Since we only analyzed 300 frames, the statistics are poor at large lag times. With more frames, we can study larger lag times.

Ensemble Mean Squared Displacement¶

Now use the emsd function to compute the ensemble mean squared displacement (EMSD) of all particles:

We can easily fit this ensemble mean-squared displacement to a power law, $At^n$, using a convenience function, fit_powerlaw, which performs a linear regression in log space.

In water, a viscous material, the expected power-law exponent $n = 1$. The value of $A = 4D$, where $D$ is the particles' diffusivity. $D$ is related to viscosity $\eta$, particle radius $r$, and temperature $T$ through the Stokes-Einstein equation:

$$ D = \displaystyle\frac{k_B T}{6\pi\eta r} $$

where $k_B$ is the Boltzmann constant. For particles with a 1 $\mu\text{m}$ diameter in room-temperature water, $A \approx 1.66$ $\mu\textrm{m}^2 / \textrm{s}$. Our values of $n$ and $A$ above are not far off. (If you'd like to know more about this measurement and its uncertainty, this paper is a thorough discussion at the advanced undergraduate level.)

This is the end of the walkthrough. Keep reading to review a few more advanced capabilities in trackpy.

Preview of Some Advanced Features¶

Check out the other tutorials for in-depth explorations of these topics and more!

Parallelization¶

Feature-finding can easily be parallelized: each frame is an independent task, and tasks can be divided among the multiple CPUs in a modern computer. See the parallelization tutorial for details. If you omit the processes argument to batch, it will default to processes='auto' and use all available CPUs on your computer.

Because starting and coordinating several processes takes some time (especially on Mac and Windows), if you are running batch on a short movie, parallelization might be disappointing or even counterproductive, and you may wish to disable it with processes=1.

For longer movies, parallelization is almost always worthwhile.

Optional High Performance Component: Numba¶

The core, time-consuming steps in particle location and linking are implemented in Python/numpy and also in pure Python optimized for numba. If numba is installed, trackpy will detect it and use it by default. You can switch it on and off to compare performance.

The linking functions similarly use numba if it's available; you can control this manually using the link_strategy option.

Streaming¶

The feature-finding and trajectory-linking functions batch and link keep all of their results in memory. This approach is simple, but it isn't necessary. We can prcoess an unlimited number of frames if we save the results as we go.

Trackpy includes a class to manage storing an retrieving data framewise in the widely-used HDF5 format. The general idea is easily extensible to other formats.

You can get results by frame with s.get(frame_number) or, when you have sufficient memory, retrieve them all. The results are identifical to what you would obtain using the basic functions batch and link.