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 быть полными путями файлов или папок как универсальный локатор ресурса (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

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

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

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

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

Значение, заданное @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

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

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

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

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

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

Примеры

свернуть все

Скрипт Open Live Script

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

fds = fileDatastore(fullfile(matlabroot,'toolbox','matlab','demos'),'ReadFcn',@load,'FileExtensions','.mat')
Скрипт Open 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
Скрипт 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 как пользовательская функция чтения. 

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-файлов, которые не умещаются в памяти.

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

|

Темы

Введенный в R2016a

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