Merge pull request #189 from InsightLab/examples

Putting examples on distances module

Author: mxaviersmp

pymove/utils/distances.py

@@ -55,6 +55,14 @@ def haversine(
     float or ndarray
         Represents distance between points in meters
 
+    Example
+    -------
+    >>> from pymove.utils.distances import haversine
+    >>> lat_fortaleza, lon_fortaleza = [-3.71839 ,-38.5434]
+    >>> lat_quixada, lon_quixada = [-4.979224744401671, -39.056434302570665]
+    >>> haversine(lat_fortaleza, lon_fortaleza, lat_quixada, lon_quixada)
+    151298.02548428564
+
     References
     ----------
     Vectorized haversine function:
@@ -98,6 +106,16 @@ def euclidean_distance_in_meters(
     -------
     float or ndarray
         euclidean distance in meters between the two points.
+
+    Example
+    -------
+    >>> from pymove.utils.distances import euclidean_distance_in_meters
+    >>> lat_fortaleza, lon_fortaleza = [-3.71839 ,-38.5434]
+    >>> lat_quixada, lon_quixada = [-4.979224744401671, -39.056434302570665]
+    >>> euclidean_distance_in_meters(
+    >>>    lat_fortaleza, lon_fortaleza, lat_quixada, lon_quixada
+    >>> )
+    151907.9670136588
     """
     y1 = utils.conversions.lat_to_y_spherical(lat=lat1)
     y2 = utils.conversions.lat_to_y_spherical(lat=lat2)
@@ -136,6 +154,21 @@ def nearest_points(
     DataFrame
         dataframe with closest points
 
+    Example
+    -------
+    >>> from pymove.utils.distances import nearest_points
+    >>> df_a
+             lat          lon               datetime    id
+    0   39.984198   116.319322   2008-10-23 05:53:06     1
+    1   39.984224   116.319402   2008-10-23 05:53:11     1
+    >>> df_b
+              lat          lon              datetime    id
+    0   39.984211   116.319389   2008-10-23 05:53:16     1
+    1   39.984217   116.319422   2008-10-23 05:53:21     1
+    >>> nearest_points(df_a,df_b)
+              lat          lon              datetime    id
+    0   39.984211   116.319389   2008-10-23 05:53:16     1
+    1   39.984211   116.319389   2008-10-23 05:53:16     1
     """
     result = pd.DataFrame(columns=traj1.columns)
 
@@ -164,8 +197,7 @@ def medp(
     """
     Returns the Mean Euclidian Distance Predictive between two trajectories.
 
-    Considers only the spatial
-    dimension for the similarity measure.
+    Considers only the spatial dimension for the similarity measure.
 
     Parameters
     ----------
@@ -184,6 +216,18 @@ def medp(
     -------
     float
         total distance
+
+    Example
+    -------
+    >>> from pymove.utils.distances import medp
+    >>> traj_1
+                lat          lon           datetime     id
+    0   39.98471   116.319865   2008-10-23 05:53:23      1
+    >>> traj_2
+                lat        lon             datetime     id
+    0   39.984674   116.31981   2008-10-23 05:53:28      1
+    >>> medp(traj_1, traj_2)
+    6.573431370981577e-05
     """
     soma = 0
     traj2 = nearest_points(traj1, traj2, latitude, longitude)
@@ -230,6 +274,17 @@ def medt(
     float
         total distance
 
+    Example
+    -------
+    >>> from pymove.utils.distances import medt
+    >>> traj_1
+             lat          lon              datetime  id
+    0   39.98471   116.319865   2008-10-23 05:53:23   1
+    >>> traj_2
+              lat         lon              datetime  id
+    0   39.984674   116.31981   2008-10-23 05:53:28   1
+    >>> medt(traj_1, traj_2)
+    6.592419887747872e-05
     """
     soma = 0
     proportion = 1000000000