add docstring in numba function

Author: AntSimi

src/py_eddy_tracker/generic.py

@@ -48,6 +48,8 @@
 @njit(cache=True)
 def reverse_index(index, nb):
     """
+    Compute a list of index, which are not in index.
+
     :param array index: index of group which will be set to False
     :param array nb: Count for each group
     :return: mask of value selected
@@ -61,7 +63,7 @@ def reverse_index(index, nb):
 
 @njit(cache=True)
 def build_index(groups):
-    """We expected that variable is monotonous, and return index for each step change
+    """We expected that variable is monotonous, and return index for each step change.
 
     :param array groups: array which contain group to be separated
     :return: (first_index of each group, last_index of each group, value to shift group)
@@ -85,12 +87,15 @@ def build_index(groups):
 
 @njit(cache=True)
 def hist_numba(x, bins):
+    """Call numba histogram  to speed up."""
     return histogram(x, bins)
 
 
 @njit(cache=True, fastmath=True, parallel=False)
 def distance_grid(lon0, lat0, lon1, lat1):
     """
+    Get distance for every couple of point.
+
     :param array lon0:
     :param array lat0:
     :param array lon1:
@@ -127,7 +132,7 @@ def distance_grid(lon0, lat0, lon1, lat1):
 @njit(cache=True, fastmath=True)
 def distance(lon0, lat0, lon1, lat1):
     """
-    Compute distance between points from each line
+    Compute distance between points from each line.
 
     :param float lon0:
     :param float lat0:
@@ -148,7 +153,7 @@ def distance(lon0, lat0, lon1, lat1):
 @njit(cache=True)
 def cumsum_by_track(field, track):
     """
-    Cumsum by track
+    Cumsum by track.
 
     :param array field: data to sum
     :pram array(int) track: id of track to separate data
@@ -172,7 +177,7 @@ def cumsum_by_track(field, track):
 @njit(cache=True, fastmath=True)
 def interp2d_geo(x_g, y_g, z_g, m_g, x, y):
     """
-    For geographic grid, test of cicularity
+    For geographic grid, test of cicularity.
 
     :param array x_g: coordinates of grid
     :param array y_g: coordinates of grid
@@ -189,6 +194,7 @@ def interp2d_geo(x_g, y_g, z_g, m_g, x, y):
     x_step = x_g[1] - x_ref
     y_step = y_g[1] - y_ref
     nb_x = x_g.shape[0]
+    nb_y = y_g.shape[0]
     is_circular = (x_g[-1] + x_step) % 360 == x_g[0] % 360
     z = empty(x.shape, dtype=z_g.dtype)
     for i in prange(x.size):
@@ -197,11 +203,16 @@ def interp2d_geo(x_g, y_g, z_g, m_g, x, y):
         i0 = int(floor(x_))
         i1 = i0 + 1
         xd = x_ - i0
+        j0 = int(floor(y_))
+        j1 = j0 + 1
         if is_circular:
             i0 %= nb_x
             i1 %= nb_x
-        j0 = int(floor(y_))
-        j1 = j0 + 1
+        else:
+            if i1 >= nb_x or i0 < 0 or j0 < 0 or j1 >= nb_y:
+                z[i] = nan
+                continue
+
         yd = y_ - j0
         z00 = z_g[i0, j0]
         z01 = z_g[i0, j1]
@@ -219,7 +230,7 @@ def interp2d_geo(x_g, y_g, z_g, m_g, x, y):
 @njit(cache=True, fastmath=True)
 def uniform_resample(x_val, y_val, num_fac=2, fixed_size=None):
     """
-    Resample contours to have (nearly) equal spacing
+    Resample contours to have (nearly) equal spacing.
 
     :param array_like x_val: input x contour coordinates
     :param array_like y_val: input y contour coordinates
@@ -246,7 +257,7 @@ def uniform_resample(x_val, y_val, num_fac=2, fixed_size=None):
 @njit(cache=True)
 def flatten_line_matrix(l_matrix):
     """
-    Flat matrix and add on between each line
+    Flat matrix and add on between each line.
 
     :param l_matrix: matrix of position
     :return: array with nan between line
@@ -267,7 +278,7 @@ def flatten_line_matrix(l_matrix):
 @njit(cache=True)
 def simplify(x, y, precision=0.1):
     """
-    Will remove all middle point which are closer than precision
+    Will remove all middle point which are closer than precision.
 
     :param array x:
     :param array y:
