Multiple minor issues the the walkthru

[Resonanz]

Lots of easy documentation fixes......

I am using Yosemite (OS X 10.10)

On this page: http://soft-matter.github.io/trackpy/tutorial/walkthrough.html

1. The first line fails under ipython and python and on various versions (2.7 and 3.3):

%matplotlib inline

1. The "print" command also fails on py 3.3:

print frames[0]  # the first frame

as it require parentheses:

print (frames[0])  # the first frame

1. The print command also fails elsewhere on the page:

print 'Before:', t['particle'].nunique()
print 'After:', t1['particle'].nunique()

1. The "frames[0]" command shows a plot in the documentation but it doesn't work in reality (elsewhere the plots seem to display fine as per the documentation).
2. Py 2.7 does not appear to like this line:

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

It complains about converting to greyscale.

1. I think it should be made explicitly clear in the documentation what python version the devs are using. I have spent considerable time trying to use trackpy with py 3.4 which I could not make work.
2. Install on py 3.4 fails:

conda install -c soft-matter trackpy

Fetching package metadata: ...
Solving package specifications: ..
Error: Unsatisfiable package specifications.
Generating hint: 
[2/2                 ] |#######################################################################| 100%

Hint: the following combinations of packages create a conflict with the
remaining packages:
  - python 3.4*
  - trackpy

1. These lines do not plot as shown in the walkthru:

d.plot()
tm = tp.subtract_drift(t1, d)
tp.plot_traj(tm)

1. To use .avi files we need to install FFMPEG. Details here: http://mikeboers.github.io/PyAV/

brew install ffmpeg

Reading video frames will fail at this stage:

frames = pims.Video('test5.avi', as_grey=True)

ImportError: This reader requires PyAV

pip install av

This seems to work (py33) and does NOT require an "import av" to work with trackpy

1. The "edit on github" link at the top of this page is broken: https://trackpy.readthedocs.org/en/latest/reference/trackpy.feature.html

and the page itself needs formatting to make it clearer. e.g. this is all on one line:

image : image array (any dimensions) diameter : feature size in px minmass : minimum integrated brightness  but should be:

image : image array (any dimensions) 
diameter : feature size in px 
minmass : minimum integrated brightness

etc...

1. Same page..... Half way down the page, dataFrame is described but does not fit the flow of parameters. I think this is the object that is returned, not a parameter that is passed to the object.
2. Same page, "preprocess" is not highlighted.
3. Same page.... "engine" and "batch" not highlighted, and what is "batch" anyway?

14 I have edited the text to look like this for my own purposes (except for change of appearance upon pasting):

# trackpy.locate(
#   raw_image,            image : image array (any dimensions)
#   diameter,             diameter : feature size in px
#   minmass=100.0,        minmass : minimum integrated brightness
#                         Default is 100, but a good value is often much higher. 
#                         This is a crucial parameter for elminating spurious features.
#   maxsize=None,         maxsize : maximum radius-of-gyration of brightness, 
#                         default None
#   separation=None,      separation : feature separation, in pixels.
#                         Default is the feature diameter + 1
#   noise_size=1,         noise_size : width of Gaussian blurring kernel, in pixels.
#                         Default is 1. 
#   smoothing_size=None,  smoothing_size : size of boxcar smoothing, in pixels.
#                         Default is the same is feature separation.        
#   threshold=None,       threshold : Clip bandpass result below this value.
#                         Default None, passed through to bandpass.
#   invert=False,         invert : Set to True if features are darker than background. 
#                         False by default. 
#   percentile=64,        percentile : Features must have a peak brighter than pixels 
#                         in this percentile. This helps eliminate spurious peaks.  
#   topn=None,            topn : Return only the N brightest features above minmass.
#                         If None (default), return all features above minmass.
#   preprocess=True,      preprocess : Set to False to turn out bandpass preprocessing.  
#   max_iterations=10,    max_iterations : integer max number of loops to refine 
#                         the center of mass, default 10  
#   filter_before=True,   filter_before : boolean. Use minmass (and maxsize, if set) 
#                         to eliminate spurious features based on their estimated mass 
#                         and size before refining position. True by default for performance.       
#   filter_after=True,    filter_after : boolean. Use final characterizations of mass 
#                         and size to eliminate spurious features. True by default.      
#   characterize=True,    characterize : boolean. Compute “extras”: eccentricity, 
#                         signal, ep. True by default.      
#   engine=u'auto'        engine : {‘auto’, ‘python’, ‘numba’} 
#   )
#
#   DataFrame([x, y, mass, size, ecc, signal]) where mass means total integrated 
#   brightness of the blob, size means the radius of gyration of its Gaussian-like
#   profile, and ecc is its eccentricity (1 is circular).
#

1. preprocess : Set to False to turn out bandpass preprocessing.

"out" or "off"?

1. Unclear what this means:

diameter,             diameter : feature size in px

Is it a max, min, average...? What is the default?

1. It is not clear to me what "A" is referring to in the following:

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 η, particle radius a, and temperature T as

D=kT6πηa.

For paritcles with a 1 μm diameter in room-temperature water, A≈1.74. Our value above is not far off.

TYPO in the above line: "particles".

[TAC edited to add markup]

[tacaswell]

