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 в виде FileSet объект, как пути к файлам, или как DsFileSet объект.

  • FileSet объект — можно задать location как FileSet объект. Определение местоположения как FileSet объект приводит к более быстрому времени создания для хранилищ данных по сравнению с определением пути или DsFileSet объект. Для получения дополнительной информации смотрите matlab.io.datastore.FileSet.

  • Путь к файлу — можно задать один путь к файлу как вектор символов или строковый скаляр. Можно задать несколько путей к файлам как массив ячеек из символьных векторов или массив строк.

  • DsFileSet объект — можно задать DsFileSet объект. Для получения дополнительной информации смотрите matlab.io.datastore.DsFileSet.

Файлы или папки могут быть локальными или удаленными:

  • Локальные файлы или папки — Задают локальные пути к файлам или папкам. Если файлы не находятся в текущей папке, то задают полные или относительные пути. Файлы в подпапках заданной папки автоматически не включены в datastore. Можно использовать подстановочный символ (*) при определении локального пути. Этот символ указывает, что datastore включает все файлы соответствия или все файлы в соответствующих папках.

  • Удаленные файлы или папки — Задают полные пути к удаленным файлам или папкам как универсальный локатор ресурса (URL) формы hdfs:///path_to_file. Для получения дополнительной информации смотрите работу с Удаленными данными.

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

Использовать subset и shuffle функции на FileDatastore объект, необходимо установить "ReadMode" к "file".

Типы данных: 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 создается.

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

Типы данных: 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
shuffleПереставьте все данные в datastore
subsetСоздайте подмножество datastore или установленный на файл

Примеры

свернуть все

Создайте объект fileDatastore, использующий или объект FileSet или пути к файлам.

Создайте объект FileSet. Создайте объект fileDatastore.

fs = matlab.io.datastore.FileSet("airlinesmall.parquet");
fds = fileDatastore(fs,"ReadFcn",@load)
fds = FileDatastore with properties:
                       Files: {
                              ' ...\matlab\toolbox\matlab\demos\airlinesmall.parquet'
                              }
                     Folders: {
                              '...\matlab\toolbox\matlab\demos'
                              }
                 UniformRead: 0
                    ReadMode: 'file'
                   BlockSize: Inf
                  PreviewFcn: @load
      SupportedOutputFormats: ["txt"    "csv"    "xlsx"    "xls"    "parquet"    "parq"    "png"    "jpg"    "jpeg"    "tif"    "tiff"    "wav"    "flac"    "ogg"    "mp4"    "m4a"]
                     ReadFcn: @load
    AlternateFileSystemRoots: {}

В качестве альтернативы можно использовать пути к файлам, чтобы создать объект fileDatastore.

fds = fileDatastore("airlinesmall.parquet","ReadFcn",@load);

Создайте 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 38 more
                              }
                     Folders: {
                              '...\matlab\toolbox\matlab\demos'
                              }
                 UniformRead: 0
                    ReadMode: 'file'
                   BlockSize: Inf
                  PreviewFcn: @load
      SupportedOutputFormats: ["txt"    "csv"    "xlsx"    "xls"    "parquet"    "parq"    "png"    "jpg"    "jpeg"    "tif"    "tiff"    "wav"    "flac"    "ogg"    "mp4"    "m4a"]
                     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

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

Советы

  • Использовать subset и shuffle функции на FileDatastore объект, необходимо установить "ReadMode" к "file".

Введенный в R2016a