NumPy supports different ways of generating arrays, and this tutorial is going to explore one way of do so, using the np.linspace() function. It returns evenly-spaced numbers and can generate arrays of any dimensionality.
The following sections are covered in the tutorial:
- What is np.linspace()?
- Function Arguments (start, stop, num)
- Create 1D Arrays
- Possible Values for the num Argument
- Use case: Plot Sine Wave using Matplotlib
- Inclusive Range using endpoint Argument
- Return Step using retstep Argument
- Return Data Type using dtype Argument
- Incremental and Decremental Ranges
- Create 2D Arrays
- Multiple Starts Multiple Stops
- Single Start Multiple Stops
- axis Argument
- Create Arrays with More than 2 Dimensions
What is np.linspace()?
linspace() is a function that is not only available in NumPy but also available in other tools such as MATLAB. By searching about it, you can find the regular answer which defines linspace() as a function to generate evenly spaced numbers.
The word linspace can be split into 2 parts—lin and space. The first part is lin which means linear that is it generates numbers represented as a line. To be clear, it is more than returning just a line [which has one dimension] and it can return an array with multiple dimensions.
The second part of the word linspace is space which means there is a space between every 2 numbers generated by the np.linspace() function.
Function Arguments (start, stop, num)
The np.linspace() function accepts the 7 arguments listed below. Note that except for the first 2 arguments, all other arguments are optional.
- start: defines the starting point of the line
- stop: defines where the line stops
- num=50: This means 50 values are returned between the start and stop
A couple of notes here. The start and stop arguments both accept a single value that could be an integer or a float, which can be positive or negative. Additionally, num is optional and its default value is 50. By changing this value, we can return any number of values between the start and the stop.
The next section starts the practical side by creating 1D arrays by using just the first 3 arguments of np.linspace().
Create 1D Arrays
np.linspace() can be used to created arrays with 1, 2, or more dimensions. In this section, we are going to create 1D arrays. The next code provides an example.
The linspace() function is called, and only the start (set to 1) and stop (set to 50) arguments are passed. By default, the range of returned numbers is inclusive, which means the first element in the returned array is 11, and the last element is 60. This can be changed later to exclude the stop value from being included in the range using the endpoint argument.
The result of the print statement is as follows. Note that the first and last values in the array match the values passed to the start and stop arguments. Note that the function returned some values between 11 and 60. How do we control these values? By using the third argument, num.
The num argument specifies the number of values to be returned in the range from start to stop. Because it is an optional argument, then it has a default value of 50. So an array of 50 values is returned.
The first value is 11 and the last value is 60. How are the remaining 48 values generated? This is done using a fixed space or step between every 2 numbers. The step can be returned using the retstep argument. It’s clear that the step in our example is 1.0.
Possible Values for the num Argument
The num argument is expected to be received in np.linspace() as a positive integer. But what if a non-positive value is assigned? Let’s discuss the different scenarios for the values that could be fed to this argument and see what happens.
- Positive integer: expected, and thus the function behaves normally
- Positive floating-point number: the function can still work without an error, but NumPy converts this number into an integer using the int() function.
- A negative integer: In this case, a ValueError is returned. This means the value of the num argument must be positive.
- A negative floating-point number: In this case, a ValueError is also returned. Again, this means the value of the num argument must be positive.
The first scenario, which is expected, is receiving a positive integer, and thus the function behaves normally.
The second scenario is to pass a positive floating-point number. In this case, the function can still work without an error, but NumPy converts this number into an integer using the int() function.
When a positive floating-point number is passed to the num argument, then the function prints a warning message and converts the number into an integer.
The third scenario for the values passed to the num argument is negative integer. In this case, a ValueError is returned which means the value of the num argument must be positive.
Use case: Plot Sine Wave using Matplotlib
To plot a signal in Matplotlib, we need to specify the values of the x and y axes. Before thinking of plotting the wave, we must create such values. We are going to use np.linspace() to create the values of the x-axis. We do this by simply generating some numbers between the start and stop values. The more numbers generated, the more smoothness in the sine wave.
The array is returned in the arr_1D variable, and then the sine of all values within the array is calculated using the np.sin() function. Finally, a plot is created using Matplotlib that shows the sine wave.
Inclusive Range using endpoint Argument
The 1D arrays created previously included the values in both the start and stop arguments. You can optionally specify whether to include the stop value in the range or not using the boolean endpoint argument, which defaults to True. This means the stop value is included in the range. Here’s an example that returns 5 numbers from 1 to 5:
When the endpoint is set to False, then the stop value is not included. Here’s an example. Note that the function still returns 5 numbers as previously, but the last value is no longer 5 but 4.2.
Return Step using retstep Argument
The np.linspace() function has the word space in its name; however, it doesn’t accept an explicit argument defining the space between every 2 numbers. The space, or more meaningful step, is calculated indirectly using the num argument. Let’s discuss how the step is calculated for start 1, stop 5, num 7, and endpoint set to True, according to the next example.
According to the printed array, the step is approximately 0.67, but how is this calculated behind the scenes?
Inside the function implementation, the step is calculated according to the next line:
The delta variable is calculated according to this line. According to our example, in which start is 1 and stop is 5, the delta value is 5–1=4.
The div variable is calculated according to this line:
Based on the values of delta and div which are 4 and 6 respectively, the step is equal to 4/6 which is approximately 0.67.
If endpoint is set to False, then the div value is equal to num which is 7 and thus the step is 4/7 (approximately 0.57).
You don’t have to calculate the step manually, as the retstep argument in np.linspace() allows returning this step for you. The retstep argument is a boolean set to False by default (to not return the step). If it’s set to True, then the step will be returned besides the generated 1D array.
Return Data Type using the dtype Argument
The default value of the dtype argument in the function header is None, which means the type is inferred from the data type of the input arguments start, stop, and num.
The next example uses the previous code after setting the dtype to np.int32.
Incremental and Decremental Ranges
The range of numbers returned by np.linspace() can be either incremental or decremental. Incremental range means the start is less than the stop, and thus we increment the lower value until reaching the upper value. In this case, the step value is positive. Note that the values of the start and stop arguments can be positive or negative integers or floating-point numbers.
The next example sets the start value to 1.1 and the stop value to 5.1 to return an incremental range. The returned step is 0.57, which is positive, reflecting that the range is increasing.
With a little modification, we can convert this range to a decremental range. All we need to do is to make the stop value lower than the start value:
For decremental ranges, take care to use a data type that supports negative numbers. In the previous example, np.int32 is used, which supports both positive and negative numbers. If a data type such as np.uint32 is used, then no negatives will be found in the range, as it supports only unsigned integers. Note that it is possible to have both start and stop set to the same value.
In the next section, we’ll create 2D arrays. Later, we’ll add more dimensions to create arrays with 3D, 4D, and more.
Create 2D Arrays
You can think of the 1D array we created above as a 2D array in which the size of the first dimension is 5 but the size of the second dimension is just 1, and thus the array size is 5×1. In this section, we’ll increase the size of the second dimension.
For creating 2D array, then the key change is to feed multiple starts and stops. Each start-stop pair creates a new dimension in the array.
Multiple Starts, Multiple Stops
The following code assigns a list of 2 numbers to each of the start and stop arguments. Because start and stop are fed a list with 2 elements, then 2 1D arrays of numbers will be created.
The first 1D array, [1, 2, 3, 4, 5], starts from the first value in start argument and stops at the first value in the stop argument. The same works for the second 1D array.
Note that you do not have to specify a list to both start and stop arguments. One argument might be assigned a list, while the other is just assigned a single value. The next section discusses when a single value is assigned to the startargument.
Single Start, Multiple Stops
This subsection creates a 2D array by just specifying a single value to the start argument and a list to the stop argument. Here is an example in which all 1D arrays start from the same value but stops at different values.
Note that the shape of the returned 2D array is (5, 4), even though the start argument is assigned to a scalar value.
The previous section created a 2D array in which each 1D array constitutes a column in the 2D array. Using the axis argument, we can specify in which axis to store these 1D arrays. It’s 0 by default, which means the 1D arrays are added as columns to the 2D array. If the axis is set to 1, then the 1D arrays are added as rows, according to the following example. The shape of the 2D array is now (2, 6) rather than (6, 2).
Create Arrays with More than 2 Dimensions
If you want to create a 3D array, then just split the single dimension of this list [5, 25] to multiple dimensions, so the result looks like [, ] with shape (2, 1). If this new list is assigned to the start argument, for example, while the stop argument is assigned a scalar value, then the shape of the returned 3D array returned by np.linspace() is (5, 2, 1).
In order to add the third dimension for creating a 3D array, all you need to do is to add elements into the 5 sub-lists that match the number of channels. Here’s a list that satisfies what we need:[[11, 2, 5], [4.7, -5, 6], [71, 21, 0.3], [91, 3, 8], [9, 0, -4]]. The following code snippet builds this example. The final shape of the 3D array is (6, 5, 3).
This tutorial guided the reader to fully understand how the np.linspace() function works in detail. We started by introducing what np.linspace() is and why it is named so. We then explored each of the 7 arguments it accepts with examples.
The function is used to return 1D arrays by either specifying positive or negative, integer or float values for the start and stop arguments. np.linspace() is not limited only to return 1D arrays, but can return an array with any dimensionality.