Give a Reusable Calculation a Clear Contract

Botie keeps converting new greenhouse reports. If we copy the same calculation into each program, one copy may use a different offset or quietly change the original data. A named function gives the rule one place to live.

The name alone is not enough. The function needs a clear agreement about its inputs, output shape, units, and treatment of invalid data. We will build that agreement as part of the code.

Choose an example, then change a value. Follow the calculation below to see which result changes and why. These are small teaching examples; the construction later asks you to choose the operations yourself.

[12,[0,6]]

def introduces a function. Its parameters name the inputs inside the function; the indented body describes the work. Defining it does not yet perform the calculation. A call supplies actual arguments. return sends a result back to the caller.

Printing and returning are different: print displays something; return makes the result available to the next calculation. A function that only prints cannot be used as a numerical result in the same way.

import numpy as np

def to_fahrenheit(celsius):
    values = np.asarray(celsius, dtype=float)
    return values * 1.8 + 32

first = to_fahrenheit([12,18,24])
reference = to_fahrenheit([0,100])
print(np.round(first,1).tolist())
print(reference.tolist())

[53.6, 64.4, 75.2]
[32.0, 212.0]

Suppose the function promises one nonempty vector of finite readings. A matrix, an empty vector, or a NaN should produce a useful error. Check these conditions before performing the calculation.

A raise statement stops the function with an exception. ValueError is appropriate when an argument's value or arrangement is unsuitable. A caller can catch a particular exception with try and except when it has a meaningful response.

import numpy as np

def checked_readings(values):
    array = np.asarray(values, dtype=float)
    if array.ndim != 1:
        raise ValueError("Supply one vector of readings.")
    if array.size == 0:
        raise ValueError("Supply at least one reading.")
    if not np.isfinite(array).all():
        raise ValueError("Every reading must be finite.")
    return array

print(checked_readings([0,18]).tolist())
try:
    checked_readings([[12,18]])
except ValueError as error:
    print(str(error))

[0.0, 18.0]
Supply one vector of readings.

Some calculations first learn a reference, then apply it elsewhere. If Botie centres each new report on its own average, comparisons no longer share the same reference. Learn from the training readings once and pass that value to the next operation.

A function can return more than one result in a tuple. The caller can unpack that tuple into names that keep their meanings distinct.

import numpy as np

def centre_from_training(training, report):
    training = np.asarray(training, dtype=float)
    report = np.asarray(report, dtype=float)
    reference = training.mean()
    return reference, report - reference

reference, centred = centre_from_training([10,14], [12,18])
print(reference)
print(centred.tolist())

12.0
[0.0, 6.0]

A check should describe what the function must do, not merely repeat the same implementation. Use reference cases with independently known answers, then include a changed input and a boundary case. Check shapes and whether the input was preserved.

A loop is useful here because we want to run a collection of separate test cases. It is not the numerical operation we are trying to vectorise.

import numpy as np

def to_fahrenheit(celsius):
    return np.asarray(celsius, dtype=float) * 1.8 + 32

cases = [([0,100],[32,212]), ([-40],[-40])]
for values, expected in cases:
    original = np.array(values, dtype=float)
    saved = original.copy()
    result = to_fahrenheit(original)
    assert result.shape == original.shape
    np.testing.assert_allclose(result, expected, rtol=0, atol=1e-10)
    assert np.array_equal(original, saved)
print("2 cases passed; inputs preserved.")

2 cases passed; inputs preserved.