Numpy Ravel, Explained

This article is originally published at https://www.sharpsightlabs.com

This tutorial will show you how to use the Numpy ravel function. It will explain the syntax of the function and show you how to use Numpy ravel to flatten an array.

The following is a table of contents. If you’re looking for something specific, you can click on any of the links to jump to the appropriate section.

Table of Contents:

• What Numpy Ravel Does
• The Syntax of Numpy Ravel
• Examples
• FAQ

Having said that, if you’re new to Numpy, I recommend reading the whole tutorial.

A Quick Introduction to Numpy Ravel

Let’s start by quickly going over what the Numpy ravel function does.

Numpy ravel flattens out a Numpy array or similar Python object.

To be clear: this is very similar to the Numpy flatten method, which also flattens out Numpy arrays.

To understand what I mean by “flatten” a Numpy array, let’s quickly review Numpy array shapes.

A Quick Review of Numpy Arrays and Array “Shapes”

You’ll probably recall that a Numpy array is a special structure in Python that holds numeric data in a row-and-column format.

Numpy Arrays Can Have Different “Shapes”

Numpy arrays can exist in a 1-dimensional, 2-dimensional, or multi-dimensional forms. They’re somewhat like vectors and tensors in mathematics.

Here’s an example of a 1D array.

And here’s an example of a 2D array.

You’ll notice that the values in both of these arrays are the same, but the “shape” is different.

In one array, the values are all arranged in a single “row.” (Although, a 1D array is a special case, and this is not exactly a row in a technical sense.)

And in the other array, the values are arranged into a structure with 2 rows and 3 columns.

Why Array Shape Matters

The shape of an array is important, because different operations in Numpy and Python require Numpy arrays to be in a specific shape.

For example, when we do machine learning with Scikit Learn, most of the input arrays need to be in a 2 dimensional shape.

However, in other cases, we sometimes need to “flatten” an array out into a 1-dimensional shape.

This often happens in more advanced data manipulation, where we need to first flatten an array, and then process it further in some way.

Ultimately, you need tools for reshaping and flattening arrays, and that’s where Numpy ravel comes in.

With all that said, let’s look at the syntax of Numpy ravel.

The Syntax of Numpy Ravel

Here, we’ll look at the syntax of the Numpy ravel function.

I’ll explain the high-level syntax, and also explain a few important parameters in detail.

A quick note about importing Numpy

Just a quick reminder about using Numpy.

Whenever we use Numpy in Python, we first need to import Numpy into our environment.

The common convention is to import Numpy with the alias “np,” using this code:

import numpy as np

All of the syntax and code that you see in this tutorial going forward will assume that you’ve imported Numpy this way.

Numpy Ravel Syntax

The syntax of the Numpy ravel function is fairly simple.

You call the function as np.ravel().

Inside the parenthesis, you must provide an array-like object or the name of an array-like object that you want to operate on.

There is also an optional parameter, the order parameter, that we’ll discuss later in this post.

So let’s assume that you have a 2D Numpy array called my_array.

To flatten this array, you can type np.ravel(my_array), which will produce a 1D array with the same elements.

We’ll look at this example (and a few other examples) in more detail in the examples section.

The parameters of Numpy ravel

The ravel function only has one parameter: the order parameter.

Let’s quickly take a look at it.

order (optional)

The order parameter allows you to specify the order in which the values will occur in the flattened output array.

Said differently, it controls how the function restructures the values into a 1D shape.

The two possible arguments to this paramter are:

• order = 'C'
• order = 'F'

This parameter is optional, so if you don’t use it, it will automatically default to order = 'C'.

Let’s take a look at both of the settings to this parameter.

order = ‘C’

If you set order = 'C', then the ravel function will flatten the elements out in row first order.

As a side note, this is called ‘C‘ order, because this is how data are stored and retrieved in the C programming language.

Remember: this is the default behavior of Numpy ravel, so if you decide not to use the parameter explicitly, the function will automatically flatten your array in row-first order.

order = ‘F’

If you set this parameter to order = 'F', the ravel function will flatten the elements out in column-first order.

