dmarrayfun

Apply function to each element in DataMatrix object

Syntax

DMObjNew1 = dmarrayfun(Func, DMObj1)
DMObjNew1 = dmarrayfun(Func, DMObj1, DMObj2, ...)
[DMObjNew1, DMObjNew2, ...] = dmarrayfun(Func, DMObj1, ...)
[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'UniformOutput', UniformOutputValue, ...)
[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'DataMatrixOutput', DataMatrixOutputValue, ...)
[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'Rows', RowsValue, ...)
[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'Columns', ColumnsValue, ...)
[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'ErrorHandler', ErrorFuncHandle, ...)


Input Arguments

Func	Function handle for a function that returns one or more scalars, and returns values of the same class each time it is called.
DMObj1	DataMatrix object, such as created by DataMatrix (object constructor).
DMObj2	Either of the following: DataMatrix object, such as created by DataMatrix (object constructor) MATLAB® numeric array Note DMObj2 and subsequent input objects or arrays must be the same size (number of rows and columns) as DMObj1.
UniformOutputValue	Specifies whether Func must return output values without encapsulation in a cell array. Choices are true (default) or false. If true, dmarrayfun must return scalar values that can be concatenated into an array. These values can also be a cell array. If false, dmarrayfun returns a cell array (or multiple cell arrays), where the I,Jth cell contains the value equal to Func(DMObj1(I,J),...).
DataMatrixOutputValue	Specifies whether return values must be DataMatrix objects. Choices are true (default) or false. If you set the 'UniformOutput' property to false, this property is ignored.
RowsValue, ColumnsValue	Specifies the rows or columns to which to apply the function. Choices are: Positive integer Vector of positive integers Character vector specifying a row or column name Cell array of character vectors Logical vector
ErrorFuncHandle	Specifies a function handle to a function that dmarrayfun calls if the call to Func fails.

Output Arguments

DMObjNew1, DMObjNew2

DataMatrix objects created from applying the function to each element in one or more DataMatrix objects. The size (number of rows and columns), row names, and column names will be the same as DMObj1.

Description

DMObjNew1 = dmarrayfun(Func, DMObj1) applies the function specified by Func to each element in DMObj1, a DataMatrix object, and returns the results in DMObjNew1, a new DataMatrix object. DMObjNew1 has the same size (number of rows and columns), row names, and column names as DMObj1. The I,Jth element of DMObjNew1 is equal to Func(DMObj1(I,J)), where Func is a function handle for a function that takes one input argument, returns one scalar value, and returns values of the same class each time it is called.

DMObjNew1 = dmarrayfun(Func, DMObj1, DMObj2, ...) evaluates the function specified by Func using elements in DMObj1, DMObj2, etc. as input arguments. The I,Jth element of DMObjNew1 is equal to Func(DMObj1(I,J), DMObj2(I,J), ...), where Func is a function handle for a function that takes multiple input arguments, returns one scalar, and returns values of the same class each time it is called.

[DMObjNew1, DMObjNew2, ...] = dmarrayfun(Func, DMObj1, ...) evaluates the function specified by Func using elements in DMObj1, and possibly other input arguments. Func is a function handle for a function that takes one or more input arguments, returns multiple scalars, and returns values of the same class each time it is called. It returns DataMatrix objects DMObjNew1, DMObjNew2, etc. with each one corresponding to one of the outputs of Func. The outputs of Func may be of different classes, however, but each output must be the same each time it is called.

[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'PropertyName', PropertyValue, ...) calls dmarrayfun with optional properties that use property name/property value pairs. You can specify one or more properties in any order. Each PropertyName must be enclosed in single quotation marks and is case insensitive. These property name/property value pairs are as follows:

[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'UniformOutput', UniformOutputValue, ...) specifies whether Func must return output values without encapsulation in a cell array. Choices are true (default) or false. If true, dmarrayfun must return scalar values that can be concatenated into an array. These values can also be a cell array. If false, dmarrayfun returns a cell array (or multiple cell arrays), where the I,Jth cell contains the value equal to Func(DMObj1(I,J),...).

[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'DataMatrixOutput', DataMatrixOutputValue, ...) specifies whether return values must be DataMatrix objects. Choices are true (default) or false. If you set the 'UniformOutput' property to false, this property is ignored.

[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'Rows', RowsValue, ...) applies the function only to the rows in the DataMatrix object specified by RowsValue, which can be a positive integer, vector of positive integers, character vector specifying a row name, cell array of character vectors, or a logical vector.

[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'Columns', ColumnsValue, ...) applies the function only to the columns in the DataMatrix object specified by ColumnsValue, which can be a positive integer, vector of positive integers, character vector specifying a column name, cell array of character vectors, or a logical vector.

[DMObjNew1, ...] = dmarrayfun(Func, DMObj1, ...'ErrorHandler', ErrorFuncHandle, ...) specifies a function handle to a function that dmarrayfun calls if the call to Func fails. The error handling function will be called with these input arguments:

• Structure with the following fields:

  • identifier — Identifier of the error

  • message — Error message text

  • index — Linear index into the input array(s) at which the error occurred

• Set of input arguments at which the call to the function failed

If you do not specify ErrorFuncHandle, dmarrayfun rethrows the error from the call to Func.

Version History

Introduced in R2008b