What’s new in the package¶

Overview¶

Release v0.3.0 adds many important enhancements and fixes. Feature location is extended to anisotropic 3D (and generally N-dimensional) features. The analysis and visualization tools now give first-class status to 3D work. A powerful new “adaptive search” capability gives fine-tuned control and detailed diagnostics of the trajectory-linking process. Several performance improvements make trackpy even faster.

Enhancements¶

• The feature-finding functionality was formerly limited to circular features, but now trackpy can locate anisotropic N-dimensional features. Their size is specified as a tuple of odd integers instead of a single odd integer. See the new 3D tutorial for details. (GH162, GH239)
• The plotting and analysis tools, many of which were limited to 2D, have been extended to 3D. (GH196)
• The numba engine for fast feature-finding has been extented to handle 3D images. (GH242)
• A new method of calculating feature mass compensates for bit depth and the details of preprocessing. This means that masses are more consistent under changes in image brightness or format. However, to obtain results comparable to those from older trackpy versions, you may have to adjust your minmass parameter (and other parts of your code that use the mass). The new minmass_version_change function lets you convert old values of minmass to the new standard (GH239).
• Feature finding returns a new column raw_mass that is the sum of intensities inside the unprocessed image. For anisotropic feature detection, size and static errors are returned per dimension: size_x etc. and ep_x etc. (GH239).
• A powerful new adaptive search feature gives much richer control of the tracking (trajectory-linking) process, and it makes formerly intractable scenarios possible to solve in a reasonable time. See the new tutorials, “Advanced Linking: Subnetworks and search_range” and “Adaptive Search: Changing search_range on the Fly,” for details.
• Uncertainty estimation is more accurate. See the docstring of trackpy.uncertainty.static_error for details. (GH239, GH259)
• The linking functions can now collect data about how each particle was linked. See the tutorial “Obtaining Diagnostic Information from Linking.”
• Nearby local maxima are “merged” – i.e., interpreted as parts of the same feature – in a more robust way. This improves accuracy in crowded images. For some data, it may have no effect, but for others it will give significantly different (but, we think, better) results than previous versions of trackpy. (GH143)
• The minimum feature separation can be as small as zero. Formerly, it was constrained to be larger than the feature diameter. If serparation=0, “merging” of duplicate maxima is effectively turned off. (GH139)
• The percentile-based thresholding was moved into a separate function, so it can now be called directly. That will be useful to users who want to inspect what the thresholding is doing to their images. It will also be useful for profiling. (GH139)
• The performance of feature-finding can now be tested in a custom way using new routines in artificial.py. Users can provide a custom feature shape to test the feature-finding on their own system.
• Various performance improvements make feature-finding and trajectory-linking faster than ever, in spite of the increased functionality. (GH203, GH204)
• More user-friendly error messages replace cryptic errors. (GH166).

Bug Fixes¶

• Fixed a bug in v0.2.3 and v0.2.4 that broke the circle_size parameter in annotate(). (GH169, GH170)
• Fixed a bug where subnetwork distances were not addded in quadrature in the python linker. (GH212). (The impact of this bug is not as large as one might expect. See issue link for details.)
• Input images with a float datatype are internally converted to integer datatype for faster computation. They were converted to signed integers; now they are converted to unsigned. (GH188). When preprocessing is turned off, integer images are not converted at all (GH264).
• Fixed a memory leak when a track is ended (GH256).
• Added a warning about slow feature-finding when linking from a Pandas view (GH#281).
• Slow feature-finding with more recent versions of the numba package (0.16 and 0.17 specifically) is addressed.
• The ax argument of subpx_bias is removed because the figure is cleared anyway by subpx_bias.

API changes¶

• The plot function annotate() now displays the image with the vertical axis inverted, to be consistent with the pims display function and plot_traj(). (GH217)
• Using trackpy to access pims functionality (e.g. trackpy.ImageSequence()) is now deprecated; it still works but will generate a warning message. This capability will be removed from future versions of trackpy, in favor of accessing it in the pims package directly (e.g. pims.ImageSequence()). (GH214)
• When trackpy estimates the error in a feature’s position (returned as the ep column), the procedure can fail and result in a nonsense value. This will now result in the value of ep being NaN (not a number); previous versions of trackpy returned a negative value in this situation. To restore the previous behavior, you can replace these values with negative numbers by using the Pandas fillna() method. (GH113)
• The mass calculation is changed. Before v0.3 the mass was calculated from a rescaled image. From this version, this rescaling is compensated at the end so that the mass reflects the actual intensities in the image. minmass_version_change() can calculate the different minmass value to use (GH239)