fileDatastore

Datastore с пользовательским средством чтения файлов

Описание

Использование FileDatastore объект для управления большими наборами пользовательских файлов формата, где набор не обязательно помещается в памяти или когда большой пользовательский файл не помещается в памяти. Можно создать FileDatastore объект с использованием fileDatastore function, задайте его свойства, а затем импортируйте и обрабатывайте данные с помощью функций object.

Создание

Синтаксис

fds = fileDatastore(location,'ReadFcn',@fcn)

fds = fileDatastore(location,'ReadFcn',@fcn,Name,Value)

Описание

fds = fileDatastore(location,'ReadFcn',@fcn) создает datastore из набора файлов, заданных location и использует функцию fcn для чтения данных из файлов.

пример

fds = fileDatastore(location,'ReadFcn',@fcn,Name,Value) задает дополнительные параметры и свойства для fds использование одного или нескольких аргументов пары "имя-значение". Например, можно задать, какие файлы включать в datastore в зависимости от их расширений с fileDatastore(location,'ReadFcn',@customreader,'FileExtensions',{'.exts','.extx'}).

Входные параметры

расширить все

`location` - Файлы или папки для включения в datastore
путь | `DsFileSet` объект

Файлы или папки, включенные в datastore, задаются в виде пути или DsFileSet объект.

path - Задайте путь как вектор символов, массив ячеек из векторов символов, строковый скаляр или строковые массивы, содержащий расположение локальных или удаленных файлов или папок.
- Локальные файлы или папки - Задайте location как локальный путь к файлам или папкам. Если файлов нет в текущей папке, то локальный путь должен задавать полные или относительные пути. Файлы в подпапках указанной папки не включаются автоматически в datastore. При указании локального пути можно использовать символ подстановки (*). Этот символ указывает, что datastore включает все соответствующие файлы или все файлы в соответствующих папках.
- Удаленные файлы или папки - Задайте location чтобы быть полными путями к файлам или папкам в качестве единого указателя ресурса (URL) формы hdfs:///path_to_file. Для получения дополнительной информации см. раздел Работа с удаленными данными.
DsFileSet объект - Вы также можете задать location как DsFileSet объект. Для получения дополнительной информации смотрите matlab.io.datastore.DsFileSet.

Когда location представляет папку, datastore включает только поддерживаемые форматы файлов и игнорирует любой другой формат. Чтобы задать пользовательский список расширений файлов, которые будут включены в ваш datastore, смотрите FileExtensions свойство.

Пример: 'file1.ext'

Пример: '../dir/data/file1.ext'

Пример: {'C:\dir\data\file1.exts','C:\dir\data\file2.extx'}

Пример: 'C:\dir\data\*.ext'

`@fcn` - Функция, считывающая данные файла
указатель на функцию

Функция, которая читает данные файла, заданная как указатель на функцию.

Сигнатура функции, представленной указателем на функцию @fcn зависит от значения заданного ReadMode. Функция, считывающая данные файла, должна подтвердить одну из этих сигнатур.

`ReadMode`	`ReadFcn` подпись
`'file'` (по умолчанию)	Функция должна иметь следующую подпись: function data = MyReadFcn(filename) ... end `filename` - Имя считываемого файла. `data` - Соответствующие данные файла.
`'partialfile'`	Функция должна иметь следующую подпись: function [data,userdata,done] = MyReadFcn(filename,userdata) ... end `userdata` - Устанавливайте и считывайте поля `userdata` сохранение данных между несколькими `FileDatastore` чтение вызовов. `done` - Установите этот `logical` аргумент любому из `true` или `false`. `false` - Продолжить чтение текущего файла. `true` - Завершает текущий файл, чтение и чтение следующего файла. `data` - Фрагмент файловых данных.
`'byte'`	Функция должна иметь следующую подпись: function data = MyReadFcn(filename,offset,size) ... end `offset` - Задайте смещение байта от первого байта в файле. `size` - Укажите количество байтов для чтения во время текущей операции чтения. `data` - Фрагмент данных файла размера, заданного в `BlockSize`. The `FileDatastore` увеличивает оба `offset` и `size` входы на основе значения, заданного в `BlockSize`.

