NumPy loadtxt()

import numpy as np

# load text from a file
array1 = np.loadtxt('file.txt')

print(array1)

'''
Output
[[0. 1.]
 [2. 3.]]
'''

loadtxt() Syntax

The syntax of loadtxt() is:

numpy.loadtxt(fname, dtype=<class 'float'>, comments='#', delimiter=None, converters=None, skiprows=0, usecols=None, unpack=False, ndmin=0, encoding='bytes', max_rows=None, *, quotechar=None, like=None)

loadtxt() Argument

The loadtxt() method takes the following arguments:

• fname- file to read (file or str or path or generator or list of str)
• dtype(optional)- type of output array
• comments(optional)- characters used to identify beginning of comment(str or None)
• delimiter(optional)- character used to separate values(str)
• converters(optional)- function used for custom parsing(dict or callable)
• skiprows(optional)- number of lines to skip at start(int)
• usecols(optional)- which columns to read(int or sequence)
• unpack(optional)- unpacks columns as separate arrays if True
• ndmin(optional)- minimum number of dimensions in the array(int)
• encoding(optional)- encoding used to decode the input file(str)
• max_rows(optional)- Number of rows to read(int)
• quotechar(optional)- character to denote the start and the end of a quoted item
• like(optional)- reference object used for the creation of non-NumPy arrays(array_like)

loadtxt() Return Value

The loadtxt() method returns an array containing data from the text file.

Example 1: Create an Array Using loadtxt

Our current compiler does not support file operations, thus we are utilizing the StringIO class. This class allows us to work around the file-related constraints by treating a string as a file-like object.

# StringIO behaves like a file object
from io import StringIO
file1 = StringIO('0 1 2\n3 4 5\n6 7 8')

# import numpy
import numpy as np

# load from file
array1 = np.loadtxt(file1)

print(array1)

Output

[[0. 1. 2.]
 [3. 4. 5.]
 [6. 7. 8.]]

Example 2: Use dtype Argument to Specify Data Type

The dtype argument helps specify the required datatype of created numpy arrays. By default, the datatype is float, however, we can change it to any compatible datatype as we like.

import numpy as np

# create two file objects using StringIO
from io import StringIO
file1 = StringIO(' 1 2\n3 4\n5 6')
file2 = StringIO(' 1 2\n3 4\n5 6')

# load from file
array1 = np.loadtxt(file1)

print("Default type:\n", array1)

# load from file to create an int array
array2 = np.loadtxt(file2, dtype = int)

print("\nInteger type:\n", array2)

Output

Default type:
[[1. 2.]
 [3. 4.]
 [5. 6.]]

Integer type:
 [[1 2]
 [3 4]
 [5 6]]

Example 3: Use comments Argument to Ignore Lines in Files

The comments argument helps specify which characters the comments start from so we can ignore them in array creation.

import numpy as np

# create two file objects using StringIO
from io import StringIO
file1 = StringIO(' 1 2\n#skip this line\n3 4\n5 6')
file2 = StringIO('1 2 3 4 5 6?skip the second half of this line')
file3 = StringIO('1 2 3 4 5 6%skip the second half of this line')

# load from the  file if comments start with #
array1 = np.loadtxt(file1, comments = '#')
print('Array1:', array1)

# load from the file and ignore all the characters after ?
array2 = np.loadtxt(file2, comments = '?')
print('Array2:', array2)

# load from the file and ignore all the characters after *
array3 = np.loadtxt(file3, comments = '*')
print('Array3:', array3)

Output

Array1: [[1. 2.]
 [3. 4.]
 [5. 6.]]
Array2: [1. 2. 3. 4. 5. 6.]
ValueError: could not convert string '6%skip' to float64 at row 0, column 6.

Here, array1 and array2 worked fine but array3 raises an error. This is because our file is using % as a comment indicator whereas our code is taking * as input. This causes array3 to not process the comments properly thus resulting in an error.

The comments argument is helpful when the text file contains additional information or metadata within lines, which is not part of the actual data we want to load.

Example 4: Use delimiter Argument to Separate Data Entries

The delimiter argument helps specify the character that separates the data entry in the input file. By default, delimiter = None, which means the white-space characters are treated as delimiters.

import numpy as np

# create two file objects using StringIO
from io import StringIO
file1 = StringIO('1 2 3 4 5 6')
file2 = StringIO('1,2,3,4,5,6')

# load from file
# by default white-space acts as delimiter
array1 = np.loadtxt(file1)
print('Array1:', array1)

# load from file with commas as delimiter
array2 = np.loadtxt(file2, delimiter = ',')
print('Array2:', array2)

Output

Array1: [1. 2. 3. 4. 5. 6.]
Array2: [1. 2. 3. 4. 5. 6.]

Example 5: Use converters Argument for Parsing Input

The converter argument helps convert and parse the input file contents to create a NumPy array.

import numpy as np

# create two file objects using StringIO
from io import StringIO
file1 = StringIO('1 2 3 4 5')

def square(n):
    return int(n)**2
    
# load from file and square
array1 = np.loadtxt(file1, converters = square)

print('Array1:', array1)

# reset file pointer
file1.seek(0)

