as_grey parameter deprecated in pims, used in examples

[charlesreid1]

Several of the example notebooks (most notably, the basic walkthrough) use pims ImageSequence objects to load images. Several use the as_grey parameter, which was removed in this pims commit back in January 2017. However, this commit has not been incorporated into the version of pims that is in PyPi, so anyone using pip install pims won't notice that the notebooks are using the deprecated parameter as_grey. Anyone building pims from source, on the other hand, will see exceptions.

I believe this issue needs input from the developers to decide how to proceed. Should the notebooks expect people to have installed pims from source, or from PyPi? Is it possible that @caspervdw or @danielballan or another soft-matter package maintainer could respond indicating whether the PyPi package for pims might be maintained in the future, or whether there is an "active" versioning/release process? The interface was deprecated nearly 1 year ago but the changes still have not made it into PyPi. Not sure how to proceed here.

I am using the PyPi version of pims (with the deprecated interface) in pull request #44, which brings several of the notebooks up to date.

[danielballan]

IMO, we should stop using as_grey in the examples. Thanks for your work on #44.

[nkeim]

Agreed. Our basic pattern in soft-matter has been to do releases infrequently. That helps with stability in scientific workflows, but it can also lead to awkward situations like this. In this case, preparing the examples for the next version of trackpy/pims is the way to go, especially since the docs for previous releases remain accessible. (We may want to do a better job of exposing that.) Again, thank you for tackling all these inconsistencies!!!

[charlesreid1]

I'm happy that I can contribute to trackpy & friends!

My timeline sounded a bit confused but I've confirmed the behavior I'm seeing with a Docker container. First, pims in PyPI lists the latest release as 0.4.1, which was released in September. (This is the pims I was using to regenerate the notebooks.) This version should have had the as_grey parameter removed, since the commit that removed it was made back in January, but the pims installed by PyPI does not remove the as_grey parameter. Building pims direct from source does remove the as_grey parameter and raised exceptions with the example notebooks.

I made a gist that illustrates what's going on - it includes commands to set up a container, build pims, and load a simple pims ImageSequence using the as_grey parameter under two separate scenarios: using pims from source, and using pims from PyPI. This uses the standard travis-garnet image from Dockerhub, and runs some commands taken almost verbatim from the .travis.yml file in the pims repo. You can see that installing pims from source leads to an error when using the as_grey parameter, but installing pims via pip does not. It may be possible that an older, pre-January 2017 version of pims was bundled and submitted to PyPI under the moniker of 0.4.1. (The version string is 0.4.1 in both cases, although the behavior is definitely different.)

(I'll be opening an issue about this in the pims repository, since it's a bit out of scope here.)

The good news here is that once the PyPi version of pims is corrected, trackpy-examples can be updated to mesh with the latest pims installed from PyPI, and no new version of pims should be required.

[danielballan]

I will try to sort this out this week. In the meantime, we should update the examples to use this method:

import pims

color_frames = pims.ImageSequence('../sample_data/bulk_water/*.png', as_grey=True)

@pims.pipeline
def as_grey(frame):
    red = frame[:, :, 0]
    green = frame[:, :, 1]
    blue = frame[:, :, 2]
    return 0.2125 * red + 0.7154 * green + 0.0721 * blue

frames = as_grey(color_frames)