This is called the ‘F‘ order, because this is how the Fortran programming language stores and retrieves data.

The output of Numpy Ravel

The Numpy Ravel function returns a 1-dimensional, flattened array that has the same elements as the input (ordered according to the order parameter, as explained above).

Importantly, the ravel function returns a view onto the original input array. This is a subtle, technical point, which I will explain in example 5.

Examples of how to use Numpy Ravel

Now that we’ve examined the syntax of Numpy ravel, let’s look at a few examples.

Examples:

• Use Numpy ravel to flatten a 2D array
• Flatten an array by row
• Flatten an array by column
• Flatten a Python list
• Change a flattened array, by changing the input array

Run this code first to import Numpy

Before we run these examples, let’s first import Numpy.

To import Numpy, you need to run this code:

import numpy as np

As explained earlier, this gives us access to the functions in the Numpy namespace, and allows us to call them with the prefix ‘np‘ (as is the common convention among Numpy users).

Run this code to create a 2D array

Now, we’re going to create a 2-dimensional Numpy array that we can use in our examples.

Here, we’ll call the Numpy Arrange function, which will create an array with 6 values. But we’ll also use the Numpy reshape method to reshape it into 2 dimensions, with 2 rows and 3 columns.

my_array = np.arange(start = 1, stop = 7).reshape([2,3])

Now, let’s print it out to see the contents:

print(my_array)

OUT:

[[1 2 3]
 [4 5 6]]

As you can see, this is a 2-dimensional array with 2 rows and 3 columns that contains the values 1 to 6.

EXAMPLE 1: Use Numpy Ravel to flatten a 2D array

Let’s start with a simple example.

Here, we’ll use Numpy ravel to flatten our 2D array, my_array.

np.ravel(my_array)

OUT:

array([1, 2, 3, 4, 5, 6])

Explanation

As you can see, the output here is a 1-dimensional array that contains the same values as the input array.

Ravel simply “flattened” the elements of the 2D input into a 1D output.

Remember that because we didn’t explicitly use the order parameter, ravel used the ‘C‘ order by default, with is row-first order.

EXAMPLE 2: Flatten an array by row

Next, we’ll use the “order” parameter to specify an order of the elements of the flattened array.

In this example, we’re going to explicitly flatten the input in row-first order. To do this, we will set order = 'C'. (As I explained in the syntax section above, setting order = 'C', flattens the array in row-first order).

Let’s take a look.

np.ravel(my_array, order = 'C')

OUT:

array([1, 2, 3, 4, 5, 6])

Explanation

In this example, we set order = 'C', which flattens the input in row-first order.

So the output is a 1-dimensional array that has the same elements as the input, ordered in row-first order.

(Note: the output in this example is the same as the output for example 1. That’s because when we don’t explicitly use the order parameter, Numpy ravel defaults to order = 'C'.)

EXAMPLE 3: Flatten an array by column

Now, let’s flatten the array with order = 'F'.

This will flatten the elements in column-first order.

np.ravel(my_array, order = 'F')

OUT:

array([1, 4, 2, 5, 3, 6])

Explanation

Here, we set order = 'F'. By doing this, we’ve told Numpy ravel to flatten the elements of the input in column-first order.

Notice that in this example, the elements in the output array are arranged differently than the output in example 2.

In example 2, the elements were arranged row-first order.

But here, because we set order = 'F', the elements have been arranged in column-first order.

EXAMPLE 4: Use Numpy Ravel to flatten a list

Next, instead of operating on a Numpy array, we’re going to operate on a Python list.

Let’s quickly create a Python list:

my_list = [[1,2,3],[4,5,6]]

And now, let’s flatten it with Numpy ravel:

np.ravel(my_list)

OUT:

array([1, 2, 3, 4, 5, 6])

Explanation

This is actually very similar to example 1. We’re just using Numpy ravel to flatten a Python object.

But instead of flatting a Numpy array, we’re flattening a Python list.

Still, as you can see, the output is a 1-dimensional list that contains the same values as the input list.

