fileDatastore

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

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

Описание

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

Создание

Синтаксис

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, чтобы быть полными путями файлов или папок как интернационализировавший идентификатор ресурса (IRI) формы 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 Имя файла, чтобы читать.

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

'partialfile'

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

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

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

сделанный Установите этот аргумент logical или на true или на false.

  • ложь Продолжите читать текущий файл.

  • tRUE Отключите текущее чтение файла и считайте следующий файл.

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

'byte'

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

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

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

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

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

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

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

Пример: @customreader

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

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

Укажите необязательные аргументы в виде пар ""имя, значение"", разделенных запятыми. Имя (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, чтобы обеспечить функцию, которая читает только минимальную необходимую часть входных данных для предварительного просмотра и высокой конструкции.

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

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

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

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

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

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

'partialfile'

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

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

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

'bytes'

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

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

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

Типы данных: 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 на локальной машине, но должны будете получить доступ и обработать данные на другой машине (возможно различной операционной системы). Кроме того, когда обработка данных с помощью Parallel Computing Toolbox™ и MATLAB Parallel Server™ и данных хранится на локальных машинах с копией доступных данных на облаке другой платформы или кластерных машинах, необходимо использовать '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, разрешенный как вектор символов, массив ячеек из символьных векторов, представляют в виде строки скаляр или массив строк, где каждый вектор символов или строка являются полным путем к файлу. Аргумент location в fileDatastore и функциях datastore задает Files, когда datastore создается.

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

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

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

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

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

Пример: @MyCustomFileReader

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

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

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

true

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

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

  • Функция ReadFcn должна возвратить данные, которые вертикально concatenateable; в противном случае метод readall возвращает ошибку.

  • Базовый тип данных вывода функции tall совпадает с типом данных вывода от ReadFcn.

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

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

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

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

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

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

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

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

hasdataОпределите, доступны ли данные для чтения
numpartitionsКоличество разделов datastore
partitionРазделите datastore
previewПодмножество данных в datastore
readСчитайте данные в datastore
readallСчитывайте все данные в datastore
resetСброс Datastore к начальному состоянию
transformПреобразуйте datastore
combineОбъедините данные от нескольких datastores

Примеры

свернуть все

Открыть скрипт

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

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

fds = 

  FileDatastore with properties:

                       Files: {
                              ' ...\matlab\toolbox\matlab\demos\accidents.mat';
                              ' ...\matlab\toolbox\matlab\demos\airfoil.mat';
                              ' ...\matlab\toolbox\matlab\demos\airlineResults.mat'
                               ... and 37 more
                              }
                 UniformRead: 0
                     ReadFcn: @load
    AlternateFileSystemRoots: {}
Открыть скрипт

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

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

fds = 

  FileDatastore with properties:

                       Files: {
                              ' ...\matlab\toolbox\matlab\demos\accidents.mat';
                              ' ...\matlab\toolbox\matlab\demos\airfoil.mat';
                              ' ...\matlab\toolbox\matlab\demos\airlineResults.mat'
                               ... and 37 more
                              }
                 UniformRead: 0
                     ReadFcn: @load
    AlternateFileSystemRoots: {}

Считайте первый файл в 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
Скрипт Open 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 как пользовательское чтение fuction. 

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

Считайте первые три переменные из файла с помощью datastore. Файл accidents.mat содержит девять переменных и каждый вызов 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-файлов, которые не умещаются в памяти.

Альтернативы

Также можно создать объект FileDatastore с помощью функции datastore. Например, ds = datastore(location,'Type','file','ReadFcn',@fcn) создает datastore из набора файлов, заданных location.

Смотрите также

| |

Темы

Введенный в R2016a

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