11. Reading and Writing Data Files: ndarrays

By Bernd Klein. Last modified: 24 Nov 2021.

Scrabble with the Text Numpy, read, write, array

There are lots of ways for reading from file and writing to data files in numpy. We will discuss the different ways and corresponding functions in this chapter:

Saving textfiles with savetxt

The first two functions we will cover are savetxt and loadtxt.

In the following simple example, we define an array x and save it as a textfile with savetxt:

import numpy as np

x = np.array([[1, 2, 3], 
              [4, 5, 6],
              [7, 8, 9]], np.int32)

np.savetxt("test.txt", x)

The file "test.txt" is a textfile and its content looks like this:

bernd@andromeda:~/Dropbox/notebooks/numpy$ more test.txt
1.000000000000000000e+00 2.000000000000000000e+00 3.000000000000000000e+00
4.000000000000000000e+00 5.000000000000000000e+00 6.000000000000000000e+00
7.000000000000000000e+00 8.000000000000000000e+00 9.000000000000000000e+00

Attention: The above output has been created on the Linux command prompt!

It's also possible to print the array in a special format, like for example with three decimal places or as integers, which are preceded with leading blanks, if the number of digits is less than 4 digits. For this purpose we assign a format string to the third parameter 'fmt'. We saw in our first example that the default delimeter is a blank. We can change this behaviour by assigning a string to the parameter "delimiter". In most cases this string will consist solely of a single character but it can be a sequence of character, like a smiley " :-) " as well:

np.savetxt("test2.txt", x, fmt="%2.3f", delimiter=",")
np.savetxt("test3.txt", x, fmt="%04d", delimiter=" :-) ")

The newly created files look like this:

bernd@andromeda:~/Dropbox/notebooks/numpy$ more test2.txt 
bernd@andromeda:~/Dropbox/notebooks/numpy$ more test3.txt 
0001 :-) 0002 :-) 0003
0004 :-) 0005 :-) 0006
0007 :-) 0008 :-) 0009

The complete syntax of savetxt looks like this:

savetxt(fname, X, fmt='%.18e', delimiter=' ', newline='\n', header='', footer='', comments='# ')
Parameter Meaning
X array_like Data to be saved to a text file.
fmt str or sequence of strs, optional
A single format (%10.5f), a sequence of formats, or a multi-format string, e.g. 'Iteration %d -- %10.5f', in which case 'delimiter' is ignored. For complex 'X', the legal options for 'fmt' are:
a) a single specifier, "fmt='%.4e'", resulting in numbers formatted like "' (%s+%sj)' % (fmt, fmt)"
b) a full string specifying every real and imaginary part, e.g. "' %.4e %+.4j %.4e %+.4j %.4e %+.4j'" for 3 columns
c) a list of specifiers, one per column - in this case, the real and imaginary part must have separate specifiers, e.g. "['%.3e + %.3ej', '(%.15e%+.15ej)']" for 2 columns
delimiter A string used for separating the columns.
newline A string (e.g. "\n", "\r\n" or ",\n") which will end a line instead of the default line ending
header A String that will be written at the beginning of the file.
footer A String that will be written at the end of the file.
comments A String that will be prepended to the 'header' and 'footer' strings, to mark them as comments. The hash tag '#' is used as the default.

Loading Textfiles with loadtxt

We will read in now the file "test.txt", which we have written in our previous subchapter:

y = np.loadtxt("test.txt")


[[ 1.  2.  3.]
 [ 4.  5.  6.]
 [ 7.  8.  9.]]
y = np.loadtxt("test2.txt", delimiter=",")


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

Nothing new, if we read in our text, in which we used a smiley to separator:

y = np.loadtxt("test3.txt", delimiter=" :-) ")


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

It's also possible to choose the columns by index:

y = np.loadtxt("test3.txt", delimiter=" :-) ", usecols=(0,2))


[[ 1.  3.]
 [ 4.  6.]
 [ 7.  9.]]

We will read in our next example the file "times_and_temperatures.txt", which we have created in our chapter on Generators of our Python tutorial. Every line contains a time in the format "hh::mm::ss" and random temperatures between 10.0 and 25.0 degrees. We have to convert the time string into float numbers. The time will be in minutes with seconds in the hundred. We define first a function which converts "hh::mm::ss" into minutes:

def time2float_minutes(time):
    if type(time) == bytes:
        time = time.decode()
    t = time.split(":")
    minutes = float(t[0])*60 + float(t[1]) + float(t[2]) * 0.05 / 3
    return minutes

for t in ["06:00:10", "06:27:45", "12:59:59"]:



You might have noticed that we check the type of time for binary. The reason for this is the use of our function "time2float_minutes in loadtxt in the following example. The keyword parameter converters contains a dictionary which can hold a function for a column (the key of the column corresponds to the key of the dictionary) to convert the string data of this column into a float. The string data is a byte string. That is why we had to transfer it into a a unicode string in our function:

y = np.loadtxt("times_and_temperatures.txt", 
               converters={ 0: time2float_minutes})


[[  360.     20.1]
 [  361.5    16.1]
 [  363.     16.9]
 [ 1375.5    22.5]
 [ 1377.     11.1]
 [ 1378.5    15.2]]
# delimiter = ";" , # i.e. use ";" as delimiter instead of whitespace 


tofile is a function to write the content of an array to a file both in binary, which is the default, and text format.

A.tofile(fid, sep="", format="%s")

The data of the A ndarry is always written in 'C' order, regardless of the order of A.

The data file written by this method can be reloaded with the function fromfile().

Parameter Meaning
fid can be either an open file object, or a string containing a filename.
sep The string 'sep' defines the separator between array items for text output. If it is empty (''), a binary file is written, equivalent to file.write(a.tostring()).
format Format string for text file output. Each entry in the array is formatted to text by first converting it to the closest Python type, and then using 'format' % item.


Information on endianness and precision is lost. Therefore it may not be a good idea to use the function to archive data or transport data between machines with different endianness. Some of these problems can be overcome by outputting the data as text files, at the expense of speed and file size.

dt = np.dtype([('time', [('min', int), ('sec', int)]),
               ('temp', float)])
x = np.zeros((1,), dtype=dt)
x['time']['min'] = 10
x['temp'] = 98.25

fh = open("test6.txt", "bw")


[((10, 0), 98.25)]


fromfile to read in data, which has been written with the tofile function. It's possible to read binary data, if the data type is known. It's also possible to parse simply formatted text files. The data from the file is turned into an array.

The general syntax looks like this:

numpy.fromfile(file, dtype=float, count=-1, sep='')

Parameter Meaning
file 'file' can be either a file object or the name of the file to read.
dtype defines the data type of the array, which will be constructed from the file data. For binary files, it is used to determine the size and byte-order of the items in the file.
count defines the number of items, which will be read. -1 means all items will be read.
sep The string 'sep' defines the separator between the items, if the file is a text file. If it is empty (''), the file will be treated as a binary file. A space (" ") in a separator matches zero or more whitespace characters. A separator consisting solely of spaces has to match at least one whitespace.
fh = open("test4.txt", "rb")

np.fromfile(fh, dtype=dt)


array([((4294967296, 12884901890), 1.0609978957e-313),
       ((30064771078, 38654705672), 2.33419537056e-313),
       ((55834574860, 64424509454), 3.60739284543e-313),
       ((81604378642, 90194313236), 4.8805903203e-313),
       ((107374182424, 115964117018), 6.1537877952e-313),
       ((133143986206, 141733920800), 7.42698527006e-313),
       ((158913789988, 167503724582), 8.70018274493e-313),
       ((184683593770, 193273528364), 9.9733802198e-313)], 
      dtype=[('time', [('min', '<i8'), ('sec', '<i8')]), ('temp', '<f8')])
import numpy as np
import os

# platform dependent: difference between Linux and Windows
#data = np.arange(50,

data = np.arange(50, dtype=np.int32)

fh = open("test4.txt", "rb")
# 4 * 32 = 128, os.SEEK_SET)

x = np.fromfile(fh, dtype=np.int32)


[32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49]


It can cause problems to use tofile and fromfile for data storage, because the binary files generated are not platform independent. There is no byte-order or data-type information saved by tofile. Data can be stored in the platform independent .npy format using save and load instead.

Best Practice to Load and Save Data

The recommended way to store and load data with Numpy in Python consists in using load and save. We also use a temporary file in the following :

import numpy as np


from tempfile import TemporaryFile

outfile = TemporaryFile()

x = np.arange(10), x) # Only needed here to simulate closing & reopening file


[32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49]
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

and yet another way: genfromtxt

There is yet another way to read tabular input from file to create arrays. As the name implies, the input file is supposed to be a text file. The text file can be in the form of an archive file as well. genfromtxt can process the archive formats gzip and bzip2. The type of the archive is determined by the extension of the file, i.e. '.gz' for gzip and bz2' for an bzip2.

genfromtxt is slower than loadtxt, but it is capable of coping with missing data. It processes the file data in two passes. At first it converts the lines of the file into strings. Thereupon it converts the strings into the requested data type. loadtxt on the other hand works in one go, which is the reason, why it is faster.

recfromcsv(fname, **kwargs)

This is not really another way to read in csv data. 'recfromcsv' basically a shortcut for

np.genfromtxt(filename, delimiter=",", dtype=None)