I wanted to show this to you so that you understand: Numpy ravel can operate on Numpy arrays, but also array-like objects such as Python lists and tuples. (This is in contrast to the Numpy flatten method, which only operates on Numpy arrays.)

EXAMPLE 5: Change a flattened array, by changing the input array (i.e., show that ravel produces a view of the original array)

Finally, let’s do one more example.

This is going to show a very subtle property of Numpy ravel and the output that it produces.

Specifically, I’m going to show you that Numpy ravel produces a view of the original array.

Create array

First, let’s just create an array. We’ll call this new_array.

new_array = np.arange(start = 1, stop = 7).reshape([2,3])

Flatten array

Next, we’ll flatten it with Numpy ravel, and save the output with the name unravelled.

unravelled = np.ravel(new_array)

Change original array

Now, we’re going to change the original array:

new_array[0,0] = 999

And let’s print it out so we can see the new contents of the array:

print(new_array)

OUT:

[[999   2   3]
 [  4   5   6]]

Notice that the first value has been changed to 999.

Check flattened array

Finally, let’s check the flattened array that we created from the 2D input:

print(unravelled)

OUT:

[999   2   3   4   5   6]

Holy sh*#.

The first value of unravelled is also changed!

Explanation

Let’s recap what happened:

• We created a 2D Numpy array
• We used Numpy ravel to flatten the 2D array to a 1D array, and we stored the new output with a new name
• We then changed the original input array
• This also changed the flattened output array

The question is, why was the flattened array also changed?

The reason is that the output of Numpy ravel is not exactly a new object.

It is a view of the original object, instead of a copy and restructure of the original object.

Read this from the Numpy manual:

When operating on NumPy arrays, it is possible to access the internal data buffer directly using a view without copying data around. This ensures good performance but can also cause unwanted problems if the user is not aware of how this works. Hence, it is important to know the difference between these two terms and to know which operations return copies and which return views.

This is somewhat technical, but a view “creates a new way of looking at the data” while keeping the same data buffer.

Again, this is a technical point, but the important thing to know is: if you change the data in the original object, it will also change the values in any of the outputs created by Numpy ravel. This can cause problems if you’re unaware of what’s going on.

Frequently asked questions about Numpy Ravel

Now that you’ve learned about Numpy ravel and seen some examples, let’s review some frequently asked questions about the technique.

Frequently asked questions:

• What’s the difference between Numpy Ravel and Numpy Flatten
• Why do the values of my flattened array change if I change the values in the original?

Question 1: What’s the difference between Numpy Ravel and Numpy Flatten

Put simply: Numpy ravel is a function, but Numpy flatten is a method.

Let’s quickly build a Numpy array and I’ll show you how to use them both:

my_array = np.arange(start = 1, stop = 7).reshape([2,3])

Now that we have an example array, we can use the flatten method:

my_array.flatten()

OUT:

array([1, 2, 3, 4, 5, 6])

Or we can use the ravel function:

np.ravel(my_array)

OUT:

array([1, 2, 3, 4, 5, 6])

And they effectively work the same way.

One subtle complication to this, however, is that Numpy flatten produces a true copy, whereas Numpy ravel produces a view. I explain what a view is in example 5.

Question 2: Why do the values of my flattened array keep changing?

If you used Numpy ravel to flatten an array, and you stored that output with a new name, then you need to understand that the output of Numpy ravel is a view instead of a strict copy.

What this means is that changing the values of the original input array will also change the values of the flattened output array.

I show this behavior in example 5.

Leave your questions in the comments below

Do you still have questions about the Numpy ravel function?

Leave your questions in the comments section below.

Join our course to learn more about Numpy

The examples you’ve seen in this tutorial should be enough to get you started, but if you’re serious about learning Numpy, you should enroll in our premium course called Numpy Mastery.

There’s a lot more to learn about Numpy, and Numpy Mastery will teach you everything, including:

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

Moreover, it will help you completely master the syntax within a few weeks. You’ll discover how to become “fluent” in writing Numpy code.

Find out more here:

Learn More About Numpy Mastery

Thanks for visiting r-craft.org
This article is originally published at https://www.sharpsightlabs.com
Please visit source website for post related comments.