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.

Timing

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: 7.20024e-05 s
Time to make random numbers: 0.109757 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()

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

T.tic()
rand = np.random.rand(n,n)
T.toc('Time to make random numbers')

Time to make zeros: 89.4 μs
Time to make random numbers: 0.110 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))
T.tt('Time to make zeros')

rand = np.random.rand(n,n)
T.tt('Time to make random numbers')

Time to make zeros: 0.104 ms
Time to make random numbers: 0.110 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: 52.2 μs
Time to make random numbers: 0.111 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))
    T.tt(f'Generating {len(rnd):,} numbers')

print('mean', T.mean())
print('std',  T.std())
print('min',  T.min())
print('max',  T.max())
T.plot();

Generating 21,494 numbers: 0.308 ms
Generating 1,776,503 numbers: 8.34 ms
Generating 1,883,004 numbers: 9.05 ms
Generating 510,032 numbers: 3.43 ms
Generating 1,919,918 numbers: 8.37 ms
mean 0.0058997154235839845
std 0.0034447334541167587
min 0.0003075599670410156
max 0.009048223495483398

Sleeping

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 0.245347 s
Pausing for 1e-12 s
Pausing for 0.0969824 s
Pausing for 1e-12 s
Pausing for 0.238824 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: 66.7 ms
Run 1: 231 ms
Run 2: 2.43 ms
Run 3: 35.4 ms

Dates

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()

1786329404.4879036

sc.now() # Equivalent to datetime.datetime.now()

datetime.datetime(2026, 8, 10, 2, 36, 44, 493406)

sc.getdate() # Equivalent to datetime.datetime.now().strftime('%Y-%b-%d %H:%M:%S')

'2026-Aug-10 02:36:44'

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

sc.date('2022-03-04')

datetime.date(2022, 3, 4)

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

d1 = sc.date('04-03-2022', format='mdy')
d2 = sc.date('04-03-2022', format='dmy')
print(d1)
print(d2)

2022-04-03
2022-03-04

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

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

['2022-02-02',
 '2022-02-03',
 '2022-02-04',
 '2022-02-05',
 '2022-02-06',
 '2022-02-07',
 '2022-02-08',
 '2022-02-09',
 '2022-02-10',
 '2022-02-11',
 '2022-02-12',
 '2022-02-13',
 '2022-02-14',
 '2022-02-15',
 '2022-02-16',
 '2022-02-17',
 '2022-02-18',
 '2022-02-19',
 '2022-02-20',
 '2022-02-21',
 '2022-02-22',
 '2022-02-23',
 '2022-02-24',
 '2022-02-25',
 '2022-02-26',
 '2022-02-27',
 '2022-02-28',
 '2022-03-01',
 '2022-03-02',
 '2022-03-03',
 '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
sc.pp(newdates)

['2022-12-02',
 '2022-12-03',
 '2022-12-04',
 '2022-12-05',
 '2022-12-06',
 '2022-12-07',
 '2022-12-08',
 '2022-12-09',
 '2022-12-10',
 '2022-12-11',
 '2022-12-12',
 '2022-12-13',
 '2022-12-14',
 '2022-12-15',
 '2022-12-16',
 '2022-12-17',
 '2022-12-18',
 '2022-12-19',
 '2022-12-20',
 '2022-12-21',
 '2022-12-22',
 '2022-12-23',
 '2022-12-24',
 '2022-12-25',
 '2022-12-26',
 '2022-12-27',
 '2022-12-28',
 '2023-01-01',
 '2023-01-02',
 '2023-01-03',
 '2023-01-04']