ReadMode

ReadFcn подпись

'file' (по умолчанию)

Функция должна иметь следующую подпись:

function data = MyReadFcn(filename)
...
end

filename - Имя считываемого файла.

data - Соответствующие данные файла.

'partialfile'

Функция должна иметь следующую подпись:

function [data,userdata,done] = MyReadFcn(filename,userdata)
...
end

userdata - Устанавливайте и считывайте поля userdata сохранение данных между несколькими FileDatastore чтение вызовов.

done - Установите этот logical аргумент любому из true или false.

false - Продолжить чтение текущего файла.
true - Завершает текущий файл, чтение и чтение следующего файла.

data - Фрагмент файловых данных.

'byte'

Функция должна иметь следующую подпись:

function data = MyReadFcn(filename,offset,size)
...
end

offset - Задайте смещение байта от первого байта в файле.

size - Укажите количество байтов для чтения во время текущей операции чтения.

data - Фрагмент данных файла размера, заданного в BlockSize.

The FileDatastore увеличивает оба offset и size входы на основе значения, заданного в BlockSize.

Значение, заданное в @fcn, устанавливает значение свойства ReadFcn.

Пример: @customreader

Типы данных: function_handle

Аргументы в виде пар имя-значение

Задайте необязательные разделенные разделенными запятой парами Name,Value аргументы. Name - имя аргумента и Value - соответствующее значение. Name должны находиться внутри кавычек. Можно задать несколько аргументов в виде пар имен и значений в любом порядке Name1,Value1,...,NameN,ValueN.

Пример: fds = fileDatastore('C:\dir\data','FileExtensions',{'.exts','.extx'})

`'IncludeSubfolders'` - Флаг включения подпапки
`true` или `false` | 0 или 1

Флаг включения подпапки, заданный как разделенная разделенными запятой парами, состоящая из 'IncludeSubfolders' и true, false, 0 или 1. Задайте true включать все файлы и подпапки в каждую папку или false для включения только файлов в каждую папку.

Если вы не задаете 'IncludeSubfolders', затем значение по умолчанию false.

Пример: 'IncludeSubfolders',true

Типы данных: logical | double

`'FileExtensions'` - Пользовательские расширения файлов в формате
вектор символов | массив ячеек из векторов символов | строковый скаляр | строковые массивы

Расширения файлов пользовательского формата, заданные как разделенная разделенными запятой парами, состоящая из 'FileExtensions' и вектор символов, массив ячеек из векторов символов, строковый скаляр или строковые массивы.

Когда вы задаете расширение файла, fileDatastore функция создает объект datastore только для файлов с заданным расширением. Можно также создать datastore для файлов без каких-либо расширений путем определения 'FileExtensions' как пустой символьный вектор, ''. Если вы не задаете 'FileExtensions', затем fileDatastore автоматически включает все файлы в папке.

Пример: 'FileExtensions',''

Пример: 'FileExtensions','.ext'

Пример: 'FileExtensions',{'.exts','.extx'}

Типы данных: char | cell | string

`'PreviewFcn'` - Функция для предварительного просмотра входных данных
`@ReadFcn` (по умолчанию) | указатель на функцию

Функция для предварительного просмотра входных данных, заданная как указатель на функцию.

Если вы не задаете функцию предварительного просмотра, FileDatastore использует значение, заданное в @ReadFcn как функцию предварительного просмотра по умолчанию. Кроме того, вы можете задать свою собственную пользовательскую функцию предварительного просмотра для ваших данных.

@ReadFcn (по умолчанию) - Использование ReadFcn для выборки FileDatastore данные. Эта опция может привести к снижению эффективности для tall конструкция.
Function handle - Используйте пользовательскую функцию предварительного просмотра для FileDatastore и tall конструкция для выборки входных данных. Использование PreviewFcn предоставить функцию, которая считывает только минимальную необходимую часть входных данных для предварительного просмотра и tall structure.

Функция, заданная как PreviewFcn должны возвращать значения с совпадающими типами данных, что и ReadFcn возвращает.

Типы данных: function_handle

