Skip to content

Commit eed6b96

Browse files
mxaviersmpmxaviersmp
authored
Merge pull request #184 from InsightLab/examples
Examples
2 parents 1758f90 + 6ae35a3 commit eed6b96

File tree

4 files changed

+175
-40
lines changed

4 files changed

+175
-40
lines changed

‎MANIFEST.in‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
include requirements.txt
22
include LICENSE
33
include README.md
4+
include .mapping.png
45
include pymove/tests/baseline/*.png

‎pymove/tests/test_utils_datetime.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -65,24 +65,24 @@ def test_str_to_datetime():
6565
assert(converted_date_time == expected_date_time)
6666

6767

68-
def test_to_str():
68+
def test_datetime_to_str():
6969

7070
expected = str_date_time_default
7171

7272
data = default_date_time
7373

74-
str_date_time = datetime.to_str(data)
74+
str_date_time = datetime.datetime_to_str(data)
7575

7676
assert(str_date_time == expected)
7777

7878

79-
def test_to_min():
79+
def test_datetime_to_min():
8080

8181
expected = 25347608
8282

8383
data = default_date_time
8484

85-
date_to_min = datetime.to_min(data)
85+
date_to_min = datetime.datetime_to_min(data)
8686

8787
assert(date_to_min == expected)
8888

@@ -145,7 +145,7 @@ def test_working_day():
145145

146146
def test_now_str():
147147

148-
expected = datetime.to_str(dt.datetime.now())
148+
expected = datetime.datetime_to_str(dt.datetime.now())
149149

150150
time_now = datetime.now_str()
151151

‎pymove/utils/datetime.py‎

Lines changed: 168 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
44
date_to_str,
55
str_to_datetime,
6-
to_str,
7-
to_min,
6+
datetime_to_str,
7+
datetime_to_min,
88
min_to_datetime,
99
to_day_of_week_int,
1010
working_day,
@@ -58,6 +58,17 @@ def date_to_str(dt: datetime) -> Text:
5858
str
5959
Represents the date in string format
6060
61+
Example
62+
-------
63+
>>> import datatime
64+
>>> time_now = datetime.datetime.now()
65+
>>> print(time_now)
66+
'2021-04-29 11:01:29.909340'
67+
>>> print(type(time_now))
68+
'<class 'datetime.datetime'>'
69+
>>> print(date_to_str(time_now), type(time_now))
70+
'2021-04-29 <class 'str'>'
71+
6172
"""
6273
return dt.strftime('%Y-%m-%d')
6374

@@ -76,14 +87,26 @@ def str_to_datetime(dt_str: Text) -> datetime:
7687
datetime
7788
Represents a datetime in datetime format
7889
90+
Example
91+
-------
92+
>>> time_1 = '2020-06-29'
93+
>>> time_2 = '2020-06-29 12:45:59'
94+
>>> print(type(time_1), type(time_2))
95+
'<class 'str'> <class 'str'>'
96+
>>> print( str_to_datetime(time_1), type(str_to_datetime(time_1)))
97+
'2020-06-29 00:00:00 <class 'datetime.datetime'>'
98+
>>> print(str_to_datetime(time_2), type(str_to_datetime(time_2)))
99+
'2020-06-29 12:45:59 <class 'datetime.datetime'>'
100+
101+
79102
"""
80103
if len(dt_str) == 10:
81104
return datetime.strptime(dt_str, '%Y-%m-%d')
82105
else:
83106
return datetime.strptime(dt_str, '%Y-%m-%d %H:%M:%S')
84107

85108

86-
def to_str(dt: datetime) -> Text:
109+
def datetime_to_str(dt: datetime) -> Text:
87110
"""
88111
Converts a date in datetime format to string format.
89112
@@ -97,11 +120,22 @@ def to_str(dt: datetime) -> Text:
97120
str
98121
Represents a datetime in string format "%Y-%m-%d %H:%M:%S".
99122
123+
Example:
124+
-------
125+
>>> import datetime
126+
>>> time_now = datetime.datetime.now()
127+
>>> print(time_now)
128+
'2021-04-29 14:15:29.708113'
129+
>>> print(type(time_now))
130+
'<class 'datetime.datetime'>'
131+
>>> print(datetime_to_str(time_now), type(datetime_to_str(time_now)))
132+
'2021-04-29 14:15:29 <class 'str' >'
133+
100134
"""
101135
return dt.strftime('%Y-%m-%d %H:%M:%S')
102136

103137

104-
def to_min(dt: datetime) -> int:
138+
def datetime_to_min(dt: datetime) -> int:
105139
"""
106140
Converts a datetime to an int representation in minutes.
107141
@@ -117,6 +151,16 @@ def to_min(dt: datetime) -> int:
117151
int
118152
Represents minutes from
119153
154+
Example
155+
-------
156+
>>> import datetime
157+
158+
>>> time_now = datetime.datetime.now()
159+
>>> print(type(datetime_to_min(time_now)))
160+
'<class 'int'>'
161+
>>> datetime_to_min(time_now)
162+
'26996497'
163+
120164
"""
121165
# get an integer time slot from a datetime
122166
return int(
@@ -140,6 +184,11 @@ def min_to_datetime(minutes: int) -> datetime:
140184
datetime
141185
Represents minutes in datetime format
142186
187+
Example
188+
-------
189+
>>> print(min_to_datetime(26996497), type(min_to_datetime(26996497)))
190+
'2021-04-30 13:37:00 <class 'datetime.datetime'>'
191+
143192
"""
144193
return datetime.utcfromtimestamp(minutes * 60)
145194

@@ -158,6 +207,16 @@ def to_day_of_week_int(dt: datetime) -> int:
158207
int
159208
Represents day of week.
160209
210+
Example
211+
-------
212+
>>> from pymove.utils.datetime import str_to_datetime
213+
>>> monday = str_to_datetime('2021-05-3 12:00:01')
214+
>>> friday = str_to_datetime('2021-05-7 12:00:01')
215+
>>> print(to_day_of_week_int(monday), type(to_day_of_week_int(monday)))
216+
'0 <class 'int'>'
217+
>>> print(to_day_of_week_int(friday), type(to_day_of_week_int(friday)))
218+
'4 <class 'int'>'
219+
161220
"""
162221
return dt.weekday()
163222

@@ -185,6 +244,20 @@ def working_day(
185244
if true, means that the day informed by the user is a working day.
186245
if false, means that the day is not a working day.
187246
247+
Examples
248+
--------
249+
>>> from pymove.utils.datetime import str_to_datetime
250+
>>> independence_day = str_to_datetime('2021-09-7 12:00:01') # In Brazil this day is a holiday
251+
>>> next_day = str_to_datetime('2021-09-8 12:00:01') # In Brazil this day is a Wednesday and isn't a holiday
252+
>>> print(working_day(independence_day, 'BR'))
253+
False
254+
>>> print(type(working_day(independence_day, 'BR')))
255+
<class 'bool'>
256+
>>> print(working_day(next_day, 'BR'))
257+
True
258+
>>> print(type(working_day(next_day, 'BR')))
259+
'<class 'bool'>'
260+
188261
References
189262
----------
190263
Countries and States names available in https://pypi.org/project/holidays/
@@ -219,12 +292,11 @@ def now_str() -> Text:
219292
220293
Examples
221294
--------
222-
>>> from pymove import datetime
223-
>>> datetime.now_str()
224-
"2019-09-02 13:54:16"
295+
>>> now_str()
296+
'2019-09-02 13:54:16'
225297
226298
"""
227-
return to_str(datetime.now())
299+
return datetime_to_str(datetime.now())
228300

229301

230302
def deltatime_str(deltatime_seconds: float) -> Text:
@@ -243,9 +315,8 @@ def deltatime_str(deltatime_seconds: float) -> Text:
243315
244316
Examples
245317
--------
246-
>>> from pymove import datetime
247-
>>> datetime.deltatime_str(1082.7180936336517)
248-
"18m:02.718s"
318+
>>> deltatime_str(1082.7180936336517)
319+
'18m:02.718s'
249320
250321
Notes
251322
-----
@@ -279,8 +350,7 @@ def timestamp_to_millis(timestamp: Text) -> int:
279350
280351
Examples
281352
--------
282-
>>> from pymove.utils.utils import datetime
283-
>>> datetime.timestamp_to_millis("2015-12-12 08:00:00.123000")
353+
>>> timestamp_to_millis('2015-12-12 08:00:00.123000')
284354
1449907200123 (UTC)
285355
286356
"""
@@ -303,9 +373,8 @@ def millis_to_timestamp(milliseconds: float) -> Timestamp:
303373
304374
Examples
305375
--------
306-
>>> from pymove.utils.utils import datetime
307-
>>> datetime.millis_to_timestamp(1449907200123)
308-
"2015-12-12 08:00:00.123000"
376+
>>> millis_to_timestamp(1449907200123)
377+
'2015-12-12 08:00:00.123000'
309378
310379
"""
311380
return Timestamp(milliseconds, unit='ms')
@@ -327,9 +396,8 @@ def time_to_str(time: Timestamp) -> Text:
327396
328397
Examples
329398
--------
330-
>>> from pymove.utils.utils import datetime
331-
>>> datetime.time_to_str("2015-12-12 08:00:00.123000")
332-
"08:00:00"
399+
>>> time_to_str("2015-12-12 08:00:00.123000")
400+
'08:00:00'
333401
334402
"""
335403
return time.strftime('%H:%M:%S')
@@ -351,8 +419,7 @@ def str_to_time(dt_str: Text) -> datetime:
351419
352420
Examples
353421
--------
354-
>>> from pymove.utils.utils import datetime
355-
>>> datetime.str_to_time("08:00:00")
422+
>>> str_to_time("08:00:00")
356423
datetime(1900, 1, 1, 8, 0)
357424
358425
"""
@@ -374,6 +441,16 @@ def elapsed_time_dt(start_time: datetime) -> int:
374441
Represents the time elapsed from the start time to the current time
375442
(when the function was called).
376443
444+
Examples
445+
--------
446+
>>> from datetime import datetime
447+
>>> from pymove.utils.datetime import str_to_datetime
448+
>>> start_time_1 = datetime(2020, 6, 29, 0, 0)
449+
>>> start_time_2 = str_to_datetime('2020-06-29 12:45:59')
450+
>>> print(elapsed_time_dt(start_time_1))
451+
26411808666
452+
>>> print(elapsed_time_dt(start_time_2))
453+
26365849667
377454
"""
378455
return diff_time(start_time, datetime.now())
379456

@@ -395,6 +472,17 @@ def diff_time(start_time: datetime, end_time: datetime) -> int:
395472
Represents the time elapsed from the start time to the current time
396473
(when the function was called).
397474
475+
Examples
476+
--------
477+
>>> from datetime import datetime
478+
>>> from pymove.utils.datetime import str_to_datetime
479+
>>> time_now = datetime.now()
480+
>>> start_time_1 = datetime(2020, 6, 29, 0, 0)
481+
>>> start_time_2 = str_to_datetime('2020-06-29 12:45:59')
482+
>>> print(diff_time(start_time_1, time_now))
483+
26411808665
484+
>>> print(diff_time(start_time_2, time_now))
485+
26365849665
398486
"""
399487
return int((end_time - start_time).total_seconds() * 1000)
400488

@@ -433,20 +521,19 @@ def create_time_slot_in_minute(
433521
434522
Examples
435523
--------
436-
from pymove import datetime
524+
>>> from pymove import datetime
437525
>>> data
438-
lat lon datetime id
439-
0 39.984094 116.319236 2008-10-23 05:44:05 1
440-
1 39.984198 116.319322 2008-10-23 05:56:06 1
441-
2 39.984224 116.319402 2008-10-23 05:56:11 1
442-
3 39.984224 116.319402 2008-10-23 06:10:15 1
443-
526+
' lat lon datetime id'
527+
'0 39.984094 116.319236 2008-10-23 05:44:05 1'
528+
'1 39.984198 116.319322 2008-10-23 05:56:06 1'
529+
'2 39.984224 116.319402 2008-10-23 05:56:11 1'
530+
'3 39.984224 116.319402 2008-10-23 06:10:15 1'
444531
>>> datetime.create_time_slot_in_minute(data, inplace=False)
445-
lat lon datetime id time_slot
446-
0 39.984094 116.319236 2008-10-23 05:44:05 1 22
447-
1 39.984198 116.319322 2008-10-23 05:56:06 1 23
448-
2 39.984224 116.319402 2008-10-23 05:56:11 1 23
449-
3 39.984224 116.319402 2008-10-23 06:10:15 1 24
532+
' lat lon datetime id time_slot'
533+
'0 39.984094 116.319236 2008-10-23 05:44:05 1 22'
534+
'1 39.984198 116.319322 2008-10-23 05:56:06 1 23'
535+
'2 39.984224 116.319402 2008-10-23 05:56:11 1 23'
536+
'3 39.984224 116.319402 2008-10-23 06:10:15 1 24'
450537
451538
"""
452539
if data.dtypes[label_datetime] != 'datetime64[ns]':
@@ -481,6 +568,21 @@ def generate_time_statistics(
481568
DataFrame
482569
Statistics infomations of the pairwise local labels
483570
571+
Example
572+
-------
573+
>>> df
574+
' local_label prev_local time_to_prev id'
575+
'0 house NaN NaN 1'
576+
'1 market house 720.0 1'
577+
'2 market market 5.0 1'
578+
'3 market market 1.0 1'
579+
'4 school market 844.0 1'
580+
581+
>>> generate_time_statistics(df)
582+
' local_label prev_local mean std min max sum count'
583+
'0 house market 844.0 0.000000 844.0 844.0 844.0 1'
584+
'1 market house 720.0 0.000000 720.0 720.0 720.0 1'
585+
'2 market market 3.0 2.828427 1.0 5.0 6.0 2'
484586
"""
485587
df_statistics = data.groupby(
486588
[local_label, PREV_LOCAL]
@@ -514,6 +616,15 @@ def _calc_time_threshold(seg_mean: float, seg_std: float) -> float:
514616
The threshold based on the mean and standard deviation
515617
of transition time for the segment.
516618
619+
Examples
620+
--------
621+
>>> print(_calc_time_threshold(12.3,2.1))
622+
14.4
623+
>>> print(_calc_time_threshold(1,1.5))
624+
2.5
625+
>>> print(_calc_time_threshold(-2,2))
626+
0.0
627+
517628
"""
518629
threshold = seg_std + seg_mean
519630
threshold = float('{:.1f}'.format(threshold))
@@ -549,6 +660,30 @@ def threshold_time_statistics(
549660
DataFrame of time statistics with the aditional feature: threshold,
550661
which indicates the time limit of the trajectory segment, or None
551662
663+
Example
664+
-------
665+
>>> from pymove.utils.datetime import generate_time_statistics
666+
667+
>>> df
668+
' local_label prev_local time_to_prev id'
669+
'0 house NaN NaN 1'
670+
'1 market house 720.0 1'
671+
'2 market market 5.0 1'
672+
'3 market market 1.0 1'
673+
'4 school market 844.0 1'
674+
675+
>>> statistics = generate_time_statistics(df)
676+
>>> statistics
677+
' local_label prev_local mean std min max sum count'
678+
'0 house market 844.0 0.000000 844.0 844.0 844.0 1'
679+
'1 market house 720.0 0.000000 720.0 720.0 720.0 1'
680+
'2 market market 3.0 2.828427 1.0 5.0 6.0 2'
681+
>>> threshold_time_statistics(statistics)
682+
' local_label prev_local mean std min max sum count threshold'
683+
'0 house market 844.0 0.000000 844.0 844.0 844.0 1 844.0'
684+
'1 market house 720.0 0.000000 720.0 720.0 720.0 1 720.0'
685+
'2 market market 3.0 2.828427 1.0 5.0 6.0 2 5.8'
686+
552687
"""
553688
if not inplace:
554689
df_statistics = df_statistics.copy()

0 commit comments

Comments
 (0)