@@ -307,7 +318,7 @@ def simplify(x, y, precision=0.1):
 @njit(cache=True)
 def split_line(x, y, i):
     """
-    Split x and y at each i change
+    Split x and y at each i change.
 
     :param x: array
     :param y: array
@@ -335,7 +346,7 @@ def split_line(x, y, i):
 @njit(cache=True)
 def wrap_longitude(x, y, ref, cut=False):
     """
-    Will wrap contiguous longitude with reference like west bound
+    Will wrap contiguous longitude with reference like west bound.
 
     :param array x:
     :param array y:
@@ -391,7 +402,7 @@ def wrap_longitude(x, y, ref, cut=False):
 @njit(cache=True, fastmath=True)
 def coordinates_to_local(lon, lat, lon0, lat0):
     """
-    Take latlong coordinates to transform in local coordinates (in m)
+    Take latlong coordinates to transform in local coordinates (in m).
 
     :param array x: coordinates to transform
     :param array y: coordinates to transform
@@ -420,7 +431,7 @@ def coordinates_to_local(lon, lat, lon0, lat0):
 @njit(cache=True, fastmath=True)
 def local_to_coordinates(x, y, lon0, lat0):
     """
-    Take local coordinates (in m) to transform to latlong
+    Take local coordinates (in m) to transform to latlong.
 
     :param array x: coordinates to transform
     :param array y: coordinates to transform
@@ -447,7 +458,7 @@ def local_to_coordinates(x, y, lon0, lat0):
 @njit(cache=True, fastmath=True)
 def nearest_grd_indice(x, y, x0, y0, xstep, ystep):
     """
-    Get nearest grid indice from a position
+    Get nearest grid indice from a position.
 
     :param x: longitude
     :param y: latitude
@@ -465,7 +476,7 @@ def nearest_grd_indice(x, y, x0, y0, xstep, ystep):
 @njit(cache=True)
 def bbox_indice_regular(vertices, x0, y0, xstep, ystep, N, circular, x_size):
     """
-    Get bbox indice of a contour in a regular grid
+    Get bbox indice of a contour in a regular grid.
 
     :param vertices: vertice of contour
     :param float x0: first grid longitude
@@ -492,7 +503,7 @@ def bbox_indice_regular(vertices, x0, y0, xstep, ystep, N, circular, x_size):
 @njit(cache=True, fastmath=True)
 def get_pixel_in_regular(vertices, x_c, y_c, x_start, x_stop, y_start, y_stop):
     """
-    Get a pixel list of a regular grid contain in a contour
+    Get a pixel list of a regular grid contain in a contour.
 
     :param array_like vertices: contour vertice (N,2)
     :param array_like x_c: longitude coordinate of grid
@@ -532,7 +543,7 @@ def get_pixel_in_regular(vertices, x_c, y_c, x_start, x_stop, y_start, y_stop):
 
 def build_circle(x0, y0, r):
     """
-    Method to built circle from center coordinates
+    Build circle from center coordinates.
 
     :param float x0: center coordinate
     :param float y0: center coordinate

src/py_eddy_tracker/poly.py

@@ -29,8 +29,9 @@
 @njit(cache=True)
 def is_left(x_line_0, y_line_0, x_line_1, y_line_1, x_test, y_test):
     """
+    Test if point is left of an infinit line.
+
     http://geomalgorithms.com/a03-_inclusion.html
-    isLeft(): tests if a point is Left|On|Right of an infinite line.
     See: Algorithm 1 "Area of Triangles and Polygons"
 
     :param float x_line_0:
@@ -55,6 +56,8 @@ def is_left(x_line_0, y_line_0, x_line_1, y_line_1, x_test, y_test):
 @njit(cache=True)
 def poly_contain_poly(xy_poly_out, xy_poly_in):
     """
+    Check if poly_in is include in poly_out.
+
     :param vertice xy_poly_out:
     :param vertice xy_poly_in:
     :return: True if poly_in is in poly_out
@@ -76,6 +79,8 @@ def poly_contain_poly(xy_poly_out, xy_poly_in):
 @njit(cache=True)
 def poly_area_vertice(v):
     """
+    Compute area from vertice.
+
     :param vertice v: polygon vertice
     :return: area of polygon in coordinates unit
     :rtype: float
@@ -86,7 +91,7 @@ def poly_area_vertice(v):
 @njit(cache=True)
 def poly_area(x, y):
     """
-    Must be call with local coordinates (in m, to get an area in m²)
+    Must be call with local coordinates (in m, to get an area in m²).
 
     :param array x:
     :param array y:
@@ -103,7 +108,7 @@ def poly_area(x, y):
 @njit(cache=True)
 def winding_number_poly(x, y, xy_poly):
     """
-    Check if x,y is in poly
+    Check if x,y is in poly.
 
     :param float x: x to test
     :param float y: y to test
@@ -137,6 +142,8 @@ def winding_number_poly(x, y, xy_poly):
 @njit(cache=True)
 def winding_number_grid_in_poly(x_1d, y_1d, i_x0, i_x1, x_size, i_y0, xy_poly):
     """