i am very distressed %matplotlib inline failed as that is strait from the IPython folks... Are you copy-pasting into an ipython terminal or running the example as a notebook?

[tacaswell]

Please put in PRs for what you can.

[Resonanz]

In python, ipython, and in a file. Kinda weird huh but seems others have same problem.

-----Original Message-----
From: "Thomas A Caswell" [email protected]
Sent: ‎1/‎22/‎2015 9:55 AM
To: "soft-matter/trackpy" [email protected]
Cc: "Rob" [email protected]
Subject: Re: [trackpy] Multiple minor issues the the walkthru (#200)

i am very distressed %matplotlib inline failed as that is strait from the IPython folks... Are you copy-pasting into an ipython terminal or running the example as a notebook?
—
Reply to this email directly or view it on GitHub.=

[tacaswell]

the inline magic only works in the notebook and in the qtconsole, not in any of the things you tried.

[Resonanz]

Sorry what does that mean Tom? I may need a like git training 😃

-----Original Message-----
From: "Thomas A Caswell" [email protected]
Sent: ‎1/‎22/‎2015 9:59 AM
To: "soft-matter/trackpy" [email protected]
Cc: "Rob" [email protected]
Subject: Re: [trackpy] Multiple minor issues the the walkthru (#200)

Please put in PRs for what you can.
—
Reply to this email directly or view it on GitHub.=

[Resonanz]

Okay but for someone starting out this is a real show stopper..... I don't even know what the notebook is that you refer to, or qtconsole. I'm on a Mac if that helps. I'm happy to edit some docs to help if you can get me started.

-----Original Message-----
From: "Thomas A Caswell" [email protected]
Sent: ‎1/‎22/‎2015 10:01 AM
To: "soft-matter/trackpy" [email protected]
Cc: "Rob" [email protected]
Subject: Re: [trackpy] Multiple minor issues the the walkthru (#200)

the inline magic only works in the notebook and in the qtconsole, not in any of the things you tried.
—
Reply to this email directly or view it on GitHub.=

[tacaswell]

http://ipython.org/notebook.html

@danielballan We need to add links to ipython notebook + instructions on how to use them to the docs someplace

@RobWardNZ download the note book file from http://nbviewer.ipython.org/github/soft-matter/trackpy-examples/tree/master/notebooks/ and then run ipython notebook in what ever file folder you saved it in.

[danielballan]

Thanks, Rob. Point taken. The notebooks is rocketing in popularity, but of course it is not universal. We will add a note advising users to use the notebook or skip the "%matplotlib inline".

[nkeim]

@RobWardNZ: I think @tacaswell meant that you should run ipython notebook in whatever directory contains that downloaded file.

Thanks for pointing out these issues! As @tacaswell suggested, the fastest way for some of them to be fixed is for you to just give us the edited files (preferably via a pull request). But we (the other contributors) are also just glad to be aware of them and will look for opportunities to address them.

[tacaswell]

Oh, yeah meant 'folder', not 'file'.

[danielballan]

@RobWardNZ, thanks again for these generously detailed notes. Apologies for letting them linger so long. Point by point:

• We can add a comment beside %matplotlib inline indicating that this only applies in an IPython notebook. You raise a good point that users will be alarmed if the very first step fails!
• Should we switch to Python 3 style print statements? My only hesitation here is that Anaconda ships py2 by default. We would have to at least at python=3.4 to the installation instructions so that our tutorial works out of the box.
• Of course frames[0] only shows the image if you are in the notebook. Perhaps we should also show how to do this with imshow.
• The issue with pims.ImageSequence('./sample_data/bulk_water/*.png', as_grey=True) is a known bug in pims. I know it's been fixed in master, but I can't recall if that fix has been released. In any case, a new pims release is coming.
• The "Unsatisfiable package specifications" issue with conda has been fixed in master.
• I think the plots (e.g., d.plot()) require you to run %matplotlib in an interpreter or %matplotlib notebook in a notebook. We'll make a note about that at the top. See After mpl 1.5.0 is out, revisit plot usage. trackpy-examples#36
• PyAV (and its dependencies, including FFmpeg) are now included in our conda package for UNIX and OSX. (There is no PyAV conda package for Windows yet -- probably within 6 months though.)
• Remove the Edit on Github links.
• Clarify meaning of the variable A.
• "paritcles" -> "particles"
• Formatting of docstring parameters has been fixed in a PR.
• In locate and batch docstring: "to turn out bandpass preprocessing", change "out" -> "off"
• Elaborate on diameter : feature size in px. I guess we could call it the "target" or "typical" feature size. @RobWardNZ, It controls the size of the circular (or ellipsoidal) mask that trackpy passes over the image in search of local maxima.
• Take a careful look at locate docstring to be sure we have caught all formatting issues.
  and the page itself needs formatting to make it clearer. e.g. this is all on one line:
• @RobWardNZ, what do you mean by "DataFrame is described but does not fit the flow of parameters. I think this is the object that is returned, not a parameter that is passed to the object."?

[tacaswell]

from __future__ import print_function should be at the top of every script ;)

[danielballan]

@caspervdw Can you check off the issues that you fixed in your recent PR?

[caspervdw]

@danielballan done

[danielballan]

All of these have been addressed or opened as new separate issues on trackpy-examples. No remaining issues involve editing the source (including docstrings) of trackpy itself.