Merge branch 'examples' of github.com:InsightLab/PyMove into examples

Author: mxaviersmp

pymove/tests/test_utils_datetime.py

@@ -65,24 +65,24 @@ def test_str_to_datetime():
     assert(converted_date_time == expected_date_time)
 
 
-def test_to_str():
+def test_datetime_to_str():
 
     expected = str_date_time_default
 
     data = default_date_time
 
-    str_date_time = datetime.to_str(data)
+    str_date_time = datetime.datetime_to_str(data)
 
     assert(str_date_time == expected)
 
 
-def test_to_min():
+def test_datetime_to_min():
 
     expected = 25347608
 
     data = default_date_time
 
-    date_to_min = datetime.to_min(data)
+    date_to_min = datetime.datetime_to_min(data)
 
     assert(date_to_min == expected)
 
@@ -145,7 +145,7 @@ def test_working_day():
 
 def test_now_str():
 
-    expected = datetime.to_str(dt.datetime.now())
+    expected = datetime.datetime_to_str(dt.datetime.now())
 
     time_now = datetime.now_str()
 

pymove/utils/datetime.py

@@ -58,6 +58,19 @@ def date_to_str(dt: datetime) -> Text:
     str
         Represents the date in string format
 
+    Example
+    -------
+    import datatime
+    time_now = datetime.datetime.now()
+
+    print(time_now)
+    >>> 2021-04-29 11:01:29.909340
+    print(type(time_now))
+    >>> <class 'datetime.datetime'>
+
+    print(date_to_str(time_now), type(time_now))
+    >>> 2021-04-29  <class 'str'>
+
     """
     return dt.strftime('%Y-%m-%d')
 
@@ -76,14 +89,27 @@ def str_to_datetime(dt_str: Text) -> datetime:
     datetime
         Represents a datetime in datetime format
 
+    Example
+    -------
+    time_1 = '2020-06-29'
+    time_2 = '2020-06-29 12:45:59'
+
+    print(type(time_1), type(time_2))
+    >>>  <class 'str'> <class 'str'>
+    print( str_to_datetime(time_1), type(str_to_datetime(time_1)))
+    >>> 2020-06-29 00:00:00 <class 'datetime.datetime'>
+    print(str_to_datetime(time_2), type(str_to_datetime(time_2)))
+    >>> 2020-06-29 12:45:59 <class 'datetime.datetime'>
+
+
     """
     if len(dt_str) == 10:
         return datetime.strptime(dt_str, '%Y-%m-%d')
     else:
         return datetime.strptime(dt_str, '%Y-%m-%d %H:%M:%S')
 
 
-def to_str(dt: datetime) -> Text:
+def datetime_to_str(dt: datetime) -> Text:
     """
     Converts a date in datetime format to string format.
 
@@ -97,11 +123,24 @@ def to_str(dt: datetime) -> Text:
     str
         Represents a datetime in string format "%Y-%m-%d %H:%M:%S".
 
+    Example:
+    -------
+    import datetime
+    time_now = datetime.datetime.now()
+
+    print(time_now)
+    >>> 2021-04-29 14:15:29.708113
+    print(type(time_now))
+    >>> <class 'datetime.datetime'>
+
+    print(data_to_str(time_now), type(data_to_str(time_now)))
+    >>> 2021-04-29 14:15:29  <class 'str' >
+
     """
     return dt.strftime('%Y-%m-%d %H:%M:%S')
 
 