+    Return index for each grid coordinates within contour.
+
     http://geomalgorithms.com/a03-_inclusion.html
 
     :param array x_1d: x of local grid
@@ -167,7 +174,7 @@ def winding_number_grid_in_poly(x_1d, y_1d, i_x0, i_x1, x_size, i_y0, xy_poly):
 @njit(cache=True, fastmath=True)
 def bbox_intersection(x0, y0, x1, y1):
     """
-    Compute bbox to check if there are a bbox intersection
+    Compute bbox to check if there are a bbox intersection.
 
     :param array x0: x for polygon list 0
     :param array y0: y for polygon list 0
@@ -207,9 +214,11 @@ def bbox_intersection(x0, y0, x1, y1):
 @njit(cache=True)
 def create_vertice(x, y):
     """
+    Return polygon vertice.
+
     :param array x:
     :param array y:
-    :return: Return the vertice of polygon
+    :return: Return polygon vertice
     :rtype: vertice
     """
     nb = x.shape[0]
@@ -223,7 +232,7 @@ def create_vertice(x, y):
 @njit(cache=True)
 def create_vertice_from_2darray(x, y, index):
     """
-    Choose a polygon in x,y list and return vertice
+    Choose a polygon in x,y list and return vertice.
 
     :param array x:
     :param array y:
@@ -242,7 +251,7 @@ def create_vertice_from_2darray(x, y, index):
 @njit(cache=True)
 def get_wrap_vertice(x0, y0, x1, y1, i):
     """
-    Return a vertice for each polygon and check that use same reference coordinates
+    Return a vertice for each polygon and check that use same reference coordinates.
 
     :param array x0: x for polygon list 0
     :param array y0: y for polygon list 0
@@ -261,6 +270,8 @@ def get_wrap_vertice(x0, y0, x1, y1, i):
 
 def vertice_overlap(x0, y0, x1, y1, minimal_area=False):
     """
+    Return percent of overlap for each item.
+
     :param array x0: x for polygon list 0
     :param array y0: y for polygon list 0
     :param array x1: x for polygon list 1
@@ -289,6 +300,8 @@ def vertice_overlap(x0, y0, x1, y1, minimal_area=False):
 
 def polygon_overlap(p0, p1, minimal_area=False):
     """
+    Return percent of overlap for each item.
+
     :param list(Polygon) p0: List of polygon to compare with p1 list
     :param list(Polygon) p1: List of polygon to compare with p0 list
     :param bool minimal_area: If True, function will compute intersection/little polygon, else intersection/union
@@ -313,8 +326,9 @@ def polygon_overlap(p0, p1, minimal_area=False):
 @njit(cache=True)
 def fit_circle(x, y):
     """
-    From a polygon, function will fit a circle
-    Must be call with local coordinates (in m, to get a radius in m)
+    From a polygon, function will fit a circle.
+
+    Must be call with local coordinates (in m, to get a radius in m).
 
     :param array x: x of polygon
     :param array y: y of polygon
@@ -357,7 +371,7 @@ def fit_circle(x, y):
 
 @njit(cache=True)
 def fit_circle_(x, y):
-    """
+    r"""
     From a polygon, function will fit a circle.
 
     Must be call with local coordinates (in m, to get a radius in m).
@@ -377,7 +391,7 @@ def fit_circle_(x, y):
 
     Solutions:
 
-    .. math:: x_0 = a / 2 , y_0 = b / 2 , r = \\sqrt{c + x_0^2 + y_0^2}
+    .. math:: x_0 = a / 2 , y_0 = b / 2 , r = \sqrt{c + x_0^2 + y_0^2}
 
 
     :param array x: x of polygon
@@ -415,11 +429,12 @@ def fit_circle_(x, y):
 
 @njit(cache=True, fastmath=True)
 def shape_error(x, y, x0, y0, r):
-    """
-    With a polygon(x,y) in local coordinates
+    r"""
+    With a polygon(x,y) in local coordinates.
+
     and circle properties(x0, y0, r), function compute a shape error:
 
-    .. math:: ShapeError = \\frac{Polygon_{area} + Circle_{area} - 2 * Intersection_{area}}{Circle_{area}} * 100
+    .. math:: ShapeError = \frac{Polygon_{area} + Circle_{area} - 2 * Intersection_{area}}{Circle_{area}} * 100
 
     When error > 100, area of difference is bigger than circle area