How to Use Numpy Argsort in Python

This tutorial explains how to use the Numpy argsort function. It explains the syntax of np.argsort, and also shows clear examples.

If you need help with something specific, you can click on any of these links. The links will take you to the appropriate part of the tutorial.

Table of Contents:

• Introduction to Numpy Argsort
• Syntax
• Examples

Having said that, Numpy argsort is somewhat unintuitive and difficult to understand. You’ll probably gain a much better understanding if you read the whole tutorial.

With that in mind, let’s get started.

A quick introduction to Numpy Argsort

Let’s begin with a quick introduction to the argsort function.

The argsort function is often confusing to Numpy users. I think that the best way to understand what it does, is to look at a clear example.

Numpy argsort returns the indexes of the input in the order that would sort the array.

Notice in this visual example how the output values correspond to the indexes of the input values:

• 10 is the smallest value in the input array, which corresponds to the index 1.
• 20 is the next largest value in the input, which corresponds to the index 0.
• 30 is the next largest value in the input, which corresponds to the index 4.
• 40 is the next largest value in the input, which corresponds to the index 2.
• 50 is the largest value in the input, which corresponds to the index 3.

So the input is an array of numbers.

But the output will be a new array, which contains the index of the input values, in the order that would sort those values.

So it operates in a way that’s similar to the Numpy sort function, but instead of returning the sorted values, it returns the indexes.

To help you understand, it will probably help to look at some working examples in Python. But first, let’s quickly look at the syntax.

The syntax of np.argsort

Now, let’s take a look at the syntax of np.argsort.

A quick note

One quick note before we look at the syntax.

The syntax explanation here and the examples below all assume that you’ve imported Numpy with the alias ‘np‘.

You can do that with this code:

import numpy as np

It’s important to point this out (just in case you’re not familiar) because how exactly you import Numpy will affect the exact syntax.

Importing Numpy this way is the common convention among Python data scientists, and we’ll be using it going forward.

np.argsort syntax

The syntax of np.argsort is simple.

You call the function as np.argsort().

Inside the parenthesis, you have several parameters that you can use to control how the function works.

Let’s look at the parameters.

The parameters of np.argsort

The np.argsort function has a few parameters:

• a
• axis
• kind

There’s also a 4th parameter called order. The order parameter is somewhat rarely used. It’s also a little more complicated to understand, so I am leaving it out of this tutorial.

Let’s look at the 3 parameters above in more detail.

a (required)

The a parameter enables you to specify the input array that you want to operate on.

So if you want to operate on an array called myarray, you can call the function as np.argsort(a = myarray).

Keep in mind that this parameter is required, so you need to provide an argument to this parameter.

Having said that, you don’t need to explicitly use the parameter name itself. Instead, you can pass in an argument by position. For example: np.argsort(myarray). If you don’t explicitly use the a= parameter, then the argsort function assumes that the first argument to the function is the input array to be passed to the a parameter.

Additionally, the argsort function will accept my different data structures as inputs. Frequently, we’ll use a Numpy array as the input. But np.argsort will also accept Python lists and array-like objects.

axis (optional)

You can use the axis parameter to control the axis along which to use argsort.

Remember that Numpy arrays have axes. Axes are like directions that point along a Numpy array.

So if you use axis = 0, argsort will operate downward (for a 2D or higher-dimensional array).

If you use axis = 1, argsort will operate horizontally (again, for a 2D or higher-dimensional array).

The axis parameter is optional. If you don’t use it explicitly, it will default to axis = -1, which is the last axis of the array (e.g., axis 1 for a 2D array).

One side note: many people are confused by how axes work. I’ll show you examples of how to use this parameter in the examples section, but if you’re still confused, you should read our tutorial on Numpy axes.

kind (optional)

The kind parameter enables you to specify the sorting algorithm you want to use for the sorting operation.

To be clear: in computer science, there are several different algorithms that you can use to sort data.

In np.argsort, here are several different options for which sorting algorithm to use with the kind parameter:

• quicksort
• heapsort
• mergesort

These different sorting techniques have different strengths and weaknesses. For example, some sorting algorithms are faster than others; some sorting algorithms use more memory; and so on.

Having said that, most of the time, for most purposes, the default (quicksort) will be fine.

Examples of how to use Numpy Argsort

Ok. Now, let’s look at a few examples.

Examples:

• Use argsort on a 1-dimensional array
• Apply argsort to a 2-dimensional array
• Use argsort along axis 1
• Use argsort along axis 0

Run this code first

Before you run the examples, you’ll need to import Numpy.

You can do that with this code:

import numpy as np

Keep in mind that by using the above import syntax, we’ll be able to call our Numpy functions with the prefix np (which is the common convention).

EXAMPLE 1: Use argsort on a 1-dimensional array

Let’ start with a simple example.

Here, we’re going to use argsort on a 1-dimensional Numpy array.

First, let’s create the array with the np.array function:

array_1d = np.array([ 20, 10, 40, 50, 30])

