Merge pull request #195 from InsightLab/examples

Examples on trajectories module

Author: mxaviersmp

pymove/utils/trajectories.py

@@ -36,7 +36,7 @@ def read_csv(
     type_: Optional[Text] = TYPE_PANDAS,
     n_partitions: Optional[int] = 1,
     **kwargs
-):
+) -> MoveDataFrame:
     """
     Reads a `csv` file and structures the data.
 
@@ -70,6 +70,19 @@ def read_csv(
     MoveDataFrameAbstract subclass
         Trajectory data
 
+    Examples
+    --------
+    >>> from pymove.utils.trajectories import read_csv
+    >>> move_df = read_csv('geolife_sample.csv')
+    >>> move_df.head()
+              lat          lon              datetime  id
+    0   39.984094   116.319236   2008-10-23 05:53:05   1
+    1   39.984198   116.319322   2008-10-23 05:53:06   1
+    2   39.984224   116.319402   2008-10-23 05:53:11   1
+    3   39.984211   116.319389   2008-10-23 05:53:16   1
+    4   39.984217   116.319422   2008-10-23 05:53:21   1
+    >>> type(move_df)
+    <class 'pymove.core.pandas.PandasMoveDataFrame'>
     """
     data = _read_csv(
         filepath_or_buffer,
@@ -95,6 +108,12 @@ def invert_dict(d: Dict) -> Dict:
     dict
         inverted dict
 
+    Examples
+    --------
+    >>> from pymove.utils.trajectories import invert_dict
+    >>> traj_dict = {'a': 1, 'b': 2}
+    >>> invert_dict(traj_dict)
+    {1: 'a, 2: 'b'}
     """
     return {v: k for k, v in d.items()}
 
@@ -125,10 +144,10 @@ def flatten_dict(
 
     Examples
     --------
-    >>> d = { 'a': 1, 'b': { 'c': 2, 'd': 3}}
+    >>> from pymove.utils.trajectories import flatten_dict
+    >>> d = {'a': 1, 'b': {'c': 2, 'd': 3}}
     >>> flatten_dict(d)
-    { 'a': 1, 'b_c': 2, 'b_d': 3 }
-
+    {'a': 1, 'b_c': 2, 'b_d': 3}
     """
     if not isinstance(d, dict):
         return {parent_key: d}
@@ -164,12 +183,27 @@ def flatten_columns(data: DataFrame, columns: List) -> DataFrame:
 
     Examples
     --------
-    >>> d = {'a': 1, 'b': {'c': 2, 'd': 3}}
-    >>>> data = pd.DataFrame({'col1': [1], 'col2': [d]})
-    >>>> flatten_columns(data, ['col2'])
-       col1  col2_b_d  col2_a  col2_b_c
-    0     1         3       1         2
-
+    >>> from pymove.utils.trajectories import flatten_columns
+    >>> move_df
+              lat          lon              datetime  id           dict_column
+    0   39.984094   116.319236   2008-10-23 05:53:05   1              {'a': 1}
+    1   39.984198   116.319322   2008-10-23 05:53:06   1              {'b': 2}
+    2   39.984224   116.319402   2008-10-23 05:53:11   1      {'c': 3, 'a': 4}
+    3   39.984211   116.319389   2008-10-23 05:53:16   1              {'b': 2}
+    4   39.984217   116.319422   2008-10-23 05:53:21   1      {'a': 3, 'c': 2}
+    >>> flatten_columns(move_df, columns='dict_column')
+              lat            lon               datetime   id \
+    dict_column_b         dict_column_c   dict_column_a
+    0   39.984094      116.319236   2008-10-23 05:53:05    1 \
+              NaN                   NaN             1.0
+    1   39.984198      116.319322   2008-10-23 05:53:06    1 \
+              2.0                   NaN             NaN
+    2   39.984224      116.319402   2008-10-23 05:53:11    1 \
+              NaN                   3.0             4.0
+    3   39.984211      116.319389   2008-10-23 05:53:16    1 \
+              2.0                   NaN             NaN
+    4   39.984217      116.319422   2008-10-23 05:53:21    1 \
+              NaN                   2.0             3.0
     """
     data = data.copy()
     if not isinstance(columns, list):
@@ -218,6 +252,16 @@ def shift(
     ----------
     https://stackoverflow.com/questions/30399534/shift-elements-in-a-numpy-array
 
+    Examples
+    --------
+    >>> from pymove.utils.trajectories import shift
+    >>> array = [1, 2, 3, 4, 5, 6, 7]
+    >>> shift(array, 1)
+    [0 1 2 3 4 5 6]
+    >>> shift(array, 0)
+    [1, 2, 3, 4, 5, 6, 7]
+    >>> shift(array, -1)
+    [2 3 4 5 6 7 0]
     """
     result = np.empty_like(arr)
     if fill_value is None:
@@ -254,6 +298,13 @@ def fill_list_with_new_values(original_list: List, new_list_values: List):
     new_list_values : list.
         The list from which elements will be copied
 
+    Example
+    -------
+    >>> from pymove.utils.trajectories import fill_list_with_new_values
+    >>> lst = [1, 2, 3, 4]
+    >>> fill_list_with_new_values(lt, ['a','b'])
+    >>> print(lst)
+    ['a', 'b', 3, 4]
     """
     n = len(new_list_values)
     original_list[:n] = new_list_values
@@ -272,6 +323,13 @@ def object_for_array(object_: Text) -> ndarray:
     -------
     array
         object converted to a list
+
+    Examples
+    --------
+    >>> from pymove.utils.trajectories import object_for_array
+    >>> list_str = '[1,2,3,4,5]'
+    >>> object_for_array(list_str)
+    array([1., 2., 3., 4., 5.], dtype=float32)
     """
     if object_ is None:
         return object_
@@ -284,7 +342,7 @@ def object_for_array(object_: Text) -> ndarray:
         return conv.astype('object_')
 
 
-def column_to_array(data: DataFrame, column: Text):
+def column_to_array(data: DataFrame, column: Text) -> DataFrame:
     """
     Transforms all columns values to list.
 
@@ -295,6 +353,29 @@ def column_to_array(data: DataFrame, column: Text):
 
     column : str
         Label of data referring to the column for conversion
+
+    Returns
+    -------
+    dataframe
+        Dataframe with the selected column converted to list
+
+    Example
+    -------
+    >>> from pymove.utils.trajectories import column_to_array
+    >>> move_df
+              lat          lon              datetime  id   list_column
+    0   39.984094   116.319236   2008-10-23 05:53:05   1        '[1,2]'
+    1   39.984198   116.319322   2008-10-23 05:53:06   1        '[3,4]'
+    2   39.984224   116.319402   2008-10-23 05:53:11   1        '[5,6]'
+    3   39.984211   116.319389   2008-10-23 05:53:16   1        '[7,8]'
+    4   39.984217   116.319422   2008-10-23 05:53:21   1       '[9,10]'
+    >>> column_to_array(move_df, column='list_column')
+              lat          lon              datetime  id    list_column
+    0   39.984094   116.319236   2008-10-23 05:53:05   1      [1.0,2.0]
+    1   39.984198   116.319322   2008-10-23 05:53:06   1      [3.0,4.0]
+    2   39.984224   116.319402   2008-10-23 05:53:11   1      [5.0,6.0]
+    3   39.984211   116.319389   2008-10-23 05:53:16   1      [7.0,8.0]
+    4   39.984217   116.319422   2008-10-23 05:53:21   1     [9.0,10.0]
     """
     data = data.copy()
     if column not in data: