\(\newcommand{L}[1]{\| #1 \|}\newcommand{VL}[1]{\L{ \vec{#1} }}\newcommand{R}[1]{\operatorname{Re}\,(#1)}\newcommand{I}[1]{\operatorname{Im}\, (#1)}\)

Keyword arguments

>>> import numpy as np

We have seen keyword arguments in action before, but we have not gone into detail about what they are.

A keyword argument is where you pass an argument value to a function along with its name, as in argname=value.

This has the big advantage that it can be a lot easier to see what the arguments mean, assuming they have a good name associated with them.

For example, compare these two calls:

>>> np.sum([[0, 1, 2], [3, 4, 5]], 0)
array([3, 5, 7])

>>> np.sum([[0, 1, 2], [3, 4, 5]], axis=0)
array([3, 5, 7])

The second form is more clear, because you can see immediately what the 0 means. For the first form, you would have to know that the second argument is the axis.

The names for the arguments correspond to the names of the arguments in the function definition, like this:

>>> def func1(arg1, arg2):
...     print('Value of arg1', arg1)
...     print('Value of arg2', arg2)

Here I can pass in the arguments by position (the first value goes into arg1, the second into arg2:

>>> func1('one', 'two')
Value of arg1 one
Value of arg2 two

I can also pass the arguments in by name, as long as I always specify both arguments:

>>> func1(arg1='first', arg2='second')
Value of arg1 first
Value of arg2 second

Now I have specified the names, they don’t any longer need to be passed in the order they are defined in the function, because the name makes it clear which value is which:

>>> func1(arg2='dos', arg1='uno')
Value of arg1 uno
Value of arg2 dos

This starts to be useful when I define default values for arguments that are optional. In this case, if I do not pass in a value for the optional arguments, they get their default values, defined in the function signature:

>>> def func2(arg1, arg2, key_arg1=10, key_arg2='my-name'):
...     print('Value of arg1', arg1)
...     print('Value of arg2', arg2)
...     print('Value of key_arg1', key_arg1)
...     print('Value of key_arg2', key_arg2)

Now I don’t need to pass anything for key_arg1 or key_arg2 - and if I don’t - they get their default values:

>>> func2('first', 'second')
Value of arg1 first
Value of arg2 second
Value of key_arg1 10
Value of key_arg2 my-name

The keyword arguments (key_arg1, key_arg2) get their values from the default in the function signature, unless you override them by giving them another value. Here I give the value by name:

>>> func2('first', 'second', key_arg1=99)
Value of arg1 first
Value of arg2 second
Value of key_arg1 99
Value of key_arg2 my-name

I can also pass in an argument to the keyword argument by position. Remember that key_arg1 is third in the argument list:

>>> func2('first', 'second', 100)
Value of arg1 first
Value of arg2 second
Value of key_arg1 100
Value of key_arg2 my-name

>>> func2('first', 'second', 100, 'another-name')
Value of arg1 first
Value of arg2 second
Value of key_arg1 100
Value of key_arg2 another-name

One very nice feature of keyword arguments is that I can have a long list of keyword arguments, each with their own default, and I only need to pass in the keyword argument values I want to change:

>>> func2('first', 'second', key_arg2='yet-another-name')
Value of arg1 first
Value of arg2 second
Value of key_arg1 10
Value of key_arg2 yet-another-name

Notice that key_arg1 still got its default value.

Many functions in numpy and scipy use arguments with defaults as a way of specifying values that you often need to change, but have sensible defaults.

For example, in Resampling with scipy.ndimage, we use order=1 in our calls to scipy.ndimage.affine_transform. This tells affine_transform to use simple (and quick) linear interpolation for resampling. The default that we are overriding is order=3. order=3 gives a higher quality but slower cubic spline interpolation. Check the doc