Чтение и запись файлов

Эта страница рассматривает общие применения; для полного набора процедур ввода-вывода см. Ввод и вывод.

Чтение текстовых и CSV-файлов

Без пропущенных значений

Используйте numpy.loadtxt.

С пропущенными значениями

Используйте numpy.genfromtxt.

numpy.genfromtxt будет либо

возвращать маску массива, маскируя пропущенные значения (если usemask=True), или
заполнять пропущенное значение значением, указанным в filling_values (по умолчанию np.nan для float, -1 для int).

С разделителями, отличными от пробелов

>>> with open("csv.txt", "r") as f:
...     print(f.read())
1, 2, 3
4,, 6
7, 8, 9

Вывод массива с маской

>>> np.genfromtxt("csv.txt", delimiter=",", usemask=True)
masked_array(
  data=[[1.0, 2.0, 3.0],
        [4.0, --, 6.0],
        [7.0, 8.0, 9.0]],
  mask=[[False, False, False],
        [False,  True, False],
        [False, False, False]],
  fill_value=1e+20)

Вывод массива

>>> np.genfromtxt("csv.txt", delimiter=",")
array([[ 1.,  2.,  3.],
       [ 4., nan,  6.],
       [ 7.,  8.,  9.]])

Вывод массива, заданное значение для заполнения

>>> np.genfromtxt("csv.txt", delimiter=",", dtype=np.int8, filling_values=99)
array([[ 1,  2,  3],
       [ 4, 99,  6],
       [ 7,  8,  9]], dtype=int8)

Разделенные пробелами

numpy.genfromtxt также может анализировать файлы данных, разделенные пробелами, содержащие пропущенные значения, если

Каждый столбец имеет фиксированную ширину: Используйте ширину как аргумент delimiter.

# File with width=4. The data does not have to be justified (for example,
# the 2 in row 1), the last column can be less than width (for example, the 6
# in row 2), and no delimiting character is required (for instance 8888 and 9
# in row 3)

>>> with open("fixedwidth.txt", "r") as f:
...    data = (f.read())
>>> print(data)
1   2      3
44      6
7   88889

# Showing spaces as ^
>>> print(data.replace(" ","^"))
1^^^2^^^^^^3
44^^^^^^6
7^^^88889

>>> np.genfromtxt("fixedwidth.txt", delimiter=4)
array([[1.000e+00, 2.000e+00, 3.000e+00],
       [4.400e+01,       nan, 6.000e+00],
       [7.000e+00, 8.888e+03, 9.000e+00]])

Специальное значение (например, "x") указывает пропущенный столбец: Используйте его как аргумент missing_values.

>>> with open("nan.txt", "r") as f:
...     print(f.read())
1 2 3
44 x 6
7  8888 9

>>> np.genfromtxt("nan.txt", missing_values="x")
array([[1.000e+00, 2.000e+00, 3.000e+00],
       [4.400e+01,       nan, 6.000e+00],
       [7.000e+00, 8.888e+03, 9.000e+00]])

Вы хотите пропустить строки с пропущенными значениями: Установите invalid_raise=False.

>>> with open("skip.txt", "r") as f:
...     print(f.read())
1 2   3
44    6
7 888 9

>>> np.genfromtxt("skip.txt", invalid_raise=False)  
__main__:1: ConversionWarning: Some errors were detected !
    Line #2 (got 2 columns instead of 3)
array([[  1.,   2.,   3.],
       [  7., 888.,   9.]])

Разделитель-пробел отличается от пробелов, указывающих на пропущенные данные. Например, если столбцы разделены \t, пропущенные данные будут распознаны, если они состоят из одного или нескольких пробелов.:
```
>>> with open("tabs.txt", "r") as f:
...    data = (f.read())
>>> print(data)
1       2       3
44              6
7       888     9

# Tabs vs. spaces
>>> print(data.replace("\t","^"))
1^2^3
44^ ^6
7^888^9

>>> np.genfromtxt("tabs.txt", delimiter="\t", missing_values=" +")
array([[  1.,   2.,   3.],
       [ 44.,  nan,   6.],
       [  7., 888.,   9.]])
```

Чтение файла в формате .npy или .npz

Варианты:

Используйте numpy.load. Он может читать файлы, созданные с помощью numpy.save, numpy.savez или numpy.savez_compressed.
Используйте отображение памяти. См. numpy.lib.format.open_memmap.

Запись в файл, который будет повторно прочитан NumPy

Бинарный

Используйте numpy.save, или для хранения нескольких массивов numpy.savez или numpy.savez_compressed.

Для обеспечения безопасности и переносимости установите allow_pickle=False, если тип данных не содержит Python-объектов, что требует сериализации с помощью pickle.

Массивы с маской can't currently be saved, а также другие произвольные подклассы массивов, не поддерживаются.

Читаемый человеком

numpy.save и numpy.savez создают двоичные файлы. Для записи файла, читаемого человеком, используйте numpy.savetxt. Массив может быть только одномерным или двумерным, и нет `savetxtz` для нескольких файлов.

Крупные массивы

См. Запись или чтение больших массивов.

Чтение файла произвольного бинарного формата («бинарный фрагмент»)

Используйте структурированный массив.

Пример:

Заголовок файла .wav представляет собой 44-байтовый блок, предшествующий data_size байтам фактических данных звука:

chunk_id         "RIFF"
chunk_size       4-byte unsigned little-endian integer
format           "WAVE"
fmt_id           "fmt "
fmt_size         4-byte unsigned little-endian integer
audio_fmt        2-byte unsigned little-endian integer
num_channels     2-byte unsigned little-endian integer
sample_rate      4-byte unsigned little-endian integer
byte_rate        4-byte unsigned little-endian integer
block_align      2-byte unsigned little-endian integer
bits_per_sample  2-byte unsigned little-endian integer
data_id          "data"
data_size        4-byte unsigned little-endian integer

Заголовок файла .wav как структурированный тип данных NumPy:

wav_header_dtype = np.dtype([
    ("chunk_id", (bytes, 4)), # flexible-sized scalar type, item size 4
    ("chunk_size", "<u4"),    # little-endian unsigned 32-bit integer
    ("format", "S4"),         # 4-byte string, alternate spelling of (bytes, 4)
    ("fmt_id", "S4"),
    ("fmt_size", "<u4"),
    ("audio_fmt", "<u2"),     #
    ("num_channels", "<u2"),  # .. more of the same ...
    ("sample_rate", "<u4"),   #
    ("byte_rate", "<u4"),
    ("block_align", "<u2"),
    ("bits_per_sample", "<u2"),
    ("data_id", "S4"),
    ("data_size", "<u4"),
    #
    # the sound data itself cannot be represented here:
    # it does not have a fixed size
])

header = np.fromfile(f, dtype=wave_header_dtype, count=1)[0]

Этот .wav пример приведен для иллюстрации; для чтения файла .wav в реальной жизни используйте встроенный модуль Python wave.

(Адаптировано из Паули Виртанена, Расширенный NumPy, лицензия CC BY 4.0.)

Запись или чтение больших массивов

Массивы, слишком большие для размещения в памяти, можно обрабатывать как обычные массивы в памяти, используя отображение памяти.

Необработанные данные массива, записанные с помощью numpy.ndarray.tofile или numpy.ndarray.tobytes, могут быть прочитаны с помощью numpy.memmap:
```
array = numpy.memmap("mydata/myarray.arr", mode="r", dtype=np.int16, shape=(1024, 1024))
```
Файлы, выведенные numpy.save (т. е. использующие формат numpy), могут быть прочитаны с помощью numpy.load с аргументом mmap_mode:
```
large_array[some_slice] = np.load("path/to/small_array", mmap_mode="r")
```

Отображение памяти не имеет функций, таких как фрагментация данных и сжатие; более функциональные форматы и библиотеки, используемые с NumPy, включают:

HDF5: h5py или PyTables.
Zarr: здесь.
NetCDF: scipy.io.netcdf_file.

О компромиссах между memmap, Zarr и HDF5 см. pythonspeed.com.

Запись файлов для чтения другими (не NumPy) инструментами

Форматы для обмена данными с другими инструментами включают HDF5, Zarr и NetCDF (см. Запись или чтение больших массивов).

Запись или чтение JSON-файла

Массивы NumPy и большинство скаляров NumPy не являются напрямую сериализуемыми в JSON. Вместо этого используйте настраиваемый json.JSONEncoder для типов NumPy, который можно найти с помощью любого удобного поисковика.

Сохранение/восстановление с помощью файла pickle

Избегайте, когда это возможно; pickle не являются безопасными против ошибочных или злонамеренно сформированных данных.

Используйте numpy.save и numpy.load. Установите allow_pickle=False, если тип данных массива не включает Python-объекты, в противном случае требуется использование pickle.

numpy.load и модуль pickle также поддерживают разасериализацию файлов, созданных с NumPy 1.26.

Преобразование из pandas DataFrame в массив NumPy

См. pandas.Series.to_numpy.

Сохранение/восстановление с помощью tofile и fromfile

В целом, предпочтительнее использовать numpy.save и numpy.load.

numpy.ndarray.tofile и numpy.fromfile теряют информацию об endianness и точности и поэтому не подходят для ничего, кроме временного хранения.