fileDatastore

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

Описание

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

Создание

Описание

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.

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

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

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

Типы данных: логический | 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 isfile или '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)

Типы данных: логический | 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')

Создайте 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

Можно создать 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 возвращает одну переменную. Поэтому, чтобы получить первые три переменные, вызовите функцию чтения три раза.

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

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