keyword_arguments.Rmd

---
jupyter:
  jupytext:
    text_representation:
      extension: .Rmd
      format_name: rmarkdown
      format_version: '1.2'
      jupytext_version: 1.11.5
---

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

## Keyword arguments

```{python}
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:

```{python}
np.sum([[0, 1, 2], [3, 4, 5]], 0)
```

```{python}
np.sum([[0, 1, 2], [3, 4, 5]], axis=0)
```

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:

```{python}
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`:

```{python}
func1('one', 'two')
```

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

```{python}
func1(arg1='first', 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:

```{python}
func1(arg2='dos', arg1='uno')
```

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:

```{python}
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:

```{python}
func2('first', 'second')
```

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:

```{python}
func2('first', 'second', key_arg1=99)
```

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

```{python}
func2('first', 'second', 100)
```

```{python}
func2('first', 'second', 100, '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:

```{python}
func2('first', 'second', 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](http://en.wikipedia.org/wiki/Linear_interpolation) for resampling. The default
that we are overriding is `order=3`. `order=3` gives a higher quality but
slower [cubic spline interpolation](https://en.wikipedia.org/wiki/Spline_interpolation).  Check the doc

<!-- vim:ft=rst -->
<!-- Course -->
<!-- BIC -->
<!-- Python distributions -->
<!-- Version control -->
<!-- Editors -->
<!-- Python and common libraries -->
<!-- IPython -->
<!-- Virtualenv and helpers -->
<!-- Pypi and packaging -->
<!-- Mac development -->
<!-- Windows development -->
<!-- Nipy and friends -->
<!-- FMRI datasets -->
<!-- Languages -->
<!-- Imaging software -->
<!-- Installation -->
<!-- Tutorials -->
<!-- MB tutorials -->
<!-- Ideas -->
<!-- Psych-214 -->
<!-- People -->
<!-- Licenses -->
<!-- Neuroimaging stuff -->
<!-- OpenFMRI projects -->
<!-- Unix -->
<!-- Substitutions -->