`'ReadMode'` - Фрагмент файла для чтения
`'file'` (по умолчанию) | `'partialfile'` | `'bytes'`

Фрагмент считываемого файла, заданная как 'file', 'partialfile', или 'bytes'.

'file' (по умолчанию)

Используйте режим чтения 'file' когда ваша пользовательская функция, заданная в ReadFcn, считывает полный файл за одну операцию чтения.

На основе вашей пользовательской функции чтения, file datastore считывает полный файл с каждым вызовом в read. Модуль параллелизации в является полным файлом.

'partialfile'

Используйте режим чтения 'partialfile' когда ваша функция чтения пользовательского файла, заданная в ReadFcn, считывает только фрагмент файла с каждой операцией чтения.

На основе вашей пользовательской функции чтения, file datastore считывает только фрагмент файла с каждым вызовом read функция.

В 'partialfile' read mode, модуль параллелизации является полным файлом. Несколько read операции последовательно необходимы для чтения полного файла.

'bytes'

Используйте режим чтения 'bytes' когда ваша пользовательская функция, заданная в ReadFcn, читает BlockSize размер фрагмента файла с каждой операцией чтения.

FileDatastore устанавливает модуль параллелизации в блок файла, содержащий количество байтов, заданное BlockSize.

На основе вашей пользовательской функции чтения, файл datastore читает BlockSize размерные фрагменты файла с каждым вызовом функции read. Несколько read для чтения полного файла необходимы параллельные операции.

Как использовать subset и shuffle функции на FileDatastore объект, вы должны задать 'ReadMode' на 'file'.

Типы данных: char | string

`'BlockSize'` - Количество байтов для чтения
`positive integer`

Количество байтов для чтения с каждым read операция, заданная как положительное целое число.

Чтобы убедиться, что вы можете распределить несколько блоков файла между несколькими параллельными MATLAB^® рабочие, задайте BlockSize как положительное целое число, больше 131072 байты (128 килобайты).

Чтобы задать или изменить значение BlockSizeСначала необходимо задать ReadMode на 'bytes'. FileDatastore устанавливает значение по умолчанию BlockSize на основе значения, заданного в ReadMode.

Если ReadMode является 'file' или 'partialfile', затем FileDatastore устанавливает значение по умолчанию BlockSize на inf.
Если ReadMode является 'bytes', затем FileDatastore устанавливает значение по умолчанию BlockSize на 128 мегабайты.

`'AlternateFileSystemRoots'` - Альтернативные корневые пути файловой системы
вектор строка | массив ячеек

Альтернативные корневые пути файловой системы, заданные как разделенная разделенными запятой парами, состоящая из 'AlternateFileSystemRoots' и строковый вектор или массив ячеек. Использование 'AlternateFileSystemRoots' когда вы создаете datastore на локальной машине, но должны получить доступ и обработать данные на другой машине (возможно, другой операционной системы). Кроме того, при обработке данных с помощью Toolbox™ Parallel Computing и Server™ MATLAB Parallel, а данные хранятся на ваших локальных машинах с копией данных, доступных на другой платформе облака или кластерных машинах, необходимо использовать 'AlternateFileSystemRoots' для связи корневых путей.

Чтобы связать набор корневых путей, эквивалентных друг другу, задайте 'AlternateFileSystemRoots' как строковый вектор. Для примера,
```
["Z:\datasets","/mynetwork/datasets"]
```
Чтобы связать несколько наборов корневых путей, эквивалентных datastore, задайте 'AlternateFileSystemRoots' как массив ячеек, содержащий несколько строк, где каждая строка представляет набор эквивалентных корневых путей. Задайте каждую строку в массиве ячеек как строковый вектор или массив ячеек из векторов символов. Для примера:
- Задайте 'AlternateFileSystemRoots' как массив ячеек из строковых векторов.
```
{["Z:\datasets", "/mynetwork/datasets"];...
 ["Y:\datasets", "/mynetwork2/datasets","S:\datasets"]}
```
- Кроме того, задайте 'AlternateFileSystemRoots' как массив ячеек массива ячеек из векторов символов.
```
{{'Z:\datasets','/mynetwork/datasets'};...
 {'Y:\datasets', '/mynetwork2/datasets','S:\datasets'}}
```

Значение 'AlternateFileSystemRoots' должны удовлетворять следующим условиям:

Содержит одну или несколько строк, где каждая строка задает набор эквивалентных корневых путей.
Каждая строка задает несколько корневых путей, и каждый корневой путь должен содержать не менее двух символов.
Корневые пути уникальны и не являются подпапками друг друга.
Содержит по крайней мере один корневой путь, указывающий на расположение файлов.

Для получения дополнительной информации смотрите Настройка Datastore для обработки на различных машинах или кластерах.

Пример: ["Z:\datasets","/mynetwork/datasets"]

Типы данных: string | cell

Свойства

расширить все

FileDatastore свойства описывают файлы, сопоставленные с FileDatastore объект. Кроме Files свойство, можно задать значение FileDatastore свойства с использованием аргументов пары "имя-значение". Чтобы просмотреть или изменить свойство после создания объекта, используйте запись через точку.

`Files` - Файлы, включенные в datastore
вектор символов | массив ячеек из векторов символов | строковый скаляр | строковые массивы

Файлы, включенные в datastore, разрешаются как векторы символов, массив ячеек из векторов символов, строкового скаляра или строковых массивов, где каждый вектор символов или строка является полным путем к файлу. The location аргумент в fileDatastore и datastore функции определяют Files при создании datastore.

Пример: {'C:\dir\data\file1.ext';'C:\dir\data\file2.ext'}

Пример: 'hdfs:///data/*.mat'

Типы данных: char | cell | string

`Folders` - Папки, используемые для создания datastore
массив ячеек из векторов символов

Это свойство доступно только для чтения.

Папки, используемые для создания datastore, возвращенные как массив ячеек из векторов символов. Массив ячеек ориентирован как вектор-столбец. Каждый вектор символов является путем к папке, которая содержит файлы данных. The location аргумент в fileDatastore и datastore функции определяют Folders при создании datastore.

The Folders свойство сбрасывается при изменении Files свойство FileDatastore объект.

Типы данных: cell

`ReadFcn` - Функция, считывающая данные файла
указатель на функцию

Функция, которая читает данные файла, заданная как указатель на функцию.

Значение, заданное @ fcn, задает значение ReadFcn свойство.

Пример: @MyCustomFileReader

Типы данных: function_handle

`UniformRead` - Вертикально конкатенируемый флаг
`false` (по умолчанию) | `true`

Это свойство доступно только для чтения.

Вертикально конкатенируемый флаг, заданный как логическое true или false. Задайте значение этого свойства при первом создании FileDatastore объект.

true

Несколько чтений FileDatastore объект возвращает равномерные данные, которые являются вертикально конкатенабельными.

Когда UniformRead значение свойства true:

The ReadFcn функция должна возвращать данные, которые являются вертикально конкатенабельными; в противном случае readall метод возвращает ошибку.
Базовый тип данных выхода tall функция совпадает с типом данных, выводимых из ReadFcn.

false (по умолчанию)

Несколько чтений FileDatastore объект не возвращает равномерные данные, которые являются вертикально конкатенабельными.

Когда UniformRead значение свойства false:

readall возвращает массив ячеек.
tall возвращает tall массива ячеек.

Пример: fds = fileDatastore(location,'ReadFcn',@load,'UniformRead',true)

Типы данных: logical | double

`SupportedOutputFormats` - Список форматов, поддерживаемых для записи
Вектор-строка

Это свойство доступно только для чтения.

Список форматов, поддерживаемых для записи, возвращаемый как вектор-строка строк. Это свойство задает возможные выходные форматы при использовании writeall для записи выходных файлов из datastore.

Типы данных: string

Функции объекта

`hasdata`	Определите, доступны ли данные для чтения
`numpartitions`	Количество разделов datastore
`partition`	Раздел datastore
`preview`	Предварительный просмотр подмножества данных в datastore
`read`	Чтение данных в datastore
`readall`	Чтение всех данных в datastore
`writeall`	Запись datastore в файлы
`reset`	Сбросьте datastore в начальное состояние
`transform`	Преобразуйте datastore
`combine`	Объедините данные из нескольких хранилищ данных
`isPartitionable`	Определите, является ли datastore разделяемым
`isShuffleable`	Определите, является ли datastore shuffleable
`shuffle`	Перетащите все данные в datastore
`subset`	Создайте подмножество datastore или набора файлов

Примеры

свернуть все

Создайте объект FileDatastore

Открыть Live Script

Создайте datastore для файлов в demos MATLAB ® папка, которая имеет .mat расширение.

fds = fileDatastore(fullfile(matlabroot,'toolbox','matlab','demos'),'ReadFcn',@load,'FileExtensions','.mat')

Чтение Datastore MAT-файлов

Открыть Live Script

Создайте datastore, содержащую все .mat файлы в MATLAB ® demos папка, задающая load функция для чтения данных файла.

fds = fileDatastore(fullfile(matlabroot,'toolbox','matlab','demos'),'ReadFcn',@load,'FileExtensions','.mat')

Прочтите первый файл в datastore, а затем - второй.

data1 = read(fds);                   
data2 = read(fds);

Считывайте все файлы в datastore одновременно.

readall(fds);

Инициализируйте массив ячеек, чтобы сохранить данные и i счетчиков.

dataarray = cell(numel(fds.Files), 1);
i = 1;

Сбросьте datastore в первый файл и считывайте файлы по одному, пока не останется данных. Присвойте данные массиву dataarray.

reset(fds);                          
while hasdata(fds)                   
    dataarray{i} = read(fds);
    i = i+1;
end

Чтение одного массива за раз из большого MAT-файла

Открыть Live Script

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

Напишите пользовательскую функцию чтения, которая читает по одному массиву за раз из MAT-файла.
Настройте параметры функции datastore, чтобы выполнить частичные чтения.
Считывайте по одному массиву из MAT-файла.

Напишите пользовательскую функцию, которая читает один массив в момент времени из MAT-файла. Функция должна иметь сигнатуру, как описано в @ReadFcn аргумент FileDatastore. Сохраните этот файл в рабочей папке или в папке, расположенной в пути MATLAB. В данном примере пользовательская функция load_variable включено здесь.

type load_variable.m

function [data,variables,done] = load_variable(filename,variables)
    
    % If variable list is empty, 
    % create list of variables from the file
    if isempty(variables) 
        variables = who('-file', filename);
    end
    
    % Load a variable from the list of variables
    data = load(filename, variables{1});
    
    % Remove the newly-read variable from the list
    variables(1) = []; 
    
    % Move on to the next file if this file is done reading.
    done = isempty(variables); 
    
end

Создайте и настройте FileDatastore содержащие accidents.mat. Задайте параметры datastore, которые будут использоваться 'partialfile' как режим чтения и load_variable как пользовательская функция чтения.

fds = fileDatastore('accidents.mat','ReadMode','partialfile','ReadFcn',@load_variable);

Считайте первые три переменные из файла с помощью datastore. Файл accidents.mat содержит девять переменных и каждый вызов read возвращает одну переменную. Поэтому, чтобы получить первые три переменные, трижды вызовите функцию read.

data = read(fds)

data = struct with fields:
    datasources: {3x1 cell}

data = read(fds)

data = struct with fields:
    hwycols: 17

data = read(fds)

data = struct with fields:
    hwydata: [51x17 double]

Обратите внимание, что образец файла accidents.mat является маленьким и помещается в памяти, но можно ожидать аналогичных результатов для больших MAT-файлов, которые не помещаются в памяти.

Совет

Как использовать subset и shuffle функции на FileDatastore объект, вы должны задать 'ReadMode' на 'file'.

См. также

mapreduce | tall

Темы

Введенный в R2016a

Документация

fileDatastore

Описание

Создание

Синтаксис

Описание

Входные параметры

`location` - Файлы или папки для включения в datastore
путь | `DsFileSet` объект

`@fcn` - Функция, считывающая данные файла
указатель на функцию

`'IncludeSubfolders'` - Флаг включения подпапки
`true` или `false` | 0 или 1

`'FileExtensions'` - Пользовательские расширения файлов в формате
вектор символов | массив ячеек из векторов символов | строковый скаляр | строковые массивы

`'PreviewFcn'` - Функция для предварительного просмотра входных данных
`@ReadFcn` (по умолчанию) | указатель на функцию

`'ReadMode'` - Фрагмент файла для чтения
`'file'` (по умолчанию) | `'partialfile'` | `'bytes'`

`'BlockSize'` - Количество байтов для чтения
`positive integer`

`'AlternateFileSystemRoots'` - Альтернативные корневые пути файловой системы
вектор строка | массив ячеек

Свойства

`Files` - Файлы, включенные в datastore
вектор символов | массив ячеек из векторов символов | строковый скаляр | строковые массивы

`Folders` - Папки, используемые для создания datastore
массив ячеек из векторов символов

`ReadFcn` - Функция, считывающая данные файла
указатель на функцию

`UniformRead` - Вертикально конкатенируемый флаг
`false` (по умолчанию) | `true`

`SupportedOutputFormats` - Список форматов, поддерживаемых для записи
Вектор-строка

Функции объекта

Примеры

Создайте объект FileDatastore

Чтение Datastore MAT-файлов

Чтение одного массива за раз из большого MAT-файла

Совет

См. также

Темы

Документация MATLAB

Поддержка

Документация

fileDatastore

Описание

Создание

Синтаксис

Описание

Входные параметры

location - Файлы или папки для включения в datastore путь | DsFileSet объект

@fcn - Функция, считывающая данные файла указатель на функцию

'IncludeSubfolders' - Флаг включения подпапки true или false | 0 или 1

'FileExtensions' - Пользовательские расширения файлов в формате вектор символов | массив ячеек из векторов символов | строковый скаляр | строковые массивы

'PreviewFcn' - Функция для предварительного просмотра входных данных @ReadFcn (по умолчанию) | указатель на функцию

'ReadMode' - Фрагмент файла для чтения 'file' (по умолчанию) | 'partialfile' | 'bytes'

'BlockSize' - Количество байтов для чтения positive integer

'AlternateFileSystemRoots' - Альтернативные корневые пути файловой системы вектор строка | массив ячеек

Свойства

Files - Файлы, включенные в datastore вектор символов | массив ячеек из векторов символов | строковый скаляр | строковые массивы

Folders - Папки, используемые для создания datastore массив ячеек из векторов символов

ReadFcn - Функция, считывающая данные файла указатель на функцию

UniformRead - Вертикально конкатенируемый флаг false (по умолчанию) | true

SupportedOutputFormats - Список форматов, поддерживаемых для записи Вектор-строка

Функции объекта

Примеры

Создайте объект FileDatastore

Чтение Datastore MAT-файлов

Чтение одного массива за раз из большого MAT-файла

Совет

См. также

Темы

Документация MATLAB

Поддержка

`location` - Файлы или папки для включения в datastore
путь | `DsFileSet` объект

`@fcn` - Функция, считывающая данные файла
указатель на функцию

`'IncludeSubfolders'` - Флаг включения подпапки
`true` или `false` | 0 или 1

`'FileExtensions'` - Пользовательские расширения файлов в формате
вектор символов | массив ячеек из векторов символов | строковый скаляр | строковые массивы

`'PreviewFcn'` - Функция для предварительного просмотра входных данных
`@ReadFcn` (по умолчанию) | указатель на функцию

`'ReadMode'` - Фрагмент файла для чтения
`'file'` (по умолчанию) | `'partialfile'` | `'bytes'`

`'BlockSize'` - Количество байтов для чтения
`positive integer`

`'AlternateFileSystemRoots'` - Альтернативные корневые пути файловой системы
вектор строка | массив ячеек

`Files` - Файлы, включенные в datastore
вектор символов | массив ячеек из векторов символов | строковый скаляр | строковые массивы

`Folders` - Папки, используемые для создания datastore
массив ячеек из векторов символов

`ReadFcn` - Функция, считывающая данные файла
указатель на функцию

`UniformRead` - Вертикально конкатенируемый флаг
`false` (по умолчанию) | `true`

`SupportedOutputFormats` - Список форматов, поддерживаемых для записи
Вектор-строка