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'}).

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

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

Файлы или папки, включенные в 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 зависит от значения заданного 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.

Значение, заданное в @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. Задайте true включать все файлы и подпапки в каждую папку или false для включения только файлов в каждую папку.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Фрагмент считываемого файла, заданная как '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

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

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

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

  • Если ReadMode является 'file' или 'partialfile', затем FileDatastore устанавливает значение по умолчанию BlockSize на inf.

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

Альтернативные корневые пути файловой системы, заданные как разделенная разделенными запятой парами, состоящая из '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 свойства с использованием аргументов пары "имя-значение". Чтобы просмотреть или изменить свойство после создания объекта, используйте запись через точку.

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

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

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

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

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

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

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

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

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

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

Пример: @MyCustomFileReader

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

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

Вертикально конкатенируемый флаг, заданный как логическое 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

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

Список форматов, поддерживаемых для записи, возвращаемый как вектор-строка строк. Это свойство задает возможные выходные форматы при использовании 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 или набора файлов

Примеры

свернуть все

Открыть Live Script

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

fds = fileDatastore(fullfile(matlabroot,'toolbox','matlab','demos'),'ReadFcn',@load,'FileExtensions','.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
Открыть Live Script

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

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

  2. Настройте параметры функции datastore, чтобы выполнить частичные чтения.

  3. Считывайте по одному массиву из 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'.

См. также

|

Темы

Введенный в R2016a

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

Поддержка

Для просмотра документации необходимо авторизоваться на сайте