Writing functions#

Materials#

As humans, we can only keep a few items in our own working memory at a time. Trying to comprehend a Python script with hundreds of lines of code can be quite daunting.

Thankfully, we can make this easier by breaking programs down into functions to make them easier to understand. We have used built-in functions, like print() in the past, but we can also write our own custom functions.

Custom functions help us understand larger/more complicated ideas by encapsulating separate parts of our program, allowing us to view each as a single “thing”. Importantly, it also lets us re-use pieces of code without having to duplicate dozens of lines of code over and over again.

Objectives#

Define a function using def with a name, parameters, and a block of code.

Python

# Import libraries
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

Default values#

For the parameters we have defined, we can also provide default values.

Python

def happy_birthday(name='Fred'):
   print('Happy Birthday,', name)

happy_birthday('Sarah')
happy_birthday()

Output

Happy Birthday, Sarah
Happy Birthday, Fred

When defining a function, we can use a combination of parameters with and without default values. However, parameters with default values must go after those without them.

Python

def quadratic_equation(a, b, c, negative=False):
   sqr_rt = (b**2 - 4*a*c)**(1/2)

   if negative:
      x = (-b - sqr_rt) / (2*a)

   else:
      x = (-b + sqr_rt) / (2*a)

   return x

quadratic_equation(1, 7, 10)

Output

-2.0

Question 3: Calling functions before defining#

Does order of operations matter for defining and calling functions?

Python

fahr_to_celsius(32)

def fahr_to_celsius(temp):
   return ((temp - 32) * (5/9))

Solution

It does matter! Because the function is called before it is defined, we will get an error here. Functions must be defined before they are called:

Python

def fahr_to_celsius(temp):
   return ((temp - 32) * (5/9))

print('freezing point of water:', fahr_to_celsius(32), 'C')
print('boiling point of water:', fahr_to_celsius(212), 'C')

Output

freezing point of water: 0.0 C
boiling point of water: 100.0 C

Composing Functions#

Now that we’ve seen how to turn Fahrenheit into Celsius, we can also write the function to turn Celsius into Kelvin:

Python

def celsius_to_kelvin(temp_c):
   return temp_c + 273.15

print('freezing point of water in Kelvin:', celsius_to_kelvin(0.))

Output

freezing point of water in Kelvin: 273.15

What about converting Fahrenheit to Kelvin? We could write out the formula, but we don’t need to. Instead, we can compose the two functions we have already created:

Python

def fahr_to_kelvin(temp_f):
   temp_c = fahr_to_celsius(temp_f)
   temp_k = celsius_to_kelvin(temp_c)
   return temp_k

print('boiling point of water in Kelvin:', fahr_to_kelvin(212.0))

Output

boiling point of water in Kelvin: 373.15

This is our first taste of how larger programs are built: we define basic operations, then combine them in ever-larger chunks to get the effect we want. Real-life functions will usually be larger than the ones shown here — typically half a dozen to a few dozen lines — but they shouldn’t ever be much longer than that, or the next person who reads it won’t be able to understand what’s going on.

Add documentation to your functions#

If the first thing in a function is a string that isn’t assigned to a variable, that string is attached to the function as its documentation. This is called a docstring and is in triple quotes.

It can be helpful to describe each argument, including the intended data type.

Note: You can also use triple quotes elsewhere in code as generic multi-line comments.

Python

def offset_mean(data, target_mean_value):
   """
   Return a new array containing the original data
   with its mean offset to match the desired value.
   ------------------------------------------------
   data (numpy.array) - n x m dimensional array
   target_mean_value (float) - desired mean value
   """
   return (data - np.mean(data)) + target_mean_value

Python

help(offset_mean)

Output

Help on function offset_mean in module __main__:

offset_mean(data, target_mean_value)
   Return a new array containing the original data
   with its mean offset to match the desired value.
   ------------------------------------------------
   data (numpy.array) - n x m dimensional array
   target_mean_value (float) - desired mean value

We can label each parameter with the desired data type, as well. Note that this will not enforce each data type, so you will need to build in checks to actually limit the data types of arguments.

Python

def my_func(x:int):
   print(x)

my_func('Not a number')

Output

Not a number

We can use conditionals to do these sorts of checks. If you don’t mind having errors thrown, you can use an assert statement, which allows you to make a quick boolean expression check with custom error message. The general format is assert BOOLEAN_EXPRESSION, ERROR_MESSAGE.

Python

def better_func(x:int):
   assert isinstance(x, int), x + " is not int"
   print(x)

better_func('Not a number')

Output

---------------------------------------------------------------------------

AssertionError                            Traceback (most recent call last)

AssertionError: Not a number is not int

Question 5: Readable functions#

Which one of these functions is more readable - s() or std_dev()? Why?

Python

def s(p):
   a = 0
   for v in p:
      a += v
   m = a / len(p)
   d = 0
   for v in p:
      d += (v - m) * (v - m)
   return np.sqrt(d / (len(p) - 1))

def std_dev(sample):
   sample_sum = 0
   for value in sample:
      sample_sum += value

   sample_mean = sample_sum / len(sample)

   sum_squared_devs = 0
   for value in sample:
      sum_squared_devs += (value - sample_mean) * (value - sample_mean)

   return np.sqrt(sum_squared_devs / (len(sample) - 1))

Solution

std_dev() is better because the function name and variable names have meaning, making it easier to understand what is going on at a brief glance. s() would require extensive documentation to make sense to an outside party (or your future self!).

Resources#

This lesson is developed from the following resources:

Writing functions#

Materials#

Objectives#

Function syntax#

Question 1: Function syntax#

Question 2: Calling functions#

Default values#

Question 3: Calling functions before defining#

Composing Functions#

Functions for tidying up code#

Question 4: Code duplication#

Add documentation to your functions#

Question 5: Readable functions#

Resources#