-def to_min(dt: datetime) -> int:
+def datetime_to_min(dt: datetime) -> int:
     """
     Converts a datetime to an int representation in minutes.
 
@@ -117,6 +156,16 @@ def to_min(dt: datetime) -> int:
     int
         Represents minutes from
 
+    Example
+    -------
+    import datetime
+
+    time_now = datetime.datetime.now()
+    print(type(to_min(time_now)))
+    >>> <class 'int'>
+    to_min(time_now)
+    >>> 26996497
+
     """
     # get an integer time slot from a datetime
     return int(
@@ -140,6 +189,11 @@ def min_to_datetime(minutes: int) -> datetime:
     datetime
         Represents minutes in datetime format
 
+    Example
+    -------
+    print(min_to_datetime(26996497), type(min_to_datetime(26996497)))
+    >>> 2021-04-30 13:37:00 <class 'datetime.datetime'>
+
     """
     return datetime.utcfromtimestamp(minutes * 60)
 
@@ -158,6 +212,18 @@ def to_day_of_week_int(dt: datetime) -> int:
     int
         Represents day of week.
 
+    Example
+    -------
+    from pymove.utils.datetime import str_to_datetime
+
+    monday = str_to_datetime('2021-05-3 12:00:01')
+    friday = str_to_datetime('2021-05-7 12:00:01')
+
+    print(to_day_of_week_int(monday), type(to_day_of_week_int(monday)))
+    >>> 0 <class 'int'>
+    print(to_day_of_week_int(friday), type(to_day_of_week_int(friday)))
+    >>> 4 <class 'int'>
+
     """
     return dt.weekday()
 
@@ -185,6 +251,20 @@ def working_day(
         if true, means that the day informed by the user is a working day.
         if false, means that the day is not a working day.
 
+    Examples
+    --------
+    from pymove.utils.datetime import str_to_datetime
+
+    independence_day = str_to_datetime('2021-09-7 12:00:01')
+    # In Brazil this day is a holiday
+    next_day = str_to_datetime('2021-09-8 12:00:01')
+    # In Brazil this day is a Wednesday and isn't a holiday
+
+    print(working_day(independence_day, 'BR'), type(working_day(independence_day, 'BR')))
+    >>> False <class 'bool'>
+    print(working_day(next_day, 'BR'), type(working_day(next_day, 'BR')))
+    >>> True <class 'bool'>
+
     References
     ----------
     Countries and States names available in https://pypi.org/project/holidays/
@@ -224,7 +304,7 @@ def now_str() -> Text:
     "2019-09-02 13:54:16"
 
     """
-    return to_str(datetime.now())
+    return datetime_to_str(datetime.now())
 
 
 def deltatime_str(deltatime_seconds: float) -> Text:
@@ -374,6 +454,18 @@ def elapsed_time_dt(start_time: datetime) -> int:
         Represents the time elapsed from the start time to the current time
         (when the function was called).
 
+    Examples
+    --------
+    from datetime import datetime
+    from pymove.utils.datetime import str_to_datetime
+
+    start_time_1 = datetime(2020, 6, 29, 0, 0)
+    start_time_2 = str_to_datetime('2020-06-29 12:45:59')
+
+    print(elapsed_time_dt(start_time_1))
+    >>> 26411808666
+    print(elapsed_time_dt(start_time_2))
+    >>> 26365849667
     """
     return diff_time(start_time, datetime.now())
 
@@ -395,6 +487,19 @@ def diff_time(start_time: datetime, end_time: datetime) -> int:
         Represents the time elapsed from the start time to the current time
         (when the function was called).
 
+    Examples
+    --------
+    from datetime import datetime
+    from pymove.utils.datetime import str_to_datetime
+
+    time_now = datetime.now()
+    start_time_1 = datetime(2020, 6, 29, 0, 0)
+    start_time_2 = str_to_datetime('2020-06-29 12:45:59')
+
+    print(diff_time(start_time_1, time_now))
+    >>> 26411808665
+    print(diff_time(start_time_2, time_now))
+    >>> 26365849665
     """
     return int((end_time - start_time).total_seconds() * 1000)
 
@@ -481,6 +586,21 @@ def generate_time_statistics(
     DataFrame
         Statistics infomations of the pairwise local labels
 
+    Example
+    -------
+    df
+    >>> local_label	     prev_local	  time_to_prev	id
+    0	house	            None	     NaN	    1
+    1	market	           house	    720.0	    1
+    2	market	           market	     5.0	    1
+    3	market	           market	     1.0	    1
+    4	school	           market	    844.0	    1
+
+    generate_time_statistics(df)
+    >>> local_label	 prev_local	   mean	    std	        min	    max	     sum	  count
+    0	 house	       market	   844.0	0.000000	844.0	844.0	844.0	   1
+    1	 market	        house	   720.0	0.000000	720.0	720.0	720.0	   1
+    2	 market	       market	    3.0	    2.828427	1.0	     5.0	6.0	       2
     """
     df_statistics = data.groupby(
         [local_label, PREV_LOCAL]
@@ -514,6 +634,15 @@ def _calc_time_threshold(seg_mean: float, seg_std: float) -> float:
         The threshold based on the mean and standard deviation
         of transition time for the segment.
 
+    Examples
+    --------
+    print(_calc_time_threshold(12.3,2.1))
+    >>> 14.4
+    print(_calc_time_threshold(1,1.5))
+    >>> 2.5
+    print(_calc_time_threshold(-2,2))
+    >>> 0.0
+
     """
     threshold = seg_std + seg_mean
     threshold = float('{:.1f}'.format(threshold))
@@ -549,6 +678,35 @@ def threshold_time_statistics(
         DataFrame of time statistics with the aditional feature: threshold,
         which indicates the time limit of the trajectory segment, or None
 
+    Example
+    -------
+    from pymove.utils.datetime import generate_time_statistics, _calc_time_threshold
+
+    df
+    >>> local_label	     prev_local	  time_to_prev	id
+    0	house	            None	     NaN	    1
+    1	market	           house	    720.0	    1
+    2	market	           market	     5.0	    1
+    3	market	           market	     1.0	    1
+    4	school	           market	    844.0	    1
+
+    statistics = generate_time_statistics(df)
+    statistics
+    >>> local_label	 prev_local	   mean	    std	        min	    max	     sum	  count
+    0	 house	       market	   844.0	0.000000	844.0	844.0	844.0	   1
+    1	 market	        house	   720.0	0.000000	720.0	720.0	720.0	   1
+    2	 market	       market	    3.0	    2.828427	1.0	     5.0	6.0	       2
+
+    threshold_time_statistics(statistics)
+    >>> local_label	 prev_local	   mean	    std	        min	    max	     sum	  count
+    0	 house	       market	   844.0	0.000000	844.0	844.0	844.0	   1
+    1	 market	        house	   720.0	0.000000	720.0	720.0	720.0	   1
+    2	 market	       market	    3.0	    2.828427	1.0	     5.0	6.0	       2
+
+       threshold
+    0    844.0
+    1    720.0
+    2    5.8
     """
     if not inplace:
         df_statistics = df_statistics.copy()