Now, let’s apply the Numpy argmax function:

np.argsort(a = array_1d)

OUT:

array([1, 0, 4, 2, 3])

Explanation

Look at the output. The output has the values [1, 0, 4, 2, 3].

Those values are the index values if the array were sorted.

In the input array, the value 10 is the smallest value. The value 10 in the input array is at index position 1. Since 10 would be the first value if we sorted the array, it’s corresponding index, 1, is the first item in the output array.

The value 20 is the second smallest value in the input array. This value is at index position 0 in the input array. So 0 is the second value in the output.

… and so on.

So the output simply provides the index positions of the input values, if the input array were sorted.

EXAMPLE 2: Apply argsort to a 2-dimensional array

Next, let’s look at how Numpy argsort operates on a 2-dimensional array.

First, we’ll create a 2D array, using the Numpy array function:

array_2d = np.array([[100, 7, 555], [22, 333, 9]])

Notice that we have some large values and some small values. The values are not sorted in any way.

Now, we’ll apply np.argsort:

np.argsort(array_2d)

OUT:

array([[1, 0, 2],
       [2, 0, 1]])

Explanation

What’s going on here?

This output has the indexes of the sorted rows.

But why?

By default, Numpy argsort sorts the indexes in the direction of axis = -1. It operates by default along the last axis.

This is a 2-dimensional array, so the last axis is actually axis-1, which is the axis that points horizontally:

So when we use Numpy argsort on a 2D array, it operates horizontally along the rows.

And therefore, the output contains the index values of the sorted rows.

EXAMPLE 3: Use argsort along axis 1

Let’s now use the axis parameter explicitly.

Here, we’ll set axis = 1.

Keep in mind that the code in example 2 actually operated on axis-1 by default, so the output will be the same. We’ll just make it explicit this time.

In this example, we’re going to re-use the array that we created in example 2, but if you didn’t run that code already, here’s the code to create the array:

array_2d = np.array([[100, 7, 555], [22, 333, 9]])

So now that we have our 2D array, let’s apply np.argsort with axis = 1:

np.argsort(array_2d, axis = 1)

OUT:

array([[1, 0, 2],
       [2, 0, 1]])

Explanation

If you already read example 2, this should make sense, but let me break it down.

Here, we’re operating explicitly on axis-1.

Remember, for a 2D array, axis-1 is the axis that points horizontally.

So using np.argsort() with axis = 1 causes the function to operate horizontally along the rows.

The output is the row-wise index, if the input array were sorted along axis-1.

EXAMPLE 4: Use argsort along axis 0

Let’s do one more example.

Here, we’ll use Numpy argsort in the axis-0 direction.

Let’s first create our array (this is the same array as the previous two examples):

array_2d = np.array([[100, 7, 555], [22, 333, 9]])

And now, let’s apply argsort:

np.argsort(array_2d, axis = 0)

OUT:

array([[1, 0, 1],
       [0, 1, 0]])

Explanation

This might still be confusing, so let me explain.

When we use argsort with axis = 0, we’re telling argsort to operate in the axis-0 direction.

Remember: for a 2D array, axis-0 points downwards.

So when we use np.argsort() with axis = 0, we’re telling the function to operate vertically down the columns.

Therefore, the output is the column-wise index, if the input array were sorted along axis-0.

If you’re still confused, read more about indexes, axes, and sorting

I’ve done my best to explain Numpy argsort.

Having said that, I realize that it’s often confusing. It’s relatively abstract, in the sense that it simumltaniously requires you to think about sorting, and Python indexes. Throw in axes, and many people feel lost.

If you’re still struggling after reading this post, you might want to go back and brush up on some of the foundations.

You can learn more about axes in our introduction to Numpy axes.

And you can learn more about sorting arrays in our tutorial on Numpy sort.

Leave Your Questions in the Comments Section

Do you still have questions about Numpy argsort?

Is there something specific that confuses you?

Is there something I’ve missed?

If so, just leave your questions in the comments section near the bottom of the page.

Join our course to learn more about Numpy

In this tutorial, I’ve shown you how to use Numpy argsort.

Numpy argsort is useful if you need to sort an array, but there are a lot more Numpy functions that you’ll need to learn, if you want to be really good at working with Numpy arrays.

So if you’re serious about learning Numpy, you should consider joining our premium course called Numpy Mastery.

Numpy Mastery will teach you everything you need to know about Numpy, including:

• How to create Numpy arrays
• How to Numpy axes work
• What the “Numpy random seed” function does
• How to use the Numpy random functions
• How to reshape, split, and combine your Numpy arrays
• Applying mathematical operations on Numpy arrays
• and more …

The course will also show you our unique practice system. This practice system will enable you to memorize all of the Numpy syntax that you learn.

If you’re struggled to remember Numpy syntax, this is the course you’ve been looking for.

If you practice like we show you, you’ll memorize all of the critical Numpy syntax in only a few weeks.

Find out more here: