.plot()

.plot()

One benefit of using Timer over StaticTimer is that all measured times are stored, which is beneficial, as it allows features like determining the best-fit-curve and graphing. .plot() by default graphs any runs in the most recent split. Although a specific split can be graphed by setting split_index to the index or label of the split.

Important: Graphing requires that there only be one independent variable. If only one variable is logged on the runs, then it will be used automatically. Otherwise, the key of the argument, either the index of the positional argument or the name of the keyword argument, must be passed into .plot() by setting key. Additionally, the value of the parameter must be an integer. If it isn't, then a function needs to be passed in to .plot() that will convert the value into an integer. This is done by setting transformer.

Very Important: The key specified for the independent variable must be found on every run in the split to be able to graph the data.

@timer.decorate(runs=100, iterations_per_run=5, log_arguments=True, call_callable_args=True)
def binary_search(sorted_array, element):
    lower, upper = 0, len(sorted_array)
    middle = upper // 2

    while middle >= lower and middle != upper:
        if element == sorted_array[middle]:
            return middle
        elif element > sorted_array[middle]:
            lower = middle + 1  # lower must be beyond middle because the middle wasn't right
        else:
            upper = middle - 1  # upper must be lower than the middle because the middle wasn't right

        middle = (upper + lower) // 2

    return None  # couldn't find it

binary_search(lambda: [i for i in range(randint(0, 10000))], lambda: randint(0, 10000))
timer.plot(key=0, transformer=len, time_unit=timer.US, x_label="List Length", equation_rounding=4,
           title="Binary Search - Random Size, Random Element")

binary_search has two logged arguments, so the first one, at index 0, is set as the key. Additionally, that argument is a list, so len is passed as the transformer. The result is the execution time of binary_search plotted against the length of the list it was passed.

.plot() can actually plot the best-fit-curve as well by setting plot_curve=True. If no curve is passed in, then the best-fit-curve will be determined automatically, but this only works were there is exactly one logged argument and its value is an integer. If determining the best-fit-curve is more complicated than that, then it can be determined beforehand and the result of .best_fit_curve() can be passed into .plot() by setting curve.

# using binary_search from above
timer.plot(
    plot_curve=True, 
    curve=timer.best_fit_curve(exclude={1}, transformers=len), 
    key=0,
    transformer=len, 
    time_unit=timer.US,
    x_label="List Length", 
    equation_rounding=4,
    title="Binary Search - Random Size, Random Element"
)

The best-fit-curve required excluding an argument and transforming another, so the curve type and parameters needed to be passed into .plot().

Multiple splits and curves can be plotted by making multiple calls to .plot() and by setting multiple=True in all but the last call.