DOC: Update feature-finding and linking docstrings.

wsyxbcl · May 27, 2019 · e245272 · e245272
1 parent 27925d3
commit e245272
Show file tree

Hide file tree

Showing 3 changed files with 49 additions and 15 deletions.
diff --git a/trackpy/feature.py b/trackpy/feature.py
@@ -219,8 +219,13 @@ def locate(raw_image, diameter, minmass=None, maxsize=None, separation=None,
 
     Parameters
     ----------
-    image : array
-         any N-dimensional image
+    raw_image : array (any dimensions)
+        Image used for final characterization. Ideally, pixel values of
+        this image are not rescaled, but it can also be identical to
+        ``image``.
+    image : array (same size as raw_image)
+        Processed image used for centroid-finding and most particle
+        measurements.
     diameter : odd integer or tuple of odd integers
         This may be a single number or a tuple giving the feature's
         extent in each dimension, useful when the dimensions do not have
@@ -237,7 +242,7 @@ def locate(raw_image, diameter, minmass=None, maxsize=None, separation=None,
     maxsize : float
         maximum radius-of-gyration of brightness, default None
     separation : float or tuple
-        Minimum separtion between features.
+        Minimum separation between features.
         Default is diameter + 1. May be a tuple, see diameter for details.
     noise_size : float or tuple
         Width of Gaussian blurring kernel, in pixels
@@ -274,10 +279,12 @@ def locate(raw_image, diameter, minmass=None, maxsize=None, separation=None,
 
     Returns
     -------
-    DataFrame([x, y, mass, size, ecc, signal])
-        where mass means total integrated brightness of the blob,
+    DataFrame([x, y, mass, size, ecc, signal, raw_mass])
+        where "x, y" are appropriate to the dimensionality of the image,
+        mass means total integrated brightness of the blob,
         size means the radius of gyration of its Gaussian-like profile,
-        and ecc is its eccentricity (0 is circular).
+        ecc is its eccentricity (0 is circular),
+        and raw_mass is the total integrated brightness in raw_image.
 
     See Also
     --------
@@ -287,7 +294,7 @@ def locate(raw_image, diameter, minmass=None, maxsize=None, separation=None,
     Notes
     -----
     Locate works with a coordinate system that has its origin at the center of
-    pixel (0, 0). In almost all cases this will be the topleft pixel: the
+    pixel (0, 0). In almost all cases this will be the top-left pixel: the
     y-axis is pointing downwards.
 
     This is an implementation of the Crocker-Grier centroid-finding algorithm.

diff --git a/trackpy/linking/linking.py b/trackpy/linking/linking.py
@@ -73,6 +73,15 @@ def link_iter(coords_iter, search_range, **kwargs):
     See also
     --------
     link
+
+    Notes
+    -----
+    This is an implementation of the Crocker-Grier linking algorithm.
+    [1]_
+
+    References
+    ----------
+    .. [1] Crocker, J.C., Grier, D.G. http://dx.doi.org/10.1006/jcis.1996.0217
     """
     # ensure that coords_iter is iterable
     coords_iter = iter(coords_iter)
@@ -156,6 +165,16 @@ def link(f, search_range, pos_columns=None, t_column='frame', **kwargs):
     See also
     --------
     link_iter
+
+    Notes
+    -----
+    This is an implementation of the Crocker-Grier linking algorithm.
+    [1]_
+
+    References
+    ----------
+    .. [1] Crocker, J.C., Grier, D.G. http://dx.doi.org/10.1006/jcis.1996.0217
+
     """
     if pos_columns is None:
         pos_columns = guess_pos_columns(f)

diff --git a/trackpy/refine/center_of_mass.py b/trackpy/refine/center_of_mass.py
@@ -35,20 +35,19 @@ def refine_com(raw_image, image, radius, coords, max_iterations=10,
     """Find the center of mass of a bright feature starting from an estimate.
 
     Characterize the neighborhood of a local maximum, and iteratively
-    hone in on its center-of-brightness. Return its coordinates, integrated
-    brightness, size (Rg), eccentricity (0=circular), and signal strength.
+    hone in on its center-of-brightness.
 
     Parameters
     ----------
     raw_image : array (any dimensions)
-        used for final characterization
-    image : array (any dimension)
-        processed image, used for locating center of mass
+        Image used for final characterization. Ideally, pixel values of
+        this image are not rescaled, but it can also be identical to
+        ``image``.
+    image : array (same size as raw_image)
+        Processed image used for centroid-finding and most particle
+        measurements.
     coords : array or DataFrame
         estimated position
-    separation : float or tuple
-        Minimum separtion between features.
-        Default is 0. May be a tuple, see diameter for details.
     max_iterations : integer
         max number of loops to refine the center of mass, default 10
     engine : {'python', 'numba'}
@@ -63,6 +62,15 @@ def refine_com(raw_image, image, radius, coords, max_iterations=10,
     pos_columns: list of strings, optional
         Column names that contain the position coordinates.
         Defaults to ``['y', 'x']`` or ``['z', 'y', 'x']``, if ``'z'`` exists.
+
+    Returns
+    -------
+    DataFrame([x, y, mass, size, ecc, signal, raw_mass])
+        where "x, y" are appropriate to the dimensionality of the image,
+        mass means total integrated brightness of the blob,
+        size means the radius of gyration of its Gaussian-like profile,
+        ecc is its eccentricity (0 is circular),
+        and raw_mass is the total integrated brightness in raw_image.
     """
     if isinstance(coords, pd.DataFrame):
         if pos_columns is None: