numpy.genfromtxt

numpy.genfromtxt(fname, dtype=<class 'float'>, comments='#', delimiter=None, skip_header=0, skip_footer=0, converters=None, missing_values=None, filling_values=None, usecols=None, names=None, excludelist=None, deletechars=None, replace_space='_', autostrip=False, case_sensitive=True, defaultfmt='f%i', unpack=None, usemask=False, loose=True, invalid_raise=True, max_rows=None, encoding='bytes')

Функция genfromtxt() загружает данные из текстового файла с указанием правил обработки отсутствующих и прочих значений.

Параметры:
fname - строка, файловый объект, экземпляр класса pathlib.Path, список строк, генератор строк.
Файл из которого должен быть загружен массив. Файлы-архивы с расширением gz или bz2 предварительно распаковываются. Строки в списке или строки созданные генератором, обрабатываются последовательно, так же как строки из файла. Строки созданные генератором в Python3 должны быть байтовыми.
dtype - тип данных NumPy (необязательный параметр).
Определяет тип данных результирующего массива. По умолчанию None, что соттветствует автоматическому определению типа каждого столбца в зависимости от его содержимого. По умолчанию, для регулярных числовых данных используется float. Если в файле находятся структурированные данные, т.е. структурированный тип данных, то результирующий массив будет одномерным, а каждая строка файла станет его отдельным элементом. В этом случае, необходимо определить структурированный тип данных, количество полей в котором должно соответствовать количеству колонок в текстовом файле.
comments - строка (необязательный параметр).
Строка, обозначающая начало строк комментирования, по умолчанию, это '#'. Все символы в строке следующие за comments отбрасываются.
delimiter - строка, число или последовательность (необязательный параметр).
Задает разделитель между элементами (столбцами) массива. По умолчанию, символы-пробелы, а так же последовательности таких пробелов, воспринимаются как разделитель. Ширина каждого поля может быть определена целым числом или последовательностью целых чисел.
skiprows - целое число (необязательный параметр).
С версии NumPy 1.10 вместо него используется параметр skip_header.
skip_header - целое число (необязательный параметр).
Количество строк в начале файла, которое необходимо пропустить.
skip_footer - целое число (необязательный параметр).
Количество строк в конце файла, которое необходимо пропустить.
converters - словарь (необязательный параметр).
Словарь, в качестве ключей которого используются целые числа соответствующие столбцам данных в файле. Числовому значению ключа сопоставляется соответствующий столбец с соответствующей ключу функцией конвертирования. Например converters = {3: lambda x: float(x.lstrip('$') or 0)}.
missing - переменная или значение (необязательный параметр).
С версии NumPy 1.10 вместо него используется параметр missing_values.
missing_values - переменная или значение (необязательный параметр).
Строка или набор строк, соответствующий отсутствующим данным.
filling_values - переменная или значение (необязательный параметр).
Значение или набор значений, используемый по умолчанию для отсутствующих данных.
usecols - целое число или кортеж целых чисел (необязательный параметр).
Указывает какие столбцы будут считаны. Первый столбец имеет номер 0. По умолчанию usecols=None что соответствует чтению всех столбцов в файле. Цлое число, например usecols=1 так же как и кортеж с одним значением usecols=(1,) приведет к считыванию единственного из всех столбца в файле, т.е. будет прочитан только второй столбец.
names - {None, True, строка, последовательность} (необязательный параметр).
Значение True приводит к тому, что имена полей считываются из первой строки, следующей за строками skip_header. Если имена полей находятся в одной строке, разделенные , или в последовательности, то они будут использоваться в качестве имен полей в структурированном типе данных NumPy. Значение None, то будут использоваться имена полей указанные в параметре dtype.
excludelist - последовательность (необязательный параметр).
Список имен, добавляемый для исключений. Этот список добавляется к списку созданному по умолчанию ['return', 'file', 'print']. Данные имена должны добавляться с символом _ в конце, например: file станет file_. Этот параметр позволяет заранее предусмотреть, имена которые имеют недопустимое значение и используется для повышения безопасности.
deletechars - строка (необязательный параметр).
Строка в которой перечислены все недопустимые символы в именах полей и которые необходимо удалить.
defaultfmt - строка (необязательный параметр).
Формат используемый для имен полей по умолчанию. Подробнее смотрите в описании savetxt().
autostrip - True или False (необязательный параметр).
Определяет необходимость автоматического удаления пробелов из значений.
replace_space - строка (необязательный параметр).
Символ или последовательность символов, используемая для замены пробелов в именах полей. По умолчанию '_'.
case_sensitive - {True, False, ‘upper’, ‘lower’} (необязательный параметр).
True приводит к чувствительности регистру символов в именах полей. Значение False или 'upper' переводит все символы имен полей в верхний регистр. 'lower' - преобразует в нижний регистр.
unpack - True или False (необязательный параметр).
True приводит к тому, что массив может быть распакован с помощью множественного присвоения, например: x, y, z = genfromtxt(fname, ...).
usemask - True или False (необязательный параметр).
True приводит к тому, что возвращается массив. False - обычный массив.
loose - True или False (необязательный параметр).
True приводит к тому, что исключения для недопустимых значений имен полей не вызываются.
invalid_raise - True или False (необязательный параметр).
True приводит к тому, что возникает исключения при несоответствии количества столбцов. False - строки с несоответствием пропускается, но об этом выдается предупреждение.
max_rows - True или False (необязательный параметр).
Задает максимальное количество строк, считываемых из файла, если задано, то должно быть не меньше 1. Использование вместе с параметром skip_footer приведет к ошибке. По умолчанию считываются все строки в файле. Доступно в NumPy с версии 1.10.0.
encoding - строка (необязательный параметр).
Кодировка используемая для декодирования смволов входного файла. Если fname - файловый объект, то encoding, не указывается. Значение 'bytes' позволяет добиться обратной совместимости между Python2 и Python3, если это возможно, в этом случае вы получите байтовые массивы, но после все строки будут обрабатываться как latin1. Значение None означает что при декодировании будет использовано системное значение. По умолчанию используется 'bytes'. Доступно в NumPy с версии 1.14.0.
Возвращает:
результат - массив NumPy
Массив считанный из файла. Если usemask = True то возвращается массив с маской.

Замечание

Если в некоторых столбцах имеются пропущенные (отсутствующие) данные, а в качестве разделителей используется пробел, то может оказаться так, что в двух соседних столбцах на против друг друга могут оказаться пропущенные данные, что может привести к ошибке.

Если имена полей заданы с помощью параметра dtype или names, то имена полей в файле должны быть либо удалены, либо пропущены.

По умолчанию, никакие пробелы не удаляются.



Примеры

В директории в которой выполняется скрипт создадим директорию с названием example, а в ней создадим текстовый документ genfromtxt_example.txt, содержащий следующий текст:

#  Некоторые данные о 15 химических элементах.
#  Сдесь представлены: "Атомный номер", 
#  "Обозначение элемента", "Группа", "Период", 
#  "Атомный масса", "Радиус атома (pm)"


1 H 7 1 1.00797 25
2 He 8 1 4.0026 30
3 Li 1 2 6.939 145
4 Be 2 2 9.0122 105
5 B 3 2 10.811 85
6 C 4 2 12.01115 70
7 N 5 2 14.0067 65
8 O 6 2 - 60
9 F 7 2 18.9984 50
10 Ne 8 2 20.179 40
11 Na 1 3 22.9898 180
12 Mg 2 3 24.305 150
13 Al 3 3 26.9815 125
14 Si 4 3 28.086 110
15 P 5 3 - 100
>>> import numpy as np
>>> 
>>> fname = 'example/genfromtxt_example.txt'
>>> 
>>> a = np.genfromtxt(fname)
>>> a
array([[  1.     ,       nan,   7.     ,   1.     ,   1.00797,  25.     ],
       [  2.     ,       nan,   8.     ,   1.     ,   4.0026 ,  30.     ],
       [  3.     ,       nan,   1.     ,   2.     ,   6.939  , 145.     ],
       ...,
       [ 13.     ,       nan,   3.     ,   3.     ,  26.9815 , 125.     ],
       [ 14.     ,       nan,   4.     ,   3.     ,  28.086  , 110.     ],
       [ 15.     ,       nan,   5.     ,   3.     ,       nan, 100.     ]])

Использование функции без каких лио параметров приводит к тому, что все нечисловые значения превращаются в np.nan. Создадим структурированный тип данных и укажем его в параметре dtype:

>>> dt_1 = np.dtype([('№','i2'),('symbol','U2'),('group','i2'),
...                  ('period', 'i2'), ('mass', 'f4'), ('radius', 'i4'),])
>>> 
>>> a = np.genfromtxt(fname, dtype = dt_1)
>>> a
array([( 1, 'H', 7, 1,  1.00797,  25), ( 2, 'He', 8, 1,  4.0026 ,  30),
       ( 3, 'Li', 1, 2,  6.939  , 145), ...,
       (13, 'Al', 3, 3, 26.9815 , 125), (14, 'Si', 4, 3, 28.086  , 110),
       (15, 'P', 5, 3,      nan, 100)],
      dtype=[('№', '<i2'), ('symbol', '<U2'), ('group', '<i2'), ('period', '<i2'), ('mass', '<f4'), ('radius', '<i4')])

Если необходимо извлеч определенные столбцы, то для них так же необходимо создать структурированный тип данных:

>>> dt_2 = np.dtype([('№','i2'),('symbol','U2'),('radius','i2'),])
>>> 
>>> a = np.genfromtxt(fname, dtype = dt_2, usecols=(0,1,5))
>>> a
array([( 1, 'H',  25), ( 2, 'He',  30), ( 3, 'Li', 145), ...,
       (13, 'Al', 125), (14, 'Si', 110), (15, 'P', 100)],
      dtype=[('№', '<i2'), ('symbol', '<U2'), ('radius', '<i2')])

В столбце с массой элементов имеются пропущенные данные, такие данные можно обрабатывать с помощью параметра onverters в котором необходимо указать словарь с ключом-номером столбца и значением-именем функции:

>>> def parse_mas(s):
         try:
             return float(s)
         except ValueError:
             return np.nan
... 
>>> dt_3 = np.dtype([('№','i2'),('symbol','U2'),('mass','f4'),])
>>> 
>>> a = np.genfromtxt(fname, dtype = dt_3, usecols=(0,1,4), converters={4: parse_mas})
>>> a
array([( 1, 'H',  1.00797), ( 2, 'He',  4.0026 ), ( 3, 'Li',  6.939  ),
       ..., (13, 'Al', 26.9815 ), (14, 'Si', 28.086  ),
       (15, 'P',      nan)],
      dtype=[('№', '<i2'), ('symbol', '<U2'), ('mass', '<f4')])

Создадим еще один текстовый файл genfromtxt_example_1.txt в который мы добавим строку с названиями столбцов:

#  Некоторые данные о 15 химических элементах.
#  Сдесь представлены: "Атомный номер", 
#  "Обозначение элемента", "Группа", "Период", 
#  "Атомный масса", "Радиус атома (pm)"

"Atomic number", "Item designation", "Group", "Period", "Atomic mass", "Atomic radius (pm)"
1, H, 7, 1, 1.00797, 25
2, He, 8, 1, 4.0026, 30
3, Li, 1, 2, 6.939, 145

А теперь попробуем считать данные из этого файла:

>>> fname = 'example/genfromtxt_example_1.txt'
>>>
>>> a = np.genfromtxt(fname, skip_header = 5, delimiter = ', ', names = True)
>>> a
array([(1., nan, 7., 1., 1.00797,  25.), (2., nan, 8., 1., 4.0026 ,  30.),
       (3., nan, 1., 2., 6.939  , 145.)],
      dtype=[('Atomic_number', '<f8'), ('Item_designation', '<f8'), ('Group', '<f8'), ('Period', '<f8'), ('Atomic_mass', '<f8'), ('Atomic_radius_pm', '<f8')])

Параметр names чувствителен к символам-разделителям, т.е. в строке имен должен использоваться тот же символ разделитель что и во всем файле. После такого считывания имена в names становятся именами столбцов:

>>> a['Atomic_number']
array([1., 2., 3.])

Однако при таком способе чтения строк из файла, имена элементов стали равны значению np.nan:

>>> a['Item_designation']
array([nan, nan, nan])

Определить явно (в ручную) парамет dtype вместе с параметром names уже не получится. Тем не менее, если массив в файле содержит только числовые данные, а строка имен является единственной, то мы получаем очень удобный способ чтения данных.

Учитывая большое количество параметров данной функции, привести исчерпывающее количество примеров, представляется очень трудным. Однако, если вы хорошо понимаете, как устроены структурированные массивы, то особых трудностей возникнуть не должно. В противном случае, если "игра не стоит свеч" (структура данных в файле слишком сложная), то лучше воспользоваться пакетом Pandas.