class timer(label=None, auto=False, start=True, unit='auto', verbose=None, **kwargs)[source]#

Bases: object

Simple timer class. Note: sc.timer() and sc.Timer() are aliases.

This wraps sc.tic() and sc.toc() with the formatting arguments and the start time (at construction).

Use this in a with block to automatically print elapsed time when the block finishes.

By default, output is displayed in seconds. You can change this with the unit argument, which can be a string or a float:

  • ‘hr’ or 3600

  • ‘min’ or 60

  • ‘s’ or 1 (default)

  • ‘ms’ or 1e-3

  • ‘us’ or 1e-6

  • ‘ns’ or 1e-9

  • ‘auto’ to choose an appropriate unit

  • label (str) – label identifying this timer

  • auto (bool) – whether to automatically increment the label

  • start (bool) – whether to start timing from object creation (else, call timer.tic() explicitly)

  • unit (str/float) – the unit of time to display; see options above

  • verbose (bool) – whether to print output on each timing

  • kwargs (dict) – passed to sc.toc() when invoked

Example making repeated calls to the same timer, using auto to keep track:

>>> T = sc.timer(auto=True)
>>> T.toc()
(0): 2.63 s
>>> T.toc()
(1): 5.00 s

Example wrapping code using with-as:

>>> with sc.timer('mylabel'):
>>>     sc.timedsleep(0.5)

Example using a timer to collect data, using timer.tt() as an alias for sc.toctic() to reset the time:

T = sc.timer(doprint=False)
for key in 'abcde':

Implementation based on https://preshing.com/20110924/timing-your-code-using-pythons-with-statement/

New in version 1.3.0: sc.timer() alias, and allowing the label as first argument
New in version 1.3.2: toc() passes label correctly; tt() method; auto argument
New in version 2.0.0: plot() method; total() method; indivtimings and cumtimings properties
New in version 2.1.0: total as property instead of method; updated repr; added disp() method
New in version 3.0.0: unit argument; verbose argument; sum, min, max, mean, std methods; rawtimings property
New in version 3.1.0: Timers can be combined by addition, including sum()
New in version 3.1.5: T.timings is now an sc.objdict() instead of an sc.odict()



Compute the cumulative time for each timing


Compute the individual time between each timing


Return an array of timings


Calculate total time





Display the full representation of the object


Set start time

toc(label=None, **kwargs)[source]#

Print elapsed time; see sc.toc() for keyword arguments

property total#

Calculate total time


Alias for sc.tic()

stop(*args, **kwargs)[source]#

Alias for sc.toc()

tocout(label=None, output=True, **kwargs)[source]#

Alias for sc.toc() with output=True

toctic(*args, reset=True, **kwargs)[source]#

Like toc, but reset time between timings

tt(*args, **kwargs)[source]#

Alias for sc.toctic()

tto(*args, output=True, **kwargs)[source]#

Alias for sc.toctic() with output=True

property rawtimings#

Return an array of timings

property indivtimings#

Compute the individual time between each timing

property cumtimings#

Compute the cumulative time for each timing


Sum of timings; similar to timer.total

New in version 3.0.0.


Minimum of timings

New in version 3.0.0.


Maximum of timings

New in version 3.0.0.


Mean of timings

New in version 3.0.0.


Standard deviation of timings

New in version 3.0.0.

plot(fig=None, figkwargs=None, grid=True, **kwargs)[source]#

Create a plot of Timer.timings

  • cumulative (bool) – how the timings will be presented, individual or cumulative

  • fig (fig) – an existing figure to draw the plot in

  • figkwargs (dict) – passed to pl.figure()

  • grid (bool) – whether to show a grid

  • kwargs (dict) – passed to pl.bar()

New in version 2.0.0.