# use lambda function as converter
array2 = np.loadtxt(file1, converters = lambda i:int(i)**2)

print('Array2:', array2)

# reset file pointer
file1.seek(0)

# use converter only on element at index 2
array3 = np.loadtxt(file1, converters = {2:square})

print('Array3:', array3)

Output

Array1: [ 1.  4.  9. 16. 25.]
Array2: [ 1.  4.  9. 16. 25.]
Array3: [1. 2. 9. 4. 5.]

Example 6: Use skiprows Argument for Skipping Rows

The skiprows argument skips the specified number of rows at the beginning before reading the file contents to create a NumPy array.

import numpy as np

# create a file object using StringIO
from io import StringIO
file1 = StringIO('Col1 Col2\n1 20\n4 50\n9 81')

# load from file and skip the 1st row
array1 = np.loadtxt(file1, skiprows = 1)

print('Array1:\n', array1)

Output

Array1:
[[ 1. 20.]
 [ 4. 50.]
 [ 9. 81.]]

Example 7: Use usecols Argument to Read Specific Columns

The usecols argument reads specified columns of the file contents to create a NumPy array.

import numpy as np

# StringIO behaves like a file object
from io import StringIO
file1 = StringIO('1 2 3\n4 5 6\n7 8 9')

# load from file
array1 = np.loadtxt(file1)

# reset file pointer
file1.seek(0)

# load from file and read only 1st and 3rd column
array2 = np.loadtxt(file1, usecols = [0,2])

print('Whole Array:\n', array1)
print('Array using Column 0 and 2:\n', array2)

Output

Whole Array:
[[1. 2. 3.]
 [4. 5. 6.]
 [7. 8. 9.]]
Array using Column 0 and 2:
 [[1. 3.]
 [4. 6.]
 [7. 9.]]

Example 8: Use unpack Argument

The unpack argument is a boolean flag specifying whether the loaded data should be unpacked.

Each column is treated as its own array when True, and when False, the entire file acts as a single array.

import numpy as np

# create two file objects using StringIO
from io import StringIO
file1 = StringIO('1 2 3\n4 5 6\n7 8 9')
file2 = StringIO('1 2 3\n4 5 6\n7 8 9')

# load from file
array1 = np.loadtxt(file1)
print('Array1:\n', array1)

# load from file and unpack it
x, y, z = np.loadtxt(file2, unpack = True)
print('Unpacked Values:\n', x, y, z)

Output

Array1:
[[1. 2. 3.]
 [4. 5. 6.]
 [7. 8. 9.]]
Unpacked Values:
 [1. 4. 7.] [2. 5. 8.] [3. 6. 9.]

Example 9: Use ndmin Argument to Specify Minimum Number of Dimensions

The ndmin argument specifies the minimum number of dimensions in the created array. By default, ndmin = 0, i.e. the created array is not forced into a specific minimum number of dimensions.

import numpy as np

# create three file object using StringIO
from io import StringIO
file1 = StringIO('1 2 3 4 5 ')
file2 = StringIO('1 2 3 4 5')
file3 = StringIO('1 2 3 4 5')

# load from file
array1 = np.loadtxt(file1)

print('Array1:\n', array1)

# load from file in an array of 1 dimension
array2 = np.loadtxt(file2, ndmin = 1)

print('Array2:\n',array2)

# load from file in an array of 2 dimensions
array3 = np.loadtxt(file3, ndmin = 2)

print('Array3:\n', array3)

Output

Array1:
[1. 2. 3. 4. 5.]
Array2:
 [1. 2. 3. 4. 5.]
Array3:
 [[1. 2. 3. 4. 5.]]

Example 10: Use max_rows Argument to Specify the Maximum Number of Rows

The max_rows argument specifies the maximum number of rows to read from the file.

import numpy as np

# create three file object using StringIO
from io import StringIO
file1 = StringIO('1 2\n3 4\n5 6')
file2 = StringIO('1 2\n3 4\n5 6')
file3 = StringIO('1 2\n3 4\n5 6')

# load all rows from the file
array1 = np.loadtxt(file1)

print('Original array:\n', array1)

# load 2 rows from file
array2 = np.loadtxt(file2, max_rows = 2)

print('Array with 2 max rows:\n', array2)

# load 1 row from file after skipping the first row
array3 = np.loadtxt(file3, skiprows = 1, max_rows = 1)

print('Array with 1 skipped row and 1 max row:\n',array3)

Output

Orginal array:
[[1. 2.]
 [3. 4.]
 [5. 6.]]
Array with 2 max rows:
 [[1. 2.]
 [3. 4.]]
Array with 1 skipped row and 1 max row:
 [3. 4.]

Example 11: Use quotechars Argument for Specifying Quotes

The quotechars argument denotes the start and end of a quoted item.

import numpy as np

# create a file object using StringIO
from io import StringIO
file1 = StringIO('Today is a !good day!')

# load text from file
array1 = np.loadtxt(file1, dtype = 'U20', quotechar = '!')

print('Array1:\n', array1)

Output

Array1:
['Today' 'is' 'a' 'good day']

Here, white-space acts as a delimiter. Although, there is a white space between good and day, the use of ! indicates that good day is a single element.