Processing Tuple-Based Iterables With starmap()

00:00 In this lesson, we’re going to jump right into the code and talk about the starmap() function, which, as you’ll see, is very similar to the map() function.

00:10 Let me show you a motivating example to illustrate when you would want to use the starmap() function. Let’s suppose that you have some function called max_abs() and it’s going to take an x- and a y-coordinate, and it’s simply going to return the maximum of the absolute value of x and the absolute value of y. In other words, it’s just going to return the maximum magnitude of the x and y values. Now, maybe you’re working with points and these points come to you specified in an x- and a y-coordinates list. So here’s the list of x-coordinates,

00:49 and that’s a list of y-coordinates. The idea is that you’re working with a set of points in the 2D plane, and those points are specified by a list of x- and y-coordinates, so each first element of those two lists specifies one point and then the second elements of the two lists specify a second point, and so on.

01:10 And so if you wanted to know what the maximum magnitude is between the points specified by these lists, you would simply call the map() function with the max_abs() function that we’ve defined, using the iterables as the x-coordinates and the y-coordinates. Let’s save the return value of map() as the variable b and then let’s just see this as a list, just so that we can see that all is working well. So yeah, for that point specified by coordinates 1.3 and -4.2 the maximum magnitude of those two coordinates is 4.2.

01:48 And for this second point with x-coordinate -2.7 and y- 9.8, the maximum magnitude is 9.8. So, nothing new here. This is, of course, a good application if you’ve got points that come to you with x- and y-coordinates separately, then you would go ahead and just, say, use the map() function if you wanted to find the maximum magnitudes.

02:12 All right, so here are those x-coordinates again and here are the y-coordinates. But what if the points that you were working with already came to you or already were constructed as a list containing tuples, and each tuple containing the x- and y-coordinates? So in other words, if these lists, x-coordinates and y-coordinates, if they were pre-zipped to create this list of tuples.

02:42 So if we try to use the map() function with the max_abs() function as the first positional argument, we’re going to get an error.

02:49 If we try to call map() with max_abs and the iterable only being the points list, if we try to create a list out of this so that the iterator starts yielding values, let’s see what’s going to happen.

03:04 We’re going to get an error because max_abs() is missing one required positional argument. Each of these tuples in the points list is considered one argument being passed into max_abs() and max_abs() takes an x and a y.

03:18 Well, we can fix this of course. Let me clear this up. We could create a new function, and maybe we’ll call it star_max_abs(), and it’s going to take a point—a tuple—consisting of an x- and a y-coordinate.

03:35 And all it will do is return the value of max_abs() by unpacking the tuple p so that max_abs() receives an x and a y value. Or in other words, p is going to be containing a tuple consisting of an x and a y, and the star operator, or the unpacking operator (*), is going to unpack the tuple and feed it in two positional arguments into max_abs().

04:02 So now let’s try running what we had before, except now with the star_max_abs() function and passing in the points list. And let’s create the list all in one go. And run that, and then this works just like we had before.

04:21 So, the starmap() function is essentially there to save you this step of creating this extra function that will unpack the tuples or the elements in the points iterable. So, let me clear that up and let’s import the starmap() function. It’s contained in the itertools module, so from the itertools module, let’s import the starmap() function.

04:47 The starmap() function takes on two positional arguments. It’s going to be a function, and that is the function that we want to map, and we want to map the function at every element returned by the iterable.

05:00 And again, the idea is that the function is going to take in, say, N positional arguments and each of the elements that are yielded by the iterable is going to be itself an iterable that unpacks to N arguments that can be fed into the function.

05:17 So, let me show you how that’s going to work with the example that we’re working with. Again, remember, we’ve got this max_abs() function. It takes on two positional arguments.

05:29 We’ve got our points list, which contains the x- and the y-coordinates all packed in, or zipped, as (x, y) tuples.

05:39 And so we can directly call the starmap() function using the max_abs() function, and the iterable is points. If we go ahead and create this list just to see that we get the exact same thing as before, all right, we see that we do indeed get the 4.2, 9.8, and so on.

06:01 So, the starmap() function is there for when you have a function—in this case, it was max_abs() for us—that takes on an N number of positional arguments and you want to map that function at every element of a list or some iterable where each element of the iterable is itself an iterable that yields the same number of values expected by the function that you want to use map() with. All right, so this is a nice way to save yourself from either having to write your own unpacking function. starmap() will do that for you.

06:39 All right, so this ends this quick lesson on the starmap() function. Again, very similar to the map() function. The main application is when you want to map a function at every element of an iterable and the elements of the iterable are already zipped up and written as either a tuple or a list or any other type of iterable, and those are the values that you’re passing in to the function that you’re mapping. All right! In the next lesson, we’ll take a quick look at how you can replace some of these functional programming tools like the map() function and the filter() and reduce() function by using some of the built-in features of the Python language like list comprehensions and generator expressions.