Dates and times#

We’ll get to the thorny issue of dates in a moment, but first let’s look at a little timer function to time your code.

Click here to open an interactive version of this notebook.


The most basic form of profiling (as covered in the previous tutorial) is just timing how long different parts of your code take. It’s not too hard to do this in Python:

import time
import numpy as np

n = 5_000

start = time.time()
zeros = np.zeros((n,n))
zeros_time = time.time()
rand = np.random.rand(n,n)
rand_time = time.time()

print(f'Time to make zeros: {(zeros_time - start):n} s')
print(f'Time to make random numbers: {(rand_time - zeros_time):n} s')
Time to make zeros: 0.000131369 s
Time to make random numbers: 0.221268 s

As you probably could’ve guessed, in Sciris there’s an easier way, inspired by Matlab’s tic and toc:

import sciris as sc

T = sc.timer()

zeros = np.zeros((n,n))
T.toc('Time to make zeros')

rand = np.random.rand(n,n)
T.toc('Time to make random numbers')
Time to make zeros: 93.0 μs
Time to make random numbers: 0.214 s

We can simplify this even further: we often call toc() followed by tic(), so instead we can just call toctic() or tt() for short; we can also omit the first tic():

T = sc.timer()

zeros = np.zeros((n,n))'Time to make zeros')

rand = np.random.rand(n,n)'Time to make random numbers')
Time to make zeros: 0.386 ms
Time to make random numbers: 0.215 s

You can also use sc.timer() in a with block, which is perhaps most intuitive of all:

with sc.timer('Time to make zeros'):
    zeros = np.zeros((n,n))

with sc.timer('Time to make random numbers'):
    rand = np.random.rand(n,n)
Time to make zeros: 0.121 ms
Time to make random numbers: 0.216 s

If we have multiple timings, we can also do statistics on them or plot the results:

T = sc.timer()

for i in range(5):
    rnd = np.random.rand(int((i+1)*np.random.rand()*1e6))'Generating {len(rnd):,} numbers')

print('mean', T.mean())
print('std',  T.std())
print('min',  T.min())
print('max',  T.max())
Generating 824,106 numbers: 8.57 ms
Generating 208,639 numbers: 2.42 ms
Generating 2,163,122 numbers: 18.4 ms
Generating 575,606 numbers: 5.62 ms
Generating 2,255,069 numbers: 18.0 ms
mean 0.010600996017456055
std 0.006504130826968382
min 0.002416849136352539
max 0.018426179885864258


For completeness, let’s talk about Sciris’ two sleep functions. Both are related to time.sleep().

The first is sc.timedsleep(). If called directly it acts just like time.sleep(). But you can also use it in a for loop to take into account the rest of the time taken by the other operations in the loop so that each loop iteration takes exactly the desired amount of time:

import numpy as np

for i in range(5):
    sc.timedsleep('start') # Initialize
    n = int(np.random.rand()*1e6) # Variable computation time
    for j in range(n):
        tmp = np.random.rand()
    sc.timedsleep(0.3, verbose=True) # Wait for 0.3 seconds per iteration including computation time
Pausing for 1e-12 s
Pausing for 0.129691 s
Pausing for 0.00981891 s
Pausing for 0.168479 s
Pausing for 1e-12 s

The other is sc.randsleep(), which as the name suggests, will sleep for a random amount of time:

for i in range(4):
    with sc.timer(f'Run {i}', unit='ms'):
        sc.randsleep(0.2) # Sleep for an average of 0.2 s, but with range 0-0.4 s
Run 0: 129 ms
Run 1: 140 ms
Run 2: 367 ms
Run 3: 391 ms


There are lots of different common date formats in Python, which probably arose through a process like this. Python’s built-in one is datetime.datetime. This format has the basics, but is hard to work with for things like plotting. NumPy made their own, called datetime64, which addresses some of these issues, but isn’t compatible with anything else. Then pandas introduced their own Timestamp, which is kind of like a combination of both.

You will probably be relieved to know that Sciris does not introduce a new datetime format, but instead tries to make it easier to work with the other formats, particularly by being able to easily interconvert them. Sciris provides shortcuts to the three common ways of getting the current datetime:

sc.time() # Equivalent to time.time()
[9]: # Equivalent to
datetime.datetime(2023, 11, 1, 22, 44, 48, 177366)
sc.getdate() # Equivalent to'%Y-%b-%d %H:%M:%S')
'2023-Nov-01 22:44:48'

Sciris’ main utility for converting between date formats is called It works like this:

[11]:, 3, 4)

It can interpret lots of different strings, although needs help with month-day-year or day-month-year formats:

d1 ='04-03-2022', format='mdy')
d2 ='04-03-2022', format='dmy')

You can create an array of dates, either as strings or datetime objects:

dates = sc.daterange('2022-02-02', '2022-03-04')

And you can also do math on dates, even if they’re just strings:

newdates = sc.datedelta(dates, months=10) # Add 10 months